SF.net SVN: safekeep: [433] safekeep/trunk/doc

[<di...@us...>]

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.