1SAFEKEEP.BACKUP(5) SafeKeep Client Configuration 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/, or
10 optionally in ~/.safekeep/backup.d/ for non-root users, to be picked up
11 automatically by safekeep(1). They must have a .backup extension.
12
14 Each configuration file controls the backup of a host. They are
15 typically named after the hostname of the machine they control the
16 backup for, and have a .backup extension (e.g. mailbox.backup). These
17 files are written in XML. Virtually all elements and attributes are
18 optional; if not present, safekeep(1) will provide reasonable, useful
19 defaults.
20 The full set of supported elements and attributes looks as follows:
22 <backup id="my_workstation" enabled="true">
25 <!-- the client backup host, the user and keys for access -->
27 <host name="myhost" user="root" nice="10"
28 key-ctrl="/home/jdoe/.ssh/backup_id_rsa"
29 key-data="/home/jdoe/.ssh/backup2_id_rsa" />
30 <!-- rate limit bandwidth (kB/s) on a client basis -->
32 <bandwidth overall="80" download="50" upload="50" />
33 <!-- where to stored the data on the server, and for now long -->
35 <repo path="./data" retention="10D" />
36 <!-- settings for database dump and for volume snapshot -->
38 <setup>
39 <!-- databases can be dumbed before the backup -->
40 <dump type="postgres" db="my_db" dbuser="foobar" options="--schema=public"
41 file="/var/backup/dumps/mydata" cleanup="true" />
42 <!-- what volume is to be snapshot, and the size of the snapshot -->
44 <snapshot device="/path/to/volume" size="500M" />
45 <!-- location of a script to be executed at different stages of the run -->
47 <script path="server:/path/to/script" />
48 </setup>
50 <!-- data to be backup -->
52 <data exclude-fifos="true" exclude-sockets="true">
53 <!-- each type of tag can be present more than one time -->
54 <!-- if a database dump was created, it must be added in this section -->
55 <include path="/home"/>
56 <exclude path="/home/guest"/>
57 <include glob="**/important/"/>
59 <exclude glob="/home/*/tmp"/>
60 <include regexp=".*\.ogg"/>
62 <exclude regexp=".*\.mp3"/>
63 </data>
64 </backup>
65
67 XML elements and attributes are referred to via XPath expressions:
68 elements are separated by /, attributes are introduced by @:
69 /backup
72 The root element of the XML file. Mandatory.
73 /backup/@id
75 This is the ID by which safekeep(1) will address this host. If
76 specified it overrides the default value derived from the filename.
77 Optional, defaults to the filename without the .backup extension.
78 Use of the default value is highly recommended.
79 /backup/@enabled
81 If specified and set to false or 0, it disables this host. It is a
82 nicer way to disable a host without renaming the file. Optional,
83 defaults to true.
84 /backup/host/@name
86 The name or IP address of the client. If you need to backup the box
87 that the server is running from, you can set this to "localhost".
88 This is different from leaving it blank, as it will establish a SSH
89 session and use the user specified by /backup/host/@user. Optional,
90 defaults to local access.
91 /backup/host/@port
93 The network port to use when connecting to the client. This must be
94 a number and is passed to the network connection agent, usually
95 SSH. Optional, default to not passing any port specification.
96 /backup/host/@user
98 The user name to use when connecting to the client. This user must
99 have read permissions for the files that will be backed up, so it
100 most likely needs to be root. Optional, defaults to the value given
101 by client.user in safekeep.conf.
102 /backup/host/@nice
104 The nice adjustment for the client. This settings is normally not
105 all that important, as most of the load rests on the server side.
106 NB: if you change this value, you will have to re-deploy the auth
107 keys. Optional, defaults to no nice level.
108 /backup/host/@key-ctrl
110 This is the private key used to establish the SSH connection to the
111 client for the control channel. Use of the default value is
112 recommended. Optional, defaults to ~/.ssh/safekeep-server-ctrl-key.
113 /backup/host/@key-data
115 This is the private key used to establish the SSH connection to the
116 client for the data channel. Use of the default value is
117 recommended. Optional, defaults to ~/.ssh/safekeep-server-data-key.
118 /backup/bandwidth/@overall
120 This is the client bandwidth limit for both upload and download. It
121 is an integer number of KB/s (see the NOTES section in
122 safekeep.conf(5) for more information). Optional, overrides
123 bandwidth.overall in safekeep.conf(5) if specified.
124 /backup/bandwidth/@download
126 This is the client bandwidth limit for download (see
127 /backup/bandwidth/@overall for more information). Optional,
128 overrides /backup/bandwidth/@overall if specified.
129 /backup/bandwidth/@upload
131 This is the client bandwidth limit for upload (see
132 /backup/bandwidth/@overall for more information). Optional,
133 overrides /backup/bandwidth/@overall if specified.
134 /backup/repo/@path
136 The path under which the backups will be stored. Relative paths are
137 based on the base.dir setting from the safekeep.conf(5). Since the
138 default value for base.dir is the user’s home directory, in a
139 typical installation the data will be stored under
140 /var/lib/safekeep/<id>/. If the directory does not exist,
141 safekeep(1) will attempt to create it automatically. The backup
142 will fail altogether if the directory can not be created. Optional,
143 defaults to the client ID, see /backup/@id. Use of the default
144 value is highly recommended. NOTE: if you must set this value
145 explicitly, you must make sure that the path is not shared between
146 different boxes; a shared repository path will result in data loss.
147 /backup/repo/@retention
149 Specifies the duration for which the backup data will be retained.
150 The incremental backup information in the destination directory
151 that has been around longer than the retention time will be
152 removed. The value specified by this attribute is an time interval:
153 an integer followed by the character s, m, h, D, W, M, or Y,
154 indicating seconds, minutes, hours, days, weeks, months, or years
155 respectively, or a number of these concatenated. For example, 32m
156 means 32 minutes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours,
157 and 7 seconds. In this context, a month means 30 days, a year is
158 365 days, and a day is always 86400 seconds. Note that backups of
159 deleted files are covered by this operation. Thus if you deleted a
160 file two weeks ago, backed up immediately afterward, and then ran
161 safekeep(1) with a retention of 10D today, no trace of that file
162 would remain. Finally, file selection options don’t affect removal
163 of incremental data. Optional, defaults to empty (unlimited
164 retention).
165 /backup/options/special-files/@include
167 NOTE: THIS OPTION HAS BEEN DEPRECATED. See data attributes below.
168 One of "true" or "false". If "true", the dump file will include all
169 special files, including device files, fifo files and socket files.
170 Optional, defaults to false. NOTE: Specification of no options is
171 equivalent to false, but the inclusion of other options may cause
172 the underlying backup defaults to be use.
173 /backup/options/rdiff-backup/@append
175 Append the specified options to the current rdiff-backup run. This
176 is planned to be specific to the current rdiff-backup, and
177 different options will be made available for other backends.
178 /backup/setup/@writable
180 A boolean (i.e. "true" or "false") to set mount as writable or not,
181 including snapshots and bind mounts. This is normally not required,
182 and, if set, overrides the system default, but is overridden by a
183 snapshot option. In general the system default is to create
184 non-writable mount for both snapshots and bind mounts. Optional for
185 a <setup> element.
186 /backup/setup/dump/@type
188 One of "postgres" or "mysql". Mandatory for a <dump> element.
189 /backup/setup/dump/@db
191 Name of the database to dump. If not specified, it defaults to all
192 databases maintained in the RDBMS specified by type. Optional,
193 defaults to all databases.
194 /backup/setup/dump/@save-db-name
196 Specify if CREATE DATABASE instructions are included in database
197 dumps. If the option is not specified then the result defaults to
198 what is natural for the default database dump function. If the
199 option is "true" then CREATE DATABASE are added in all cases. If
200 the option is "false" then no CREATE DATABASE statement is added.
201 NOTE: For Postgres it is not possible to suppress the CREATE
202 DATABASE statement when dumping all databases, i.e. no single
203 database named, in which case this option is ignored. Optional,
204 defaults to not set.
205 /backup/setup/dump/@dbuser
207 Name of the database user to use while doing the dump. Optional,
208 defaults to whatever the database determines based on the system
209 user.
210 /backup/setup/dump/@dbpasswd
212 Password of the database user to use while doing the dump. NB: this
213 makes the DB password available in a plain text file. Make sure you
214 use appropriate read permissions on the backup configuration file
215 to prevent unauthorized access to the password. Optional, it has no
216 default value.
217 /backup/setup/dump/@options
219 Extra options to be passed along to the dump command. This is
220 database specific, and it is passed along as-is. Please refer to
221 your database documentation for possible values that you can pass
222 along. Optional, it has no default value.
223 /backup/setup/dump/@user
225 The system user under which the dump should take place. Please note
226 that using this feature requires that safekeep(1) runs as root on
227 the client. Optional, defaults to the user under which safekeep(1)
228 runs on the client side.
229 /backup/setup/dump/@file
231 The full path to the dump file on the client host. Mandatory for a
232 <dump> element.
233 /backup/setup/dump/@cleanup
235 One of "true" or "false". If "true", the dump file will be deleted
236 from the client system once the backup is over. It is usually
237 futile to delete it, since it will be created for each backup, and
238 hence you will need to have the space available. Optional, defaults
239 to false.
240 /backup/setup/snapshot/@device
242 The path (device location) to the client LVM volume to snapshot
243 before the backup commences. Note that the snapshot happens on the
244 client machines, and it ensures that the data that is being
245 backed-up is in a consistent state throughout the backup process.
246 Multiple snapshots may be specified, in which case the order is
247 important, the associated filesystems are mounted in the order
248 given. Please note that using this feature requires that
249 safekeep(1) runs as root on the client. Mandatory for a <snapshot>
250 element.
251 /backup/setup/snapshot/@size
253 The size of the snapshot. Unallocated space must exist on the
254 volume group. It is recommended that it is about 15-20% of the
255 original device’s size. This can be specified as a percentage, e.g.
256 20%, which is equivalent to 20% of the logical volume. Other values
257 as listed for lvcreate(8) can also be given. Optional, defaults to
258 snapshot.size as specified in safekeep.conf.
259 /backup/setup/snapshot/@tag
261 A list of tags to be added to the snapshot, with the --addtag
262 argument to lvcreate(8). The @tag entry consists of a , separated
263 list of tags. An @ is automatically added to each generated tag.
264 Optional for a <snapshot> element.
265 /backup/setup/snapshot/@mountoptions
267 Mount options to be used with the snapshot device. This is normally
268 not required, as the default options should suit routine usage.
269 Optional for a <snapshot> element.
270 /backup/setup/snapshot/@writable
272 A boolean (i.e. "true" or "false") to set if snapshot mount is
273 writable or not. This is normally not required, and, if set,
274 overrides other settings from the setup option or the system
275 default. Optional for a <snapshot> element.
276 /backup/setup/script/@path
278 Execute the script specified path on the client or server at
279 certain steps of the backup process. This script is executed with
280 four arguments:
281 · Backup id (/backup/@id)
284 · Backup step
286 · Backup root directory (valid after creation of a snapshot) for
288 client or safekeep backup directory for server
289 · Run-on parameter, i.e. client or server For client-side
291 scripts, the location optionally consists of an optional host
292 and a mandatory path, separated by a ":", where the host part
293 is either "client" or "server". If no host part is specified
294 then it is first looked for on the client, and if not found,
295 then is looked for on the server. If it not found on either,
296 then a warning is raised. Only one <script> element may be
297 specified. See the CLIENT AND SERVER SCRIPTS section for more
298 information. Mandatory for a <script> element.
299 /backup/setup/script/@run-on
301 Execute the script on the "server" or the "client". Optional,
302 defaults to client.
303 /backup/data/@exclude-devices
305 One of "true" or "false". If "true", the dump file will exclude all
306 device files. Optional, defaults to false. NOTE: specification of
307 no attributes is equivalent to false, but the inclusion of other
308 options may cause the underlying backup defaults to be use.
309 /backup/data/@exclude-fifos
311 One of "true" or "false". If "true", the dump file will exclude all
312 fifos. Optional, defaults to false. NOTE: specification of no
313 attributes is equivalent to false, but the inclusion of other
314 options may cause the underlying backup defaults to be use.
315 /backup/data/@exclude-sockets
317 One of "true" or "false". If "true", the dump file will exclude all
318 sockets. Optional, defaults to false. NOTE: specification of no
319 attribute is equivalent to false, but the inclusion of other
320 options may cause the underlying backup defaults to be use.
321 /backup/data/exclude/@path
323 Exclude the file or files matched by the path. If a directory is
324 matched, then files under that directory will also be matched. See
325 the FILE SELECTION section for more information.
326 /backup/data/include/@path
328 Include the file or files matched by the path. If a directory is
329 matched, then files under that directory will also be matched. See
330 the FILE SELECTION section for more information.
331 /backup/data/exclude/@glob
333 Exclude the file or files matched by the shell pattern. If a
334 directory is matched, then files under that directory will also be
335 matched. See the FILE SELECTION section for more information.
336 /backup/data/include/@glob
338 Include the file or files matched by the shell pattern. If a
339 directory is matched, then files under that directory will also be
340 matched. See the FILE SELECTION section for more information.
341 /backup/data/exclude/@regexp
343 Exclude the file or files matched by the regular expression. If a
344 directory is matched, then files under that directory will also be
345 matched. See the FILE SELECTION section for more information.
346 /backup/data/include/@regexp
348 Include the file or files matched by the regular expression. If a
349 directory is matched, then files under that directory will also be
350 matched. See the FILE SELECTION section for more information.
351
353 safekeep(1) supports file selection options similar to rdiff-backup(1).
354 When rdiff-backup is run, it searches through the given source
355 directory and backs up all the files specified by the file selection
356 system.
357 The file selection system comprises a number of file selection
359 conditions, which are set using one of the <include>/<exclude>
360 elements. Each file selection condition either matches or doesn’t match
361 a given file. A given file is included or excluded by the file
362 selection system when the first matching file selection condition
363 specifies that the file be included or excluded respectively; if the
364 file matches no include or exclude statement, it is by default
365 excluded.
366 When backing up, if a file is excluded, safekeep(1) acts as if that
368 file does not exist in the source directory.
369 For more information on file selection semantics, please see
371 rdiff-backup(1).
372
374 safekeep(1) support the optional execution of a script or program on
375 the client or server systems at different steps during execution of the
376 backup.
377 Currently only a single script, either client-side or server-side can
379 be specified for a client.
380 For client-side scripts the script may be located on either the server
382 or the client. If it is located on the server, then the file is copied
383 to the client into a temporary directory before execution. Note that
384 this directory is located where ever the system normally creates
385 temporary files, and it is possible that the execution of scripts are
386 disallowed. In that case it is recommended that a client based script
387 is used. In addition, the script is copied from the server on a line by
388 line basis, and so it is not suitable to pass binary files.
389 For server-side scripts the script must be located on the server.
391 Note: specification of a script which does not exist is not considered
393 an error, and is treated as the same as not specifying a script.
394 However, if the specified path does match a file or directory, the
395 security tests listed below will occur.
396 This script is executed with the following four arguments:
398 · Safekeep step
401 · Backup id
403 · Backup root directory, which may be set during the creation of a
405 snapshot for client or safekeep backup directory for server.
406 · Run-on parameter, i.e. client or server
408 For both client-side and server-side scripts, the steps currently
409 defined and tokens passed, are:
410 · STARTUP - prior to any execution, however, if it exits with a
413 non-zero status this constitutes an error and the backup is
414 aborted.
415 · PRE-SETUP - prior to running any setup steps being run. A non-zero
417 status is considered a warning and execution continues.
418 · POST-SETUP - after setup, but prior to execution of backup. A
420 non-zero status is considered a warning, and execution continues.
421 · POST-BACKUP - after execution of backup. A non-zero status is
423 considered a warning, and execution continues.
424 · POST-SCRUB - after execution of a server cleanup step, normally
426 only seen after a backup failure. A non-zero status is considered a
427 warning, and execution continues.
428 Due to security considerations, there are a number of checks made on
429 this script prior to execution and failure of any of these steps will
430 cause the backup for that client to be aborted. The following tests are
431 applied prior to each execution of the script (i.e. multiple time per
432 backup), in order: - script is a regular file, not a directory or
433 special file, - script is executable by the user running on the client
434 system, - script is owned by root or the user running on the client
435 system, - script is NOT writable by any one except the script owner.
436 Note: no test is made on the ownership of the parent directory or any
438 other directories.
439
441 /etc/safekeep/backup.d/
442 ~/.safekeep/backup.d/
443
445 safekeep(1), safekeep.conf(5), rdiff-backup(1), lvcreate(8)
446
448 This man page was originally written by Dimi Paun
449 <dimi@lattica.com[1]>.
450
452 1. dimi@lattica.com
453 mailto:dimi@lattica.com
454safekeep 02/23/2019 SAFEKEEP.BACKUP(5)