Pre- and post-backup commands

Apr 22, 2020

Overview

It is possible to execute arbitrary commands at the very start and at the very end of a backup run. These can be configured in the More Options section of Backup Settings window.

Pre/post-backup commands allow customizing both the logic and the flow of every backup. They can be used to cancel backups if certain condition is not met, to mount volumes before the backup, to rearrange things after a backup, to feed events and alerts into existing management systems, etc.

Commands can be either a regular program

c:\path\abc.exe --flags --options 123

a batch file

c:\path\abc.bat

or something else that can be executed by invoking shell rather than by spawning a process (see below).

Default behavior

By default, the program will wait for both commands to complete before proceeding with the backup, but timing out after 1 hour.

All aspects of this behavior are configurable - it's possible to change the timeout, make the program launch the command and continue with the backup immediately, cancel the backup if the command doesn't exit with a specific code, etc.

Environment variables

Details of the backup state and configuration are passed to the commands with a set of environment variables that are set up by the program.

Variable names start with BVCKUP_ and they cover Environment, Program details, Backup configuration and Backup status.

For example -

BVCKUP_src - the source location
BVCKUP_dst - the destination
BVCKUP_description - the description
BVCKUP_run - the run number of the backup
BVCKUP_state - the state of the backup and it is set to "Initializing" for pre-backup command, and to one of "Cancelled", "Completed", "Failed" for the post-backup command. The "failed" backup run is the one that did not manage to get to the actual backup phase and failed during the preparation (scanning/planning/etc) phase.

Some variables are valid only for a post-backup command as they capture the _results_ of a backup run, e.g. -

BVCKUP_errors - the number of errors encountered by the backup

BVCKUP_stats_files_created - self-explanatory
BVCKUP_stats_files_updated - self-explanatory
BVCKUP_stats_files_deleted - self-explanatory
BVCKUP_stats_files_moved - self-explanatory
BVCKUP_stats_bytes_read - how much data was read from the disk
BVCKUP_stats_bytes_written - how much was written out

The variable set used for email alerts is almost exactly as the set used for external commands. The only difference is that the latter prefixes all variable names with BVCKUP_. See https://bvckup2.com/support/forum/topic/473 for additional information on email alerts.

Testing

There's over 80 different variables and a good way to get a feel of how this all works is to set both commands to

cmd /k set

This will simply open a command line window and run "set" command that dumps the environment variables. You should see something like this -

Commands are spawn by the engine, so running "cmd /k" in a service mode will simply cause the backup to stall for an hour. That's because the shell window will be opened on a desktop of a service user account and will not be visible.

Timeout can also be set to "0 sec", in which case the program will not wait for the command at all.

2. Critical / ReturnCode

conf.command_pre_crit <value>
conf.command_pre_rc <rc>

conf.command_post_crit <value>
conf.command_post_rc <rc>

<value> of 0 will cause the program to merely log command's exit code and proceed with the backup unconditionally.

<value> of 1 will cause the program to log an error if the command's exit code is different from <rc> and then abort the backup.

<value> of 2 is applicable to pre-backup command only and it will cause the program to gracefully cancel the backup if the command's exit code is different from <rc>. This is meant to allow for NOT running a backup if certain external conditions are not met.

This override controls if the command is launched by creating a process or via the Windows shell.

<value> of 1 is to create a process.

<value> of 2 is to use shell, just as if the command is typed into Windows-R prompt.

<value> of 3 is "auto", meaning that the program looks at the command and if it specifies an existing file that ends with ".bat", then it uses the shell method. Otherwise it goes with the process option.