From f0de8b85bf7fde9d0214428330c31056c30528c5 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sat, 14 Jul 2012 22:09:59 +0300 Subject: Update the docs. * beam.conf: Set PATH * doc/.gitignore: Add new generated files. * doc/Makefile.am: Build and install beam-list.1 and beam-module.5. * doc/beam-backup.1in: Update. * doc/beam-list.1in: New file. * doc/beam-module.5in: New file. * doc/beam-restore.1in: Update. * doc/beam.1in: Update. * .gitignore: Update. --- .gitignore | 5 +- beam.conf | 3 + doc/.gitignore | 4 ++ doc/Makefile.am | 32 ++++++++- doc/beam-backup.1in | 17 +++-- doc/beam-list.1in | 74 ++++++++++++++++++++ doc/beam-module.5in | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/beam-restore.1in | 17 +++-- doc/beam.1in | 11 ++- 9 files changed, 332 insertions(+), 18 deletions(-) create mode 100644 doc/beam-list.1in create mode 100644 doc/beam-module.5in diff --git a/.gitignore b/.gitignore index acaa165..9124b80 100644 --- a/.gitignore +++ b/.gitignore @@ -10,7 +10,10 @@ Makefile.in TAGS aclocal.m4 autom4te.cache +beam +beam.sh build-aux +cleaner.sh config.h config.h.in config.log @@ -20,7 +23,7 @@ core list.sh backup.sh restore.sh -s3mount.sh +s3.sh build.sed *.tar.* tmp diff --git a/beam.conf b/beam.conf index f416088..cc8be64 100644 --- a/beam.conf +++ b/beam.conf @@ -9,6 +9,9 @@ echo >&2 "$0: WARNING: using default configuration boilerplate" # "beam restore --dry-run". # For a detailed descriptions of these commands, see beam(1). +PATH=/usr/sbin:$PATH +export PATH + ########################################################################## # Hooks ########################################################################## diff --git a/doc/.gitignore b/doc/.gitignore index b46e6f4..8b50b90 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,5 +1,9 @@ +beam.1 +beam-cleaner.1 beam-backup.1 beam-restore.1 beam-cleanup.1 +beam-list.1 beam-s3.1 beam.conf.5 +beam-module.5 diff --git a/doc/Makefile.am b/doc/Makefile.am index 8a8e045..334b315 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,13 +1,39 @@ if COND_S3MOUNT S3=beam-s3.1 endif -man_MANS = beam.1 beam.conf.5 beam-backup.1 beam-restore.1 beam-cleaner.1 $(S3) +man_MANS = \ + beam.1\ + beam.conf.5\ + beam-backup.1\ + beam-restore.1\ + beam-list.1\ + beam-cleaner.1\ + beam-module.5\ + $(S3) beam.1: beam.1in Makefile beam-backup.1: beam-backup.1in Makefile beam.conf.5: beam.conf.5in Makefile beam-restore.1: beam-restore.1in Makefile +beam-list.1: beam-list.1in Makefile beam-s3.1: beam-s3.1in Makefile beam-cleanup.1: beam-cleanup.1in Makefile -EXTRA_DIST=beam.1in beam-backup.1in beam-restore.1in beam.conf.5in beam-cleaner.1 beam-s3.1in -CLEANFILES=beam.1 beam.conf.5 beam-backup.1 beam-restore.1 beam-s3.1 beam-cleanup.1 +beam-module.5: beam-module.5in Makefile +EXTRA_DIST=\ + beam.1in\ + beam-backup.1in\ + beam-restore.1in\ + beam-list.1in\ + beam.conf.5in\ + beam-cleaner.1\ + beam-module.5in\ + beam-s3.1in +CLEANFILES=\ + beam.1\ + beam.conf.5\ + beam-backup.1\ + beam-restore.1\ + beam-list.1\ + beam-module.5\ + beam-s3.1\ + beam-cleanup.1 include $(top_srcdir)/Make.rules diff --git a/doc/beam-backup.1in b/doc/beam-backup.1in index 162c522..83d1ab5 100644 --- a/doc/beam-backup.1in +++ b/doc/beam-backup.1in @@ -14,19 +14,22 @@ .\" You should have received a copy of the GNU General Public License .\" along with BEAM. If not, see . .\" -.TH BEAM-BACKUP 1 "June 1, 2012" "BEAM" "BEAM User Reference" +.TH BEAM-BACKUP 1 "July 14, 2012" "BEAM" "BEAM User Reference" .SH NAME beam-backup \- create a back up. .SH SYNOPSIS -.B beam backup -[\fB\-h\fR] [\fB\-\-help\fR] - .B beam backup [\fB\-vnN\fR] [\fB\-\-verbose\fR] [\fB\-l\fR \fIFILE\fR]\ [\fB\-\-logfile\fR \fIFILE\fR]\ [\fB\-\-dry\-run\fR] [\fB\-L\fR \fIN\fR] [\fB\-\-level\fR \fIN\fR] [\fB\-R\fR \fIN\fR] [\fB\-\-round\fR \fIN\fR] [\fB\-\-week\fR \fIN\fR] + +.B beam backup +[\fB\-h\fR] [\fB\-\-help\fR] + +.B beam backup +[\fB\-V\fR] [\fB\-\-version\fR] .SH DESCRIPTION The .B beam-backup @@ -193,12 +196,14 @@ necessary to handle that particular item type. .TP .BR @LIBDIR@/beam/common.sh Settings and definitions shared between -.BR beam-backup +.BR beam-backup , +.BR beam-restore (1), and -.BR beam-restore (1). +.BR beam-list (1). .SH "SEE ALSO" .BR beam (1), .BR beam-restore (1), +.BR beam-list (1), .BR beam.conf (5). .SH AUTHORS Sergey Poznyakoff diff --git a/doc/beam-list.1in b/doc/beam-list.1in new file mode 100644 index 0000000..7acb95a --- /dev/null +++ b/doc/beam-list.1in @@ -0,0 +1,74 @@ +.\" 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 . +.\" +.TH BEAM-LIST 1 "July 14, 2012" "BEAM" "BEAM User Reference" +.SH NAME +beam-list \- list items included in backup +.SH SYNOPSIS +.B beam list +[\fB\-l\fR] [\fB\-\-number\fR] + +.B beam list +[\fB\-h\fR] [\fB\-\-help\fR] + +.B beam list +[\fB\-V\fR] [\fB\-\-version\fR] +.SH DESCRIPTION +The command +.B beam list +produces a list of items included in the backup. +.SH OPTIONS +.TP +.BR \-l , \-\-number +Produce a numbered list. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display a short help summary. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display program version. +.SH FILES +.TP +.BR @SYSCONFDIR@/beam.conf +Default configuration file. +.TP +.BR @LIBDIR@/beam +Backup module directory. Whenever a beam item of type \fBT\fR is +requested, \fBbeam\fR will attempt to load from this directory a +file named \fBT.sh\fR. This file provides methods and definitions +necessary to handle that particular item type. +.TP +.BR @LIBDIR@/beam/common.sh +Settings and definitions shared between this command, +.BR beam-backup (1) +and +.BR beam-restore (1). +.SH "SEE ALSO" +.BR beam (1), +.BR beam-restore (1), +.BR beam-backup (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: 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 . +.\" +.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: diff --git a/doc/beam-restore.1in b/doc/beam-restore.1in index 4d52656..59c5069 100644 --- a/doc/beam-restore.1in +++ b/doc/beam-restore.1in @@ -14,13 +14,10 @@ .\" You should have received a copy of the GNU General Public License .\" along with BEAM. If not, see . .\" -.TH BEAM-RESTORE 1 "June 1, 2012" "BEAM" "BEAM User Reference" +.TH BEAM-RESTORE 1 "July 14, 2012" "BEAM" "BEAM User Reference" .SH NAME beam-restore \- restore file system from a backup. .SH SYNOPSIS -.B beam restore -[\fB\-h\fR] [\fB\-\-help\fR] - .B beam restore [\fB\-cntv\fR] [\fB\-\-confirm\fR] [\fB\-C\fR \fIDIR\fR]\ [\fB\-\-directory\fR \fIDIR\fR] [\fB\-\-verbose\fR] @@ -28,6 +25,12 @@ beam-restore \- restore file system from a backup. [\fB\-L\fR \fIN\fR] [\fB\-\-level\fR \fIN\fR] [\fB\-R\fR \fIN\fR] [\fB\-\-round\fR \fIN\fR] [\fB\-\-week\fR \fIN\fR] [\fBITEM\fR [\fBITEM\fR...]] + +.B beam restore +[\fB\-h\fR] [\fB\-\-help\fR] + +.B beam restore +[\fB\-V\fR] [\fB\-\-version\fR] .SH DESCRIPTION The .B beam-restore @@ -117,12 +120,14 @@ necessary to handle that particular item type. .TP .BR @LIBDIR@/beam/common.sh Settings and definitions shared between -.BR beam-backup (1) +.BR beam-backup (1), +.BR beam-restore , and -.BR beam-restore. +.BR beam-list (1). .SH "SEE ALSO" .BR beam (1), .BR beam-backup (1), +.BR beam-list (1), .BR beam.conf (5) .SH AUTHORS Sergey Poznyakoff diff --git a/doc/beam.1in b/doc/beam.1in index de7b9d4..18d4eb9 100644 --- a/doc/beam.1in +++ b/doc/beam.1in @@ -14,7 +14,7 @@ .\" You should have received a copy of the GNU General Public License .\" along with BEAM. If not, see . .\" -.TH BEAM 1 "May 29, 2012" "BEAM" "BEAM User Reference" +.TH BEAM 1 "July 14, 2012" "BEAM" "BEAM User Reference" .SH NAME beam \- a backup manager .SH SYNOPSIS @@ -24,6 +24,9 @@ backup [\fIoptions\fB] .B beam restore [\fIoptions\fB] +.B beam +list [\fIoptions\fB] + .B beam s3 [\fIoptions\fB] @@ -89,6 +92,10 @@ Create a backup. See Restore files from backup. See .BR beam-restore (1). .TP +.B list +List items included in the backup. See +.BR beam-list (1). +.TP .B s3 Mount or unmount a backup s3 bucket. This command is available only if @@ -121,10 +128,10 @@ If defined, this variable supplies full pathname of the configuration file to use instead of the default .BR @SYSCONFDIR@/beam.conf . .SH "SEE ALSO" -.BR beam (1), .BR beam-backup (1), .BR beam-restore (1), .BR beam-s3 (1), +.BR beam-module (5), .BR beam.conf (5). .SH AUTHORS Sergey Poznyakoff -- cgit v1.2.1