Article ID: m0571Last Modified: 29-Sep-2024

Image-Based Backups

Use CLI to create and customize image-based backup and restore plans.

Create a Backup Plan

Use the addBackupIBBPlan command to create and configure a new image-based backup plan.

C:\Program Files\MyCompany\Online Backup\cbb addBackupIBBPlan -?

Mandatory Parameters

The following parameters are required to execute the addBackupIBBPlan command.

  • -n Specifies the backup plan name

  • -a or -aid. Specifies the name or ID of a storage account to where to upload your backups.

  • -r, ****or -av, or -v Specifies the disk volumes to back up.

The following command creates an image-based backup plan that includes only system-required disk volumes.

cbb addBackupIBBPlan -a "account" -n "plan_name" -r

The following command creates an image-based backup plan that includes all available disk volumes.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av

The following command creates an image-based backup plan that includes a specified disk volume.

cbb addBackupIBBPlan -a "account" -n "plan_name" -v "58a6f458-8948-4ad7-aea7-a7ade7aba85e"

You can obtain a disk volume's ID to specify the "-v" parameter by copying the WindowsVolumeIdentity value returned by the listDiskVolumes command.

Alternatively, you can execute the addBackupIBBPlan command with a "-clonePlan" parameter to create a copy of an existing plan. For example:

cbb addBackupIBBPlan -clonePlan "existing_plan_name" -n "new_plan_name"

Optional Parameters

You can use the following parameters to configure your backup plan.

  • -useBlockLevelBackup

    Set this parameter to "no" to disable a block-level backup.

    When this option is enabled, which is the default setting for newly created image-based backups, you can schedule a full backup.

  • -c
    Indicates whether or not to compress the data in the backup (the default value is "yes"). For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -c no

    This can speed up uploading of your backup while it takes longer to process it before uploading.

  • -ea and -ep
    Encrypts the backup's contents using a specified algorithm (AES128, AES192 or AES256) and protects the backup with a password. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -ea "AES192" -ep "password"

    When updating an existing file-level backup that was not previously encrypted, the encryption will only apply to the newly uploaded files.

  • -sse
    Enables server-side encryption of the backup's contents (if a storage provider supports this feature).
    For example:

    cbb addBackupIBBPlan -a "Amazon_S3_account" -n "plan_name" -av -sse yes

  • -sia
    When using an Amazon storage account, enables an S3 Standard-Infrequent Access storage class.
    For example:

    cbb addBackupIBBPlan -a "Amazon_S3_account" -n "plan_name" -av -sia yes

  • -useSystemVss
    Forces the Backup Agent to use the system default VSS (Volume Shadow Copy Service) provider. Use this option when there are any third-party VSS providers installed on the system that may interfere with the proper processing of VSS snapshots by the Backup Agent. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -useSystemVss yes

  • -disableVss
    Disables Volume Shadow Copy Service (VSS), which may be required when a disk is not used for writing operations and has not enough space to create a VSS snapshot (typically, this is the case with system volumes). When this option is enabled, direct access to NTFS volumes is used instead. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -disableVss yes

  • -ignoreBadSectors
    Enable this option to allow the recovery process to complete after encountering any damaged sectors on a disk drive. After restoring such a volume, bad sectors will become empty sectors and you will not be able to read any files that were using them. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -ignoreBadSectors yes

  • -prefetchBlockCount
    Specifies the maximum number of blocks that Backup Agent can store in memory for each disk volume. This value should be within a 0 - 100 range, with a zero value indicating that prefetch is not used. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -prefetchBlockCount 0

    A block is a minimum unit of information that Backup Agent can process at a time when preparing a backup.

    When you need to perform a block-level backup over a disk containing several terabytes of data, you can speed up the backup processing by increasing the block size (see below).

  • -blockSize
    Specifies the amount of data Backup Agent can process at a time, in kilobytes. Supported values: "128", "256", "512", or "1024". For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -blockSize 512

  • -sp
    Indicates whether or not to save the backup plan configuration to the backup storage along with the backup's contents. For example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -sp yes

Executing Custom Scripts

Use the following parameters to execute custom scripts before and/or after running a backup plan.

  • -preAction Specifies a command to execute before launching the backup.
  • -pac Indicates whether or not the backup service should continue backup processing if the pre-backup action failed.
  • -postAction Specifies a command to execute after completing the backup.
  • -paa Indicates whether or not the backup service should execute the post-backup action regardless of the backup processing result.

The following command creates a plan and specifies custom scripts to be executed before and after running this plan.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -preAction "C:\_Temp\script.cmd /F:ON /C" -pac yes -postAction "PowerShell.exe Start-Process cmd.exe exit" -paa no

Customizing Email Notification Settings

Use the following parameters to specify how the backup service should deliver email notifications after executing your backup plan and maintain the service log.

  • -notification Specifies whether to send email notifications only when a backup fails ("errorOnly") or in all cases ("on").
  • -winLog Indicates whether to add an entry to Windows Event Log only when the backup fails ("errorOnly") or in all cases ("on").

The following example illustrates how you can use these parameters.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -notification "errorOnly" -winLog "on"

Customizing Retention Settings

Use the following options to configure the retention settings of your backup plan.

  • -purge Makes a backup service delete file versions that were modified or uploaded to your backup storage more than a certain number of days ago. The following values are supported:
    • "no" - indicates that data is stored for an indefinite period.
    • "d (day)" - specifies how many days to store your data.
    • "w (week)" - specifies how many weeks to store your data.
    • "m (month)" - specifies for how many months to store your data.
  • -delayPurge Specifies the maximum number of versions that a backup service should keep in the storage for each file. The following values are supported:
    • "no" - enables immediate removal of files after they have been deleted in source storage.
    • "d (day)" - specifies how many days to keep locally deleted files in the backup storage.
    • "w (week)" - specifies for how many weeks to keep locally deleted files in the backup storage.
    • "m (month)" - specifies how many months to keep locally deleted files in the backup storage.
  • -keep Specifies the maximum number of versions that a backup service should keep in the storage for each file.
  • -keepLastVersion Indicates whether to keep the last version of each file in a backup storage at all times, regardless of any other retention settings.

The following example illustrates how you can specify these parameters.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -purge 1week -delayPurge 1week -keep 5 -keepLastVersion yes

Customizing Scheduling Settings

Use the following parameters to enable your backup plan to run automatically on schedule.

  • -at

    Specifies the time at which the backup plan should run. When other scheduling parameters are not defined, specifying only the time indicates that the backup plan should run at this time on the day of this plan's creation.

    This parameter is required if you need to run your backup plan on a recurrent basis and specify corresponding scheduling options described below.
    Instead of using the "-at" parameter, you can use the "-occurs" parameter (see below) to run the backup plan once in a specified number of hours or days.

    You can specify both the date and time if you do not need to run your backup plan on a recurring basis, for example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -at "5/28/2018 6:00 PM"

  • -every Enables you to run the backup plan on a recurring basis. The following values are supported:

    • "day"
      Enables running the backup plan every day. For example:

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -at "6:00 PM" -every day

    • "week"
      Enables running the backup plan every week. Use the "-weekday" parameter to specify one or more weekdays. For example:

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -at "6:00 PM" -every week -weekday "su, mo"

    • "month"
      Enables running the backup plan on a monthly basis. When no additional parameters are specified, the backup plan will run every month on the first Sunday by default. You can use the "-weekNumber" and "-weekday" parameters to specify a custom monthly schedule. For example, the following plan will be executed on the third Monday of every month.

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -at "6:00 PM" -every month -weekNumber "third" -weekday "mo"
      • The following values are supported for the "-weekNumber" parameter: "first", "second", "third", "fourth", "penultimate", "last".
      • The following values are supported for the "-weekday" parameter: "su", "mo", "tu", "we", "th", "fr", "sa".

  • "dayOfMonth" Not supported.

  • -occurs
    When the "-every" parameter is set to "day" (see above), indicating that the backup plan should run on a daily basis, you can make the backup plan run once in a certain number of hours or days within a specified time period by using the "-occurs" parameter instead of "-at".

If the "-every" parameter is set to "day", specifying both the "-occurs" and "-at" parameters at once will result in an error.

The following values are supported for the "-occurs" parameter:

  • "day" - enables running the backup plan once in a specified number of days.
  • "hour" - enables running the backup plan once in a specified number of hours.

After specifying this parameter, use the "-occurValue" parameter to specify how many hours or days should pass before each run.

In addition, you can use the "-dailyFrom" and "-dailyTill" parameters to specify the time range within which the recurrence should take effect. These parameters accept a time-span value in the following format: "dd.hh:mm:ss".

The following example illustrates how to make a backup plan run every two hours between 6:00 AM and 6:00 PM every day.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -every day -occurs hour -occurValue 2 -dailyFrom "00.06:00:00" -dailyTill "00.18:00:00"
  • -runMissed Set this parameter to "yes" to make the backup plan run automatically when computer starts up if a scheduled run was missed for any reason.

Scheduling a Full Backup

When the "-useBlockLevelBackup" parameter is set to "yes" (see above), indicating that block-level backup is enabled, which is the default setting for newly created image-based backups, we recommend that you force a full backup on schedule by using the parameters described below. The full backup's schedule is independent from the general scheduling options defined for a backup plan.

  • -atForceFull
    Similar to the "-at" parameter of a general schedule, this parameter specifies the time at which a full backup should run. When other scheduling parameters are not defined, specifying only the time indicates that a full backup should run at this time on the day of this plan's creation.

    This parameter is required if you need to run a full backup on a recurrent basis and specify corresponding scheduling options described below.

    Instead of using the "-atForceFull" parameter, you can use the "-occursForceFull" parameter (see below) to run a full backup once in a specified number of hours or days.

    You can specify both the date and time if you do not need to run a full backup plan on a recurring basis, for example:

    cbb addBackupIBBPlan -a "account" -n "plan_name" -av -atForceFull "4/28/2018 6:00 PM"

  • -everyForceFull Enables you to run a full backup on a recurring basis. The following values are supported:

    • "day"
      Enables running a full backup every day. For example:

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -atForceFull "6:00 PM" -everyForceFull day

    • "week"
      Enables running a full backup every week on a specified weekday. Use the "-weekdayForceFull" parameter to specify one or more weekdays. For example:

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -atForceFull "6:00 PM" -everyForceFull week -weekdayForceFull "su, mo"

    • "month"
      Enables running a full backup on a monthly basis. When no additional parameters are specified, the full backup will run every month on the first Sunday by default. You can use the "-weekNumberForceFull" and "-weekdayForceFull" parameters to specify a custom monthly schedule. For example, the following full backup will run on every third Monday of every month .

      cbb addBackupIBBPlan -a "account" -n "plan_name" -av -atForceFull "6:00 PM" -everyForceFull month -weekNumberForceFull "third" -weekdayForceFull "mo"
      • The following values are supported for the "-weekNumberForceFull" parameter: "first", "second", "third", "fourth", "penultimate", "last".
      • The following values are supported for the "-weekdayForceFull" parameter: "su", "mo", "tu", "we", "th", "fr", "sa".

  • "dayOfMonth" Not supported.

  • -occursForceFull
    When the "-everyForceFull" parameter is set to "day" (see above), indicating that a full backup should run on a daily basis, you can make the full backup run once in a certain number of hours or days within a specified time period by using the "-occursForceFull" parameter instead of "-atForceFull".

If the "-everyForceFull" parameter is set to "day", specifying both the "-occursForceFull" and "-atForceFull" parameters at once will result in an error.

The following values are supported for the "-occursForceFull" parameter:

  • "day" - enables running a full backup once in a specified number of days.
  • "hour" - enables running a full backup once in a specified number of hours.

After specifying this parameter, use the "-occurValueForceFull" parameter to specify how many hours or days should pass before each run.

In addition, you can use the "-dailyFromForceFull" and "-dailyTillForceFull" parameters to specify the time range within which the recurrence should take effect. These parameters accept a time-span value in the following format: "dd.hh:mm:ss".

The following example illustrates how to make a full backup run every two hours between 6:00 AM and 6:00 PM every day.

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -everyForceFull day -occursForceFull hour -occurValueForceFull 2 -dailyFromForceFull "00.06:00:00" -dailyTillForceFull "00.18:00:00"

Additional Options

Use the "-tag" parameter to specify custom additional information for your backup plan. For example:

cbb addBackupIBBPlan -a "account" -n "plan_name" -av -tag "Custom info"

The following parameters define the standard output format for this command.

  • -json Send the status to stdout in a JSON format.
  • -xml Send the status to stdout in an XML format.
  • -output Specifies the output format: "short" or "full" (the default value).

Edit a Backup Plan

Use the editBackupIbbPlan command to customize an existing image-based backup plan.

C:\Program Files\MyCompany\Online Backup\cbb editBackupIbbPlan -?

The following example illustrates how to rename a backup plan.

cbb editBackupIbbPlan -n "old_name" -nn "new_name"

See the previous section of this document to learn about other parameters available for editing a backup plan using the editBackupIbbPlan command.

Manage Image-Based Backups

You can use the listIbbContent command to obtain information about disks and disk volumes available in your backups.

C:\Program Files\MyCompany\Online Backup\cbb listIbbContent -?

Mandatory Parameters

The following parameters are required to execute the listIbbContent command.

  • -a or -aid
    Specifies the name or ID of a storage account where your image-based backups are stored.

    You can execute the "cbb account -list" command to obtain information about the storage accounts available in the Backup Agent.

The following image illustrates a result of executing the listIbbContent command.

Optional Parameters

You can use the following parameters to obtain information about disks and disk volumes available in your backups.

  • -listVolumes
    Use this parameter to obtain information about disk volumes available in each of your image-based backups. The following image illustrates the result of executing the listIbbContent command with the "-listVolumes" parameter.

  • -bp
    Enables you to obtain information about disks and disk volumes available in a bucket/container corresponding to a specified backup prefix (it is set to a computer name by default).

    You can list backup prefixes available in a specified storage by executing the cbb prefixes command.

    For example:

    cbb listIbbContent -a "account" -bp "PC_name"

  • -r (-systemRequired)
    Use this parameter to list only system-required disk volumes. For example:

    cbb listIbbContent -a "account" -systemRequired

  • -d (-diskID)
    Specifies the disk ID (GUID) whose volumes you would like to list. For example:

    cbb listIbbContent -a "account" -diskID "c5117cb2-8a50-48a1-b8b0-8bc3aa5077fd"

  • -rt (-restoreType) and -rpt
    Specifies whether to list information related to image-based backups that store the latest version of disk images that are available in a specified backup storage at this moment (when this parameter is set to "LatestVersion"), or to list image-based backups that store a latest version available at a specific point in time (when this parameter is set to "PointInTime").

    When the "-rt" parameter is set to "PointInTime", you should specify the "-rpt" parameter as well, indicating a required point in time. For example:

    cbb listIbbContent -a "account" -rt PointInTime -rpt "4/27/2018 3:00:00 PM"

Additional Options

The following parameters define the standard output format for this command.

  • -json Send the status to stdout in a JSON format.
  • -xml Send the status to stdout in an XML format.
https://git.cloudberrylab.com/egor.m/doc-help-mbs.git