'\" t
.\"     Title: safekeep.backup
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/10/2023
.\"    Manual: SafeKeep Client Configuration
.\"    Source: safekeep
.\"  Language: English
.\"
.TH "SAFEKEEP\&.BACKUP" "5" "09/10/2023" "safekeep" "SafeKeep Client Configuration"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
safekeep.backup \- Configuration file for a \*(Aqsafekeep(1)\*(Aq client
.SH "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 \fIsafekeep(1)\fR\&. They must have a \&.backup extension\&.
.SH "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 \fI\&.backup\fR 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:

.sp
.if n \{\
.RS 4
.\}
.nf
<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="\&.*\e\&.ogg"/>
    <exclude regexp="\&.*\e\&.mp3"/>
  </data>
</backup>
.fi
.if n \{\
.RE
.\}
.SH "PARAMETERS"
XML elements and attributes are referred to via XPath expressions: elements are separated by \fI/\fR, attributes are introduced by \fI@\fR:

.PP
/backup
.RS 4
The root element of the XML file\&. Mandatory\&.
.RE
.PP
/backup/@id
.RS 4
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 \fBhighly\fR recommended\&.
.RE
.PP
/backup/@enabled
.RS 4
If specified and set to \fIfalse\fR or \fI0\fR, it disables this host\&. It is a nicer way to disable a host without renaming the file\&. Optional, defaults to \fItrue\fR\&.
.RE
.PP
/backup/host/@name
.RS 4
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\&.
.RE
.PP
/backup/host/@port
.RS 4
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\&.
.RE
.PP
/backup/host/@user
.RS 4
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 \fIroot\fR\&. Optional, defaults to the value given by client\&.user in safekeep\&.conf\&.
.RE
.PP
/backup/host/@nice
.RS 4
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\&.
.RE
.PP
/backup/host/@key\-ctrl
.RS 4
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\&.
.RE
.PP
/backup/host/@key\-data
.RS 4
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\&.
.RE
.PP
/backup/bandwidth/@overall
.RS 4
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\&.
.RE
.PP
/backup/bandwidth/@download
.RS 4
This is the client bandwidth limit for download (see /backup/bandwidth/@overall for more information)\&. Optional, overrides /backup/bandwidth/@overall if specified\&.
.RE
.PP
/backup/bandwidth/@upload
.RS 4
This is the client bandwidth limit for upload (see /backup/bandwidth/@overall for more information)\&. Optional, overrides /backup/bandwidth/@overall if specified\&.
.RE
.PP
/backup/repo/@path
.RS 4
The path under which the backups will be stored\&. Relative paths are based on the \fIbase\&.dir\fR setting from the \fIsafekeep\&.conf(5)\fR\&. Since the default value for \fIbase\&.dir\fR is the user\(cqs 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 \fBhighly\fR recommended\&. \fBNOTE\fR: if you must set this value explicitly, you must make sure that the path is not shared between different boxes; a shared repository path \fIwill\fR result in data loss\&.
.RE
.PP
/backup/repo/@retention
.RS 4
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 \fI10D\fR today, no trace of that file would remain\&. Finally, file selection options don\(cqt affect removal of incremental data\&. Optional, defaults to empty (unlimited retention)\&.
.RE
.PP
/backup/options/special\-files/@include
.RS 4
\fBNOTE: THIS OPTION HAS BEEN DEPRECATED\&.\fR 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 \fIfalse\fR\&. \fBNOTE\fR: Specification of no options is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be use\&.
.RE
.PP
/backup/options/rdiff\-backup/@append
.RS 4
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\&.
.RE
.PP
/backup/options/rdiff\-backup/@exec_local
.RS 4
Executable to be run on the local host\&. Optional, defaults to \fIrdiff\-backup\fR
.RE
.PP
/backup/options/rdiff\-backup/@exec_remote
.RS 4
Executable to be run on the remote host\&. Optional, defaults to \fIrdiff\-backup\fR
.RE
.PP
/backup/setup/@writable
.RS 4
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\&.
.RE
.PP
/backup/setup/dump/@type
.RS 4
One of "postgres" or "mysql"\&. Mandatory for a <dump> element\&.
.RE
.PP
/backup/setup/dump/@db
.RS 4
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\&.
.RE
.PP
/backup/setup/dump/@save\-db\-name
.RS 4
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\&. \fBNOTE\fR: 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\&.
.RE
.PP
/backup/setup/dump/@dbuser
.RS 4
Name of the database user to use while doing the dump\&. Optional, defaults to whatever the database determines based on the system user\&.
.RE
.PP
/backup/setup/dump/@dbpasswd
.RS 4
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\&.
.RE
.PP
/backup/setup/dump/@options
.RS 4
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\&.
.RE
.PP
/backup/setup/dump/@user
.RS 4
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\&.
.RE
.PP
/backup/setup/dump/@file
.RS 4
The full path to the dump file on the client host\&. Mandatory for a <dump> element\&.
.RE
.PP
/backup/setup/dump/@cleanup
.RS 4
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 \fIfalse\fR\&.
.RE
.PP
/backup/setup/snapshot/@device
.RS 4
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\&.
.RE
.PP
/backup/setup/snapshot/@size
.RS 4
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\(cqs 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 \fIsnapshot\&.size\fR as specified in safekeep\&.conf\&.
.RE
.PP
/backup/setup/snapshot/@tag
.RS 4
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\&.
.RE
.PP
/backup/setup/snapshot/@mountoptions
.RS 4
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\&.
.RE
.PP
/backup/setup/snapshot/@writable
.RS 4
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\&.
.RE
.PP
/backup/setup/script/@path
.RS 4
Execute the script specified path on the client or server at certain steps of the backup process\&. This script is executed with four arguments:

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Backup id (/backup/@id)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Backup step
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Backup root directory (valid after creation of a snapshot) for client or safekeep backup directory for server
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Run\-on parameter, i\&.e\&. \fIclient\fR or \fIserver\fR 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\&.
.RE
.RE
.PP
/backup/setup/script/@run\-on
.RS 4
Execute the script on the "server" or the "client"\&. Optional, defaults to \fIclient\fR\&.
.RE
.PP
/backup/data/@exclude\-devices
.RS 4
One of "true" or "false"\&. If "true", the dump file will exclude all device files\&. Optional, defaults to \fIfalse\fR\&. \fBNOTE\fR: specification of no attributes is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be use\&.
.RE
.PP
/backup/data/@exclude\-fifos
.RS 4
One of "true" or "false"\&. If "true", the dump file will exclude all fifos\&. Optional, defaults to \fIfalse\fR\&. \fBNOTE\fR: specification of no attributes is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be use\&.
.RE
.PP
/backup/data/@exclude\-sockets
.RS 4
One of "true" or "false"\&. If "true", the dump file will exclude all sockets\&. Optional, defaults to \fIfalse\fR\&. \fBNOTE\fR: specification of no attribute is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be use\&.
.RE
.PP
/backup/data/exclude/@path
.RS 4
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\&.
.RE
.PP
/backup/data/include/@path
.RS 4
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\&.
.RE
.PP
/backup/data/exclude/@glob
.RS 4
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\&.
.RE
.PP
/backup/data/include/@glob
.RS 4
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\&.
.RE
.PP
/backup/data/exclude/@regexp
.RS 4
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\&.
.RE
.PP
/backup/data/include/@regexp
.RS 4
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\&.
.RE
.SH "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\(cqt 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)\&.
.SH "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:

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Safekeep step
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Backup id
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Backup root directory, which may be set during the creation of a snapshot for client or safekeep backup directory for server\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Run\-on parameter, i\&.e\&. \fIclient\fR or \fIserver\fR
.RE
For both client\-side and server\-side scripts, the steps currently defined and tokens passed, are:

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
STARTUP \- prior to any execution, however, if it exits with a non\-zero status this constitutes an error and the backup is aborted\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
PRE\-SETUP \- prior to running any setup steps being run\&. A non\-zero status is considered a warning and execution continues\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
POST\-SETUP \- after setup, but prior to execution of backup\&. A non\-zero status is considered a warning, and execution continues\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
POST\-BACKUP \- after execution of backup\&. A non\-zero status is considered a warning, and execution continues\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
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\&.
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
/etc/safekeep/backup\&.d/
~/\&.safekeep/backup\&.d/
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
safekeep(1), safekeep\&.conf(5), rdiff\-backup(1), lvcreate(8)
.SH "AUTHOR"
This man page was originally written by Dimi Paun <\m[blue]\fBdimi@lattica\&.com\fR\m[]\&\s-2\u[1]\d\s+2>\&.
.SH "NOTES"
.IP " 1." 4
dimi@lattica.com
.RS 4
\%mailto:dimi@lattica.com
.RE