|
From: <di...@us...> - 2007-03-06 21:15:29
|
Revision: 433
http://safekeep.svn.sourceforge.net/safekeep/?rev=433&view=rev
Author: dimi
Date: 2007-03-06 13:15:27 -0800 (Tue, 06 Mar 2007)
Log Message:
-----------
Rename the man page safekeep.conf to safekeep.backup
to match the new naming convention.
Adjust the docs to the new directory structure.
Modified Paths:
--------------
safekeep/trunk/doc/safekeep.txt
Added Paths:
-----------
safekeep/trunk/doc/safekeep.backup.txt
Removed Paths:
-------------
safekeep/trunk/doc/safekeep.conf.txt
Copied: safekeep/trunk/doc/safekeep.backup.txt (from rev 425, safekeep/trunk/doc/safekeep.conf.txt)
===================================================================
--- safekeep/trunk/doc/safekeep.backup.txt (rev 0)
+++ safekeep/trunk/doc/safekeep.backup.txt 2007-03-06 21:15:27 UTC (rev 433)
@@ -0,0 +1,254 @@
+safekeep.backup(5)
+================
+
+NAME
+----
+safekeep.backup - Configuration file for 'safekeep(1)'
+
+SYNOPSIS
+--------
+These files are usually placed in `/etc/safekeep/clients.d/` to be picked
+up automatically be 'safekeep(1)'. They must have a `.conf` 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 '.conf' extension (e.g. `mailbox.conf`). 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"
+ />
+
+ <!-- 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"), 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 -->
+ <dump
+ type="postgres"
+ db="dbname"
+ user="foobar"
+ 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"
+ />
+
+ </setup>
+
+ <!-- data to be backup -->
+ <data>
+ <!-- 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. Use of the default value is recommended.
+ Optional, defaults to the filename without the `.conf` extension.
+
+/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/repo/@path::
+ The path under which the backups will be stored. Relative
+ paths are based on current working directory where `safekeep(1)`
+ server is run. Typically this working directory will be the home
+ directory of the user under which `safekeep(1)` runs on the server.
+ As a result, 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`.
+
+/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/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/@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 LVM volume to snapshot
+ before the backup commences. It is recommended
+ 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.
+ Mandatory for a `<snapshot>` element.
+
+/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 respecively; 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)`.
+
+
+FILES
+-----
+ /etc/safekeep/clients.d/
+
+SEE ALSO
+--------
+safekeep(1), rdiff-backup(1), lvcreate(8)
+
Deleted: safekeep/trunk/doc/safekeep.conf.txt
===================================================================
--- safekeep/trunk/doc/safekeep.conf.txt 2007-03-06 21:07:23 UTC (rev 432)
+++ safekeep/trunk/doc/safekeep.conf.txt 2007-03-06 21:15:27 UTC (rev 433)
@@ -1,254 +0,0 @@
-safekeep.conf(5)
-================
-
-NAME
-----
-safekeep.conf - Configuration file for 'safekeep(1)'
-
-SYNOPSIS
---------
-These files are usually placed in `/etc/safekeep.d/` to be picked
-up automatically be 'safekeep(1)'. They must have a `.conf` 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 '.conf' extension (e.g. `mailbox.conf`). 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"
- />
-
- <!-- 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"), 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 -->
- <dump
- type="postgres"
- db="dbname"
- user="foobar"
- 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"
- />
-
- </setup>
-
- <!-- data to be backup -->
- <data>
- <!-- 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. Use of the default value is recommended.
- Optional, defaults to the filename without the `.conf` extension.
-
-/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/repo/@path::
- The path under which the backups will be stored. Relative
- paths are based on current working directory where `safekeep(1)`
- server is run. Typically this working directory will be the home
- directory of the user under which `safekeep(1)` runs on the server.
- As a result, 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`.
-
-/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/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/@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 LVM volume to snapshot
- before the backup commences. It is recommended
- 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.
- Mandatory for a `<snapshot>` element.
-
-/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 respecively; 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)`.
-
-
-FILES
------
- /etc/safekeep.d/
-
-SEE ALSO
---------
-safekeep(1), rdiff-backup(1), lvcreate(8)
-
Modified: safekeep/trunk/doc/safekeep.txt
===================================================================
--- safekeep/trunk/doc/safekeep.txt 2007-03-06 21:07:23 UTC (rev 432)
+++ safekeep/trunk/doc/safekeep.txt 2007-03-06 21:15:27 UTC (rev 433)
@@ -88,7 +88,7 @@
or a directory containing several configuration files (one per
backup client). Can be specified multiple times.
If not specified at all, SafeKeep will default in non-client mode
- to searching `/etc/safekeep.d/` for configuration files.
+ to searching `/etc/safekeep/clients.d/` for configuration files.
Simply using this default is the recommended usage.
-e, --email=EMAIL::
@@ -119,10 +119,10 @@
CONFIGURATION
-------------
-Normally the configuration files are placed in the `/etc/safekeep.d/` directory
-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:
+Normally the configuration files are placed in the `/etc/safekeep/clients.d/`
+directory 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" />
@@ -173,14 +173,14 @@
directories. Older data will be retained for 10 days.
For full reference documentation of the configuration format, see
-safekeep.conf(5).
+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.conf(5).
+information on this topic, see safekeep.backup(5).
KEY DEPLOYMENT
--------------
@@ -206,8 +206,8 @@
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.d/mybox.conf`, the data will be stored under
-`/var/lib/safekeep/mybox/`. Please refer to `safekeep.conf(5)` for more
+`/etc/safekeep/clients.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
@@ -242,11 +242,11 @@
...
------------------------------------------------------------------------
-Please see safekeep.conf(5) for more information on file selection.
+Please see safekeep.backup(5) for more information on file selection.
SEE ALSO
--------
-rdiff-backup(1), safekeep.conf(5)
+rdiff-backup(1), safekeep.backup(5)
AUTHOR
------
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|