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
  74 Order is important, since all files are read (if possible) and values in the
  75 last configuration file read overwrites old values. The script takes an optional
  76 parameter, which is another location to look for a configuration file. The
  77 configuration file passed as argument will be read last, and an error will be
  78 printed if can't be found (no error is issued if any of the other configuration
  79 files are missing).
  80
  81 The configuration file is a Bash_ script too, and these are the default values:
  82
  83 .. include:: bacap
  84         :literal:
  85         :start-after: #_INCLUDE_START_
  86         :end-before: #_INCLUDE_END_
  87
  88 Once you've created the configuration file(s), you should create the directory
  89 ``$CONFIG_PATH`` (meaning, the value you used for that variable in the
  90 configuration file)::
  91
  92         mkdir -p $CONFIG_PATH
  93
  94 The create a directory for each host you want to backup there, the directory
  95 name should be the name of the host (as you would use to connect to it using
  96 ssh_). For now let's say we will only backup ``localhost``::
  97
  98         mkdir $CONFIG_PATH/$LOCALHOST
  99
 100 You should be able to guess what ``$LOCALHOST`` stands for by now =)
 101
 102 Now, you should create at least one file there, ``paths`` which should have one
 103 line for each path to backup in that host. Let's say we want to backup only
 104 ``/etc`` and ``/home``::
 105
 106         echo /etc > $CONFIG_PATH/$LOCALHOST/paths
 107         echo /home > $CONFIG_PATH/$LOCALHOST/paths
 108
 109 But sometimes there are things there that you don't want to backup, in that
 110 case you can create a file named ``excludes`` too, and write which paths you
 111 want to exclude there, one path in each line (you can use wildcards and anything
 112 supported by the ``--exclude-from`` rsync_ option). Let's say we don't want to
 113 backup rata's home::
 114
 115         echo /home/rata/ > $CONFIG_PATH/$LOCALHOST/excludes
 116
 117 That's pretty much it. If you want to add other hosts, just create the host
 118 directory and the needed host configuration files.
 119
 120 You may want to automate it using *cron*. I will not include a *cron* tutorial
 121 here, but if you are completely lost, you can add this line to ``/etc/crontab``
 122 to make a daily backup at 6:30::
 123
 124         25 6 * * * root /path/to/bacap
 125
 126 If you are a Debian_ user, you can also simply install the script in
 127 ``/etc/cron.daily`` (or make a symlink or something similar) and you are set.
 128
 129 .. _Debian: http://www.debian.org/
 130
 131
 132
 133 Usage
 134 =====
 135
 136 As we said in the configuration section, the only argument the script take is an
 137 extra configuration file. All options are managed through configurations files.
 138
 139 The script creates a new directory in ``$BACKUP_PATH/$host/$date`` and copies
 140 (hard-links) the configured paths for each ``$host``. ``$date`` is the current
 141 date at the time of starting the script, formated according to ``$DATE_FMT``. By
 142 default this has day *resolution*, but you can add hours, minutes or even
 143 seconds if you want to do more frequent backups. If the directory already exist
 144 for any host, it skips that host.
 145
 146 A symbolic link is created at the end of the backup, with the name
 147 ``$BACKUP_PATH/$host/current``, and pointing to the newly created directory.
 148
 149
 150
 151 Similar alternatives
 152 ====================
 153
 154 * Do it yourself: this script was **heavily** inspired by an article__ by `Kevin
 155   Korb`__ (well, it was really inspired by the `previous version`__ of the
 156   article =).
 157 * `Back In Time`__: Nice looking graphical alternative.
 158 * `rsnapshot`__: A more mature and heavier alternative. I didn't really used it
 159   though, so I can't say much.
 160
 161 __ http://www.sanitarium.net/golug/rsync_backups_2010.html
 162 __ http://www.sanitarium.net/
 163 __ http://www.sanitarium.net/golug/rsync_backups_2005.html
 164
 165 __ http://backintime.le-web.org/
 166
 167 __ http://rsnapshot.org/
 168
 169
 170 I'm sure there are plenty of others, if you have one and want to be listed here,
 171 please feel free to `drop me an e-mail`__.
 172
 173 __ mailto:luca@llucax.com.ar
 174
 175