1SAFEKEEP.BACKUP(5)       SafeKeep Client Configuration      SAFEKEEP.BACKUP(5)
2
3
4

NAME

6       safekeep.backup - Configuration file for a 'safekeep(1)' client
7

SYNOPSIS

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

DESCRIPTION

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
21       The full set of supported elements and attributes looks as follows:
22
23
24           <backup id="my_workstation" enabled="true">
25
26             <!-- 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
31             <!-- rate limit bandwidth (kB/s) on a client basis -->
32             <bandwidth overall="80" download="50" upload="50" />
33
34             <!-- where to stored the data on the server, and for now long -->
35             <repo path="./data" retention="10D" />
36
37             <!-- 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
44             <!-- 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
50               <!-- what volume is to be snapshot, and the size of the snapshot -->
51               <snapshot device="/path/to/volume" size="500M" />
52
53               <!-- location of a script to be executed at different stages of the run -->
54               <script path="server:/path/to/script" />
55
56             </setup>
57
58             <!-- 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
65               <include glob="**/important/"/>
66               <exclude glob="/home/*/tmp"/>
67
68               <include regexp=".*\.ogg"/>
69               <exclude regexp=".*\.mp3"/>
70             </data>
71           </backup>
72

PARAMETERS

74       XML elements and attributes are referred to via XPath expressions:
75       elements are separated by /, attributes are introduced by @:
76
77
78       /backup
79           The root element of the XML file. Mandatory.
80
81       /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
87       /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
92       /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
99       /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
104       /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
110       /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
116       /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
121       /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
126       /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
132       /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
137       /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
142       /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
155       /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
173       /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
181       /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
186       /backup/options/rdiff-backup/@exec_local
187           Executable to be run on the local host. Optional, defaults to
188           rdiff-backup
189
190       /backup/options/rdiff-backup/@exec_remote
191           Executable to be run on the remote host. Optional, defaults to
192           rdiff-backup
193
194       /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
202       /backup/setup/dump/@type
203           One of "postgres" or "mysql". Mandatory for a <dump> element.
204
205       /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
210       /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
221       /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
226       /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
233       /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
239       /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
245       /backup/setup/dump/@file
246           The full path to the dump file on the client host. Mandatory for a
247           <dump> element.
248
249       /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
256       /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
267       /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
275       /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
281       /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
286       /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
292       /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
297
298           •   Backup id (/backup/@id)
299
300           •   Backup step
301
302           •   Backup root directory (valid after creation of a snapshot) for
303               client or safekeep backup directory for server
304
305           •   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
315       /backup/setup/script/@run-on
316           Execute the script on the "server" or the "client". Optional,
317           defaults to client.
318
319       /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
325       /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
331       /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
337       /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
342       /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
347       /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
352       /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
357       /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
362       /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

FILE SELECTION

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
373       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
382       When backing up, if a file is excluded, safekeep(1) acts as if that
383       file does not exist in the source directory.
384
385       For more information on file selection semantics, please see
386       rdiff-backup(1).
387

CLIENT AND SCRIPTS

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
393       Currently only a single script, either client-side or server-side can
394       be specified for a client.
395
396       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
405       For server-side scripts the script must be located on the server.
406
407       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
412       This script is executed with the following four arguments:
413
414
415       •   Safekeep step
416
417       •   Backup id
418
419       •   Backup root directory, which may be set during the creation of a
420           snapshot for client or safekeep backup directory for server.
421
422       •   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
426
427       •   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
431       •   PRE-SETUP - prior to running any setup steps being run. A non-zero
432           status is considered a warning and execution continues.
433
434       •   POST-SETUP - after setup, but prior to execution of backup. A
435           non-zero status is considered a warning, and execution continues.
436
437       •   POST-BACKUP - after execution of backup. A non-zero status is
438           considered a warning, and execution continues.
439
440       •   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
452       Note: no test is made on the ownership of the parent directory or any
453       other directories.
454

FILES

456           /etc/safekeep/backup.d/
457           ~/.safekeep/backup.d/
458

SEE ALSO

460       safekeep(1), safekeep.conf(5), rdiff-backup(1), lvcreate(8)
461

AUTHOR

463       This man page was originally written by Dimi Paun
464       <dimi@lattica.com[1]>.
465

NOTES

467        1. dimi@lattica.com
468           mailto:dimi@lattica.com
469
470
471
472safekeep                          07/23/2022                SAFEKEEP.BACKUP(5)
Impressum