--- /dev/null
+==============
+Brioche Backup
+==============
+
+:Author: Amand Tihon
+:Contact: <amand.tihon@alrj.org>
+:Version: 1.0
+:Date: Jan 5th, 2008
+:Copyright: GNU GPL, see copyright file.
+
+
+Abstract
+========
+
+Brioche is yet another backup shell script. Its main features are
+
+- Full and differential backups
+- LVM snapshots
+- Xen+paravirt oriented (somehow)
+- Soon: Upload to a distant FTP server.
+
+
+Rationale
+=========
+
+Large numbers of backup solutions are freely available today, but when playing
+with incremental or differential backups, most of them rely on some filesystem
+capabilities, like *hard-linking*. If the only remote location available to
+store the backups is an FTP server, this is not a solution.
+Brioche relies on GNU tar's ``--listed-incremental`` option to create *real*
+differential[#diff]_ archives.
+
+.. [#diff] Each differential backup is based upon the last *full* backup, unlike
+ incremental, which are based upon the last (full or incremental)
+ backup.
+
+A second feature that makes Brioche interresting is the ability to use LVM
+snapshots. In the case of a Xen setup where the domUs use logical volumes as
+partitions, Brioche is able to backup everything from the dom0.
+
+Getting Brioche
+===============
+
+You can download the tarball from http://www.alrj.org/projects/brioche
+or get the latest development version with the following git command::
+
+ git clone http://git.alrj.org/brioche.git
+
+
+Installation
+============
+
+Copy the three files ``brioche``, `` brioche.conf`` and ``briochetab`` where
+you like, and set the ``CONFIG_FILE`` variable in the ``brioche`` script
+accordingly. If needed, run ``chmod +x /path/to/brioche``.
+
+
+Using Brioche
+=============
+
+Configuration
+-------------
+
+Edit the file ``brioche.conf`` to suit your needs. Each option is commented
+inline and will be detailed here.
+
+BACKUPTAB
+ Full absolute path to the briochetab file. This file describes which logical
+ volumes and partitions must be backed up. Its format is explained in the
+ `Defining backups`_ section.
+
+MAILTO
+ When the job is done, Brioche will send a summary of the operations by email.
+ You can set it to any value that your ``mail`` command understands.
+
+.. _REPODIR:
+
+REPODIR
+ Brioche will store all the generated archives in this directory.Note that
+ before doing a full backup, Brioche will move all previous archives into an
+ "undo" subdirectory, which will be removed only if the backup is successful.
+ Make sure there's enough free space on the device where REPODIR is located.
+
+USAGE_WARN
+ The report email will include a warning if the space used on REPODIR goes
+ beyond the given threshold. The value must be an integer.
+
+COMPRESS
+ This directive allows to specify the compression method to apply to the
+ archives. Possible values are "gz", "bz2" and "lzma". **Warning** : lzma may
+ not be available with older versions of GNU tar.
+
+TAR_OPTS
+ Additionnal options that you may want to pass to tar. A typical value could
+ be ``"--one-filesystem -S"``. The first option will skip all other mointpoints
+ (very usefull if you have /dev, /proc, /sys or REPODIR mounted under a device
+ that must be archived). The second one will try to deal with sparse files.
+
+SNAPSHOT_MOUNTPOINT
+ Sets the directory where the temporary LVM snapshots must be mounted.
+
+SNAPSHOT_NAME
+ The name to use for the snapshot volumes.
+
+SNAPSHOT_SIZE
+ Set the size of the snapshot volume. The same suffix than for lvcreate(8)
+ are available.
+
+USE_FTP
+ Still TODO.
+
+
+Defining backups
+----------------
+
+The backups are defined in the file ``birochetab``. Here is a typical example
+for a Xen config where cottman is the dom0 and syrtis, kadarin, valeron are
+domUs ::
+
+ # Partition or LV Snapshot Host name Volume name
+ # ---------------------------------------------------------------
+ / no cottman root
+ /usr no cottman usr
+
+ /dev/vg00/valeron-root yes valeron root
+
+ /dev/vg00/kadarin-root yes kadarin root
+ /dev/vg00/kadarin-home yes kadarin home
+
+ /dev/vg00/syrtis-root yes syrtis root
+ /dev/vg00/syrtis-home yes syrtis home
+ /dev/vg00/syrtis-usr yes syrtis usr
+ /dev/vg00/syrtis-var yes syrtis var
+
+Blank lines, or lines beginning with # are ignored.
+
+The first column defines the directory or logical volume to backup. In this
+example,the first two lines are plain directories, while the other ones point
+to LVM devices.
+
+The second column specify if the backup should be taken from an LVM snapshot or
+not. It **must** be set to "no" for the backup of a directory and to "yes" for
+the backup of a logical volume.
+
+The last two columns are more or less cosmetic, and define where the archive
+files will be stored, and how they'll be named. The destination directory will
+be created under the REPODIR_, and its name will be the value on the third
+column. Inside this directory, archive files will be named from the value given
+in the fourth column. For instance, a full and a differential backup for
+valeron would lead to the following structure ::
+
+ user:/REPODIR$ ls -l valeron/
+ total 356544
+ -rw-r--r-- 1 root root 363545613 Jan 3 03:10 root.full.20090103.tar.bz2
+ -rw-r--r-- 1 root root 504722 Jan 3 03:10 root.full.snar
+ -rw-r--r-- 1 root root 504725 Jan 4 04:06 root.incr.20090104.snar
+ -rw-r--r-- 1 root root 160542 Jan 4 04:06 root.incr.20090104.tar.bz2
+
+
+Running Brioche
+---------------
+
+Brioche understands the following arguments:
+
+-f, --full Do a full backup (by default, brioche will do a differential).
+-h, --help Show a very limited help.
+
+When everything is ready, execute the ``brioche`` script as root. The
+script is pretty verbose, so don't panic if you see lots of lines scrolling in
+your terminal. By default, Brioche will try to make differential backups, but
+will gracefully fall back and do a full backup if none is available.
+
+If all is fine, it can be added in the system crontab. Here's a suggestion for
+weekly full backup on Sunday, with differential during the weekdays ::
+
+ # Daily incremental backup
+ 30 3 * * 1-6 /usr/local/bin/brioche > /var/log/backup.`date "+%a"`.log 2>&1
+ # Weekly full backup on Sunday
+ 30 3 * * 0 /usr/local/bin/brioche -f > /var/log/backup.`date "+%a"`.log 2>&1
+
+The output of the script will be saved in /var/log/backup.DOW.log with DOW
+being the abbreviated day of the week (see man date(1) for the format).
+
+
+Bug reporting
+=============
+
+There's no bugtracker for this project, your bug reports should be sent to the
+author : Amand Tihon <amand.tihon@alrj.org>. Please include as much information
+as possible in your report.
+
+
+References
+==========
+
+GNU tar documentation : http://www.gnu.org/software/tar/manual/
+LVM documentation and links : http://sourceware.org/lvm2/
+
+
+
+
+
projects / brioche.git / blobdiff