BEAM-MODULE

NAME
DESCRIPTION
MODULE FILE FORMAT
VARIABLES
FUNCTIONS
SEE ALSO
AUTHORS
BUG REPORTS

NAME

beam-module - format of beam(1) modules

DESCRIPTION

This manual page explains how to write new modules for beam(1).

Beam is a modular backup system written in shell. It is mainly designed to create incremental backups of file systems using tar(1), and restore from such backups. However, there are special kinds of data that cannot be reliably backed up using this method. An example of these are SQL databases. Simply archiving the database files while the database engine is running is not likely to produce a reliable backup - such files will most probably be in inconsistent state, because of eventual transactions not being finished at the time of the backup. While stopping the database for the duration of the backup could produce a consistent backup, it is usually not an option. The obvious solution in this case is to create a database dump using the DBMS-specific software, and archive the created file or files.

To handle such cases, beam introduces a special entity, called backup item.

Backup items
A backup item is a set of data that are backed up and restored using a particular method.

In beam configuration, backup items are identified by unique names. The method used to back up an item is defined by the item_type configuration keyword.

Modules
For each backup method, defined by item_type keywords, beam looks for a shell script, called method.sh and located in the /usr/local/lib/beam directory.

For example, if the configuration file contains:

backup_items="cfg db"

cfg_type=fs
db_type=mysql

then the following files will be loaded:

/usr/local/lib/beam/fs.sh
/usr/local/lib/beam/mysql.sh

These files should provide the functions used to list, back up and restore the corresponding items.

MODULE FILE FORMAT

Each module file must define the following functions (name stands for the name of the module):
name_check(item)

This function is called once for each backup item before starting backup or restore. Its purpose is to check whether the configuration for that particular item is correct (e.g. whether all the mandatory configuration keywords are defined and have consistent values, etc.)

If the configuration is correct, the function shall return 0. Otherwise, it shall produce appropriate diagnostic messages using error or abend (see below) and return a non-zero value.

As an example, consider the check function from the fs module. It verifies whether the two mandatory parameters, item_dir and item_files, are defined:

fs_check() {
local rc=0 root files

eval root=\$${1}_dir
eval files=\$${1}_files

test -z "$root" && rc=1 && error "${1}_dir not set"
test -z "$files" && rc=1 && error "${1}_files not set"
return $rc
}

name_list(item,prefix)

Produces a listing of the item prefixed by prefix .

This function is used by the beam list command (see beam-list(1)).

The following is a simplified example from the fs module:

fs_list() {
local dir files

eval dir=\$${1}_dir files=\$${1}_files
echo "${2}Files and directories in $dir:$files"
}

name_backup(item)

This function backs up the given item.

A very simplified version from the fs module illustrates this:

fs_backup() {
local basename text root files exclude addopts s e

basename=$1-$week-$round-$level
eval dir=\$${1}_dir files=\$${1}_files

$dry_run tar $verbose $taroptions \
-f $backup_archive_dir/$basename.$tar_suffix \
--listed=$backup_snapshot_dir/$basename.db \
-C $dir $files
}

name_restore(item)

This function does the opposite to name_backup: it restores
the given item from the backup.

VARIABLES

Apart from the variables defined in beam.conf(5), a module can access the following ones:

	week		Number of the current week in year, as a two-digit decimal number in the range 01 to 53. Weeks are numbered starting with the first Sunday as the first day of week 01. For more details, see strftime(3) conversion %U.
	round		Number of this backup round. See beam-backup(1), for a detailed discussion.
	level		Incremental level of this backup.

dry_run

If the dry-run module is enabled, the value of this variable is echo, otherwise it is empty. Place this variable in front of a shell command to ensure it will be printed, but not executed when in dry-run mode. For example:

$dry_run rm $dbdir/*

The dry-run mode is enabled by the --dry-run or -n option to beam-backup(1) and beam-restore(1).

verbose

In verbose mode, the value of this variable is -v, otherwise it is empty. Most programs use the -v option to enable the verbose mode, so this variable can be used in constructing their command lines, e.g.:

$dry_run tar $verbose -c -f $archive .

tarerror

Keeps the number of errors that occurred so far. Increase this variable when an error occurred, that cannot be fixed automatically by the module. See also the tarcode function below.

FUNCTIONS

The following functions are available for use in modules:

	logit		Writes its arguments to the selected log stream. The resulting line is prefixed with the current date.
	error		Write its arguments to the standard error, prefixing the line with the current date.
	abend		This function takes 2 or more arguments. The first argument is a decimal number, treated as the shell exit code. The rest of arguments supplies a diagnostic message. The function writes that message to the standard error, and returns the supplied code to the shell.

tarcode

The argument is a decimal return code from a tar(1) invocation. The function prints a human-readable description of the error code and increases tarerror if it is equal to or greater than 2.

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org.ua>.

Manpage server at man.gnu.org.ua.