The support forum

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

BVCKUP_time_started - start time (see below)
BVCKUP_time_finished - finish time
BVCKUP_time_elapsed - elapsed time in human readable format, e.g “4 hours 16 minutes” or “13 seconds”

Start/finish time is in

        yyyy-mm-dd hh:mm:ss.mmm

format, e.g. "2014-07-19 11:22:33.444"

External commands vs. email alerts


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 -

        https://bvckup2.com/support/data/ext-cmd-pre.png
        https://bvckup2.com/support/data/ext-cmd-post.png

Type "exit" to close the window and let the backup proceed.

Service mode


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.

Apr 22, 2020

Detailed configuration


Command behavior can be configured with the following overrides:

1. Timeout

        conf.command_pre_timeout    <interval>
        conf.command_post_timeout  <interval>

For example,  "conf.command_pre_timeout  1 min".

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.

The default is 0.

3. ShowCommand

        conf.command_pre_window     <value>
        conf.command_post_window   <value>

This override controls if the command will be spawned with its window shown, hidden, minimized, etc. Available <values> are listed here, the SW_xxx constants - http://msdn.microsoft.com/en-us/library/windows/desktop/ms633548%28v=vs.85%29.aspx.

The default is SW_SHOWNORMAL.

5. Type

        conf.command_pre_type   <value>

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.

The default is "auto".

Adding an override


For how to add an override, see https://bvckup2.com/support/forum/topic/1140

New topic

Create
Made by IO Bureau in Switzerland
Support

Updates
Blog / RSS
Follow Twitter
Reddit
Miscellanea Press kit
Testimonials
Company Imprint

Legal Terms
Privacy