added ninjahelper
[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  - secure, remote, incremental filesytem backup (via rdiff-backup).
17    incremental data is compressed. permissions are retained even
18    with an unpriviledged backup user.
19  - backup of mysql databases (via mysqlhotcopy and mysqldump).
20  - backup of ldap databases (via slapcat and ldapsearch).
21  - passwords are never sent via the command line to helper programs.
22  - you can drop in scripts to handle new types of backups.
23  - backup actions can be scheduled
24  - you can choose when status report emails are mailed to you
25    (always, on warning, on error, never).
26  - works with Linux-Vservers (http://linux-vserver.org/)
27  
28 The following options are available:
29 -h, --help           This usage message
30 -d, --debug          Run in debug mode, where all log messages are
31                      output to the current shell.
32 -f, --conffile FILE  Use FILE for the main configuration instead
33                      of /etc/backupninja.conf
34 -t, --test           Run in test mode, no actions are actually taken.
35 -n, --now            Perform actions now, instead of when they
36                      might be scheduled.
37 --run FILE           runs the specified action FILE (e.g. one of the /etc/backup.d/ files)
38
39 CONFIGURATION FILES
40 ===================
41
42 The general configuration file is /etc/backupninja.conf. In this file
43 you can set the log level and change the default directory locations.
44 You can force a different general configuration file with "backupninja
45 -f /path/to/conf".
46
47 To preform the actual backup, backupninja processes each configuration
48 file in /etc/backup.d according to the file's suffix:
49  
50   .sh      --  run this file as a shell script.
51   .rdiff   --  this is a configuration for rdiff-backup
52   .maildir --  this is a configuration to backup maildirs
53   .dup     --  this is a configuration for duplicity
54   .mysql   --  mysql backup configuration
55   .ldap    --  ldap backup configuration
56   .sys     --  general system reports
57   .svn     --  subversion repository backups
58
59 Support for additional configuration types can be added by dropping
60 bash scripts with the name of the suffix into /usr/share/backupninja. 
61
62 The configuration files are processed in alphabetical order. However,
63 it is suggested that you name the config files in "sysvinit style." 
64
65 For example:
66         00-disabled.ldap
67         10-runthisfirst.sh
68         20-runthisnext.mysql
69         90-runthislast.rdiff
70
71 Typically, you will put a '.rdiff' config file last, so that any
72 database dumps you make are included in the filesystem backup. 
73 Configurations files which begin with 0 (zero) are skipped.
74
75 Unless otherwise specified, the config file format is "ini style."
76
77 For example:
78
79    # this is a comment
80    
81    [fishes]
82    fish = red
83    fish = blue
84
85    [fruit]
86    apple = yes
87    pear = no thanks \
88    i will not have a pear.
89
90
91 SCHEDULING
92 ==========
93
94 By default, each configuration file is processed everyday at 01:00 (1
95 AM). This can be changed by specifying the 'when' option in a config
96 file.
97
98 For example:
99
100   when = sundays at 02:00
101   when = 30th at 22
102   when = 30 at 22:00
103   when = everyday at 01            <-- the default
104   when = Tuesday at 05:00
105
106 A configuration file will be processed at the time(s) specified by the
107 "when" option. If multiple "when" options are present, then they all
108 apply. If two configurations files are scheduled to run in the same
109 hour, then we fall back on the alphabetical ordering specified above.
110 If two configurations files are scheduled close to one another in
111 time, it is possible to have multiple copies of backupninja running if
112 the first instance is not finished before the next one starts.
113
114 These values for 'when' are equivalent:
115
116   when = tuesday at 05:30
117   when = TUESDAYS at 05
118
119 These values for 'when' are invalid:
120   
121   when = tuesday at 2am
122   when = tuesday at 2
123   when = tues at 02
124
125
126 REAL WORLD USAGE
127 ================
128
129 Backupninja can be used to impliment whatever backup strategy you
130 choose. It is intended, however, to be used like so:
131
132 (1) First, databases are safely copied or exported to /var/backups.
133     Typically, you cannot make a file backup of a database while it
134     is in use, hence the need to use special tools to make a safe copy
135     or export into /var/backups.
136      
137 (2) Then, vital parts of the file system, including /var/backups, are
138     nightly pushed to a remote, off-site, hard disk (using
139     rdiff-backup). The local user is root, but the remote user is not
140     priviledged. Hopefully, the remote filesystem is encrypted. 
141
142 There are many different backup strategies out there, including "pull
143 style", magnetic tape, rsync + hard links, etc. We believe that the
144 strategy outlined above is the way to go because: (1) hard disks are
145 very cheap these days, (2) pull style backups are no good, because then
146 the backup server must have root on the production server, and (3)
147 rdiff-backup is more space efficient and featureful than using rsync +
148 hard links. 
149
150
151 SSH KEYS
152 ========
153
154 In order for rdiff-backup to sync files over ssh unattended, you must
155 create ssh keys on the source server and copy the public key to the
156 remote user's authorized keys file. For example:
157
158   root@srchost# ssh-keygen -t dsa
159   root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost 
160
161 Now, you should be able to ssh from user 'root' on srchost to
162 user 'backup' on desthost without specifying a password.
163
164 Note: when prompted for a password by ssh-keygen, just leave it
165 blank by hitting return.
166
167
168 INSTALLATION
169 ============
170    
171 Requirements:
172   apt-get install bash gawk
173
174 Recommended: 
175   apt-get install rdiff-backup gzip hwinfo
176
177 Files:
178   /usr/sbin/backupninja        -- main script
179   /etc/cron.d/backupninja      -- runs main script nightly
180   /etc/logrotate.d/backupninja -- rotates backupninja.log
181   /etc/backup.d/               -- directory for configuration files
182   /etc/backupninja.conf        -- general options 
183   /usr/share/backupninja       -- handler scripts which do the actual work
184
185 Installation:
186   There is no install script, but you just need to move files to the
187   correct locations. All files should be owned by root.
188  
189   # tar xvzf backupninja.tar.gz
190   # cd backupninja
191   # mv backupninja /usr/sbin/backupninja
192   # mv etc/logrotate.d/backupninja /etc/logrotate.d/backupninja
193   # mv etc/cron.d/backupninja /etc/cron.d/backupninja
194   # mkdir /etc/backup.d/
195   # mv etc/backupninja.conf /etc/backupninja.conf
196   # mv handlers /usr/share/backupninja
197
198
199 VSERVERS
200 ========
201
202 If you are using Linux-Vservers (http://linux-vserver.org/) there are some
203 special capabilities that different handlers have to make vserver backups easier.
204 Set the variable "vservers" to be "yes" in /etc/backupninja.conf and see the
205 example configuration files for each handler to configure the vserver specific
206 variables.
207
208 Additional vserver variables that can be configured in /etc/backupninja.conf. but
209 probably don't need to be changed:
210
211 VSERVERINFO (default: /usr/sbin/vserver-info)
212 VSERVER (default: /usr/sbin/vserver)
213 VROOTDIR (default: `$VSERVERINFO info SYSINFO |grep vserver-Rootdir | awk '{print $2}'; fi`)
214