:man source: safekeep
:man version: {revnumber}
:man manual: SafeKeep Client Configuration

safekeep.backup(5)
================

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

SYNOPSIS
--------
These files are usually placed in `/etc/safekeep/backup.d/`, or optionally
in `~/.safekeep/backup.d/` for non-root users, to be picked
up automatically by 'safekeep(1)'. They must have a `.backup` extension.

DESCRIPTION
-----------
Each configuration file controls the backup of a host. They are typically
named after the hostname of the machine they control the backup for, and
have a '.backup' extension (e.g. `mailbox.backup`). These files are written
in XML. Virtually all elements and attributes are optional; if not present,
`safekeep(1)` will provide reasonable, useful defaults.

The full set of supported elements and attributes looks as follows:
------------------------------------------------------------------------
<backup id="my_workstation" enabled="true">

  <!-- the client backup host, the user and keys for access -->
  <host name="myhost" user="root" nice="10"
        key-ctrl="/home/jdoe/.ssh/backup_id_rsa" 
        key-data="/home/jdoe/.ssh/backup2_id_rsa" />

  <!-- rate limit bandwidth (kB/s) on a client basis -->
  <bandwidth overall="80" download="50" upload="50" />

  <!-- where to stored the data on the server, and for now long -->
  <repo path="./data" retention="10D" />

  <!-- set options affecting execution of rdiff-backup for this host -->
  <options>
    <!-- An option to run a different version of rdiff-backup locally, -->
    <!-- say for compatibility with older systems -->
    <!-- <rdiff-backup exec_local="rdiff-backup-1" /> -->
  </options>

  <!-- settings for database dump and for volume snapshot -->
  <setup>
    <!-- databases can be dumbed before the backup -->
    <dump type="postgres" db="my_db" dbuser="foobar" options="--schema=public"
          file="/var/backup/dumps/mydata" cleanup="true" />

    <!-- what volume is to be snapshot, and the size of the snapshot -->
    <snapshot device="/path/to/volume" size="500M" />

    <!-- location of a script to be executed at different stages of the run --> 
    <script path="server:/path/to/script" />

  </setup>

  <!-- data to be backup -->
  <data exclude-fifos="true" exclude-sockets="true">
    <!-- each type of tag can be present more than one time -->
    <!-- if a database dump was created, it must be added in this section -->
    <include path="/home"/>
    <exclude path="/home/guest"/>

    <include glob="**/important/"/>
    <exclude glob="/home/*/tmp"/>

    <include regexp=".*\.ogg"/>
    <exclude regexp=".*\.mp3"/>
  </data>
</backup>
------------------------------------------------------------------------

PARAMETERS
----------
XML elements and attributes are referred to via XPath expressions: elements
are separated by '/', attributes are introduced by '@':

/backup::
	The root element of the XML file.
	Mandatory.

/backup/@id::
	This is the ID by which `safekeep(1)` will address this host.
	If specified it overrides the default value derived from the filename. 
	Optional, defaults to the filename without the `.backup` extension.
	Use of the default value is *highly* recommended. 
          
/backup/@enabled::
	If specified and set to 'false' or '0', it disables this host. It is a
	nicer way to disable a host without renaming the file.
	Optional, defaults to 'true'.

/backup/host/@name::
	The name or IP address of the client. If you need to backup the
	box that the server is running from, you can set this to "localhost".
	This is different from leaving it blank, as it will establish a
	SSH session and use the user specified by `/backup/host/@user`.
	Optional, defaults to local access.
          
/backup/host/@port::
	The network port to use when connecting to the client.  This must
	be a number and is passed to the network connection agent, usually
	SSH.
	Optional, default to not passing any port specification.

/backup/host/@user::
	The user name to use when connecting to the client. This user
	must have read permissions for the files that will be backed up,
	so it most likely needs to be 'root'.
	Optional, defaults to the value given by `client.user` in
	`safekeep.conf`.

/backup/host/@nice::
	The nice adjustment for the client. This settings is normally
	not all that important, as most of the load rests on the server side.
	NB: if you change this value, you will have to re-deploy the auth keys.
	Optional, defaults to no nice level.

/backup/host/@key-ctrl::
	This is the private key used to establish the SSH connection
	to the client for the control channel. Use of the default value 
	is recommended.
	Optional, defaults to `~/.ssh/safekeep-server-ctrl-key`.

/backup/host/@key-data::
	This is the private key used to establish the SSH connection
	to the client for the data channel. Use of the default value 
	is recommended.
	Optional, defaults to `~/.ssh/safekeep-server-data-key`.

/backup/bandwidth/@overall::
        This is the client bandwidth limit for both upload and download. 
	It is an integer number of KB/s (see the NOTES section in 
	`safekeep.conf(5)` for more information).
        Optional, overrides `bandwidth.overall` in `safekeep.conf(5)`
	if specified. 
	
/backup/bandwidth/@download::
        This is the client bandwidth limit for download (see 
	`/backup/bandwidth/@overall` for more information).
        Optional, overrides `/backup/bandwidth/@overall` if specified. 
	
/backup/bandwidth/@upload::
        This is the client bandwidth limit for upload (see 
	`/backup/bandwidth/@overall` for more information).
        Optional, overrides `/backup/bandwidth/@overall` if specified. 

/backup/repo/@path::
	The path under which the backups will be stored. Relative
	paths are based on the 'base.dir' setting from the 'safekeep.conf(5)'.
	Since the default value for 'base.dir' is the user's home directory,
	in a typical installation the data will be stored under 
	`/var/lib/safekeep/<id>/`. If the directory does not exist,
	`safekeep(1)` will attempt to create it automatically. The backup
	will fail altogether if the directory can not be created.
	Optional, defaults to the client ID, see `/backup/@id`.
	Use of the default value is *highly* recommended. 
	*NOTE*: if you must set this value explicitly, you must
	make sure that the path is not shared between different boxes;
	a shared repository path _will_ result in data loss.

/backup/repo/@retention::
	Specifies the duration for which the backup data will be retained.
	The incremental backup information in the destination directory that 
	has been around longer than the retention time will be removed. 
	The value specified by this attribute is an time interval: an integer 
	followed by the character s, m, h, D, W, M, or Y, indicating seconds, 
	minutes, hours, days, weeks, months, or years respectively, or a
	number of these concatenated. For example, 32m means 32 minutes, and 
	3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 seconds. In this
	context, a month means 30 days, a year is 365 days, and a day is 
	always 86400 seconds.
	Note that backups of deleted files are covered by this operation. 
	Thus if you deleted a file two weeks ago, backed up immediately
	afterward, and then ran `safekeep(1)` with a retention of '10D' 
	today, no trace of that file would remain. Finally, file selection 
	options don't affect removal of incremental data.
	Optional, defaults to empty (unlimited retention).

/backup/options/special-files/@include::
       *NOTE: THIS OPTION HAS BEEN DEPRECATED.*  See data attributes below.
       One of "true" or "false". If "true", the dump file will
       include all special files, including device files, fifo files and
       socket files.
       Optional, defaults to 'false'. 
       *NOTE*: Specification of no options is equivalent to false, but the
       inclusion of other options may cause the underlying backup defaults
       to be use.

/backup/options/rdiff-backup/@append::
       Append the specified options to the current rdiff-backup run.
       This is planned to be specific to the current rdiff-backup, and
       different options will be made available for other backends.

/backup/options/rdiff-backup/@exec_local::
       Executable to be run on the local host.
       Optional, defaults to 'rdiff-backup'

/backup/options/rdiff-backup/@exec_remote::
       Executable to be run on the remote host.
       Optional, defaults to 'rdiff-backup'

/backup/setup/@writable::
	A boolean (i.e. "true" or "false") to set mount as writable or not,
	including snapshots and bind mounts.
	This is normally not required, and, if set, overrides the system
	default, but is overridden by a snapshot option.
	In general the system default is to create non-writable mount for
	both snapshots and bind mounts.
	Optional for a `<setup>` element.

/backup/setup/dump/@type::
	One of "postgres" or "mysql".
	Mandatory for a `<dump>` element.
	
/backup/setup/dump/@db::
	Name of the database to dump. If not specified, it defaults
	to all databases maintained in the RDBMS specified by `type`.
	Optional, defaults to all databases.

/backup/setup/dump/@save-db-name::
	Specify if CREATE DATABASE instructions are included in database
	dumps.  If the option is not specified then the result defaults
	to what is natural for the default database dump function.
	If the option is "true" then CREATE DATABASE are added in all cases.
	If the option is "false" then no CREATE DATABASE statement is added.
	*NOTE*: For Postgres it is not possible to suppress the CREATE
	DATABASE statement when dumping all databases, i.e. no single
	database named, in which case this option is ignored.
	Optional, defaults to not set.

/backup/setup/dump/@dbuser::
	Name of the database user to use while doing the dump. 
	Optional, defaults to whatever the database determines
	based on the system user. 

/backup/setup/dump/@dbpasswd::
	Password of the database user to use while doing the dump.
	NB: this makes the DB password available in a plain text file.
	Make sure you use appropriate read permissions on the backup
	configuration file to prevent unauthorized access to the password.
	Optional, it has no default value.

/backup/setup/dump/@options::
	Extra options to be passed along to the dump command.
	This is database specific, and it is passed along as-is.
	Please refer to your database documentation for possible
	values that you can pass along.
	Optional, it has no default value.

/backup/setup/dump/@user::
	The system user under which the dump should take place.
	Please note that using this feature requires that `safekeep(1)`
	runs as `root` on the client.
	Optional, defaults to the user under which `safekeep(1)` runs
	on the client side.

/backup/setup/dump/@file::
	The full path to the dump file on the client host.
	Mandatory for a `<dump>` element.
	
/backup/setup/dump/@cleanup::
	One of "true" or "false". If "true", the dump file will
	be deleted from the client system once the backup is over.
	It is usually futile to delete it, since it will be created
	for each backup, and hence you will need to have the space
	available.   
	Optional, defaults to 'false'. 

/backup/setup/snapshot/@device::
	The path (device location) to the client LVM volume to snapshot
	before the backup commences. Note that the snapshot happens
	on the client machines, and it ensures that the data that is
	being backed-up is in a consistent state throughout the backup
	process. Multiple snapshots may be specified, in which case the
	order is important, the associated filesystems are mounted
	in the order given.
	Please note that using this feature requires that `safekeep(1)`
	runs as `root` on the client.
	Mandatory for a `<snapshot>` element.
	  
/backup/setup/snapshot/@size::
	The size of the snapshot. Unallocated space must exist on
	the volume group. It is recommended that it is about 15-20%
	of the original device's size.  This can be specified as a
	percentage, e.g. `20%`, which is equivalent to 20% of the
	logical volume.  Other values as listed for `lvcreate(8)`
	can also be given.
	Optional, defaults to 'snapshot.size' as specified in `safekeep.conf`.

/backup/setup/snapshot/@tag::
	A list of tags to be added to the snapshot, with the `--addtag`
	argument to `lvcreate(8)`.  The @tag entry consists of a `,`
	separated list of tags.
	An `@` is automatically added to each generated tag.
	Optional for a `<snapshot>` element.

/backup/setup/snapshot/@mountoptions::
	Mount options to be used with the snapshot device.  This is normally
	not required, as the default options should suit routine usage.
	Optional for a `<snapshot>` element.

/backup/setup/snapshot/@writable::
	A boolean (i.e. "true" or "false") to set if snapshot mount is
	writable or not.
	This is normally not required, and, if set, overrides other
	settings from the setup option or the system default.
	Optional for a `<snapshot>` element.

/backup/setup/script/@path::
	Execute the script specified path on the client or server at
	certain steps of the backup process.
	This script is executed with four arguments:
	- Backup id (/backup/@id)
	- Backup step
	- Backup root directory (valid after creation of a snapshot) for client
	  or safekeep backup directory for server
	- Run-on parameter, i.e. 'client' or 'server'
	For client-side scripts, the `location` optionally consists of an
	optional `host` and a mandatory `path`, separated by a ":", where
	the host part is either "client" or "server".  If no host part is
	specified then it is first looked for on the client, and if not
	found, then is looked for on the server.  If it not found on
	either, then a warning is raised.
	Only one `<script>` element may be specified.
	See the `CLIENT AND SERVER SCRIPTS` section for more information.
	Mandatory for a `<script>` element.

/backup/setup/script/@run-on::
	Execute the script on the "server" or the "client".
	Optional, defaults to 'client'.

/backup/data/@exclude-devices::
       One of "true" or "false". If "true", the dump file will
       exclude all device files.
       Optional, defaults to 'false'. 
       *NOTE*: specification of no attributes is equivalent to false, but the
       inclusion of other options may cause the underlying backup defaults
       to be use.

/backup/data/@exclude-fifos::
       One of "true" or "false". If "true", the dump file will
       exclude all fifos.
       Optional, defaults to 'false'. 
       *NOTE*: specification of no attributes is equivalent to false, but the
       inclusion of other options may cause the underlying backup defaults
       to be use.

/backup/data/@exclude-sockets::
       One of "true" or "false". If "true", the dump file will
       exclude all sockets.
       Optional, defaults to 'false'. 
       *NOTE*: specification of no attribute is equivalent to false, but the
       inclusion of other options may cause the underlying backup defaults
       to be use.

/backup/data/exclude/@path::
	Exclude the file or files matched by the path. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.
	
/backup/data/include/@path::
	Include the file or files matched by the path. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.

/backup/data/exclude/@glob::
	Exclude the file or files matched by the shell pattern. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.

/backup/data/include/@glob::
	Include the file or files matched by the shell pattern. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.

/backup/data/exclude/@regexp::	 
	Exclude the file or files matched by the regular expression. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.

/backup/data/include/@regexp::	 
	Include the file or files matched by the regular expression. 
	If a directory is matched, then files under that directory will also
	be matched.
	See the `FILE SELECTION` section for more information.

FILE SELECTION
--------------
`safekeep(1)` supports file selection options similar to `rdiff-backup(1)`. 
When rdiff-backup is run, it searches through the given source directory 
and backs up all the files specified by the file selection system. 

The file selection system comprises a number of file selection conditions, 
which are set using one of the `<include>`/`<exclude>` elements.
Each file selection condition either matches or doesn't match a given file. 
A given file is included or excluded by the file selection system when the
first matching file selection condition specifies that the file be included
or excluded respectively; if the file matches no include or exclude 
statement, it is by default excluded.

When backing up, if a file is excluded, `safekeep(1)` acts 
as if that file does not exist in the source directory. 

For more information on file selection semantics, please see
`rdiff-backup(1)`.

CLIENT AND SCRIPTS
------------------
`safekeep(1)` support the optional execution of a script or program
on the client or server systems at different steps during execution of
the backup.

Currently only a single script, either client-side or server-side can
be specified for a client.

For client-side scripts the script may be located on either the server or
the client.  If it is located on the server, then the file is copied to
the client into a temporary directory before execution.  Note that this
directory is located where ever the system normally creates temporary
files, and it is possible that the execution of scripts are disallowed.
In that case it is recommended that a client based script is used.
In addition, the script is copied from the server on a line by line basis,
and so it is not suitable to pass binary files.

For server-side scripts the script must be located on the server.

Note: specification of a script which does not exist is not considered an
error, and is treated as the same as not specifying a script.  However, if
the specified path does match a file or directory, the security tests listed
below will occur.

This script is executed with the following four arguments:

- Safekeep step
- Backup id
- Backup root directory, which may be set during the creation of a snapshot
for client or safekeep backup directory for server.
- Run-on parameter, i.e. 'client' or 'server'

For both client-side and server-side scripts, the steps currently defined
and tokens passed, are:

- STARTUP - prior to any execution, however, if it exits with a non-zero
status this constitutes an error and the backup is aborted.
- PRE-SETUP - prior to running any setup steps being run.  A non-zero status
is considered a warning and execution continues.
- POST-SETUP - after setup, but prior to execution of backup.  A non-zero
status is considered a warning, and execution continues.
- POST-BACKUP - after execution of backup.  A non-zero status is considered
a warning, and execution continues.
- POST-SCRUB - after execution of a server cleanup step, normally only seen
after a backup failure.  A non-zero status is considered a warning, and
execution continues.

Due to security considerations, there are a number of checks made on this
script prior to execution and failure of any of these steps will cause the
backup for that client to be aborted.  The following tests are applied prior
to each execution of the script (i.e. multiple time per backup), in order:
- script is a regular file, not a directory or special file,
- script is executable by the user running on the client system,
- script is owned by root or the user running on the client system,
- script is NOT writable by any one except the script owner.

Note: no test is made on the ownership of the parent directory or any other
directories.


FILES
-----
    /etc/safekeep/backup.d/
    ~/.safekeep/backup.d/

SEE ALSO
--------
safekeep(1), safekeep.conf(5), rdiff-backup(1), lvcreate(8)

AUTHOR
------
This man page was originally written by Dimi Paun <dimi@lattica.com>.
