1 files changed, 208 insertions, 0 deletions
diff --git a/doc/backup.1in b/doc/backup.1in
new file mode 100644
index 0000000..b6087b5
--- /dev/null
+++ b/doc/backup.1in
@@ -0,0 +1,208 @@
+.\" This file is part of backup -*- nroff -*-
+.\" Copyright (C) 2012 Sergey Poznyakoff
+.\"
+.\" Backup 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.
+.\"
+.\" Backup 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 backup.  If not, see <http://www.gnu.org/licenses/>.
+.\"
+.TH BACKUP 1 "May 17, 2012" "BACKUP" "Backup User Reference"
+.SH NAME
+backup \- create a back up.
+.SH SYNOPSIS
+.B backup
+[\fB\-h\fR] [\fB\-\-help\fR]
+
+.B 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]
+.SH DESCRIPTION
+The
+.B backup
+script creates full or incremental backups of file systems and other
+objects described in its configuration file
+.BR backup.conf .
+The configuration file by default is searched in
+.BR @SYSCONFDIR@ .
+Another location can be specified by setting the environment variable
+.B BACKUP_CONFIG
+to the full pathname of the configuration file.
+.PP
+After loading the configuration file, the script examines its command
+line for options that modify its behavior.  These are described in
+detail in the section
+.BR OPTIONS ,
+below.
+.PP
+The script uses
+.BR tar (1)
+to produce incremental backups.  The produced archives are named using
+the following pattern:
+.sp
+.nf
+.in +2
+.BR ITEM - WEEK - ROUND - LEVEL . SUFFIX
+.in
+.fi
+.sp
+where:
+.TP
+.B ITEM
+The name of the backup item.  Backup items are defined in the
+configuration variable \fBbackup_items\fR and identify file systems
+(or other objects, such as PostgreSQL databases) to backup.  See the
+section
+.B BACKUP ITEMS
+in
+.BR backup.conf (5),
+for a detailed description.
+.TP
+.B WEEK
+The number of week when this backup was taken.  This is a number of
+week in year, formatted 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
+The \fBround number\fR of this backup.  This number identifies a
+particular series of incremental backups (starting at level 1), taken
+with respect to the same full backup.
+
+Consider for example the following backup schedule.  A full backup is
+taken each Sunday.  Then, during the week, incremental backups are
+taken daily: level one backup on Monday, level two backup on Tuesday,
+then again level one on Wednesday, and so on.  In this scheme you get
+three rounds of backups each week.  See the
+.B EXAMPLES
+section for an example of this schedule.
+.TP
+.B LEVEL
+Incremental level number.
+.TP
+.B SUFFIX
+The value of \fBbackup_suffix\fR configuration variable.  If not set,
+.B tar
+is assumed.
+.PP
+The archives are stored in the directory specified by the
+.B backup_archive_dir
+configuration variable.  This directory can be a local as well as a
+remote one.  To use a remote location, set this variable to
+.sp
+.nf
+.in +2
+.BR HOST : DIR
+.in
+.fi
+.sp
+where
+.B HOST
+is the IP address or hostname of the remote machine, and
+.B DIR
+is the pathname on its file system.  See the \fBThe GNU Tar Manual\fR,
+section 9.2 \fBRemote Tape Server\fR for more information on the subject.
+.PP
+The corresponding snapshots are stored in the directory specified by
+the \fBbackup_snapshot_dir\fR configuration variable and follow the
+same scheme as the archives, except that
+.B db
+is used as their suffix.
+.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verbosity.  This overrides the \fBbackup_verbose\fR
+configuration variable.
+.TP
+\fB\-l\fR, \fB\-\-logfile\fR \fIFILE\fB
+Log to FILE.  This overrides the \fBbackup_logfile\fR configuration
+variable.
+.TP
+\fB\-n\fR, \fB\-\-dry\-run
+Do nothing, print what would have been done.  Use this to debug your
+configuration.
+.TP
+\fB\-N\fR, \fB\-\-no\-logfile
+Do not use \fBbackup_logfile\fR variable, log to standard error
+instead.
+.TP
+\fB\-L\fR, \fB\-\-level \fIN\fR
+Create incremental dump level \fIN\fR.
+.TP
+\fB-R\fR, \fB\-\-round \fIN\fR
+Mark archives with incremental round number \fIN\fR.
+.TP
+\fB\-\-week \fIN\fR
+Force using week number \fIN\fR.  By default, the current week number
+(as returned by
+.BR strftime (3)
+conversion
+.BR %U )
+is used.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display a short help summary.
+.SH EXAMPLES
+Usually \fBbackup\fR is started as a cron job.  The following
+example shows a root crontab designed so as to create full (level 0)
+backups on Sundays, level 1 backups on Mondays, Wednesdays and Fridays
+and level 2 backups on Tuesdays, Thursdays and Saturdays.
+.sp
+.nf
+.in +2
+# Create one full backup weekly.
+0 3 * * sun  backup --round 0 --level 0
+# Create incremental backups daily.
+0 3 * * mon  backup --round 0 --level 1
+0 3 * * tue  backup --round 0 --level 2
+0 3 * * wed  backup --round 1 --level 1
+0 3 * * thu  backup --round 1 --level 2
+0 3 * * fri  backup --round 2 --level 1
+0 3 * * sat  backup --round 2 --level 2
+.in
+.fi
+.sp
+.SH FILES
+.TP
+.BR @SYSCONFDIR@/backup.conf
+Default configuration file.
+.TP
+.BR @LIBDIR@/backup
+Backup module directory.  Whenever a backup item of type \fBT\fR is
+requested, \fBbackup\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@/backup/common.sh
+Settings and definitions shared between
+.BR backup
+and
+.BR restore (1).
+.SH "SEE ALSO"
+.BR restore (1),
+.BR backup.conf (5).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray@gnu.org.ua>.
+.\" 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:
+