1 .. HTML version generated with rst2html -t README > README.html
8 :Contact: <amand.tihon@alrj.org>
11 :Copyright: GNU GPL, see copyright file.
15 .. contents:: Table of contents
22 Brioche is yet another backup shell script. Its main features are
24 - Full and differential backups
26 - Xen oriented (somehow)
27 - Upload to a distant FTP server.
33 Large numbers of backup solutions are freely available today, but when playing
34 with incremental or differential backups, most of them rely on some filesystem
35 capabilities, like *hard-linking*. If the only remote location available to
36 store the backups is an FTP server, this is not a solution.
37 Brioche relies on GNU tar's ``--listed-incremental`` option to create *real*
38 differential [#diff]_ archives.
40 A second feature that makes Brioche interresting is the ability to use LVM
41 snapshots. In the case of a Xen setup where the domUs use logical volumes as
42 partitions, Brioche is able to backup everything from the dom0.
45 .. [#diff] Each differential backup is based upon the last *full* backup, unlike
46 incremental, which are based upon the last (full or incremental) backup.
52 You can download the tarball from http://www.alrj.org/projects/brioche
53 or get the latest development version with the following git command: ::
55 git clone http://git.alrj.org/git/brioche.git
57 A gitweb interface is also available at http://git.alrj.org/
63 Brioche relies on a few easily available free software :
65 - In any case, Brioche will require GNU tar, which is able to deal with
66 incremental backups. Don't even try it with any other tar implementation.
67 Tested with version 1.16.
68 - For LVM snapshots, lvm2 will obviously be needed.
69 - FTP backups, if they're used, will require lftp.
71 See the `References`_ section for links to the aforementioned softwares.
77 Copy the three files ``brioche``, ``brioche.conf`` and ``briochetab`` where
78 you like, and set the ``CONFIG_FILE`` variable in the ``brioche`` script
79 accordingly. If needed, run ``chmod +x /path/to/brioche``. In a typical setup,
80 the ``brioche`` script will be put in ``/usr/local/bin`` with the other two
90 Edit the file ``brioche.conf`` to suit your needs. Each option is commented
91 inline and will be detailed here.
94 Full absolute path to the briochetab file. This file describes which logical
95 volumes and partitions must be backed up. Its format is explained in the
96 `Defining backups`_ section.
99 When the job is done, Brioche will send a summary of the operations by email.
100 You can set it to any value that your ``mail`` command understands.
105 Brioche will store all the generated archives in this directory.Note that
106 before doing a full backup, Brioche will move all previous archives into an
107 "undo" subdirectory, which will be removed only if the backup is successful.
108 Make sure there's enough free space on the device where REPODIR is located.
111 The report email will include a warning if the space used on REPODIR goes
112 beyond the given threshold. The value must be an integer.
115 This directive allows to specify the compression method to apply to the
116 archives. Possible values are "gz", "bz2" and "lzma". **Warning** : lzma may
117 not be available with older versions of GNU tar.
120 Additionnal options that you may want to pass to tar. A typical value could
121 be ``"--one-file-system -S"``. The first option will skip all other
122 mointpoints (very usefull if you have /dev, /proc, /sys or REPODIR mounted
123 under a device that must be archived). The second one will try to deal with
127 Sets the directory where the temporary LVM snapshots must be mounted.
130 The name to use for the snapshot volumes.
133 Set the size of the snapshot volume. The same suffix than for lvcreate(8)
137 If set to "yes", Brioche will upload the backups on an FTP server.
138 See the `Using FTP`_ section for more information about this feature.
141 The address of the FTP server.
144 The base directory on the FTP server under which all the archives will be
145 stored. Brioche will never touch anything that is not below this directory.
148 Tells Brioche to keep a certain amount of older runs on the FTP. A *run* is
149 a full backup plus all its subsequent differential backups. See the `Using
150 FTP`_ section for a more detailed explanation.
156 The backups are defined in the file ``birochetab``. Here is a typical example
157 for a Xen config where cottman is the dom0 and syrtis, kadarin, valeron are
160 # Partition or LV Snapshot Host name Volume name
161 # ---------------------------------------------------------------
165 /dev/vg00/valeron-root yes valeron root
167 /dev/vg00/kadarin-root yes kadarin root
168 /dev/vg00/kadarin-home yes kadarin home
170 /dev/vg00/syrtis-root yes syrtis root
171 /dev/vg00/syrtis-home yes syrtis home
172 /dev/vg00/syrtis-usr yes syrtis usr
173 /dev/vg00/syrtis-var yes syrtis var
175 Blank lines, or lines beginning with # are ignored.
177 The first column defines the directory or logical volume to backup. In this
178 example,the first two lines are plain directories, while the other ones point
181 The second column specify if the backup should be taken from an LVM snapshot or
182 not. It **must** be set to "no" for the backup of a directory and to "yes" for
183 the backup of a logical volume.
185 The last two columns are more or less cosmetic, and define where the archive
186 files will be stored, and how they'll be named. The destination directory will
187 be created under the REPODIR_, and its name will be the value on the third
188 column. Inside this directory, archive files will be named from the value given
189 in the fourth column. Grouping by domUs' hostnames is only a suggestion, it can
190 be completely different and adapted to suit your needs.
192 For instance, a full and a differential backup for the host valeron of the
193 previous example would lead to the following structure: ::
195 user:/REPODIR$ ls -l valeron/
197 -rw-r--r-- 1 root root 363545613 Jan 3 03:10 root.full.20090103.tar.bz2
198 -rw-r--r-- 1 root root 504722 Jan 3 03:10 root.full.snar
199 -rw-r--r-- 1 root root 504725 Jan 4 04:06 root.incr.20090104.snar
200 -rw-r--r-- 1 root root 160542 Jan 4 04:06 root.incr.20090104.tar.bz2
202 +--------------------------------------------------------------------------+
205 | In case your REPODIR_ is not on a distinct device, it will be included |
206 | in the backup if you've included the device in your ``briochetab``. |
208 | To avoid this issue, you can either exclude it explicitely by adding an |
209 | "``--exclude=...``" option in TAR_OPTS, or simply specify in your |
210 | ``briochetab`` file which directories need to be archived. |
211 +--------------------------------------------------------------------------+
217 With the help of lftp, Brioche is able to store an history of backups on an FTP
218 server. This is mainly usefull when no other distant repository is available.
219 If possible, consider using an CIFS, NFS, sshfs or any other kind of remote
220 mountpoint for your REPODIR_.
222 The archives present in the local REPODIR_ will be mirrored to the FTP server
223 after each backup, be it a full or a differential one.
225 Since there is no way to hide the credentials if they are passed to lftp on the
226 command line, the authentication relies on your ``.netrc`` file. See ``man
227 netrc(5)`` for more information. In the home directory of the user that runs
228 Brioche (typically root's), create the ``.netrc`` file with the following
231 machine ftp.example.com
235 Don't forget to secure it with ``chmod 600 .netrc`` or lftp will refuse to use
236 it. The machine name must match the FTP_HOST configuration directive in
239 On the FTP server, Brioche will keep a configurable amount of *runs*.
240 Each *run* consists of a full backup and all the differential backups that are
241 based on it. Before doing a full backup, Brioche will rotate the
242 *runs* and keep only the configured number of older backups. The current
243 backups can always be found under ``/FTP_DIR/hostname/latest/``. Older ones
244 will be under ``/FTP_DIR/hostname/run-X/`` with *X* equal to 1 for the previous
245 run, 2 for the one before and so forth, up to the value of FTP_KEEP.
247 Here's what happens during the rotation:
249 - the oldest run is removed
250 - all the ``run-X/`` directories are shifted (``run-3/`` becomes ``run-4/``,
252 - the ``latest/`` directory is renamed to ``run-1/``
253 - a new, empty, ``latest/`` directory is created, ready to accept the new files.
260 Brioche understands the following arguments:
262 -f, --full Do a full backup (by default, brioche will try to do a
264 -h, --help Show a very limited help.
266 When everything is ready, execute the ``brioche`` script as root. The
267 script is pretty verbose, so don't panic if you see lots of lines scrolling in
268 your terminal. By default, Brioche will try to make differential backups, but
269 will gracefully fall back and do a full backup if none is available.
271 If all is fine, it can be added in the system crontab. Here's a suggestion for
272 weekly full backup on Sunday, with differential during the weekdays: ::
274 # Daily incremental backup
275 30 3 * * 1-6 /usr/local/bin/brioche > /var/log/backup.`date "+%a"`.log 2>&1
276 # Weekly full backup on Sunday
277 30 3 * * 0 /usr/local/bin/brioche -f > /var/log/backup.`date "+%a"`.log 2>&1
279 The output of the script will be saved in /var/log/backup.DOW.log with DOW
280 being the abbreviated day of the week (see man date(1) for the format).
286 There's no bugtracker for this project, your bug reports should be sent to the
287 author : Amand Tihon <amand.tihon@alrj.org>. Please include as much information
288 as possible in your report.
295 - GNU tar documentation : http://www.gnu.org/software/tar/manual/
296 - LVM documentation and links : http://sourceware.org/lvm2/
297 - lftp homepage : http://lftp.yar.ru/