Performing Backups

Performing Backups

The most basic command for performing a backup is:

$ backup perform --trigger my_backup

This command will load the main configuration file, located by default at ~/Backup/config.rb. The main configuration file config.rb is setup to load all models from the models/ subdirectory relative to it's location. So, by default this will be: ~/Backup/models/.

Therefore, in order for the above command to work, a model must exist which defines the my_backup trigger.

Backup::Model.new(:my_backup, 'My Backup') do
  # backup configuration...
end

The best way to create your initial main configuration file and backup model file(s) is to use the Generator.

Command Line Options

--trigger (aliases: --triggers, -t)

The --trigger option specifies which backup model you wish to run. Multiple triggers may be specified, which will run each corresponding backup in the order the triggers are given.

$ backup perform --trigger my_backup
$ backup perform --triggers my_backup1,my_backup2,my_backup3 (no spaces between trigger names)
$ backup perform -t my_backup1,my_backup2

--config-file (alias: -c)

The Generator allows you to specify the --config-path when generating a model, if you want to store your configuration in a location other than the default ~/Backup. If you have done so, then you will need to specify this location when performing your backup, like so:

$ backup perform --trigger my_backup --config-file /path/to/config.rb

--data-path (alias: -d)

Backup has a Cycling feature, which can automatically perform backup rotation for you. In order to do this, Backup stores a YAML formatted data file with information about your backups, based on the Storages used. This data is stored by default in ~/Backup/data. If you are storing this data in another location, it will need to be specified using the --data-path option.

$ backup perform --trigger my_backup --data-path /path/to/data/dir/

--tmp-path

During the backup process, all of the Archives and Databases being processed are stored in ~/Backup/.tmp, where they are packaged and optionally Split into chunks before being transferred to your Storages. If you want to specify a different directory for this, use:

$ backup perform --trigger my_backup --tmp-path /path/to/.tmp/

--cache-path

If you're using the Dropbox service, then Backup uses the ~/Backup/.cache directory to store the session cache file used to authorize connections to Dropbox. To store this in another location, use:

$ backup perform --trigger my_backup --cache-path /path/to/.cache/

--root-path (alias: -r)

If you are happy with the default directory names, but would like to establish this hierarchy in a location other than ~/Backup, then you can specify a new root directory using:

$ backup perform --trigger my_backup --root-path /path/to/root/dir/

The --root-path may be specified as an absolute path, or a relative path from where the backup command is being run. In either case, the specified directory must exist.

The command above would then result in:

--config-file => /path/to/root/dir/config.rb
--data-path   => /path/to/root/dir/data/
--log-path    => /path/to/root/dir/log/
--tmp-path    => /path/to/root/dir/.tmp/
--cache-path  => /path/to/root/dir/.cache/

If you use the --root-path option, you can still specify one of the other options above. However, how that option will behave depends on how you specify the path for that option. If the other option is specified as an absolute path, then it will be used as you supply it. If it is given as a relative path, it will be appended to the specified --root-path. Note that while --root-path must already exist, all other paths specified will be created if needed.

Examples:

$ backup perform --trigger my_backup --root-path /new/root/ --tmp-path /tmp/backup

--config-file => /new/root/config.rb
--data-path   => /new/root/data/
--log-path    => /new/root/log/
--tmp-path    => /tmp/backup/
--cache-path  => /new/root/.cache/


$ backup perform --trigger my_backup --root-path /new/root/ --tmp-path temp/dir/ --config-file my_config.rb

--config-file => /new/root/my_config.rb
--data-path   => /new/root/data/
--log-path    => /new/root/log/
--tmp-path    => /new/root/temp/dir/
--cache-path  => /new/root/.cache/

Given you are running backup from the directory /foo:

$ backup perform --trigger my_backup --root-path my_backups --tmp-path temp/dir/

--config-file => /foo/my_backups/config.rb
--data-path   => /foo/my_backups/data/
--log-path    => /foo/my_backups/log/
--tmp-path    => /foo/my_backups/temp/dir/
--cache-path  => /foo/my_backups/.cache/

$ backup perform --trigger my_backup --root-path . --tmp-path /tmp/backup --config-file cfg_dir/cfg.rb

--config-file => /foo/cfg_dir/cfg.rb
--data-path   => /foo/data/
--log-path    => /foo/log/
--tmp-path    => /tmp/backup/
--cache-path  => /foo/.cache/

Logging Options

Backup produces various informational messages during the backup process. The following command line options may be used to control where these messages are sent and/or stored. Logging options may also be configured within your config.rb file. For more information, see the Logging page.

--quiet (alias: -q)

By default, Backup will output all log messages to the console. Use of this flag will disable all console output.

You may also force console output using --no-quiet.

--logfile

By default, Backup keeps a backup.log file containing all messages produced for all backup jobs. The backup.log file will be kept truncated (to ~500KB by default), with older entries being removed.

Since this is the default behavior, use of this flag is not needed. However, you may use --no-logfile to force Backup not to use this log file.

--log-path (alias: -l)

The default location for the backup.log file is in the ~/Backup/log directory. If you would like to store the log for your backup in another location, then specify an alternate --log-path on the command line:

$ backup perform --trigger my_backup --log-path /path/to/log/dir/

This path may be given as an absolute path (as shown above), or a path relative to the --root-path. By default, this is set to log/ and will be relative to the --root-path (which by default is ~/Backup).

--syslog

Backup also supports sending log message to your system's Syslog facility. Use of this flag enables this option.

Additional syslog configuration may be set within your config.rb file. See the Logging page for details.

You may also force disable this option using --no-syslog.

Exit Status Codes

The backup perform command will exit with the following status codes:

0: All triggers were successful and no warnings were issued. 1: All triggers were successful, but some had warnings. 2: All triggers were processed, but some failed. 3: A fatal error caused Backup to exit. Some triggers may not have been processed.

Checking for Configuration Errors

--check

Adding --check to your command line allows you to test your configuration for any errors or warnings. This option will load your config.rb and all your Models, but will perform no backups.

If any errors or warnings are issued during this check, all messages will be output to the console (and only the console). The command will exit with status code 1.

If this check succeeds, the command will exit with status code 0, and a success message will be sent based on the logging options you have set.

Understand, this means that if both --quiet and --check are used, a successful check would produce no console output - messages would only be sent to the log file or syslog, depending on your configuration. You may use --check --no-quiet to force console output.

Note that this check does not process the jobs for the given triggers in any way. This is not a guarantee that these jobs will actually run. You should perform a live test for your backup job for this. This check will only catch errors or warnings generated by the process of loading your configuration to prepare to run a backup.