.. HTML version generated with rst2html -t README > README.html
==============
Brioche Backup
==============
:Author: Amand Tihon
:Contact:
: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.
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.
.. [#diff] Each differential backup is based upon the last *full* backup, unlike
incremental, which are based upon the last (full or incremental) backup.
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/git/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 . 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/