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.1
  10 :Date:      Jan 5th, 2008
  11 :Copyright: GNU GPL, see copyright file.
  12
  13 .. sectnum::
  14
  15 .. contents:: Table of contents
  16    :backlinks: none
  17
  18
  19 Abstract
  20 ========
  21
  22 Brioche is yet another backup shell script. Its main features are
  23
  24 - Full and differential backups
  25 - LVM snapshots
  26 - Xen oriented (somehow)
  27 - Upload to a distant FTP server.
  28
  29
  30 Rationale
  31 =========
  32
  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.
  39
  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.
  43
  44
  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.
  47
  48
  49 Getting Brioche
  50 ===============
  51
  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: ::
  54
  55   git clone http://git.alrj.org/git/brioche.git
  56
  57 A gitweb interface is also available at http://git.alrj.org/
  58
  59
  60 Requirements
  61 ============
  62
  63 Brioche relies on a few easily available free software :
  64
  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.
  70
  71 See the `References`_ section for links to the aforementioned softwares.
  72
  73
  74 Installation
  75 ============
  76
  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
  81 files under ``/etc``.
  82
  83
  84 Using Brioche
  85 =============
  86
  87 Configuration
  88 -------------
  89
  90 Edit the file ``brioche.conf`` to suit your needs. Each option is commented
  91 inline and will be detailed here.
  92
  93 BACKUPTAB
  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.
  97
  98 MAILTO
  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.
 101
 102 .. _REPODIR:
 103
 104 REPODIR
 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.
 109
 110 USAGE_WARN
 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.
 113
 114 COMPRESS
 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.
 118
 119 TAR_OPTS
 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
 124   sparse files.
 125
 126 SNAPSHOT_MOUNTPOINT
 127   Sets the directory where the temporary LVM snapshots must be mounted.
 128
 129 SNAPSHOT_NAME
 130   The name to use for the snapshot volumes.
 131
 132 SNAPSHOT_SIZE
 133   Set the size of the snapshot volume. The same suffix than for lvcreate(8)
 134   are available.
 135
 136 USE_FTP
 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.
 139
 140 FTP_HOST
 141   The address of the FTP server.
 142
 143 FTP_DIR
 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.
 146
 147 FTP_KEEP
 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.
 151
 152
 153 Defining backups
 154 ----------------
 155
 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
 158 domUs: ::
 159
 160   # Partition or LV           Snapshot    Host name     Volume name
 161   # ---------------------------------------------------------------
 162   /                           no          cottman       root
 163   /usr                        no          cottman       usr
 164
 165   /dev/vg00/valeron-root      yes         valeron       root
 166
 167   /dev/vg00/kadarin-root      yes         kadarin       root
 168   /dev/vg00/kadarin-home      yes         kadarin       home
 169
 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
 174
 175 Blank lines, or lines beginning with # are ignored.
 176
 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
 179 to LVM devices.
 180
 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.
 184
 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.
 191
 192 For instance, a full and a differential backup for the host valeron of the
 193 previous example would lead to the following structure: ::
 194
 195   user:/REPODIR$ ls -l valeron/
 196   total 356544
 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
 201
 202 +--------------------------------------------------------------------------+
 203 | **WARNING !**                                                            |
 204 |                                                                          |
 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``.      |
 207 |                                                                          |
 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 +--------------------------------------------------------------------------+
 212
 213
 214 Using FTP
 215 ---------
 216
 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_.
 221
 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.
 224
 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
 229 lines: ::
 230
 231   machine ftp.example.com
 232   login username
 233   password SikRet
 234
 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
 237 ``brioche.conf``.
 238
 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.
 246
 247 Here's what happens during the rotation:
 248
 249 - the oldest run is removed
 250 - all the ``run-X/`` directories are shifted (``run-3/`` becomes ``run-4/``,
 251   etc)
 252 - the ``latest/`` directory is renamed to ``run-1/``
 253 - a new, empty, ``latest/`` directory is created, ready to accept the new files.
 254
 255
 256
 257 Running Brioche
 258 ---------------
 259
 260 Brioche understands the following arguments:
 261
 262 -f, --full  Do a full backup (by default, brioche will try to do a
 263             differential).
 264 -h, --help  Show a very limited help.
 265
 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.
 270
 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: ::
 273
 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
 278
 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).
 281
 282
 283 Bug reporting
 284 =============
 285
 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.
 289
 290
 291
 292 References
 293 ==========
 294
 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/
 298
 299
 300
 301