:man source: safekeep
:man version: {revnumber}
:man manual: SafeKeep Manual

safekeep(1)
==========

NAME
----
safekeep - Client/server backup script

SYNOPSIS
--------
'safekeep' --server [-q] [-v] [--noemail] [--force] [-c file] [--cleanup] [--tempdir=<tempdir>] <clientid>*

'safekeep' --keys [-q] [-v] [--noemail] [-c file] [-i file] [--status] [--print] [--deploy] <clientid>*

'safekeep' --list [-q] [-v] [--noemail] [-c file] [--increments] [--parsable-output] [--sizes] [--changed=<time>] [--at-time=<time>] <clientid>*

'safekeep' --client [--cleanup]

'safekeep' -h | -V

DESCRIPTION
-----------
SafeKeep is a client/server backup script which enhances the
power of rdiff-backup with simple configuration and use.

SafeKeep can work in server mode, client mode, SSH key management mode
or list mode.

In server mode, SafeKeep parses a set of configurations files which
defines a set of backup clients. For each backup client, SafeKeep
connects to the client host over SSH (using a public key authentification
system previously set up using `safekeep --keys --deploy`), and launches
`safekeep --client` onto the client host. The client does the real backup
and sends the data over SSH to the SafeKeep server which stores it in
the specified location.

In client mode, SafeKeep does a few setup steps, depending on the
client configuration (database dump, LVM device snapshot), then backups
the client data using `rdiff-backup`, and then cleanups the state
(removes the database dumps, deactivates the LVM snapshots)

Note that the client mode of SafeKeep should never be invoked manually,
this mode is meant to be used only by the server mode of SafeKeep.
The only exception to this is if run with the `--cleanup` option, which
is used to remove LVM snapshots and mounts created by Safekeep, after a
crash or some other failure, without a connection to the server.
Normally this cleanup would be performed through the server command
`safekeep --server --cleanup`.

The SSH key management mode is a helper mode for deploying or verifying
the setup of the SSH authentification keys.

In list mode, SafeKeep lists the details of existing archives.  This is
basically an interface to the relevant options for `rdiff-backup`.

In server, keys management and list mode, you can restrict the operation
to a specific set of clients by listing the desired client IDs as
arguments. If no client ID is given, SafeKeep will operate over all known
clients.

Each mode accepts a few options as described below.

OPERATION MODE
--------------
--server::
	Selects the server mode 

--client::
	Selects the client mode. This should never be invoked manually, the
	clients are started automatically by the server on the client machines
	using SSH.

--keys::
	Selects the SSH key management mode

--list::
	Selects the list mode

Please note that you must always specify an operation mode. Earlier 
versions used do default to `--server` mode, but that proved to work 
out poorly in practice.

GENERAL OPTIONS
---------------
-c, --conf=FILE::
	Specifies the configuration file location.
        If not specified at all, SafeKeep will default to
	`/etc/safekeep/safekeep.conf`, or optionally in
	`~/.safekeep/safekeep.conf` for non-root users, if it exists.
        Simply using this default is the recommended usage.

-h, --help::
	Selects the help mode, in which safekeep prints out the
	online help and exits.

-V, --version::
	Selects the version mode, in which safekeep prints out the
	version number and exits.

-q, --quiet::
	Decreases the verbosity level. Can be specified more than
	once.

-v, --verbose::
	Increases the verbosity level. Can be specified more than
	once.

--noemail::
	Disables the sending of email, no matter what the settings
	within the configuration file.

SERVER OPTIONS
--------------
--force::
	Pass the `--force` option to `rdiff-backup`, allowing it
	to overwrite the backup directory metadata. This option
	is potentially dangerous, and should only be used if the
	backup directory becomes corrupt, and `rdiff-backup` error
	logs tells you to use this option.

--cleanup::
	Remove LVM snapshots and mounts left by Safekeep after a
	crash or other failure.  This will run also run the standard
	cleanup processes, such as the removal of an DB dumps, and
	forces a consistency check of the `rdiff-backup` destination
	directory.  This is the prefered cleanup procedure and can
	be run with no danger of corrupting the system if there is
	nothing to cleanup.

--tempdir TEMPDIR::
	Specifes a TEMPDIR for use with `rdiff-backup'.  This overrides
	any TEMPDIR specified in the `safekeep.conf'.

CLIENT OPTIONS
--------------
--cleanup::
	Remove LVM snapshots and mounts left after a crash or other
	failure from the local system.  Unlike the equivalent `--server`
	option, it does not do any other of the standard cleanups.
	This option should only be used when it is not possible to
	refer to the server, for example, when the network connection
	to the server is no longer available.

KEYS OPTIONS
------------
-i FILE::
	Forces `ssh(1)` to use FILE for the identity (private key) in 
	RSA/DSA authentication.  If not specified, ssh(1) will use its 
	default identity files.

--status::
	Display the key status for the clients. It is implied if no other
        option is specified. In effect this option prints the steps that
        will be taken when the keys are deployed to the client.

--print::
	Display the authorization keys for the clients. This is useful in
        case you want to manually copy it into the client's 
        `~/.ssh/authorized_keys` file. This option is seldom useful.

--deploy::
	Deploy the authorization keys on the clients.

LIST OPTIONS
------------
--increments::
	Pass the `--list-increments` option to `rdiff-backup`, to
	list the number and date of partial incremental backups for
	the given or all clients.  This is the default list option.

--parseable-output::
	Pass the `--parsable-output` option to `rdiff-backup` to
	generate output in a format that is easily parsed by other
	programs.  This currently only works with the `--increments`.

--sizes::
	Pass the `--list-increment-sizes` option to `rdiff-backup`,
	to list the total size of all increment and mirror files by
	time for the given or all clients.  Note, this may take some time.

--changed=TIME::
	Pass the `--list-changed-since` option for TIME to `rdiff-backup`,
	to list the files changed since TIME for the given clients.
	TIME is passed directly to `rdiff-backup`.  Note, this may take
	some time and generate considerable output.  Also, unlike
	`rdiff-backup` the is no option to select sub-directories.

--at-time=TIME::
	Pass the `--list-at-time` option for TIME to `rdiff-backup`,
	to list the files in the archive that were present at the
	given time for the given clients.  Note, this may take some
	time and generate considerable output.  Also, unlike
	`rdiff-backup` the is no option to select sub-directories.

CONFIGURATION
-------------

Normally the configuration files are placed in the `/etc/safekeep/backup.d/` 
directory, or optionally in `~/.safekeep/backup.d/` for non-root users,
from where they will get picked up automatically by SafeKeep. 
Each backup client is described by a configuration file in XML format. 
The minimum configuration file is:
------------------------------------------------------------------------
<backup>
  <host name="my_workstation" />
</backup>
------------------------------------------------------------------------
This will simply backup all relevant files (excluding temporary files,
caches, etc) from the client with the address `my_workstation`.

A more realistic example:
------------------------------------------------------------------------
<backup>
  <host name="my_workstation" />
  <repo retention="10D" />
  <setup>
      <dump type="postgres" dbuser="postgres" file="/var/lib/pgsql/backups/all_dbs" />
      <dump type="mysql" user="mysql" dbuser="dbbackup" db="adatabase" file="/var/backups/dumps/adatabase_dbs" />
      <dump type="mysql" user="mysql" dbuser="dbbackup" db="mysql" file="/var/backups/dumps/mysql_dbs" cleanup="true" />
      <snapshot device="/dev/mapper/VolGroup00-LogVol00" size="500M" />
  </setup>

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

    <include path="/etc"/>

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

    <include path="/root"/>

    <include path="/srv"/>

    <exclude path="/var/cache"/>
    <exclude path="/var/lock"/>
    <exclude path="/var/run"/>
    <exclude path="/var/tmp"/>
    <include path="/var/named/chroot/etc"/>
    <include path="/var/named/chroot/var/named"/>
    <exclude path="/var/named/chroot"/>
    <include path="/var"/>

    <exclude path="/"/>
  </data>
</backup>
------------------------------------------------------------------------
In this case, SafeKeep will dump all databases managed by PostgreSQL,
snapshot the disk via LVM, and proceed to backup `/etc`, `/home`,
`/root`, `/srv`, `/var`, while excluding some unneeded files and
directories. Older data will be retained for 10 days.

For full reference documentation of the configuration format, see
safekeep.backup(5).

CLIENT IDS
----------
Normally the client IDs are generated automatically from the configuration
filenames without the extension. E.g. if a configuration file is named
`my_workstation.conf`, the client ID becomes `my_workstation`. For more
information on this topic, see safekeep.backup(5).

KEY DEPLOYMENT
--------------
The `safekeep(1)` server needs to access the clients in order to conduct
the backup. To that end, it establishes two ssh(1) pipes: one for control,
and one for data. To simplify the deployment of the keys, `safekeep(1)`
has a key deploy mode. 

When deploying keys using the built-in key management functionality,
`safekeep(1)` needs to be invoked as the user under which it will function
as a server. By default, that user is 'safekeep'. For extra security,
you can not login into that account, so you have to invoke `safekeep(1)`
as 'root':
------------------------------------------------------------------------
	[root@yourbox ~] # safekeep --keys --deploy
------------------------------------------------------------------------

RESTORING
---------
Since `safekeep(1)` is built around `rdiff-backup(1)`, it doesn't have any
built-in restore capabilities. It simply relies on `rdiff-backup` to perform
this task.

To do so, you just need to know the directory where the data is actually
stored. In a typical installation, for a box configured via the file
`/etc/safekeep/backup.d/mybox.backup`, the data will be stored under
`/var/lib/safekeep/mybox/`. Please refer to `safekeep.backup(5)` for more
information on this matter.

Once you have determined where the data will be stored (we'll continue
the example above), all you have to do is run `rdiff-backup`:
------------------------------------------------------------------------
	# rdiff-backup -r 1s /var/lib/safekeep/mybox my-restore-dir
------------------------------------------------------------------------
You will be able to find more information on the restore procedure in
the `rdiff-backup(1)` man page.

FILE SELECTION
--------------
It is important to note that the `include`/`exclude` directives that
control file selection are matched in the order they appear in the
configuration file, and the first one that matches dictates whether
the file will be included or excluded. As a result, you have to
add the more specific ones first, or the more generic specifications
will always win. For example:
------------------------------------------------------------------------
...
    <include path="/home"/>
    <exclude path="/home/joe"/>
...
------------------------------------------------------------------------
will NOT do what you expect, because the `/home` will match before 
`/home/joe`, and thus all files under `/home` will be included.
The correct way is to flip the two around
------------------------------------------------------------------------
...
    <exclude path="/home/joe"/>
    <include path="/home"/>
...
------------------------------------------------------------------------

Please see safekeep.backup(5) for more information on file selection.

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

AUTHOR
------
Written by Dimi Paun <dimi@lattica.com> and Stelian Pop <stelian@lattica.com>.

