diff options
Diffstat (limited to 'doc/beam.conf.5in')
-rw-r--r-- | doc/beam.conf.5in | 283 |
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: + |