safekeep.backup

Langue: en

Autres versions - même langue

Version: 12/15/2009 (fedora - 01/12/10)

Section: 5 (Format de fichier)

NAME

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

SYNOPSIS

These files are usually placed in /etc/safekeep/backup.d/ 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">
 
   <!-- the client backup host, the user under which the servers will connect,
        the SSH keys used for control and data transfer -->
   <host
     name="myhost" user="root"
     key-ctrl="/home/jdoe/.ssh/backup_id_dsa"
     key-data="/home/jdoe/.ssh/backup2_id_dsa"
   />
 
   <!-- you can customize the bandwidth limit on a client basis,
        for example to 50KB/s download/upload -->
   <bandwidth overall="80" download="50" upload="50" />
 
   <!-- location where the backups will be stored on the server
        and for how long (D=days, W=weeks, M=months, or Y=years) -->
   <repo path="./data" retention="10D"/>
 
   <!-- settings for database dump and for volume snapshot -->
   <setup>
     <!-- database type ("postgres" or "mysql"), and database name,
          DB user with backup rights, location of the dump file on the client
          host, and flag to remove or not the dump file after the backup is done.
          Databases can be dumped individually using a dump clause for each database. -->
     <dump
       type="postgres"
       db="my_db"
       dbuser="foobar"
       options="--schema=public"
       file="/var/backup/dumps/mydata"
       cleanup="true"
     />
 
     <!-- what volume is to be snapshot (device location) and the size
          of the snapshot (free space must exist in the volume group) -->
     <snapshot
       device="/path/to/volume"
       size="500M"
     />
 
     <!-- location of a script to be executed on the client at different
          stages of the run.  It is called with three arguments:
          the step of the backup, backup id and the backup root directory -->
     <script
       path="/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/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/@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 root.

/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 usercqs 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 doncqt 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/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/@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 devicecqs size. Mandatory for a <snapshot> element.

/backup/setup/script/@path

Execute the script specified path on the client at certain steps of the backup process. This script is executed with three arguments:

* Backup id (/backup/@id)
* Backup step
* Backup root directory (valid after creation of a snapshot) See the CLIENT SCRIPT section for more information. Mandatory for a <script> element.

/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 doesncqt 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 SCRIPT

safekeep(1) support the optional execution of a script or program on the client system at different steps during execution of the backup.

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 three arguments: - Safekeep step - Backup id - Backup root directory, which may be set during the creation of a snapshot.

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/
 

SEE ALSO

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