X-Git-Url: https://git.alrj.org/?p=brioche.git;a=blobdiff_plain;f=README;fp=README;h=7e33dcdd4fa09f01a35f1e8b7456c1d8b0b5e986;hp=0000000000000000000000000000000000000000;hb=f4201c6cef13f8f0853ff096b4deb580d5161429;hpb=902cf37d03ebaa6f3b7a5ff645a13945f8ee2e57 diff --git a/README b/README new file mode 100644 index 0000000..7e33dcd --- /dev/null +++ b/README @@ -0,0 +1,202 @@ +============== +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. + +.. [#diff] Each differential backup is based upon the last *full* backup, unlike + incremental, which are based upon the last (full or incremental) + backup. + +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. + +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/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/ + + + + +