]> git.llucax.com Git - software/bacap.git/blob - README
Use $HOSTNAME as the default name of the local host
[software/bacap.git] / 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 The 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 You may want to automate it using *cron*. I will not include a *cron* tutorial
131 here, but if you are completely lost, you can add this line to ``/etc/crontab``
132 to make a daily backup at 6:30::
133
134         25 6 * * * root /path/to/bacap
135
136 If you are a Debian_ user, you can also simply install the script in
137 ``/etc/cron.daily`` (or make a symlink or something similar) and you are set.
138
139 .. _Debian: http://www.debian.org/
140
141
142
143 Usage
144 =====
145
146 As we said in the configuration section, the only argument the script take is an
147 extra configuration file. All options are managed through configurations files.
148
149 The script creates a new directory in ``$BACKUP_PATH/$host/$date`` and copies
150 (hard-links) the configured paths for each ``$host``. ``$date`` is the current
151 date at the time of starting the script, formated according to ``$DATE_FMT``. By
152 default this has day *resolution*, but you can add hours, minutes or even
153 seconds if you want to do more frequent backups. If the directory already exist
154 for any host, it skips that host.
155
156 A symbolic link is created at the end of the backup, with the name
157 ``$BACKUP_PATH/$host/current``, and pointing to the newly created directory.
158
159
160
161 Similar alternatives
162 ====================
163
164 * Do it yourself: this script was **heavily** inspired by an article__ by `Kevin
165   Korb`__ (well, it was really inspired by the `previous version`__ of the
166   article =).
167 * `Back In Time`__: Nice looking graphical alternative.
168 * `rsnapshot`__: A more mature and heavier alternative. I didn't really used it
169   though, so I can't say much.
170
171 __ http://www.sanitarium.net/golug/rsync_backups_2010.html
172 __ http://www.sanitarium.net/
173 __ http://www.sanitarium.net/golug/rsync_backups_2005.html
174
175 __ http://backintime.le-web.org/
176
177 __ http://rsnapshot.org/
178
179
180 I'm sure there are plenty of others, if you have one and want to be listed here,
181 please feel free to `drop me an e-mail`__.
182
183 __ mailto:luca@llucax.com.ar
184
185