X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=9c687f42d575606cdb852bf7b829e4def7d64edf;hp=731cabb89485418f0326611e18176bca4a982f1e;hb=723146898de138324dd6e421af05fd61c6cda848;hpb=4acdbf0a039635bd98807d92dfdd60bb15f4d650

diff --git a/dss.ggo b/dss.ggo
index 731cabb..9c687f4 100644
--- a/dss.ggo
+++ b/dss.ggo
@@ -3,7 +3,7 @@
 # Licensed under the GPL v2. For licencing details see COPYING.
 
 package "dss"
-version "0.0.5"
+version "0.1.2"
 purpose "the dyadic snapshot scheduler
 
 dss creates hardlink-based snapshots of a given directory on a remote
@@ -82,12 +82,17 @@ details="
 	is also given.
 "
 
+##################
+section "Commands"
+##################
+
 defgroup "command"
 #=================
 groupdesc="
 	dss supports a couple of commands each of which corresponds
 	to a different command line option. Exactly one of these
 	options must be given.
+
 "
 required
 
@@ -102,13 +107,14 @@ details="
 
 groupoption "prune" P
 #~~~~~~~~~~~~~~~~~~~~
-"Remove a redundant snapshot"
+"Remove redundant and outdated snapshots"
 group="command"
 details="
-	A snapshot is considered redundant if it ether belongs to
-	an interval greater than the maximum number of intervals,
-	or if it belongs to an interval that already contains more
-	than the desired number of snapshots.
+	A snapshot is considered outdated if it belongs to an interval
+	greater than the maximum number of intervals. It is said to be
+	redundant if it belongs to an interval that already contains
+	more than the desired number of snapshots. This command gets
+	rid of such snapshots.
 "
 
 groupoption "ls" L
@@ -127,7 +133,9 @@ groupoption "run" R
 group="command"
 details="
 	This is the main mode of operation. Snapshots will be created
-	as needed and pruned automatically.
+	in an endless loop as needed and pruned automatically. The loop
+	only terminates on fatal errors or if a terminating signal was
+	received. See also the --exit-hook option.
 "
 
 ###############################
@@ -187,8 +195,12 @@ string typestr="option"
 optional
 multiple
 details="
-	These option may be given multiple times. The arguments passed
-	to that option are passed verbatim to the rsync command.
+	This option may be given multiple times. The given argument is
+	passed verbatim to the rsync command. Note that in order to use
+	rsync options that require an argument, you have to specify the
+	option and its argument as separate --rsync-options, like this:
+
+		--rsync-option --exclude --rsync-option /proc
 "
 
 ###################
@@ -208,13 +220,14 @@ details="
 	unit intervals.
 
 	dss removes any snapshots older than n times u and tries to
-	keep 2^(k-1) snapshots in interval k, where the interval number
-	k counts from zero, zero being the most recent unit interval.
+	keep 2^(n - k - 1) snapshots in interval k, where the interval
+	number k counts from zero, zero being the most recent unit
+	interval.
 
 	In other words, the oldest snapshot will at most be u * n days
 	(= 20 days if default values are used) old.  Moreover, there
 	are at most 2^n - 1 snapshots in total (i. e. 31 by default).
-	Observe that you have to create at least 2 ^ (n - 1) snapshots
+	Observe that you have to create at least 2^(n - 1) snapshots
 	each interval for this to work out because that is the number
 	of snapshots in interval zero.
 "
@@ -264,6 +277,53 @@ details="
 	store them in a database for further analysis.
 "
 
+option "pre-remove-hook" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Executed before snapshot removal"
+string typestr="command"
+optional
+details="
+	Execute this command before removing a snapshot. If this
+	command returns with a non-zero exit status, no snapshot is
+	being removed and the operation is retried later.
+
+	For example, one might want to execute a script that checks
+	whether the snapshot to be deleted is currently used by
+	another process, e.g. by a tape-based backup system that runs
+	concurrently to dss.
+
+	Another possible application of this is to record disk-usage
+	patterns before and after snapshot removal.
+"
+
+option "post-remove-hook" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Executed after snapshot removal"
+string typestr="command"
+optional
+details="
+	Execute this after a snapshot has successfully been
+	removed. The full path of the removed snapshot is
+	passed to the hook as the first argument. The exit code of
+	this hook is ignored.
+"
+
+option "exit-hook" e
+#~~~~~~~~~~~~~~~~~~~
+"Executed if run command exits"
+string typestr="command"
+optional
+details="
+	This hook is only used if the --run command was given which
+	instructs dss to run in an endless loop. The exit-hook gets
+	executed whenever this endless loop terminates. The reason
+	for terminating the loop is passed as the first argument.
+
+	One possible application for this hook is to send email to the
+	system administrator to let her know that no more snapshots
+	are going to be created.
+"
+
 ###############################
 section "Disk space monitoring"
 ###############################
@@ -316,3 +376,17 @@ details="
 
 	A value of zero (the default) deactivates this check.
 "
+
+option "keep-redundant" k
+#~~~~~~~~~~~~~~~~~~~~~~~~
+"Prune by disk space only"
+flag off
+details="
+	If this flag is not given dss removes redundant and outdated
+	snapshots automatically.
+
+	Otherwise, this feature is deactivated so that snapshots are
+	only being removed in case disk space or number of free inodes
+	becomes low. Use this flag if the file system containing the
+	destination directory is used for snapshots only.
+"