aboutsummaryrefslogtreecommitdiff
path: root/doc/beam.conf.5in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/beam.conf.5in')
-rw-r--r--doc/beam.conf.5in283
1 files changed, 283 insertions, 0 deletions
diff --git a/doc/beam.conf.5in b/doc/beam.conf.5in
new file mode 100644
index 0000000..cf196e9
--- /dev/null
+++ b/doc/beam.conf.5in
@@ -0,0 +1,283 @@
+.\" 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.CONF 1 "May 16, 2012" "BEAM" "BEAM User Reference"
+.SH NAME
+beam.conf \- configuration file for
+.B backup becomes easy
+.SH DESCRIPTION
+The \fBbeam.conf\fR configuration file defines what files are to be
+included in the backup, what backup methods to use and where to store
+the resulting archives. The
+.BR backup (1)
+and
+.BR restore (1)
+utilities expect to find it in the
+.B @SYSCONFDIR@
+directory.
+.SH SYNTAX
+The file is essentially a shell script that defines variables
+controlling backup and restore procedures. The names of the variables
+used by the backup scripts begin with
+.BR backup_ .
+.SH GENERAL SETUP
+.TP
+.B backup_logfile
+If set, redirect standard error and standard output to that file. The
+file will be created if it does not exist. Otherwise, the output will be
+appended to it.
+.TP
+.B backup_rsh_command
+Use this command to access remote archives. Unless set, the backup
+utilities will first look for an executable file named
+.BR @BINDIR@/speedssh .
+If not found, they will fall back to using \fB/usr/bin/ssh\fR. It is
+the responsibility of the administrator to provide for authentication
+on the remote system, e.g. by using shared-key authentication.
+.TP
+.B backup_retain_interval
+Sets the interval, in weeks, during which old backups and snapshots
+are retained. Empty value or zero means never delete the backups.
+
+This variable is used by
+.BR backup (1),
+which calls
+.BR backup-cleaner (1)
+if it is set.
+.SH S3 SETUP
+To keep archives in a
+.B s3
+bucket you will need the
+.BR s3backer (1)
+utility.
+.TP
+.B backup_s3backer_options
+Additional options for
+.BR s3backer (1).
+
+Use it, e.g., to pass the
+.B \-\-vhost
+option if your bucket is located outside of the US region.
+.TP
+.B backup_bucket_name
+Sets the name of the
+.B s3
+bucket to keep the archives in.
+.TP
+.B backup_mp_s3backer
+Defines mount point for the "raw" bucket.
+
+Default value is
+.BR /mnt/s3backer .
+.TP
+.B backup_mp_s3
+Defines mount point for the actual s3-backed filesystem.
+
+Default value is
+.BR /mnt/s3 .
+.SH TAR SETUP
+Tar setup variables control additional options and arguments passed to
+.BR tar (1).
+.TP
+.B backup_tar_options
+Use this variable to pass additional options to tar. Do not place tar
+operation switches (such as \fB-c\fR, \fB-t\fR, etc.) here! These
+will be added automatically by appropriate scripts, depending on the
+operation being performed
+
+By default this variable is empty (no additional options passed to tar).
+.TP
+.B backup_suffix
+This variable supplies suffix for created archive names. The default
+is
+.B tar .
+The dot is inserted between the file name and its suffix.
+
+This variable is useful if you request compression and want archive
+file names to reflect it. For example:
+.sp
+.nf
+.in +2
+backup_tar_options="-j"
+backup_suffix="tar.bz2"
+.in
+.fi
+.sp
+.TP
+.B backup_archive_dir
+Directory where archive files are located. It's OK to specify
+a remote directory here, e.g.
+.sp
+.nf
+.in +2
+backup_archive_dir="10.10.0.1:/export/backup"
+.in
+.fi
+.sp
+This variable must be defined and whatever directory it points to must
+already exist.
+.TP
+.B backup_snapshot_dir
+Directory for incremental snapshot files. These files are be named after
+their archive counterparts, by appending the
+.B .db
+suffix.
+.TP
+.B backup_verbose
+Set this variable to any non-empty value to request additional
+verbosity. The effect of this setting depends on backup methods being
+used. For example, the
+.B fs
+method adds a
+.B \-v
+option to each invocation of
+.BR tar (1).
+.SH BACKUP ITEMS
+A
+.B backup item
+identifies information that needs to be backed up. Syntactically,
+items follow the same rules as shell variable names. Backup items
+are introduced using the following variable:
+.TP
+.B backup_items
+A whitespace-separated list of backup items.
+.PP
+For each backup item
+.B name
+the configuration file must provide a set of variables describing
+where to obtain this information and how to store it to the archive.
+These variables follow the same naming convention:
+.sp
+.nf
+.in +2
+\fBname\fR_\fBvar\fR
+.in
+.fi
+.sp
+where \fBname\fR is the item name and \fIvar\fR is a valid shell
+identifier.
+
+The
+.B \fBname\fR_type
+variable must always be defined. It identifies the backup method
+to be applied to that item. Currently two backup methods are
+implemented:
+.TP
+.B fs
+A file system backup.
+.TP
+.B postgres
+Backup of a PostgreSQL database.
+.SH FS BACKUP TYPE
+This is the basic backup type, which means incremental backups of a
+specified file system. For each item of this type, the following
+variables must be defined:
+.TP
+.B \fIitem\fB_dir
+The absolute path to the file system being backed up.
+.TP
+.B \fIitem\fB_files
+A whitespace-separated list of directories and/or files in the
+.B \fIitem\fB_dir
+directory.
+.PP
+For example:
+.sp
+.nf
+.in +2
+backup_items="system"
+
+system_type=fs
+system_dir="/"
+system_files="etc var/spool"
+.in
+.fi
+.sp
+This configuration requests incremental backups of everything found in
+the directories \fB/etc\fR and \fB/var/spool\fR.
+.SH POSTGRES BACKUP TYPE
+The
+.B postgres
+type creates a dump of a PostgreSQL database and archives it using
+.BR tar (1).
+The following variables must be defined for items of this type:
+.TP
+.B \fIitem\fB_database
+The database name.
+.SH HOOKS
+Two special variables, called hooks, allow you to supply arbitrary
+procedures to be run before and after backup.
+.TP
+.B prologue_hook
+This variable contains a whitespace-separated list of the commands to
+be invoked before starting backup (or restore). The commands are
+started in order of their appearance in the list and are called
+without arguments. By default, this variable is empty.
+.TP
+.B epilogue_hook
+This variable contains a whitespace-separated list of the commands to
+be invoked after the backup (or restore) has finished. The commands are
+started in order of their appearance in the list and are called
+without arguments. By default, this variable is empty.
+.SH EXAMPLES
+A simple configuration file for backing up the contents of
+.BR /etc,
+.BR /home ,
+and the PostreSQL database
+.BR savane :
+.sp
+.nf
+.in +2
+# Request bzip2 compression:
+backup_tar_options="-j"
+# Modify file name suffix accordingly
+backup_suffix="tar.bz2"
+# Write data to \fB/dev/rmt1\fR on a remote machine:
+backup_archive_dir=192.168.0.1:/dev/rmt1
+# Keep snapshots in this directory:
+backup_snapshot_dir=/var/snapshots
+
+# Two backup items are defined:
+backup_items="dbdump system"
+
+# The \fBdbdump\fR item dumps the database:
+dbdump_type=postgres
+dbdump_database=savane
+
+# The \fBsystem\fR item backs up the file system:
+system_type=fs
+system_dir="/"
+system_files="etc home"
+.in
+.fi
+.sp
+.SH "SEE ALSO"
+.BR beam (1),
+.BR beam-restore (1),
+.BR beam-backup (1),
+.BR beam-cleaner (1).
+.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.