aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2012-07-14 22:09:59 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2012-07-14 22:13:40 +0300
commitf0de8b85bf7fde9d0214428330c31056c30528c5 (patch)
treefbe97ec37676bc54060f88938d0a24ab8dd013e0 /doc
parent35212ddd3ceb7d3b20957b9ce6786f4ddd716bbe (diff)
downloadbeam-f0de8b85bf7fde9d0214428330c31056c30528c5.tar.gz
beam-f0de8b85bf7fde9d0214428330c31056c30528c5.tar.bz2
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/.gitignore4
-rw-r--r--doc/Makefile.am32
-rw-r--r--doc/beam-backup.1in17
-rw-r--r--doc/beam-list.1in74
-rw-r--r--doc/beam-module.5in187
-rw-r--r--doc/beam-restore.1in17
-rw-r--r--doc/beam.1in11
7 files changed, 325 insertions, 17 deletions
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 <http://www.gnu.org/licenses/>.
.\"
-.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 <http://www.gnu.org/licenses/>.
+.\"
+.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 <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:
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,20 +14,23 @@
.\" 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-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]
[\fB\-\-dry\-run\fR] [\fB\-\-list\fR] [\fB\-\-logfile\fR \fIFILE\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]
[\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 <http://www.gnu.org/licenses/>.
.\"
-.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
@@ -25,6 +25,9 @@ backup [\fIoptions\fB]
restore [\fIoptions\fB]
.B beam
+list [\fIoptions\fB]
+
+.B beam
s3 [\fIoptions\fB]
.B beam
@@ -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

Return to:

Send suggestions and report system problems to the System administrator.