aboutsummaryrefslogtreecommitdiff
path: root/doc/beam-module.5in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/beam-module.5in')
-rw-r--r--doc/beam-module.5in187
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:

Return to:

Send suggestions and report system problems to the System administrator.