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