Create Backup Plans (CLI 2.0)
As of Backup Agent 4.1 for macOS, a new command line interface (CLI 2.0 or CLI V2)is introduced. CLI 2.0 is a separate command line interface solution that has the enhanced functionality that covers the new backup format requirements.
Note that all actions and settings in the new backup format are supported in the CLI V2 only
Create File Backup Plan Using CLI V2 (new and current backup formats)
To create a new backup plan, use the plan create_backup file command.
./cbbV2 plan create_backup file --format nbf --name “Plan Name" --account “Account Name” --source “Source” --confirm
This chapter covers the following topics:
- Command Examples
- Run backup plan
- Stop backup plan
- Command parameters
Create Backup Plan Command Examples
Create Backup Plan in the New Backup Format
The most common use-case: create a backup plan in the new backup format, specify the plan name, storage account and source.
* ./cbbV2 plan create_backup file --format nbf --name “My first plan Name" --account “My storage account” --source “/home/usr/me/backup/” --confirm
* ./cbbV2 plan create_backup file -n “Plan Name” -ac “Account Name" -s “Source” --confirm
View the example of creating a scheduled backup plan.
./cbbV2 plan create_backup --name "plan65" -a "test14" -f "nbf" -s "/home/jmisth/tmp" --schedule "true" --use-recurring-option "true" --frequency-value "Monthly" --monthly-type-value "1" --monthly-repeat-from "23.09.2022" -c
Create Backup Plan in the current backup format
View the command examples to create backup plans in the currenty backup format:
./cbbV2 plan create_backup file --format cbf --name “Plan Name" --account “Account Name” --source “Source” --confirm
./cbbV2 plan create_backup file --format cbf --name “Plan Name" --account “Account Name” --source “Source” --confirm
./cbbV2 plan create_backup file --name “Plan Name” --account “Account Name" --source “Source” --confirm
Run Backup Plan
View the command examples to execute backup plans:
* ./cbbV2 plan start -n “Plan Name”. This command runs the plan named "Plan name"
* ./cbbV2 plan start –name “Plan Name”. This command runs the plan named "Plan name"
* ./cbbV2 plan start -n “Plan Name” -f. This command runs full backup of the plan named "Plan name"
* ./cbbV2 plan start –name “Plan Name” -f. This command runs full backup of the plan named "Plan name"
* ./cbbV2 plan start -n “Plan Name” --force-full. This command runs full backup of the plan named "Plan name"
* ./cbbV2 plan start –name “Plan Name” --force-full. This command runs full backup of the plan named "Plan name"
* ./cbbV2 plan start –id “Plan ID”. This command runs the backup plan with the "Plan ID" instead of a plan name
Stop Backup Plan
View the command examples to stop running backup plans:
./cbbV2 plan stop -n “Plan Name”
./cbbV2 plan stop –name “Plan Name”
./cbbV2 plan stop –id “Plan ID”
Command Parameters
--format
This parameter sets the backup format of backup plan and is mandatory.
Parameter syntax:
- --format
- -f
Possible values:
- nbf
- cbf (default value)
--name
This parameter sets the backup plan name and is mandatory.
Parameter syntax:
- --name
- -n
Possible values:
- None. Default value is: Backup and the date of the backup plan creation
--id
This parameter sets the backup plan ID.
Parameter syntax:
- --id
- -i
--account
This parameters sets the storage account name (or account ID) and is mandatory.
Parameter syntax:
- --account
- -a
Possible values:
- Existing storage accounts
--storage-class
Sets the storage class for AWS S3 or Azure storage accounts.
Amazon:
- Standard
- StandardIA
- OneZoneIA
- Glacier
- Intelligent
- DeepArchive
Azure:
- hot
- cool
- archive
--sse
Sets the server-side encryption. This parameter can be applied to Amazon S3 storage accounts only.
Possible values:-
- true
- false (default)
--transfer-acceleration
Enables or disables the Amazon S3 transfer acceleration
Posssible values:
- true
- false (default)
--sync
Executes synchronization with the plan storage account before the plan execution.
Possible values:
- on
- off (default)
--source
Specifies the backup source. This parameter can be used multiple times in one command.
--exclude
Exclude files and folders from backup plan, repeatable param
--hidden
Disables/enables system and hidden file backup.
Possible values:
- true
- false (default, system and hidden files will be not backed up))
--saveconfig
Saves the backup pkan configuration to the backup storage. This enable the restore of the backup plan configuration. This paremeter can be applied to backup plans in the current backup format only.
Possible values:
- true (default)
- false
--block-level
Enables the block-level backup.
Possible values:
- true
- false (default)
--compression
Enables compression.
Possible values:
- true (default)
- false
For free editions compression is always disabled.
--encryption
Enables encryption.
Possible values:
- true
- false (default)
For free editions encryption is always disabled.
--encryption-algorithm
Sets the encryption algorithm. This paremeter is used with the --encryption parameter and "true" value.
Possible values:
- aes-128
- aes-192
- aes-256 (default)
--encryption-password
Sets the encryption password.
--encryption-hint
Sets the hint for encryption password. This parameter is used with the --encryption-password "true".
--empty
Enables/disables empty directories backup.
Possible values:
- true
- false (default)
--file-mask-type
Sets the behavior for files excluded from backup by mask. This parameter is used with the --file-mask parameter.
Possible values:
- skip
- backup
- all
--file-mask
--skip-folders
Excludes specified directories from backup plan.
Examples: abc*; xyz*
--skip-in-use
Disables/enables backup of files in use.
Possible values:
- true
- false (default, files in use will be backed up)
--retention-policy
Sets the retention policy mode.
Possible values:
- Default (default)
- Custom
--delete-version-older
Enables ‘Delete version older than’ option. This parameter is used with --delete-version-older-type and--delete-version-older-age
--delete-version-older-type. Additionally, the custom retention policy must be set. The parameter is not compatible with the new backup format.
Possible values:
- true
- false (default)
Month Week Day
Sets the period type for the delete version older than parameter. This parameter is used with --delete-version-older and --delete-version-older-age parameters. Possible values: Month, Week, Day
--delete-version-older-age
Sets the period length for the delete version older than parameter. This parameter must be used with --delete-version-older and --delete-version-older-type parameters.
Example:
--delete-version-older-type Week --delete-version-older-age 2
--nbf-retention-policy
Enables retention policy in plans in the new backup format.
Possible values:
- true
- false (default)
--keep-backup-type
Sets the period type for retention policy. This parameter is used with --nbf-retention-policy.
Possible values:
- Year
- Month
- Week
- Day.
Example:
--nbf-retention-policy “true” --keep-backup-type “Week”
--keep-backup-number
Sets the period for retention policy. This parameter is used with --nbf-retention-policy and --keep-backup-type parameters.
Possible values: 1-999.
Example:
--nbf-retention-policy “true” --keep-backup-type “Month” --keep-backup-number “8”
--delete-date-type
Sets the period type for retention policy to count. This parameter is used with --delete-version-older parameter. Applies to the current backup format.
Possible values:
- backup-date
- modified-date (default)
--keep-last-version
Enables/disables keeping the last file version on backup storage. Applies to the current backup format only
--keep-version
Enables keeping the specified number of file versions kept on backup storage. This parameter cannot be applied to plans in the new backup format. The value must be an integer
--keep-version-number
Sets the numbers of file versions kept on backup storage. The value must be an integer and >0. This parameter cannot be applied to plans in the new backup format.
--delete-locally
Enables the delete locally deleted files option.
Possible values:
- true
- false (default)
--delete-locally-delay
Sets delay for locally deleted files delay. Example: –delete-locally-delay 4 sets the 4-day delay of deleting files in backup storage that were deleted locally.
--run-missed-option
Executes the plan if it was missed for some reason as the computer boots up.
Possible values:
- true
- false (default)
--schedule
Enables schedule for the plan.
Possible values:
- true
- false (default)
--specific-date-option
Runs the plan on a specific date. Applies to the current backup format only.
Possible values:
- true
- false (default)
--specific-date-value
Runs the plan on specific date and time. Applies to the current backup format only.
Example: --specific-date-value “14.04.2022 14:05”
--stop-auto-option
Enables plan stopping if it runs more than specified period.
Possible values:
- true
- false (default)
--stop-auto-hours-value
Sets the value in hours for the --stop-auto-option.
Value range: 0-99.
Example: --stop-auto-option “true” --stop-auto-hours value “6”
--stop-auto-minutes-value
Sets the value in minutes for the --stop-auto-option.
Value range: 0-59.
Example: --stop-auto-option “true” --stop-auto-hours value “5” --stop-auto-minutes-value “45”
--use-recurring-option
Enables recurring schedule usage. Applies to the current backup format only.
Possible values:
- true
- false (default)
--frequency-value
Sets the frequency value for recurring schedule. Applies to the current backup format only.
Possible values:
- Daily
- Weekly
- Monthly
--occurs-at-option
Enables/disables the backup plan execution at specific time. This parameter is used with the --frequency-value set “Daily”.
Possible values:
- true
- false
--occurs-at-value
Sets the date and time of the backup plan execution. This parameter is used with the --frequency-value set “Daily” and the --occurs-at-option set “true”
--occurs-every-option
Enables or disables the occurs every option in the schedule. This parameter is used with schedule frequency set as daily.
Possible values:
- on
- off
--occurs-every-value
Sets the time in minutes for the --occurs-every-option parameter. This parameter is used with schedule frequency set as daily.
Possible values: integer, value range 1-60.
--occurs-every-from
Sets the start date and time the occurs every option is enabled.
Example: --occurs-every-from “11:30”
--occurs-every-to
Sets the date and time the ‘occurs every’ option is enabled until.
Example: --occurs-every-to “23:00”
--week-day-numbers
Sets the day of the week the backup plan is executed. Possible values, integer, range 1-7. This parameter is used with the --frequency-value=Weekly parameter.
--monthly-type-value
Sets the type of monthly backup execution.
Possible values: 0-6.
- If 0 is set, backup will be executed every month on the day specified by --monthly-day parameter.
- If values in 1-6 [First, Second, Third, Fourth, Penultimate, Last] range are set, backup will be executed every month on the specific week (e.g first week, second week, etc.) on the day specified by --monthly-day parameter.
--monthly-day
Sets days of the week the backup plan is executed.
Possible values: range 1 to 7
This parameter is used with the following parameters:
- --frequency-value=Monthly
--monthly-every
Set the value for monthly schedule. This parameter is applied with monthly schedule parameters only.
Possible values: range 1 to 12
--monthly-repeat-from
Sets the repeat every value for incremental backup.
Date format: “dd.MM.yyyy”
Applies with the --frequency-value "Monthly" value.
--full-monthly-repeat-from
Sets the repeat every value for full backup.
Date format: “dd.MM.yyyy”
Applies with the --frequency-value "Monthly" value.
--force-stop
Stops the plan execution if it runs longer than the specified period set in hours and minutes.
Possible values: no(default), "hh:mm".
Example: --force-stop “06:30”
--force-stop-full
Stops the full backup execution if it runs longer than the specified period set in hours and minutes. Possible values: no(default), "hh:mm". Example: --force-stop-full “12:00”
--detailed-report
Generates the detailed report of the backup plan execution.
Possible values:
- true
- false (default)
--notification
Sets the condition for sending notification email:
Possible values:
- on : Notification email will be sent in all cases
- off : Do not send the notification email
- error-only (default) : Notification email will be sent if backup plan fails
--subject
Sets the notification email subject.
Example: --subject “Your backup plan results”
--consistency-check
Configures the full consistency check execution. This parameter can be applied to the new backup format only.
Possible values:
- true (default)
- false
--pre-action-enabled
Enables the execution of a pre-backup action.
Possible values:
- true
- false (default)
--pre-action-command
Sets the path to the script to be executed before the backup plan start. The path must match one of the formats: “\“path/to/file\” arg1 arg2” or '"/path/to/file" arg1 arg2'
Examples:
--pre-action-command '"/home/usr/scripts.cleanup.s"'
--pre-action-command ""/home/usr/scripts.cleanup.s""
--pre-action-exitonfail
Sets the condition of the pre-backup action. Possible values: true, false. If the value is set as “true”, a backup plan is not executed if a pre-backup action fails. If the value is set “false”, backup plan is executed regardless of the pre-backup action result --post-action-enabled
Possible values:
- true
- false (default)
--post-action-command
Sets the path to the script to be executed after the backup plan is complete. The path must match one of the formats: “\“path/to/file\” arg1 arg2” or '"/path/to/file" arg1 arg2'
Examples:
--post-action-command '"/home/usr/scripts.cleanup.s"'
--post-action-command ""/home/usr/scripts.cleanup.s""
--post-action-runonfail
Sets the condition of the post-backup action.
Possible values:
- true
- false
If the value is set to "true", a post-backup action is executed regardless of the backup plan result. If the value is set to "false", post-backup action is not executed if a backup plan fails.
--full-schedule
Enables the schedule for full backup.
Possible values:
- on
- off
--full-stop-auto-option
Enables the automatic backup plan termination of a full backup.
Possible values:
- on
- off (default)
--full-stop-auto-hours-value
Sets the threshold period in hours for a full backup plan execution.
Possible values: integer, range 0-24.
--full-stop-auto-minutes-value
Sets the threshold period in minutes for a full backup plan execution.
Possible values: integer, range 0-60.
--full-specific-date-option
Runs the plan on a specific date. Applies to the current backup format only. Possible values: true, false (default)
--full-specific-date-value
Executes a full backup on a specific date and time.
Example: --full-specific-date-value “24.04.2023 12:30”
--use-recurring-option
Enables or disables the recurring schedule.
Possible values:
- true
- false *default
--full-frequency-value
Applies to the current backup format only.
Possible values:
- Daily
- Weekly
- Monthly
--full-occurs-at-option
Enables or disables the execution of a full backup on specified moment in time.
Possible values:
- true
- false
--full-occurs-at-value
Sets the time of a full backup execution.
Time on “hh:mm” format
--full-occurs-every-option
Sets the 'occurs every' option.
Possible values:
- on
- off
--full-occurs-every-value
Sets the value for 'occurs every' option for full backup schedule.
--full-occurs-every-from
Sets the time of starting a full backup.
Possible values: time on “hh:mm” format
--full-occurs-every-to
Sets the time full backup plan is executed until.
Possible values: time on “hh:mm” format
--full-week-day-numbers
Sets the days of a week full backup is executed.
Possible values: numbers of day: 1,2… (1-7)
--full-monthly-type-value
Sets the type of monthly backup execution.
Possible values: 0-6.
- If 0 is set, backup will be executed every month on the day specified by --full-monthly-day parameter.
- If values in 1-6 [First, Second, Third, Fourth, Penultimate, Last] range are set, backup will be executed every month on the specific week (e.g first week, second week, etc.) on the day specified by --full-monthly-day parameter.
--full-monthly-day
Sets the weekday a full backup is executed on.
Possible values: number of days from 1 to 7
--full-monthly-every
Sets the date to the monthly schedule of full backup executions.
Possible values: month from 1 to 12
--full-monthly-repeat-every
Sets the date to the monthly schedule of full backup executions.
Possible values: date in format “dd.MM.yyyy”