README

   1 .. HTML version generated with rst2html -t README > README.html
   2
   3 ==============
   4 Brioche Backup
   5 ==============
   6
   7 :Author:    Amand Tihon
   8 :Contact:   <amand.tihon@alrj.org>
   9 :Version:   1.0
  10 :Date:      Jan 5th, 2008
  11 :Copyright: GNU GPL, see copyright file.
  12
  13
  14 Abstract
  15 ========
  16
  17 Brioche is yet another backup shell script. Its main features are
  18
  19 - Full and differential backups
  20 - LVM snapshots
  21 - Xen+paravirt oriented (somehow)
  22 - Soon: Upload to a distant FTP server.
  23
  24
  25 Rationale
  26 =========
  27
  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.
  34
  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.
  38
  39
  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.
  42
  43
  44 Getting Brioche
  45 ===============
  46
  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::
  49
  50   git clone http://git.alrj.org/git/brioche.git
  51
  52
  53 Installation
  54 ============
  55
  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``.
  59
  60
  61 Using Brioche
  62 =============
  63
  64 Configuration
  65 -------------
  66
  67 Edit the file ``brioche.conf`` to suit your needs. Each option is commented
  68 inline and will be detailed here.
  69
  70 BACKUPTAB
  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.
  74
  75 MAILTO
  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.
  78
  79 .. _REPODIR:
  80
  81 REPODIR
  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.
  86
  87 USAGE_WARN
  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.
  90
  91 COMPRESS
  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.
  95
  96 TAR_OPTS
  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.
 101
 102 SNAPSHOT_MOUNTPOINT
 103   Sets the directory where the temporary LVM snapshots must be mounted.
 104
 105 SNAPSHOT_NAME
 106   The name to use for the snapshot volumes.
 107
 108 SNAPSHOT_SIZE
 109   Set the size of the snapshot volume. The same suffix than for lvcreate(8)
 110   are available.
 111
 112 USE_FTP
 113   Still TODO.
 114
 115
 116 Defining backups
 117 ----------------
 118
 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
 121 domUs ::
 122
 123   # Partition or LV           Snapshot    Host name     Volume name
 124   # ---------------------------------------------------------------
 125   /                           no          cottman       root
 126   /usr                        no          cottman       usr
 127
 128   /dev/vg00/valeron-root      yes         valeron       root
 129
 130   /dev/vg00/kadarin-root      yes         kadarin       root
 131   /dev/vg00/kadarin-home      yes         kadarin       home
 132
 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
 137
 138 Blank lines, or lines beginning with # are ignored.
 139
 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
 142 to LVM devices.
 143
 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.
 147
 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 ::
 154
 155   user:/REPODIR$ ls -l valeron/
 156   total 356544
 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
 161
 162
 163 Running Brioche
 164 ---------------
 165
 166 Brioche understands the following arguments:
 167
 168 -f, --full  Do a full backup (by default, brioche will do a differential).
 169 -h, --help  Show a very limited help.
 170
 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.
 175
 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 ::
 178
 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
 183
 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).
 186
 187
 188 Bug reporting
 189 =============
 190
 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.
 194
 195
 196
 197 References
 198 ==========
 199
 200 - GNU tar documentation : http://www.gnu.org/software/tar/manual/
 201 - LVM documentation and links : http://sourceware.org/lvm2/
 202
 203
 204
 205
 206