:Author: Amand Tihon
:Contact: <amand.tihon@alrj.org>
-:Version: 1.0
+:Version: 1.1
:Date: Jan 5th, 2008
:Copyright: GNU GPL, see copyright file.
+.. sectnum::
+
+.. contents:: Table of contents
+ :backlinks: none
+
Abstract
========
- Full and differential backups
- LVM snapshots
-- Xen+paravirt oriented (somehow)
-- Soon: Upload to a distant FTP server.
+- Xen oriented (somehow)
+- Upload to a distant FTP server.
Rationale
===============
You can download the tarball from http://www.alrj.org/projects/brioche
-or get the latest development version with the following git command::
+or get the latest development version with the following git command: ::
git clone http://git.alrj.org/git/brioche.git
+A gitweb interface is also available at http://git.alrj.org/
+
+
+Requirements
+============
+
+Brioche relies on a few easily available free software :
+
+- In any case, Brioche will require GNU tar, which is able to deal with
+ incremental backups. Don't even try it with any other tar implementation.
+ Tested with version 1.16.
+- For LVM snapshots, lvm2 will obviously be needed.
+- FTP backups, if they're used, will require lftp.
+
+See the `References`_ section for links to the aforementioned softwares.
+
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``.
+accordingly. If needed, run ``chmod +x /path/to/brioche``. In a typical setup,
+the ``brioche`` script will be put in ``/usr/local/bin`` with the other two
+files under ``/etc``.
Using Brioche
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.
+ be ``"--one-file-system -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.
are available.
USE_FTP
- Still TODO.
+ If set to "yes", Brioche will upload the backups on an FTP server.
+ See the `Using FTP`_ section for more information about this feature.
+
+FTP_HOST
+ The address of the FTP server.
+
+FTP_DIR
+ The base directory on the FTP server under which all the archives will be
+ stored. Brioche will never touch anything that is not below this directory.
+
+FTP_KEEP
+ Tells Brioche to keep a certain amount of older runs on the FTP. A *run* is
+ a full backup plus all its subsequent differential backups. See the `Using
+ FTP`_ section for a more detailed explanation.
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 ::
+domUs: ::
# Partition or LV Snapshot Host name Volume name
# ---------------------------------------------------------------
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 ::
+in the fourth column. Grouping by domUs' hostnames is only a suggestion, it can
+be completely different and adapted to suit your needs.
+
+For instance, a full and a differential backup for the host valeron of the
+previous example would lead to the following structure: ::
user:/REPODIR$ ls -l valeron/
total 356544
-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
++--------------------------------------------------------------------------+
+| **WARNING !** |
+| |
+| In case your REPODIR_ is not on a distinct device, it will be included |
+| in the backup if you've included the device in your ``briochetab``. |
+| |
+| To avoid this issue, you can either exclude it explicitely by adding an |
+| "``--exclude=...``" option in TAR_OPTS, or simply specify in your |
+| ``briochetab`` file which directories need to be archived. |
++--------------------------------------------------------------------------+
+
+
+Using FTP
+---------
+
+With the help of lftp, Brioche is able to store an history of backups on an FTP
+server. This is mainly usefull when no other distant repository is available.
+If possible, consider using an CIFS, NFS, sshfs or any other kind of remote
+mountpoint for your REPODIR_.
+
+The archives present in the local REPODIR_ will be mirrored to the FTP server
+after each backup, be it a full or a differential one.
+
+Since there is no way to hide the credentials if they are passed to lftp on the
+command line, the authentication relies on your ``.netrc`` file. See ``man
+netrc(5)`` for more information. In the home directory of the user that runs
+Brioche (typically root's), create the ``.netrc`` file with the following
+lines: ::
+
+ machine ftp.example.com
+ login username
+ password SikRet
+
+Don't forget to secure it with ``chmod 600 .netrc`` or lftp will refuse to use
+it. The machine name must match the FTP_HOST configuration directive in
+``brioche.conf``.
+
+On the FTP server, Brioche will keep a configurable amount of *runs*.
+Each *run* consists of a full backup and all the differential backups that are
+based on it. Before doing a full backup, Brioche will rotate the
+*runs* and keep only the configured number of older backups. The current
+backups can always be found under ``/FTP_DIR/hostname/latest/``. Older ones
+will be under ``/FTP_DIR/hostname/run-X/`` with *X* equal to 1 for the previous
+run, 2 for the one before and so forth, up to the value of FTP_KEEP.
+
+Here's what happens during the rotation:
+
+- the oldest run is removed
+- all the ``run-X/`` directories are shifted (``run-3/`` becomes ``run-4/``,
+ etc)
+- the ``latest/`` directory is renamed to ``run-1/``
+- a new, empty, ``latest/`` directory is created, ready to accept the new files.
+
+
Running Brioche
---------------
Brioche understands the following arguments:
--f, --full Do a full backup (by default, brioche will do a differential).
+-f, --full Do a full backup (by default, brioche will try to do a
+ differential).
-h, --help Show a very limited help.
When everything is ready, execute the ``brioche`` script as root. The
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 ::
+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
- GNU tar documentation : http://www.gnu.org/software/tar/manual/
- LVM documentation and links : http://sourceware.org/lvm2/
-
+- lftp homepage : http://lftp.yar.ru/
projects / brioche.git / blobdiff