1SAFEKEEP.BACKUP(5) [FIXME: manual] SAFEKEEP.BACKUP(5)
2
6 safekeep.backup - Configuration file for a 'safekeep(1)' client
7
9 These files are usually placed in /etc/safekeep/backup.d/ to be picked
10 up automatically by safekeep(1). They must have a .backup extension.
11
13 Each configuration file controls the backup of a host. They are
14 typically named after the hostname of the machine they control the
15 backup for, and have a .backup extension (e.g. mailbox.backup). These
16 files are written in XML. Virtually all elements and attributes are
17 optional; if not present, safekeep(1) will provide reasonable, useful
18 defaults.
19 The full set of supported elements and attributes looks as follows:
21 <backup id="my_workstation">
24 <!-- the client backup host, the user under which the servers will connect,
26 the SSH keys used for control and data transfer -->
27 <host
28 name="myhost" user="root" nice="10"
29 key-ctrl="/home/jdoe/.ssh/backup_id_dsa"
30 key-data="/home/jdoe/.ssh/backup2_id_dsa"
31 />
32 <!-- you can customize the bandwidth limit on a client basis,
34 for example to 50KB/s download/upload -->
35 <bandwidth overall="80" download="50" upload="50" />
36 <!-- location where the backups will be stored on the server
38 and for how long (D=days, W=weeks, M=months, or Y=years) -->
39 <repo path="./data" retention="10D"/>
40 <!-- settings for database dump and for volume snapshot -->
42 <setup>
43 <!-- database type ("postgres" or "mysql"), and database name,
44 DB user with backup rights, location of the dump file on the client
45 host, and flag to remove or not the dump file after the backup is done.
46 Databases can be dumped individually using a dump clause for each database. -->
47 <dump
48 type="postgres"
49 db="my_db"
50 dbuser="foobar"
51 options="--schema=public"
52 file="/var/backup/dumps/mydata"
53 cleanup="true"
54 />
55 <!-- what volume is to be snapshot (device location) and the size
57 of the snapshot (free space must exist in the volume group) -->
58 <snapshot
59 device="/path/to/volume"
60 size="500M"
61 />
62 <!-- location of a script to be executed on the client at different
64 stages of the run. It is called with three arguments:
65 the step of the backup, backup id and the backup root directory -->
66 <script
67 path="/path/to/script"
68 />
69 </setup>
71 <!-- data to be backup -->
73 <data exclude-fifos="true" exclude-sockets="true">
74 <!-- each type of tag can be present more than one time -->
75 <!-- if a database dump was created, it must be added in this section -->
76 <include path="/home"/>
77 <exclude path="/home/guest"/>
78 <include glob="**/important/"/>
80 <exclude glob="/home/*/tmp"/>
81 <include regexp=".*\.ogg"/>
83 <exclude regexp=".*\.mp3"/>
84 </data>
85 </backup>
86
88 XML elements and attributes are referred to via XPath expressions:
89 elements are separated by /, attributes are introduced by @:
90 /backup
92 The root element of the XML file. Mandatory.
93 /backup/@id
95 This is the ID by which safekeep(1) will address this host. If
96 specified it overrides the default value derived from the filename.
97 Optional, defaults to the filename without the .backup extension.
98 Use of the default value is highly recommended.
99 /backup/host/@name
101 The name or IP address of the client. If you need to backup the box
102 that the server is running from, you can set this to "localhost".
103 This is different from leaving it blank, as it will establish a SSH
104 session and use the user specified by /backup/host/@user. Optional,
105 defaults to local access.
106 /backup/host/@user
108 The user name to use when connecting to the client. This user must
109 have read permissions for the files that will be backed up, so it
110 most likely needs to be root. Optional, defaults to root.
111 /backup/host/@nice
113 The nice adjustment for the client. This settings is normally not
114 all that important, as most of the load rests on the server side.
115 NB: if you change this value, you will have to re-deploy the auth
116 keys. Optional, defaults to no nice level.
117 /backup/host/@key-ctrl
119 This is the private key used to establish the SSH connection to the
120 client for the control channel. Use of the default value is
121 recommended. Optional, defaults to ~/.ssh/safekeep-server-ctrl-key.
122 /backup/host/@key-data
124 This is the private key used to establish the SSH connection to the
125 client for the data channel. Use of the default value is
126 recommended. Optional, defaults to ~/.ssh/safekeep-server-data-key.
127 /backup/bandwidth/@overall
129 This is the client bandwidth limit for both upload and download. It
130 is an integer number of KB/s (see the NOTES section in
131 safekeep.conf(5) for more information). Optional, overrides
132 bandwidth.overall in safekeep.conf(5) if specified.
133 /backup/bandwidth/@download
135 This is the client bandwidth limit for download (see
136 /backup/bandwidth/@overall for more information). Optional,
137 overrides /backup/bandwidth/@overall if specified.
138 /backup/bandwidth/@upload
140 This is the client bandwidth limit for upload (see
141 /backup/bandwidth/@overall for more information). Optional,
142 overrides /backup/bandwidth/@overall if specified.
143 /backup/repo/@path
145 The path under which the backups will be stored. Relative paths are
146 based on the base.dir setting from the safekeep.conf(5). Since the
147 default value for base.dir is the user’s home directory, in a
148 typical installation the data will be stored under
149 /var/lib/safekeep/<id>/. If the directory does not exist,
150 safekeep(1) will attempt to create it automatically. The backup
151 will fail altogether if the directory can not be created. Optional,
152 defaults to the client ID, see /backup/@id. Use of the default
153 value is highly recommended. NOTE: if you must set this value
154 explicitly, you must make sure that the path is not shared between
155 different boxes; a shared repository path will result in data loss.
156 /backup/repo/@retention
158 Specifies the duration for which the backup data will be retained.
159 The incremental backup information in the destination directory
160 that has been around longer than the retention time will be
161 removed. The value specified by this attribute is an time interval:
162 an integer followed by the character s, m, h, D, W, M, or Y,
163 indicating seconds, minutes, hours, days, weeks, months, or years
164 respectively, or a number of these concatenated. For example, 32m
165 means 32 minutes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours,
166 and 7 seconds. In this context, a month means 30 days, a year is
167 365 days, and a day is always 86400 seconds. Note that backups of
168 deleted files are covered by this operation. Thus if you deleted a
169 file two weeks ago, backed up immediately afterward, and then ran
170 safekeep(1) with a retention of 10D today, no trace of that file
171 would remain. Finally, file selection options don’t affect removal
172 of incremental data. Optional, defaults to empty (unlimited
173 retention).
174 /backup/options/special-files/@include
176 NOTE: THIS OPTION HAS BEEN DEPRECATED. See data attributes below.
177 One of "true" or "false". If "true", the dump file will include all
178 special files, including device files, fifo files and socket files.
179 Optional, defaults to "false". NOTE: specification of no options is
180 equivalent to false, but the inclusion of other options may cause
181 the underlying backup defaults to be use.
182 /backup/options/rdiff-backup/@append
184 Append the specified options to the current rdiff-backup run. This
185 is planned to be specific to the current rdiff-backup, and
186 different options will be made available for other backends.
187 /backup/setup/dump/@type
189 One of "postgres" or "mysql". Mandatory for a <dump> element.
190 /backup/setup/dump/@db
192 Name of the database to dump. If not specified, it defaults to all
193 databases maintained in the RDBMS specified by type. Optional,
194 defaults to all databases.
195 /backup/setup/dump/@dbuser
197 Name of the database user to use while doing the dump. Optional,
198 defaults to whatever the database determines based on the system
199 user.
200 /backup/setup/dump/@dbpasswd
202 Password of the database user to use while doing the dump. NB: this
203 makes the DB password available in a plain text file. Make sure you
204 use appropriate read permissions on the backup configuration file
205 to prevent unauthorized access to the password. Optional, it has no
206 default value.
207 /backup/setup/dump/@options
209 Extra options to be passed along to the dump command. This is
210 database specific, and it is passed along as-is. Please refer to
211 your database documentation for possible values that you can pass
212 along. Optional, it has no default value.
213 /backup/setup/dump/@user
215 The system user under which the dump should take place. Please note
216 that using this feature requires that safekeep(1) runs as root on
217 the client. Optional, defaults to the user under which safekeep(1)
218 runs on the client side.
219 /backup/setup/dump/@file
221 The full path to the dump file on the client host. Mandatory for a
222 <dump> element.
223 /backup/setup/dump/@cleanup
225 One of "true" or "false". If "true", the dump file will be deleted
226 from the client system once the backup is over. It is usually
227 futile to delete it, since it will be created for each backup, and
228 hence you will need to have the space available. Optional, defaults
229 to "false".
230 /backup/setup/snapshot/@device
232 The path (device location) to the client LVM volume to snapshot
233 before the backup commences. Note that the snapshot happens on the
234 client machines, and it ensures that the data that is being
235 backed-up is in a consistent state throughout the backup process.
236 Multiple snapshots may be specified, in which case the order is
237 important, the associated filesystems are mounted in the order
238 given. Please note that using this feature requires that
239 safekeep(1) runs as root on the client. Mandatory for a <snapshot>
240 element.
241 /backup/setup/snapshot/@size
243 The size of the snapshot. Unallocated space must exist on the
244 volume group. It is recommended that it is about 15-20% of the
245 original device’s size. Mandatory for a <snapshot> element.
246 /backup/setup/script/@path
248 Execute the script specified path on the client at certain steps of
249 the backup process. This script is executed with three arguments:
250 · Backup id (/backup/@id)
253 · Backup step
255 · Backup root directory (valid after creation of a snapshot) See
257 the CLIENT SCRIPT section for more information. Mandatory for a
258 <script> element.
259 /backup/data/@exclude-devices
261 One of "true" or "false". If "true", the dump file will exclude all
262 device files. Optional, defaults to "false". NOTE: specification of
263 no attributes is equivalent to false, but the inclusion of other
264 options may cause the underlying backup defaults to be use.
265 /backup/data/@exclude-fifos
267 One of "true" or "false". If "true", the dump file will exclude all
268 fifos. Optional, defaults to "false". NOTE: specification of no
269 attributes is equivalent to false, but the inclusion of other
270 options may cause the underlying backup defaults to be use.
271 /backup/data/@exclude-sockets
273 One of "true" or "false". If "true", the dump file will exclude all
274 sockets. Optional, defaults to "false". NOTE: specification of no
275 attribute is equivalent to false, but the inclusion of other
276 options may cause the underlying backup defaults to be use.
277 /backup/data/exclude/@path
279 Exclude the file or files matched by the path. If a directory is
280 matched, then files under that directory will also be matched. See
281 the FILE SELECTION section for more information.
282 /backup/data/include/@path
284 Include the file or files matched by the path. If a directory is
285 matched, then files under that directory will also be matched. See
286 the FILE SELECTION section for more information.
287 /backup/data/exclude/@glob
289 Exclude the file or files matched by the shell pattern. If a
290 directory is matched, then files under that directory will also be
291 matched. See the FILE SELECTION section for more information.
292 /backup/data/include/@glob
294 Include the file or files matched by the shell pattern. If a
295 directory is matched, then files under that directory will also be
296 matched. See the FILE SELECTION section for more information.
297 /backup/data/exclude/@regexp
299 Exclude the file or files matched by the regular expression. If a
300 directory is matched, then files under that directory will also be
301 matched. See the FILE SELECTION section for more information.
302 /backup/data/include/@regexp
304 Include the file or files matched by the regular expression. If a
305 directory is matched, then files under that directory will also be
306 matched. See the FILE SELECTION section for more information.
307
309 safekeep(1) supports file selection options similar to rdiff-backup(1).
310 When rdiff-backup is run, it searches through the given source
311 directory and backs up all the files specified by the file selection
312 system.
313 The file selection system comprises a number of file selection
315 conditions, which are set using one of the <include>/<exclude>
316 elements. Each file selection condition either matches or doesn’t match
317 a given file. A given file is included or excluded by the file
318 selection system when the first matching file selection condition
319 specifies that the file be included or excluded respectively; if the
320 file matches no include or exclude statement, it is by default
321 excluded.
322 When backing up, if a file is excluded, safekeep(1) acts as if that
324 file does not exist in the source directory.
325 For more information on file selection semantics, please see
327 rdiff-backup(1).
328
330 safekeep(1) support the optional execution of a script or program on
331 the client system at different steps during execution of the backup.
332 Note: specification of a script which does not exist is not considered
334 an error, and is treated as the same as not specifying a script.
335 However, if the specified path does match a file or directory, the
336 security tests listed below will occur.
337 This script is executed with the following three arguments: - Safekeep
339 step - Backup id - Backup root directory, which may be set during the
340 creation of a snapshot.
341 The steps currently defined and tokens passed, are: - STARTUP - prior
343 to any execution, however, if it exits with a non-zero status this
344 constitutes an error and the backup is aborted. - PRE-SETUP - prior to
345 running any setup steps being run. A non-zero status is considered a
346 warning and execution continues. - POST-SETUP - after setup, but prior
347 to execution of backup. A non-zero status is considered a warning, and
348 execution continues. - POST-BACKUP - after execution of backup. A
349 non-zero status is considered a warning, and execution continues. -
350 POST-SCRUB - after execution of a server cleanup step, normally only
351 seen after a backup failure. A non-zero status is considered a warning,
352 and execution continues.
353 Due to security considerations, there are a number of checks made on
355 this script prior to execution and failure of any of these steps will
356 cause the backup for that client to be aborted. The following tests are
357 applied prior to each execution of the script (i.e. multiple time per
358 backup), in order: - script is a regular file, not a directory or
359 special file, - script is executable by the user running on the client
360 system, - script is owned by root or the user running on the client
361 system, - script is NOT writable by any one except the script owner.
362 Note: no test is made on the ownership of the parent directory or any
364 other directories.
365
367 /etc/safekeep/backup.d/
368
370 safekeep(1), safekeep.conf(5), rdiff-backup(1), lvcreate(8)
371[FIXME: source] 11/27/2011 SAFEKEEP.BACKUP(5)