README

   1 .. -*- restructuredtext -*-
   2
   3
   4 ==========================================
   5 Bacap - The extremely simple backup script
   6 ==========================================
   7
   8 :Author: Leandro Lucarella
   9 :Contact: luca@llucax.com.ar
  10 :Copyright: Leandro Lucarella (2010), released under the BOLA_ license
  11
  12 .. _BOLA: http://blitiri.com.ar/p/bola/
  13
  14
  15
  16 About
  17 =====
  18
  19 Bacap_ is a very simple script (~100 SLOC_ of Bash_) to do an incremental backup
  20 that saves space using rsync_ and hard-links. Is not the first, and it probably
  21 will not be the last, so why should you use precisely this one? I have **no**
  22 idea. All I can tell you is:
  23
  24 1. I did it, so it has to be great!
  25 2. Is very simple, meaning is very easy to understand and customize.
  26 3. You can backup multiple hosts.
  27
  28 Did I mention is very simple? I guess that is the only selling point, so
  29 remember: **It's very simple** =)
  30
  31 .. _Bacap: http://www.llucax.com.ar/proj/bacap/
  32 .. _SLOC: http://en.wikipedia.org/wiki/Source_lines_of_code
  33 .. _Bash: http://www.gnu.org/software/bash/
  34 .. _rsync: http://rsync.samba.org/
  35
  36
  37
  38 Instalation
  39 ===========
  40
  41 Doing something very complex in ~100 SLOC_ is not easy, unless you're standing
  42 in the shoulders of giants. I'm standing in the shoulders of rsync_ mainly, so
  43 you should install it before using the script. You will need a bunch of `basic
  44 POSIX commands`__, like ``date``, ``dirname``, ``readlink``, ``basename``,
  45 ``cat``, ``awk``, etc.; and ``crontab`` if you don't want to run the script
  46 manually each time you remember to actually do a backup; but I'm sure you
  47 already have those.  And of course, Bash_, but again, I'm sure you have it too.
  48 If you want to backup remote hosts, be sure ssh_ is installed too.
  49
  50 __ http://www.opengroup.org/onlinepubs/009695399/utilities/toc.html
  51 .. _ssh: http://www.openssh.com/
  52
  53 Once you have it all, just `download the script`__ from the git_ repo__ and copy
  54 it to wherever you like. Set the executable bit if appropriate::
  55
  56         chmod a+x bacap
  57
  58 __ http://git.llucax.com.ar/w/software/bacap.git?a=blob_plain;f=bacap;hb=HEAD
  59 __ http://git.llucax.com.ar/w/software/bacap.git
  60 .. _git: http://git-scm.com/
  61
  62
  63
  64 Configuration
  65 =============
  66
  67 If you don't like the defaults (you probably wont), you can add a configuration
  68 file. Configuration files are searched in this places:
  69
  70 1. ``/etc/bacaprc``
  71 2. ``/etc/bacap/bacaprc``
  72 3. ``bacaprc`` in the same directory as the ``bacap`` script
  73 4. Optional parameter passed as argument to the script
  74 5. ``$CONFIG_PATH/$HOST/bacaprc``
  75
  76 Order is important, since all files are read (if possible) and values in the
  77 last configuration file read overwrites old values. The script takes an optional
  78 parameter, which is another location to look for a configuration file. If the
  79 configuration file passed as argument can't be found, an error will be printed
  80 (no error is issued if any of the other configuration files are missing).
  81 Also, config options could be specified on a per host basis by creating a
  82 ``bacaprc`` file in ``$CONFIG_PATH/$HOST``. As a side effect of this,
  83 configuration file(s) are read initially and each time the script backups a new
  84 host. So the configuration file(s) are read at least two times even if you
  85 backup one host.
  86
  87 The configuration file is a Bash_ script too, and these are the default values:
  88
  89 .. include:: bacap
  90         :literal:
  91         :start-after: #_INCLUDE_START_
  92         :end-before: #_INCLUDE_END_
  93
  94 Once you've created the configuration file(s), you should create the directory
  95 ``$CONFIG_PATH`` (meaning, the value you used for that variable in the
  96 configuration file)::
  97
  98         mkdir -p $CONFIG_PATH
  99
 100 Then create a directory for each host you want to backup there, the directory
 101 name should be the name of the host (as you would use to connect to it using
 102 ssh_). For now let's say we will only backup ``localhost``::
 103
 104         mkdir $CONFIG_PATH/$LOCALHOST
 105
 106 You should be able to guess what ``$LOCALHOST`` stands for by now =)
 107
 108 Now, you should create at least one file there, ``paths`` which should have one
 109 line for each path to backup in that host. Let's say we want to backup only
 110 ``/etc`` and ``/home``::
 111
 112         echo /etc > $CONFIG_PATH/$LOCALHOST/paths
 113         echo /home >> $CONFIG_PATH/$LOCALHOST/paths
 114
 115 But sometimes there are things there that you don't want to backup, in that
 116 case you can create a file named ``excludes`` too, and write which paths you
 117 want to exclude there, one path in each line (you can use wildcards and anything
 118 supported by the ``--exclude-from`` rsync_ option). Let's say we don't want to
 119 backup rata's home::
 120
 121         echo /home/rata/ > $CONFIG_PATH/$LOCALHOST/excludes
 122
 123 Also, if you don't want to exclude files matching some pattern, you can create
 124 a file named ``includes`` with the patterns you want to include (you can use
 125 anything supported by the ``--include-from`` rsync_ option)
 126
 127 That's pretty much it. If you want to add other hosts, just create the host
 128 directory and the needed host configuration files.
 129
 130
 131
 132 Usage
 133 =====
 134
 135 As we said in the configuration section, the only argument the script take is an
 136 extra configuration file. All options are managed through configurations files.
 137
 138 The script creates a new directory in ``$BACKUP_PATH/$host/$date`` and copies
 139 (hard-links) the configured paths for each ``$host``. ``$date`` is the current
 140 date at the time of starting the script, formated according to ``$DATE_FMT``. By
 141 default this has day *resolution*, but you can add hours, minutes or even
 142 seconds if you want to do more frequent backups. If the directory already exist
 143 for any host, it skips that host.
 144
 145 A symbolic link is created at the end of the backup, with the name
 146 ``$BACKUP_PATH/$host/current``, and pointing to the newly created directory.
 147
 148
 149
 150 Tips
 151 ====
 152
 153 Here are a few tips on how to configure Bacap_ for several common scenarios.
 154
 155 Automating backups using cron
 156 -----------------------------
 157
 158 You probably want to automate your backup using *cron*. I will not include
 159 a *cron* tutorial here, but if you are completely lost, you can add this line to
 160 ``/etc/crontab`` to make a daily backup at 6:30::
 161
 162         30 6 * * * root /path/to/bacap
 163
 164 If you are a Debian_ user, you can also simply install the script in
 165 ``/etc/cron.daily`` (or make a symlink or something similar) and you are set.
 166
 167 .. _Debian: http://www.debian.org/
 168
 169
 170 Providing a ssh_ key
 171 --------------------
 172
 173 When doing a backup of a remote host, you probably want ssh_ to be able to login
 174 without providing a password. To do so, you can generate a ssh_ key, copy the
 175 public key to the target's ``/root/.ssh/authorized_keys`` (or the user that runs
 176 the backup) and set the Bacap_ configuration variable ``RSYNC_RSH`` to something
 177 like::
 178
 179         RSYNC_RSH="ssh -i /path/to/priv-key -o NumberOfPasswordPrompts=0"
 180
 181 The ``-o NumberOfPasswordPrompts=0`` is not necessary, but you would appreciate
 182 it if something is wrong with your key, since if you don't use it, rsync_ will
 183 hang asking for a password.
 184
 185
 186 Backup local networks nodes (or nodes with a fast connection)
 187 -------------------------------------------------------------
 188
 189 When the bandwidth is not tight, you probably want to ensure ssh_ doesn't use
 190 compression::
 191
 192         RSYNC_RSH="ssh -o Compression=no"
 193
 194 And if your network is trusted, you probably don't need very string encryption
 195 either::
 196
 197         RSYNC_RSH="ssh -o Compression=no -c arcfour"
 198
 199
 200 Listing differences between 2 snapshots
 201 ---------------------------------------
 202
 203 If you want to see what have actually changed between two backups you can run
 204 rsync_ with your usual flags plus ``-nv --delete``. For example if you just use
 205 ``-a``, to see the differences between ``lolaus/2010-07-11`` and
 206 ``lolaus/2010-07-12`` you can run::
 207
 208         rsync -nav --delete lolaus/2010-07-11/ lolaus/2010-07-12/
 209
 210
 211
 212 Similar alternatives
 213 ====================
 214
 215 * Do it yourself: this script was **heavily** inspired by an article__ by `Kevin
 216   Korb`__ (well, it was really inspired by the `previous version`__ of the
 217   article =).
 218 * `Back In Time`__: Nice looking graphical alternative.
 219 * `rsnapshot`__: A more mature and heavier alternative. I didn't really used it
 220   though, so I can't say much.
 221
 222 __ http://www.sanitarium.net/golug/rsync_backups_2010.html
 223 __ http://www.sanitarium.net/
 224 __ http://www.sanitarium.net/golug/rsync_backups_2005.html
 225
 226 __ http://backintime.le-web.org/
 227
 228 __ http://rsnapshot.org/
 229
 230
 231 I'm sure there are plenty of others, if you have one and want to be listed here,
 232 please feel free to `drop me an e-mail`__.
 233
 234 __ mailto:luca@llucax.com.ar
 235
 236