Ubuntu Manpage: backup2l - low-maintenance backup/restore tool

NAME

       backup2l -  low-maintenance backup/restore tool

SYNOPSIS

       backup2l [ -c conffile ] [ -t backup-ID ] command

DESCRIPTION

backup2l is a tool for generating, maintaining and restoring backups on a mountable file system (e. g.
hard disk). The main design goals are low maintenance effort, efficiency, transparency and robustness.
It features differential backups at multiple hierarchical levels and provides rollback functionality.

All control files are stored together with the archives on the backup device, and their contents are
mostly self-explaining. Hence, in the case of an emergency, a user does not only have to rely on the
restore functionality of backup2l, but can - if necessary - browse the files and extract archives
manually.

An open driver architecture allows one to use virtually any archiving program as a backend. Built-in
drivers support .tar.gz, .tar.bz2, or .afioz files. Further drivers can be added by the user. When
restoring data, an appropriate driver is selected automatically for each archive depending on the suffix
of the archive file.

The method of hierarchical differential backups is a generalization to the concept of the "daily",
"weekly" and "monthly" backups. Each backup has a level and a serial number. Maximum-level backups are
comparable with daily differential backups, level-0 backups are full backups. For example, let MAX_LEVEL
be 4 and MAX_PER_LEVEL be 5. After 5 level-4 backups (e. g. after 5 days), a new level-3 backup is made.
After 5 level-3 backups (and 5*5 at level-4), a new level-2 backup is made, and so on. Each differential
backup contains the changes towards the previous backup of the same or a lower level.

This scheme allows one to efficiently generate small incremental backups at short intervals. At the same
time, the total number of archives that have to be stored (or processed in the case of a restore) only
increases logarithmically with the number of backups since the last full backup. Time-consuming full
backups are only sparsely needed. In the example above, a new full backup is only necessary after 780
(=5^4+5^3+5*5+5) days, while only at most 20 (=4*5) archives have to be processed.

For backup2l, each backup archive is identified by its backup ID (BID). The number of digits determines
the level. Level-0 (full) backups have a 1-digit BID, level-n backups have a BID of n+1 digits. The last
digit is a serial number, the prefix identifies the lower-level backups on which a given backup is based
on. For example, the archive 235 contains the differences towards archive 234, and to restore the file
system state of the time it was generated, the full backup 2, the level-1 backups 21, 22, 23 and the
level-2 backups 231, ..., 235 have to be processed. All serial numbers are between 1 and 9, a zero in
the BID indicates that no archive of the respective level is contained in the chain. For example, the
level-3 backup 1201 is immediately based on the level-1 backup 12.

For deciding whether a file is new or modified, backup2l looks at its name, modification time, size,
ownership and permissions. Unlike other backup tools, the i-node is not considered in order to avoid
problems with non-Unix file systems like FAT32.

OPTIONS

       -c, --conf conffile
              This argument specifies the configuration file (default: etc/backup2l.conf).

       -t, --time BID
              If present, this option selects a certain backup for the --locate and --restore commands.  E.  g.,
              the  latter will restore files and directories exactly as they were on the system at the time when
              the specified backup was made. If not present, the latest available backup is selected.

COMMANDS

-h, --help
Display the usage info.

-e, --estimate [ level ]
Prints the number of files, estimated amount of data and other information on the backup that
would be generated next. No backup archives are actually created or removed. If specified, the
parameter level overrides the MAX_LEVEL setting.

-b, --backup [ level ]
Creates a new backup and removes old archives based on the given configuration file. If
specified, the parameter level overrides the MAX_LEVEL setting. This is useful e. g. shortly
before or after major changes are performed with the file system. In this case, a lower level
should be specified in order to avoid that a large number of files are backed up multiple times
again.

-s, --get-summary
Shows a table describing each backup (date, size, files, ...) and the file system usage of the
backup device.

-a, --get-available [ pattern list ]
Shows all files removed and added for all backups. A '+' in the output indicates that the file is
new and thus contained in the archive file. A '-' indicates that the file has been removed (or
replaced). If one or several patterns are supplied, grep(1) is used to filter the list. All
status messages go to stderr, so that the generated file list can easily be redirected.

Note: The search pattern is not just applied to the file names, but to the whole entry in the
.list.gz file. This allows one to not only search for file names but also for other attributes
like ownership, modification time etc. . In order to apply a search pattern to file names only,
precede it by "<space>/.*".

-l, --locate [ pattern list ]
Shows most recent backup location for active files. If one or several patterns are supplied,
grep(1) is used to filter the list in the same way as for --get-available (see above) . All status
messages go to stderr, so that the generated file list can easily be redirected.

Active files are files that have been on the system at the time of the selected backup, which is
either the latest backup or the one specified by --time (see above). Files that were removed at
that time but are still stored in some later archive will not be shown.

Altogether, this command tells you, which files have to be extracted from which archive in order
to restore the state of the system at the time of the selected backup.

-r, --restore [ pattern list ]
Performs the same steps like --locate and then restores the respective files. All files are
restored relative to the current directory. They can be restored to their original location by
cd'ing into / before, but this is not recommended.

-p, --purge BID list
Removes the specified backup archive(s) and all depending backups.

-m, --make-check [ BID list ]
Creates (a) check file(s) for the specified archive(s) using md5sum(1). If no BID is specified,
check files are created wherever missing.

-v, --verify [ BID list ]
Verifies the specified backup archive(s). If no BID is specified, all existing archives are
checked. If a check file exists, this allows one a comprehensive test including e. g. media
failures. If the check file is missing, only the existence of all files and the immediate base
archive are verified.

-x, --extract capacity max-free BID-list
Split and collect files to be stored on removable media (e. g. CDs). capacity is the medium
capacity in MB. max-free is the maximum amount of empty space on each medium (except for the last
one, of course). BID-list specifies the archives and may contain wildcards, e. g.: 1 '2*'. The
operation generates enumbered subdirectories representing the media contents. Some more files are
generated that may be useful, e. g. to print labels.

While guaranteeing a minimum waste of max-free MB per medium, the collection procedure preserves
the ordering of files and keeps all control files of an archive always together on the same
medium. Large archive files are split into multiple files with serial numbers appended to their
names.

The operation is interactive. Just run it and look what it is about to do. If that is not what
you want, you can stop it.

CONFIGURATION

       In the configuration file (/etc/backup2l.conf by default),  the  following  variables  have  to  be  set,
       following the bash(1) syntax:

       FOR_VERSION=version
              Defines  the  backup2l  version  for  which  the  configuration  file is written. This way, future
              versions can automatically print a warning if the syntax has changed.

       SRCLIST=( source list )
              This is a blank-separated list of all top-level directories to make backups of.   Directory  names
              with  spaces have to be quoted, e. g.: SRCLIST=("/my dir" /another/dir).  The last elements of the
              list may be options for find(1). For example -xdev can be used  to  skip  subdirs  on  other  file
              systems such as /dev or /proc, or -L will cause all symbolic links to be followed (use with care).

       SKIPCOND=( find condition )
              Files  for  which  this  condition  is  'true'  are  not  considered  for backup.  See find(1) for
              information on how to formulate possible conditions.  Special characters ("(", ")", "!", ...) must
              be quoted by a leading backslash ("\(", "\)", " \!", ...). An empty condition (i. e. if you do not
              want any files to be skipped) must be specified as "( -false )".

       [ BACKUP_DEV="mount_point" ]
              If defined, backup2l mounts the backup device before any operation.  Afterwards, it  is  unmounted
              unless it was already mounted before.

       BACKUP_DIR="backup dir"
              Destination  directory  for  backup  files.  This  must  be  different  from MOUNT_POINT, i. e.  a
              subdirectory on the device.

       VOLNAME="volname"
              This is a common prefix for all backup and control files. Multiple backup volumes are possible  if
              for each volume a separate configuration file is written.

       MAX_LEVEL=max_level
              Maximum backup level. Possible values are 1..9.

       MAX_PER_LEVEL=max_per_level
              Number of differential backups per level. Possible values are 1..9.

       MAX_FULL=max_full
              Number of full backups kept. Possible values are 1..8.

       GENERATIONS=generations
              Number  of  backup  generations  to  keep  for  each non-zero level. Old backups are automatically
              removed as long as at least GENERATIONS * MAX_PER_LEVEL backups for the respective level remain.

              For example, with MAX_LEVEL=3, MAX_PER_LEVEL=5, GENERATIONS=2 it is always possible to access  the
              last  10 level-3 (e. g. daily) backups, the last 10 level-2 backups (e. g. 5, 10, 15, ..., 50 days
              old), and so on.

       PRE_BACKUP () { do something }
              This function is called before writing the backup. It can be used to dump  some  important  system
              information, e. g. the HD's partition table, to a file which is then backed up.

       POST_BACKUP () { do something }
              This  function is called after writing the backup. Together with PRE_BACKUP it can be used to stop
              and restart e. g. database or mail services which may frequently alter some files that have to  be
              backed up.

       [ AUTORUN=1 ]
              If  set to 1, backup2l performs the --backup operation when invoked without arguments.  Otherwise,
              the usage information is shown.

       [ SIZE_UNITS= B | K | M | G ]
              Sets the units for archive sizes in summary listings to  bytes,  KB,  MB,  or  GB.   If  unset,  a
              user-readable  format is chosen automatically. If set, the units are the same for the whole table,
              which may be even more user-friendly.

       [ CREATE_DRIVER="archive driver" ]
              Selects an archive driver for creating backups. An archive  driver  is  responsible  for  managing
              backup files. If unset, the default driver "DRIVER_TAR_GZ" is used. The --help operation lists all
              available drivers. More drivers can be defined in the configuration file (see below).

       [ USER_DRIVER_LIST="user-defined drivers" ]
              Declares additional, user-defined archive drivers which are implemented in the configuration file.
              The  sample  configuration  file  contains  a  commented example. Read it in order to learn how to
              implement your own driver.

FILES

       /etc/backup2l.conf
              Configuration file.

       VOLNAME.BID.tar.gz, VOLNAME.BID.afioz, ...
              Archive files.

       VOLNAME.BID.list.gz
              List of all active files when  the  backup  was  made.  Each  file  is  preceded  with  its  size,
              modification time, and other information.

       VOLNAME.BID.new.gz
              List  of  all  new  ore  modified files when the backup was made (pathnames only). Unless an error
              occurred, this list reflects the contents of the archive.

       VOLNAME.BID.obsolete.gz
              List of all obsolete files when the backup was made (pathnames only).

       VOLNAME.BID.skipped.gz
              Complete list of all files that were skipped according to SKIPMASK.

       VOLNAME.BID.error.gz
              This file is generated by comparing the .new.gz  file  with  the  actual  archive  contents  using
              diff(1). If the error file is non-empty, something may have gone wrong.

       VOLNAME.BID.check
              MD5  check  sums  of  all  files of the present archive and the .list.gz file of the base archive.
              This file is optional and may be used by the --verify operation.

INVOCATION BY CRON

       backup2l is designed to be run autonomously as a cron job.  If the variable AUTORUN is set, it  generates
       a backup if invoked without any parameters, and you can simply create a symlink, e. g. by:

                                ln -s `command -v backup2l` /etc/cron.daily/zz-backup2l

       The "zz-" prefix causes the backup job to be the last one executed, so that other jobs are not delayed if
       the backup takes somewhat longer. The status output is e-mailed to root by the cron daemon.

MANIPULATING FILES AND CONFIGURATIONS

       backup2l  has been designed to be robust with respect to errors and configuration changes.  If the backup
       process is interrupted, e. g. because of a shutdown while it is running, no serious data  corruption  can
       occur.  Some  temporary  files  may  remain  which are cleaned up during the next run. If file is changed
       during the backup generation, it may not be contained in the current backup. However,  it  is  guaranteed
       that it is considered modified during the next backup.

       In  order to save disk space, e. g. after some archives have been copied to external media, archive files
       (.tar.gz or .afioz, for example) can safely be removed from the backup directory.  As long as all control
       files are kept, backup2l retains full functionality as far as possible.  The  --restore  command  prompts
       for  eventually  missing archive files for the respective request (and only those). The --extract command
       completely ignores all backups with missing archive files.

       The configuration, especially the settings for MAX_LEVEL,  MAX_PER_LEVEL, MAX_FULL and the  specification
       of  source  files,  can  be  arbitrarily  changed without having to expect data corruption. backup2l will
       gracefully adapt the new settings during the next run.

BUGS

       After a restore operation, the modification time of directories is equal to the  restoration  time  while
       for files it is equal to the original modification time.

AUTHOR

       backup2l was written by Gundolf Kiefer <gundolfk at web.de>.

       This  program  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 2 of the License,  or
       (at your option) any later version.

       This  program  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.