README

   1 ==============
   2 Brioche Backup
   3 ==============
   4
   5 :Author:    Amand Tihon
   6 :Contact:   <amand.tihon@alrj.org>
   7 :Version:   1.0
   8 :Date:      Jan 5th, 2008
   9 :Copyright: GNU GPL, see copyright file.
  10
  11
  12 Abstract
  13 ========
  14
  15 Brioche is yet another backup shell script. Its main features are
  16
  17 - Full and differential backups
  18 - LVM snapshots
  19 - Xen+paravirt oriented (somehow)
  20 - Soon: Upload to a distant FTP server.
  21
  22
  23 Rationale
  24 =========
  25
  26 Large numbers of backup solutions are freely available today, but when playing
  27 with incremental or differential backups, most of them rely on some filesystem
  28 capabilities, like *hard-linking*. If the only remote location available to
  29 store the backups is an FTP server, this is not a solution.
  30 Brioche relies on GNU tar's ``--listed-incremental`` option to create *real*
  31 differential[#diff]_ archives.
  32
  33 .. [#diff] Each differential backup is based upon the last *full* backup, unlike
  34            incremental, which are based upon the last (full or incremental)
  35            backup.
  36
  37 A second feature that makes Brioche interresting is the ability to use LVM
  38 snapshots. In the case of a Xen setup where the domUs use logical volumes as
  39 partitions, Brioche is able to backup everything from the dom0.
  40
  41 Getting Brioche
  42 ===============
  43
  44 You can download the tarball from http://www.alrj.org/projects/brioche
  45 or get the latest development version with the following git command::
  46
  47   git clone http://git.alrj.org/brioche.git
  48
  49
  50 Installation
  51 ============
  52
  53 Copy the three files ``brioche``, `` brioche.conf`` and ``briochetab`` where
  54 you like, and set the ``CONFIG_FILE`` variable in the ``brioche`` script
  55 accordingly. If needed, run ``chmod +x /path/to/brioche``.
  56
  57
  58 Using Brioche
  59 =============
  60
  61 Configuration
  62 -------------
  63
  64 Edit the file ``brioche.conf`` to suit your needs. Each option is commented
  65 inline and will be detailed here.
  66
  67 BACKUPTAB
  68   Full absolute path to the briochetab file. This file describes which logical
  69   volumes and partitions must be backed up. Its format is explained in the
  70   `Defining backups`_ section.
  71
  72 MAILTO
  73   When the job is done, Brioche will send a summary of the operations by email.
  74   You can set it to any value that your ``mail`` command understands.
  75
  76 .. _REPODIR:
  77
  78 REPODIR
  79   Brioche will store all the generated archives in this directory.Note that
  80   before doing a full backup, Brioche will move all previous archives into an
  81   "undo" subdirectory, which will be removed only if the backup is successful.
  82   Make sure there's enough free space on the device where REPODIR is located.
  83
  84 USAGE_WARN
  85   The report email will include a warning if the space used on REPODIR goes
  86   beyond the given threshold. The value must be an integer.
  87
  88 COMPRESS
  89   This directive allows to specify the compression method to apply to the
  90   archives. Possible values are "gz", "bz2" and "lzma". **Warning** : lzma may
  91   not be available with older versions of GNU tar.
  92
  93 TAR_OPTS
  94   Additionnal options that you may want to pass to tar. A typical value could
  95   be ``"--one-filesystem -S"``. The first option will skip all other mointpoints
  96   (very usefull if you have /dev, /proc, /sys or REPODIR mounted under a device
  97   that must be archived). The second one will try to deal with sparse files.
  98
  99 SNAPSHOT_MOUNTPOINT
 100   Sets the directory where the temporary LVM snapshots must be mounted.
 101
 102 SNAPSHOT_NAME
 103   The name to use for the snapshot volumes.
 104
 105 SNAPSHOT_SIZE
 106   Set the size of the snapshot volume. The same suffix than for lvcreate(8)
 107   are available.
 108
 109 USE_FTP
 110   Still TODO.
 111
 112
 113 Defining backups
 114 ----------------
 115
 116 The backups are defined in the file ``birochetab``. Here is a typical example
 117 for a Xen config where cottman is the dom0 and syrtis, kadarin, valeron are
 118 domUs ::
 119
 120   # Partition or LV           Snapshot    Host name     Volume name
 121   # ---------------------------------------------------------------
 122   /                           no          cottman       root
 123   /usr                        no          cottman       usr
 124
 125   /dev/vg00/valeron-root      yes         valeron       root
 126
 127   /dev/vg00/kadarin-root      yes         kadarin       root
 128   /dev/vg00/kadarin-home      yes         kadarin       home
 129
 130   /dev/vg00/syrtis-root       yes         syrtis        root
 131   /dev/vg00/syrtis-home       yes         syrtis        home
 132   /dev/vg00/syrtis-usr        yes         syrtis        usr
 133   /dev/vg00/syrtis-var        yes         syrtis        var
 134
 135 Blank lines, or lines beginning with # are ignored.
 136
 137 The first column defines the directory or logical volume to backup. In this
 138 example,the first two lines are plain directories, while the other ones point
 139 to LVM devices.
 140
 141 The second column specify if the backup should be taken from an LVM snapshot or
 142 not. It **must** be set to "no" for the backup of a directory and to "yes" for
 143 the backup of a logical volume.
 144
 145 The last two columns are more or less cosmetic, and define where the archive
 146 files will be stored, and how they'll be named. The destination directory will
 147 be created under the REPODIR_, and its name will be the value on the third
 148 column. Inside this directory, archive files will be named from the value given
 149 in the fourth column. For instance, a full and a differential backup for
 150 valeron would lead to the following structure ::
 151
 152   user:/REPODIR$ ls -l valeron/
 153   total 356544
 154   -rw-r--r-- 1 root root 363545613 Jan  3 03:10 root.full.20090103.tar.bz2
 155   -rw-r--r-- 1 root root    504722 Jan  3 03:10 root.full.snar
 156   -rw-r--r-- 1 root root    504725 Jan  4 04:06 root.incr.20090104.snar
 157   -rw-r--r-- 1 root root    160542 Jan  4 04:06 root.incr.20090104.tar.bz2
 158
 159
 160 Running Brioche
 161 ---------------
 162
 163 Brioche understands the following arguments:
 164
 165 -f, --full  Do a full backup (by default, brioche will do a differential).
 166 -h, --help  Show a very limited help.
 167
 168 When everything is ready, execute the ``brioche`` script as root. The
 169 script is pretty verbose, so don't panic if you see lots of lines scrolling in
 170 your terminal. By default, Brioche will try to make differential backups, but
 171 will gracefully fall back and do a full backup if none is available.
 172
 173 If all is fine, it can be added in the system crontab. Here's a suggestion for
 174 weekly full backup on Sunday, with differential during the weekdays ::
 175
 176   # Daily incremental backup
 177   30  3  *  *  1-6  /usr/local/bin/brioche > /var/log/backup.`date "+%a"`.log 2>&1
 178   # Weekly full backup on Sunday
 179   30  3  *  *  0  /usr/local/bin/brioche -f > /var/log/backup.`date "+%a"`.log 2>&1
 180
 181 The output of the script will be saved in /var/log/backup.DOW.log with DOW
 182 being the abbreviated day of the week (see man date(1) for the format).
 183
 184
 185 Bug reporting
 186 =============
 187
 188 There's no bugtracker for this project, your bug reports should be sent to the
 189 author : Amand Tihon <amand.tihon@alrj.org>. Please include as much information
 190 as possible in your report.
 191
 192
 193 References
 194 ==========
 195
 196 GNU tar documentation : http://www.gnu.org/software/tar/manual/
 197 LVM documentation and links : http://sourceware.org/lvm2/
 198
 199
 200
 201
 202