aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2012-07-15 15:20:09 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2012-07-15 15:20:09 +0300
commit0ff98bbc90778852c889ebabdf952420bb29e287 (patch)
treea60738667d91d0faff4f68d1175221435d72e4b6
parent8c225eeb2cb48c3d32d1ac0fa7e9e60353c69d4f (diff)
downloadbeam-0ff98bbc90778852c889ebabdf952420bb29e287.tar.gz
beam-0ff98bbc90778852c889ebabdf952420bb29e287.tar.bz2
Update the docs.
-rw-r--r--Makefile.am15
-rw-r--r--NEWS19
-rw-r--r--README16
-rw-r--r--doc/Makefile.am18
-rw-r--r--doc/beam-module.5in103
-rw-r--r--doc/beam.1in2
-rw-r--r--doc/beam.conf.5in6
7 files changed, 158 insertions, 21 deletions
diff --git a/Makefile.am b/Makefile.am
index 3a5be3f..c65a39d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,3 +1,18 @@
+# This file is part of BEAM
+# 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/>.
SUBDIRS=. lib doc
if COND_S3MOUNT
S3MOUNT=s3
diff --git a/NEWS b/NEWS
index 90c72bd..0b81bed 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-BEAM NEWS -- history of user-visible changes. 2012-06-21
+BEAM NEWS -- history of user-visible changes. 2012-07-15
Copyright (C) 2012 Sergey Poznyakoff.
See the end of file for copying conditions.
@@ -7,7 +7,22 @@ Please send mailutils bug reports to <gray@gnu.org.ua>.
Version 1.3
-Bugfixes.
+* Add beam-cleaner
+
+Beam-cleaner is a utility for removing outdated backup archives and
+snapshot files.
+
+* Provide a way to dump all MySQL databases
+
+* A default log rotation hook
+
+* New command: list
+
+* New backup module: ldap
+
+* Document backup modules.
+
+* Bugfixes.
Version 1.2 (git)
diff --git a/README b/README
index 24e1b90..c407c0a 100644
--- a/README
+++ b/README
@@ -40,10 +40,10 @@ The usual way:
# [become root]
make install
-The configure script provides lot of options to tailor the
+The configure script provides a lot of options to tailor the
installation to your needs.
-Most important options are:
+The most important options are:
--prefix=DIR
Use DIR as the installation prefix. Installation prefix is
@@ -65,7 +65,7 @@ Most important options are:
--with-s3
Install modules for handling file systems backed by the Amazon
- Simple Storage Service (Amazon S3).
+ Simple Storage Service (S3).
For the list of available generic options, consult the file INSTALL.
@@ -78,7 +78,7 @@ are available:
beam backup - runs a backup
beam restore - restores from a backup
beam list - lists what is included in a backup
- beam s3 - manages the s3-backed file system
+ beam s3 - manages a s3-backed file system
beam help COMMAND - displays a short help for COMMAND
Configuration settings are read from the file beam.conf, located in the
@@ -88,10 +88,10 @@ The package uses modular structure which makes it extremely flexible.
The low-level commands are located in the LIBEXECDIR. For example,
running "beam backup" indirectly invokes LIBEXECDIR/beam-backup utility.
-Particular backup items are handled by modules, located in the
-directory PREFIX/lib/beam. Each module is a shell program providing
-primitives for a paricular task. For example, the mysql.sh module
-handles backups of MySQL databases.
+Backup methods are provided by modules, located in the directory
+PREFIX/lib/beam. Each module is a shell program providing primitives
+for a particular task. For example, the mysql.sh module handles
+backups of MySQL databases.
* Documentation
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 334b315..846c1de 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,18 @@
+# This file is part of BEAM
+# 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/>.
if COND_S3MOUNT
S3=beam-s3.1
endif
@@ -26,7 +41,8 @@ EXTRA_DIST=\
beam.conf.5in\
beam-cleaner.1\
beam-module.5in\
- beam-s3.1in
+ beam-s3.1in\
+ crontab.weekly
CLEANFILES=\
beam.1\
beam.conf.5\
diff --git a/doc/beam-module.5in b/doc/beam-module.5in
index 99e7a63..f65ce52 100644
--- a/doc/beam-module.5in
+++ b/doc/beam-module.5in
@@ -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-MODULE 5 "July 14, 2012" "BEAM" "BEAM Programmer Reference"
+.TH BEAM-MODULE 5 "July 15, 2012" "BEAM" "BEAM Programmer Reference"
.SH NAME
beam-module \- format of
.BR beam (1)
@@ -31,13 +31,13 @@ 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,
+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 DBS-specific software, and archive the created file or files.
+using the DBMS-specific software, and archive the created file or files.
.PP
To handle such cases,
.B beam
@@ -87,11 +87,11 @@ stands for the name of the module):
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.)
+configuration keywords are defined and have consistent values, etc.)
If the configuration is correct, the function shall return
.BR 0 .
-Otherwise, it shall produce appropiate diagnostic messages using
+Otherwise, it shall produce appropriate diagnostic messages using
.B error
or
.B abend
@@ -171,6 +171,97 @@ fs_backup() {
.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).
@@ -180,7 +271,7 @@ Sergey Poznyakoff
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-start: ".TH [A-Z_][A-Z0-9_-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
diff --git a/doc/beam.1in b/doc/beam.1in
index 18d4eb9..8da0298 100644
--- a/doc/beam.1in
+++ b/doc/beam.1in
@@ -75,7 +75,7 @@ directory.
.PP
The backup process is controlled by the configuration file
.BR @SYSCONFDIR@/beam.conf .
-This file is a set of shell variable assingments which define the
+This file is a set of shell variable assignments which define the
items to include in the backup.
.PP
For a detailed description of
diff --git a/doc/beam.conf.5in b/doc/beam.conf.5in
index 8cad913..572db3b 100644
--- a/doc/beam.conf.5in
+++ b/doc/beam.conf.5in
@@ -14,10 +14,10 @@
.\" 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.CONF 5 "Jun 14, 2012" "BEAM" "BEAM User Reference"
+.TH BEAM.CONF 5 "July 15, 2012" "BEAM" "BEAM User Reference"
.SH NAME
beam.conf \- configuration file for
-.B backup becomes easy
+.B BEAM
.SH DESCRIPTION
The \fBbeam.conf\fR file defines what data are to be included in the
backup, what backup methods to use and where to store the resulting
@@ -507,7 +507,7 @@ Sergey Poznyakoff
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-start: ".TH [A-Z_][A-Z0-9_.]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20

Return to:

Send suggestions and report system problems to the System administrator.