safekeep-1.5.1.tar.gz: .../safekeep.backup.txt

"Fossies" - the Fresh Open Source Software Archive

Member "safekeep-1.5.1/doc/safekeep.backup.txt" (16 Nov 2020, 20339 Bytes) of package /linux/misc/safekeep-1.5.1.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "safekeep.backup.txt":

1.5.0_vs_1.5.1.

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