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