.\" This file is part of BEAM -*- nroff -*-
.\" Copyright (C) 2012-2014 Sergey Poznyakoff
.\"
.\" BEAM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" BEAM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with BEAM.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH BEAM\-MODULE 5 "March 19, 2014" "BEAM" "BEAM Programmer Reference"
.SH NAME
beam\-module \- format of 
.BR beam (1)
modules
.SH DESCRIPTION
This manual page explains how to write new modules for
.BR beam (1).
.PP
.B Beam
is a modular backup system written in shell.  It is mainly designed to
create incremental backups of file systems using
.BR 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
.B dump
using the DBMS-specific software, and archive the created file or files.
.PP
To handle such cases,
.B beam
introduces a special entity, called
.BR "backup item" .
.SS Backup items
A backup item is a set of data that are backed up and restored using a
particular
.BR method .
.PP
In
.B beam
configuration, backup items are identified by unique names.  The
method used to back up an item is defined by the \fIitem\fB_type\fR
configuration keyword.
.SS Modules
For each backup method, defined by \fIitem\fB_type\fR keywords,
.B beam
looks for a shell script, called \fImethod\fB.sh\fR and located in the
.B @LIBDIR@/beam
directory.
.PP
For example, if the configuration file contains:
.sp
.nf
.in +2
backup_items="cfg db"

cfg_type=fs
db_type=mysql
.in
.fi
.sp
then the following files will be loaded:

  @LIBDIR@/beam/fs.sh
  @LIBDIR@/beam/mysql.sh

.PP
These files should provide the functions used to list, back up and
restore the corresponding items.
.SH MODULE FILE FORMAT
Each module file must define the following functions (\fIname\fR
stands for the name of the module):
.TP
.BR \fIname\fB_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
.BR 0 .
Otherwise, it shall produce appropriate diagnostic messages using
.B error
or
.B abend
(see below) and return a non-zero value.

As an example, consider the
.B check
function from the
.B fs
module.  It verifies whether the two mandatory parameters,
\fIitem\fB_dir\fR and \fIitem\fB_files\fR, are defined:
.sp
.nf
.in +2
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
}
.in
.fi
.TP
.BR \fIname\fB_list( item , prefix )
Produces a listing of the
.B item
prefixed by
.B prefix .

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

The following is a simplified example from the
.B fs
module:
.sp
.nf
.in +2
fs_list() {
  local dir files
  
  eval dir=\\$${1}_dir files=\\$${1}_files
  echo "${2}Files and directories in $dir:$files"
}
.in
.fi
.TP
.BR \fIname\fB_backup( item )
This function backs up the given
.BR item .

A very simplified version from
the
.B fs
module illustrates this:
.sp
.nf
.in +2
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
}
.TP
.BR \fIname\fB_restore( item )
This function does the opposite to \fIname\fB_backup\fR: it restores
the given item from the backup.
.SH VARIABLES
Apart from the variables defined in
.BR beam.conf (5),
a module can access the following ones:
.TP
.B 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
.BR strftime (3)
conversion
.BR %U .
.TP
.B round
Number of this backup round.  See
.BR beam\-backup (1),
for a detailed discussion.
.TP
.B level
Incremental level of this backup.
.TP
.B dry_run
If the
.B dry\-run
module is enabled, the value of this variable is
.BR 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
.B dry\-run
mode.  For example:
.sp
.nf
.in +2
  $dry_run rm $dbdir/*
.in
.fi
.sp
The
.B dry\-run
mode is enabled by the
.BR \-\-dry\-run " or " \-n
option to
.BR beam\-backup (1)
and
.BR beam\-restore (1).
.TP
.B verbose
In verbose mode, the value of this variable is
.BR \-v ,
otherwise it is empty.  Most programs use the
.B \-v
option to enable the verbose mode, so this variable can be used in
constructing their command lines, e.g.:
.sp
.nf
.in +2
  $dry_run tar $verbose \-c \-f $archive .
.in
.fi
.sp
.TP
.B 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
.B tarcode
function below.
.SH FUNCTIONS
The following functions are available for use in modules:
.TP
.B logit
Writes its arguments to the selected log stream.  The resulting line
is prefixed with the current date.
.TP
.B error
Write its arguments to the standard error, prefixing the line with the
current date.
.TP
.B 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.
.TP
.B tarcode
The argument is a decimal return code from a
.BR tar (1)
invocation.  The function prints a human-readable description of the
error code and increases
.B tarerror
if it is equal to or greater than 2.
.SH "SEE ALSO"
.BR beam (1),
.BR beam.conf (5).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <@PACKAGE_BUGREPORT@>.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: