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.

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.

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 not perform the given --trigger.

The result of this check will be output to the console. Any of logging options on the command line will be ignored. This command will exit with status code 0 if successful and 1 if unsuccessful.

See The Command Line Utility page for details.

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.

Passing Arbitrary Variables

If you wish to pass in parameters other then the predefined Command Line Options, you can do so using environment-variables. For example:

$ DB_NAME=my_app_production STORAGE_PATH=~/backups/production backup perform --trigger my_backup

Then, you can access these in the my_backup.rb model:

Model.new(:my_backup, 'Description for my_backup') do
  database MongoDB do |db|
    db.name = ENV["DB_NAME"] || "default_name"
    #...
  end

  store_with Local do |local|
    local.path = ENV['STORAGE_PATH']
  end
end

Or you can use a single environment-variable to setup a number of local variables:

$ BACKUP_ENV=production backup perform --trigger my_backup

Then, configure your model using:

Model.new(:my_backup, 'Description for my_backup') do
  case ENV['BACKUP_ENV']
  when 'production'
    db_name = 'my_app_production'
    storage_path = '~/backups/production'
  when 'development'
    db_name = 'my_app_development'
    storage_path = '~/backups/development'
  else
    raise 'you must provide BACKUP_ENV'
  end

  database MongoDB do |db|
    db.name = db_name
    #...
  end

  store_with Local do |local|
    local.path = storage_path
  end
end