diff options
Diffstat (limited to 'doc/beam-module.5in')
| -rw-r--r-- | doc/beam-module.5in | 278 |
1 files changed, 0 insertions, 278 deletions
diff --git a/doc/beam-module.5in b/doc/beam-module.5in deleted file mode 100644 index 9ba239f..0000000 --- a/doc/beam-module.5in +++ /dev/null @@ -1,278 +0,0 @@ -.\" 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: |