1 .. HTML version generated with rst2html -t README > README.html
8 :Contact: <amand.tihon@alrj.org>
11 :Copyright: GNU GPL, see copyright file.
17 Brioche is yet another backup shell script. Its main features are
19 - Full and differential backups
21 - Xen+paravirt oriented (somehow)
22 - Soon: Upload to a distant FTP server.
28 Large numbers of backup solutions are freely available today, but when playing
29 with incremental or differential backups, most of them rely on some filesystem
30 capabilities, like *hard-linking*. If the only remote location available to
31 store the backups is an FTP server, this is not a solution.
32 Brioche relies on GNU tar's ``--listed-incremental`` option to create *real*
33 differential [#diff]_ archives.
35 A second feature that makes Brioche interresting is the ability to use LVM
36 snapshots. In the case of a Xen setup where the domUs use logical volumes as
37 partitions, Brioche is able to backup everything from the dom0.
40 .. [#diff] Each differential backup is based upon the last *full* backup, unlike
41 incremental, which are based upon the last (full or incremental) backup.
47 You can download the tarball from http://www.alrj.org/projects/brioche
48 or get the latest development version with the following git command::
50 git clone http://git.alrj.org/git/brioche.git
56 Copy the three files ``brioche``, ``brioche.conf`` and ``briochetab`` where
57 you like, and set the ``CONFIG_FILE`` variable in the ``brioche`` script
58 accordingly. If needed, run ``chmod +x /path/to/brioche``.
67 Edit the file ``brioche.conf`` to suit your needs. Each option is commented
68 inline and will be detailed here.
71 Full absolute path to the briochetab file. This file describes which logical
72 volumes and partitions must be backed up. Its format is explained in the
73 `Defining backups`_ section.
76 When the job is done, Brioche will send a summary of the operations by email.
77 You can set it to any value that your ``mail`` command understands.
82 Brioche will store all the generated archives in this directory.Note that
83 before doing a full backup, Brioche will move all previous archives into an
84 "undo" subdirectory, which will be removed only if the backup is successful.
85 Make sure there's enough free space on the device where REPODIR is located.
88 The report email will include a warning if the space used on REPODIR goes
89 beyond the given threshold. The value must be an integer.
92 This directive allows to specify the compression method to apply to the
93 archives. Possible values are "gz", "bz2" and "lzma". **Warning** : lzma may
94 not be available with older versions of GNU tar.
97 Additionnal options that you may want to pass to tar. A typical value could
98 be ``"--one-filesystem -S"``. The first option will skip all other mointpoints
99 (very usefull if you have /dev, /proc, /sys or REPODIR mounted under a device
100 that must be archived). The second one will try to deal with sparse files.
103 Sets the directory where the temporary LVM snapshots must be mounted.
106 The name to use for the snapshot volumes.
109 Set the size of the snapshot volume. The same suffix than for lvcreate(8)
119 The backups are defined in the file ``birochetab``. Here is a typical example
120 for a Xen config where cottman is the dom0 and syrtis, kadarin, valeron are
123 # Partition or LV Snapshot Host name Volume name
124 # ---------------------------------------------------------------
128 /dev/vg00/valeron-root yes valeron root
130 /dev/vg00/kadarin-root yes kadarin root
131 /dev/vg00/kadarin-home yes kadarin home
133 /dev/vg00/syrtis-root yes syrtis root
134 /dev/vg00/syrtis-home yes syrtis home
135 /dev/vg00/syrtis-usr yes syrtis usr
136 /dev/vg00/syrtis-var yes syrtis var
138 Blank lines, or lines beginning with # are ignored.
140 The first column defines the directory or logical volume to backup. In this
141 example,the first two lines are plain directories, while the other ones point
144 The second column specify if the backup should be taken from an LVM snapshot or
145 not. It **must** be set to "no" for the backup of a directory and to "yes" for
146 the backup of a logical volume.
148 The last two columns are more or less cosmetic, and define where the archive
149 files will be stored, and how they'll be named. The destination directory will
150 be created under the REPODIR_, and its name will be the value on the third
151 column. Inside this directory, archive files will be named from the value given
152 in the fourth column. For instance, a full and a differential backup for
153 valeron would lead to the following structure ::
155 user:/REPODIR$ ls -l valeron/
157 -rw-r--r-- 1 root root 363545613 Jan 3 03:10 root.full.20090103.tar.bz2
158 -rw-r--r-- 1 root root 504722 Jan 3 03:10 root.full.snar
159 -rw-r--r-- 1 root root 504725 Jan 4 04:06 root.incr.20090104.snar
160 -rw-r--r-- 1 root root 160542 Jan 4 04:06 root.incr.20090104.tar.bz2
166 Brioche understands the following arguments:
168 -f, --full Do a full backup (by default, brioche will do a differential).
169 -h, --help Show a very limited help.
171 When everything is ready, execute the ``brioche`` script as root. The
172 script is pretty verbose, so don't panic if you see lots of lines scrolling in
173 your terminal. By default, Brioche will try to make differential backups, but
174 will gracefully fall back and do a full backup if none is available.
176 If all is fine, it can be added in the system crontab. Here's a suggestion for
177 weekly full backup on Sunday, with differential during the weekdays ::
179 # Daily incremental backup
180 30 3 * * 1-6 /usr/local/bin/brioche > /var/log/backup.`date "+%a"`.log 2>&1
181 # Weekly full backup on Sunday
182 30 3 * * 0 /usr/local/bin/brioche -f > /var/log/backup.`date "+%a"`.log 2>&1
184 The output of the script will be saved in /var/log/backup.DOW.log with DOW
185 being the abbreviated day of the week (see man date(1) for the format).
191 There's no bugtracker for this project, your bug reports should be sent to the
192 author : Amand Tihon <amand.tihon@alrj.org>. Please include as much information
193 as possible in your report.
200 - GNU tar documentation : http://www.gnu.org/software/tar/manual/
201 - LVM documentation and links : http://sourceware.org/lvm2/