Extending vbackup

If you’re interested in extending vbackup then read below and have a look at the existing modules (I recommend mount and tar/xfsdump). A template for new modules is available with the name ‘skel’ under the scripts/ directory of the source code.

If you believe you’ve created something that will be useful for others too, I’ll be glad to include it in the distribution (preserving your copyright of course)

File tree

The installation layout should comply with the latest FHS (2.3 as of Nov 2006). Everything different than that should be reported as bug.

${bindir}/                     The vbackup program

${sysconfdir}/
       vbackup/
               rc.d/           Backup configurations
               backup.daily/   Links to appropriate rc.d scripts
                       vbackup.conf    Per backup global configuration file
               backup.weekly/  ....
               backup.monthly/ ....

${datadir}/
       vbackup/
               bin/            Core scripts (run) used by vbackup
                               (They are standalone scripts)
               helpers/        Helper scripts (not standalone)
               scripts/        The backup scripts
               wizard/         Wizard configuration files
               samples/        Sample configurations. Also used for --rc

${docdir}/
       vbackup/                Documentation

Backup scripts

Each backup script must provide:

Functions

do_help()
A function to display help and return
do_check_conf()

Check whether all configuration variables are ok

Return: 0: OK, 1: Error

May display error messages

do_run()
Do the backup

Variables

NAME The script name (“psql”)
VERSION The script version (“1.0.0”)
DESC A short description (“Backup a postgresql database”)
COPYRIGHT Copyright (“Copyright (c) 2006 Harhalakis Stefanos”)
LICENCE The license of the script (“GPLv2”)
CONTACT A contact email for bugreports etc (“v13@v13.gr”)

It may expect

  • If the configuration file includes a DESTDIR options, it will be prepended with the DESTDIR0 prefix. It will also be transformed by changing %X% variables (for example %D1%)
  • A variable named ABORT is set to 1 if a script previously exited with error code 2 (see below). Most scripts should abort with exit code 0 when they detect this. For example: a script that checks for free space may exit with error code 2. The ABORT variable will be set automatically. All backup scripts must detect this and do nothing. The umount script will ignore this and actually try to umount the directory.
  • A variable named LEVEL that indicates the backup level as passed to the vbackup command.
  • A variable named STRATEGY that indicates the strategy as passed to the vbackup command. This will be empty if no strategy was specified.
  • A variable named STATEDIR that points to a script-specific directory to store state. Note that the directory may not exist. If needed, the script should use h_ensuredir to create the directory

It must return (from each function)

0 Everything were OK
1 Error occurred - continue backups
2 Error occurred - abort backup sequence
3 Error occurred - force abort of backup sequence

Notes:

  • When a script returns 2, the flag ABORT is set to 1. This is checked by backup scripts and they will not do anything at all. Scripts like umount may ignore this and umount the directory
  • When a script returns 3, the backup is immediately aborted. This should be used by scripts like mount

Configuration files:

Some configuration files may include a DESTDIR directive. For example, ‘%D1%’ which will be replaced by YYMMDD of the current date E.g.: /tmp/backups/filesystem/%D1% will be converted to: /tmp/backups/filesystem/061117 (as of 17 Nov 2006)

The following special sequences are recognised:

%D0% Day of the week (1-7). 1 is Monday
%D1% YYMMDD of the current date
%D2% YYMMDDHH
%D3% YYMMDDHHMM
%L% The backup level

Configuration directives:

Configuration directives should preserve the same name across scripts when possible. Common directives are (using regexp):

DESTDIR Where to backup to
DATABASES The databases to backup, for DB backups
PASSWORD To hold a password
.*USER To hold a username (examples: PGUSER, MYUSER etc..)

NOTE! The directive USER should never be used. I repeat NEVER USE THE USER DIRECTIVE! Same thing applies for other well known directives that may be set by sh/bash.

Common configuration variables:

Common configuration variables are variables that are set in vbackup.conf or in other configuration files. The vbackup.conf entry is the main one but it may be overridden by individual configuration files.

COMPRESS Whether to compress the backup or not (yes/no, on/off, 1/0)

Sample files:

Sample configuration files are parsed by vbackup when “–rc –add” is used. The configuration files are parsed using the following logic:

  • Ignore all comments lines from the top of the file until an empty line is found
  • If in the above block of comments there’s a line ‘## No autoconfig’ then the ‘–rc –add’ will just copy the file and not try to autoconfigure it. This is useful for example in the case of the exec plugin.
  • All files of the sample configuration file end up in the target configuration file. This means that all comments and empty lines will be copyied over there.
  • Look for blocks of directives. All blocks are assumed to have some comments followed by one or more configuration directives.
  • All the comments of a block will be displayed to the user. Only lines that start with ‘# ‘ (hash and a space) are assumed to be comments.
  • When a line that doesn’t start with ‘# ‘ is found then it’s interpreted as a configuration directive.
  • If the line start with # (e.g: #DESTDIR=”test”) then it is assumed not to have a default value. However, a line of text will be displayed to the user saying: “Sample value: test”.
  • If the line doesn’t start with # (e.g: DESTDIR=”test”) then it is assumed that the value is the default value. It will be presented both as a sample line and as default value. If the user presses enter then he will use that value.

Wizard:

Inside the wizard dir, each script may place a configuration file. This file will describe a wizard step for initial configuration creation.

Each wizard configuration file includes:

NAME="the name of the configuration script"
PRI="Priority of configuration file"
w_do_ask()

A function that will be called to ask for configuration parameters. This function may be called multiple times to answer different questions. The first argument mandates the question to me asked Initialy, this function is called with “ENABLE” as the first argument. All capital letter names should be reserved for vbackup usage. This function must set the variable ASK_NEXT to “” whenever the series of questions is finished, or to a name that will be passed as the first argument to the next function call.

The last function call must return 0 to indicate that this method is active or 1 to indicate that it is not

Example call tree:

  • do_ask ENABLE ==> Set ASK_NEXT=path
  • do_ask path ==> Set ASK_NEXT=level
  • do_ask level ==> Set ASK_NEXT=””, return code=0
  • finished asking questions, method is enabled

This function may also write to the temporary file $CFG:

echo 'DIRS="/tmp"' >> $CFG
echo '# Comment' >> $CFG

This file will be available when w_get_config() is called. Typically, this should contain the majority of the configuration options except maybe from static options.

w_get_config()
A function that should print to its stdout the configuration file.