Add more Makefile templates
[matthijs/upstream/backupninja.git] / README
1
2                                           |\_
3                  B A C K U P N I N J A   /()/
4                                          `\|
5                          
6       a silent flower blossom death strike to lost data.
7
8 Backupninja allows you to coordinate system backup by dropping a few
9 simple configuration files into /etc/backup.d/. Most programs you
10 might use for making backups don't have their own configuration file
11 format. Backupninja provides a centralized way to configure and
12 coordinate many different backup utilities. 
13
14 Features:
15  - easy to read ini style configuration files.
16  - you can drop in scripts to handle new types of backups.
17  - backup actions can be scheduled
18  - you can choose when status report emails are mailed to you
19    (always, on warning, on error, never).
20  - console-based wizard (ninjahelper) makes it easy to create
21    backup action configuration files.
22  - passwords are never sent via the command line to helper programs.
23  - works with Linux-Vservers (http://linux-vserver.org/)
24  
25 Backup types:
26  - secure, remote, incremental filesytem backup (via rdiff-backup).
27    incremental data is compressed. permissions are retained even
28    with an unpriviledged backup user.
29  - backup of mysql databases (via mysqlhotcopy and mysqldump).
30  - backup of ldap databases (via slapcat and ldapsearch).
31  - basic system and hardware info
32  - encrypted remote backups (via duplicity).    
33  - backup of subversion repositories.
34
35 The following options are available:
36 -h, --help           This usage message
37 -d, --debug          Run in debug mode, where all log messages are
38                      output to the current shell.
39 -f, --conffile FILE  Use FILE for the main configuration instead
40                      of /etc/backupninja.conf
41 -t, --test           Test run mode. This will test if the backup could run, without actually
42                      preforming any backups. For example, it will attempt to authenticate
43                      or test that ssh keys are set correctly.
44 -n, --now            Perform actions now, instead of when they might be scheduled.
45                      No output will be created unless also run with -d.
46 --run FILE           Runs the specified action FILE (e.g. one of the /etc/backup.d/ files).
47                      Also puts backupninja in debug mode.
48
49 CONFIGURATION FILES
50 ===================
51
52 The general configuration file is /etc/backupninja.conf. In this file
53 you can set the log level and change the default directory locations.
54 You can force a different general configuration file with "backupninja
55 -f /path/to/conf".
56
57 To preform the actual backup, backupninja processes each configuration
58 file in /etc/backup.d according to the file's suffix:
59  
60   .sh      --  run this file as a shell script.
61   .rdiff   --  filesystem backup (using rdiff-backup)
62   .dup     --  filesystem backup (using duplicity)
63   .mysql   --  backup mysql databases
64   .ldap    --  backup ldap databases
65   .pgsql   --  backup PostgreSQL databases
66   .sys     --  general hardware, partition, and system reports.
67   .svn     --  backup subversion repositories
68   .maildir --  incrementally backup maildirs (very specialized)
69
70 Support for additional configuration types can be added by dropping
71 bash scripts with the name of the suffix into /usr/share/backupninja. 
72
73 The configuration files are processed in alphabetical order. However,
74 it is suggested that you name the config files in "sysvinit style." 
75
76 For example:
77         00-disabled.ldap
78         10-runthisfirst.sh
79         20-runthisnext.mysql
80         90-runthislast.rdiff
81
82 Typically, you will put a '.rdiff' config file last, so that any
83 database dumps you make are included in the filesystem backup.
84 Configurations files with names beginning with 0 (zero) or ending with
85 .disabled (preferred method) are skipped.
86
87 Unless otherwise specified, the config file format is "ini style."
88
89 For example:
90
91    # this is a comment
92    
93    [fishes]
94    fish = red
95    fish = blue
96
97    [fruit]
98    apple = yes
99    pear = no thanks \
100    i will not have a pear.
101
102
103 SCHEDULING
104 ==========
105
106 By default, each configuration file is processed everyday at 01:00 (1
107 AM). This can be changed by specifying the 'when' option in a config
108 file.
109
110 For example:
111
112   when = sundays at 02:00
113   when = 30th at 22
114   when = 30 at 22:00
115   when = everyday at 01            <-- the default
116   when = Tuesday at 05:00
117
118 A configuration file will be processed at the time(s) specified by the
119 "when" option. If multiple "when" options are present, then they all
120 apply. If two configurations files are scheduled to run in the same
121 hour, then we fall back on the alphabetical ordering specified above.
122 If two configurations files are scheduled close to one another in
123 time, it is possible to have multiple copies of backupninja running if
124 the first instance is not finished before the next one starts.
125
126 Make sure that you put the "when" option before any sections in your
127 configuration file.
128
129 These values for 'when' are equivalent:
130
131   when = tuesday at 05:30
132   when = TUESDAYS at 05
133
134 These values for 'when' are invalid:
135   
136   when = tuesday at 2am
137   when = tuesday at 2
138   when = tues at 02
139
140
141 REAL WORLD USAGE
142 ================
143
144 Backupninja can be used to implement whatever backup strategy you
145 choose. It is intended, however, to be used like so:
146
147 (1) First, databases are safely copied or exported to /var/backups.
148     Typically, you cannot make a file backup of a database while it
149     is in use, hence the need to use special tools to make a safe copy
150     or export into /var/backups.
151      
152 (2) Then, vital parts of the file system, including /var/backups, are
153     nightly pushed to a remote, off-site, hard disk (using
154     rdiff-backup). The local user is root, but the remote user is not
155     priviledged. Hopefully, the remote filesystem is encrypted. 
156
157 There are many different backup strategies out there, including "pull
158 style", magnetic tape, rsync + hard links, etc. We believe that the
159 strategy outlined above is the way to go because: (1) hard disks are
160 very cheap these days, (2) pull style backups are no good, because then
161 the backup server must have root on the production server, and (3)
162 rdiff-backup is more space efficient and featureful than using rsync +
163 hard links. 
164
165
166 SSH KEYS
167 ========
168
169 In order for rdiff-backup to sync files over ssh unattended, you must
170 create ssh keys on the source server and copy the public key to the
171 remote user's authorized keys file. For example:
172
173   root@srchost# ssh-keygen -t dsa
174   root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost 
175
176 Now, you should be able to ssh from user 'root' on srchost to
177 user 'backup' on desthost without specifying a password.
178
179 Note: when prompted for a password by ssh-keygen, just leave it
180 blank by hitting return.
181
182 The included helper program "ninjahelper" will walk you through creating
183 an rdiff-backup configuration, and will set up the ssh keys for you.
184
185 INSTALLATION
186 ============
187    
188 Requirements:
189   apt-get install bash gawk
190
191 Recommended: 
192   apt-get install rdiff-backup gzip hwinfo
193
194 Files:
195   /usr/sbin/backupninja        -- main script
196   /etc/cron.d/backupninja      -- runs main script nightly
197   /etc/logrotate.d/backupninja -- rotates backupninja.log
198   /etc/backup.d/               -- directory for configuration files
199   /etc/backupninja.conf        -- general options 
200   /usr/share/backupninja       -- handler scripts which do the actual work
201
202 Installation:
203   There is no install script, but you just need to move files to the
204   correct locations. All files should be owned by root.
205  
206   # tar xvzf backupninja.tar.gz
207   # cd backupninja
208   # mv backupninja /usr/sbin/backupninja
209   # mv ninjahelper /usr/sbin/ninjahelper
210   # mv etc/logrotate.d/backupninja /etc/logrotate.d/backupninja
211   # mv etc/cron.d/backupninja /etc/cron.d/backupninja
212   # mkdir /etc/backup.d/
213   # mv etc/backupninja.conf /etc/backupninja.conf
214   # mv handlers /usr/share/backupninja
215
216
217 VSERVERS
218 ========
219
220 If you are using Linux-Vservers (http://linux-vserver.org/) there are some
221 special capabilities that different handlers have to make vserver backups easier.
222 Set the variable "vservers" to be "yes" in /etc/backupninja.conf and see the
223 example configuration files for each handler to configure the vserver specific
224 variables.
225
226 Additional vserver variables that can be configured in /etc/backupninja.conf. but
227 probably don't need to be changed:
228
229 VSERVERINFO (default: /usr/sbin/vserver-info)
230 VSERVER (default: /usr/sbin/vserver)
231 VROOTDIR (default: `$VSERVERINFO info SYSINFO |grep vserver-Rootdir | awk '{print $2}'`)
232
233 NINJAHELPER
234 ===========
235
236 Ninjahelper is an additional script which will walk you through the process of
237 configuring backupninja. Ninjahelper has a menu driven curses based interface
238 (using dialog). 
239
240 To add an additional 'wizard' to ninjahelper, follow these steps:
241
242 (1) to add a helper for the handler "blue", create the file
243     blue.helper in the directory where the handlers live.
244     (ie /usr/share/backupninja).
245
246 (2) next, you need to add your helper to the global HELPERS variable
247     and define the main function for your helper (the function name
248     is always <helper>_wizard). for example, blue.helper:
249        HELPERS="$HELPERS blue:description_of_this_helper"
250        blue_wizard() {
251          ... do work here ...
252        }
253
254 (3) check the examples of the included helpers to see how they are
255     written. The dialog functions are defined in easydialog.sh.
256