diff options
Diffstat (limited to 'doc/beam-module.5in')
-rw-r--r-- | doc/beam-module.5in | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/doc/beam-module.5in b/doc/beam-module.5in new file mode 100644 index 0000000..99e7a63 --- /dev/null +++ b/doc/beam-module.5in @@ -0,0 +1,187 @@ +.\" This file is part of BEAM -*- nroff -*- +.\" Copyright (C) 2012 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 "July 14, 2012" "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 insconsistent 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 DBS-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 consistend values, etc.) + +If the configuration is correct, the function shall return +.BR 0 . +Otherwise, it shall produce appropiate 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 "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: |