"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   <!-- the client backup host, the user and keys for access -->
   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   <!-- rate limit bandwidth (kB/s) on a client basis -->
   36   <bandwidth overall="80" download="50" upload="50" />
   37 
   38   <!-- where to stored the data on the server, and for now long -->
   39   <repo path="./data" retention="10D" />
   40 
   41   <!-- set options affecting execution of rdiff-backup for this host -->
   42   <options>
   43     <!-- An option to run a different version of rdiff-backup locally, -->
   44     <!-- say for compatibility with older systems -->
   45     <!-- <rdiff-backup exec_local="rdiff-backup-1" /> -->
   46   </options>
   47 
   48   <!-- settings for database dump and for volume snapshot -->
   49   <setup>
   50     <!-- databases can be dumbed before the backup -->
   51     <dump type="postgres" db="my_db" dbuser="foobar" options="--schema=public"
   52           file="/var/backup/dumps/mydata" cleanup="true" />
   53 
   54     <!-- what volume is to be snapshot, and the size of the snapshot -->
   55     <snapshot device="/path/to/volume" size="500M" />
   56 
   57     <!-- location of a script to be executed at different stages of the run --> 
   58     <script path="server:/path/to/script" />
   59 
   60   </setup>
   61 
   62   <!-- data to be backup -->
   63   <data exclude-fifos="true" exclude-sockets="true">
   64     <!-- each type of tag can be present more than one time -->
   65     <!-- if a database dump was created, it must be added in this section -->
   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>.