X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.suite;h=16c7e58542eff8750c8437dcea137f347a435950;hp=e7473cb6d2f4ab619c753262664ff5c377ed21c6;hb=HEAD;hpb=3025388040c1521121255e5ae7ceabdcb1b1e421

diff --git a/dss.suite b/dss.suite
index e7473cb..f9cf8af 100644
--- a/dss.suite
+++ b/dss.suite
@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: GPL-2.0
+
 [suite dss]
 caption = Subcommands
 
@@ -34,7 +36,7 @@ caption = Subcommands
 			However, there is one exception to this rule: The run subcommand
 			re-reads the configuration file when it receives the HUP signal. In
 			this case the options in the config file override any options that
-			were previously given at the command line. This allows to change the
+			were previously given at the command line. This allows changing the
 			configuration of a running dss process by sending SIGHUP.
 		[/help]
 	[option loglevel]
@@ -60,13 +62,15 @@ caption = Subcommands
 		typestr = dirname
 		arg_info = required_arg
 		arg_type = string
+		flag multiple
 		[help]
 			The directory on the remote host from which snapshots are taken.
 			Of course, the user specified as --remote-user must have read access
 			to this directory.
 
-			This option is mandatory for the create and run subcommands: It must
-			be given at the command line or in the config file.
+			This option is mandatory for the create and run subcommands: It may
+			be given multiple times to specify more than one source directory.
+			However, all source directories must reside on the same server.
 		[/help]
 	[option dest-dir]
 		summary = where snapshots are stored
@@ -78,6 +82,19 @@ caption = Subcommands
 			written. This must be writable by the user who runs dss.
 
 			This option is mandatory for all subcommands except kill.
+			Unlike --source-dir, this option may only be given once.
+		[/help]
+	[option mountpoint]
+		summary = abort if destination directory is not a mountpoint
+		[help]
+			This option checks whether a file system is mounted on the directory
+			specified as the argument to --dest-dir. Operation proceeds only
+			if this is the case. Otherwise dss exits unsuccessfully without
+			performing any action. Use this option to prevent snapshot creation
+			if the snapshot file system is not mounted.
+
+			This option is silently ignored for subcommands which do not depend
+			on the destination directory.
 		[/help]
 	[option Rsync-options]
 		summary = Controlling how rsync is run
@@ -109,6 +126,29 @@ caption = Subcommands
 			Set this if the user that runs dss is different from the user on the
 			remote host.
 		[/help]
+	[option checksum]
+		summary = run rsync with --checksum occasionally
+		typestr = permille
+		arg_info = required_arg
+		arg_type = uint32
+		default_val = 0
+		[help]
+			If a file on the backup becomes corrupt in a way that file size
+			and modification time still match the original file, rsync will not
+			consider the file for transfer ("quick check"). Hence the corruption
+			stays on the backup until the file is modified on the source.
+			The --checksum option of rsync disables the quick check and compares
+			the contents of each file, fixing such corruptions. Since computing
+			the checksums adds a significant slowdown due to a lot of disk I/O,
+			the option is not enabled by default.
+
+			The argument to the --checksum option of dss is a number between 0
+			and 1000, inclusively, which determines the probability of adding
+			--checksum to the rsync options each time a snapshot is created. The
+			default value zero means to never add the option. The value 100 will
+			create every tenth snapshot (on average) using checksums, and the
+			value 1000 will always pass --checksum to rsync.
+		[/help]
 	[option rsync-option]
 		short_opt = O
 		summary = further rsync options
@@ -289,8 +329,8 @@ caption = Subcommands
 		typestr = percent
 		default_val = 2
 		[help]
-			This is like --min-free-mb but allows to specify the amount of
-			free disk space as a percentage. It is not recommended to set both
+			This is like --min-free-mb but the amount of free disk space
+			is specified as a percentage. It is not recommended to set both
 			--min-free-mb and --min-free-percent to zero as this will cause your
 			file system to fill up quickly.
 		[/help]
@@ -410,19 +450,38 @@ caption = Subcommands
 		snapshots.
 	[/description]
 [subcommand prune]
-	purpose = remove redundant and outdated snapshots
+	purpose = remove snapshots
 	[description]
-		A snapshot is considered outdated if its interval number is greater or
-		equal than the specified number of unit intervals. See --unit-interval
-		and --num-intervals above.
+		A snapshot is said to be (a) outdated if its interval number is greater
+		or equal than the specified number of unit intervals, (b) redundant if
+		the interval it belongs to contains more than the configured number of
+		snapshots, and (c) orphaned if it is incomplete and not being created
+		or deleted. All other snapshots are called regular.
 
-		A snapshot is said to be redundant if the interval it belongs to
-		contains more than the configured number of snapshots.
+		Unless --dry-run is given, which just prints the snapshot that would be
+		removed, this subcommand gets rid of non-regular snapshots.  At most
+		one snapshot is removed per invocation. If no such snapshot exists
+		and disk space is low, the subcommand also removes regular snapshots,
+		always picking the oldest one.
 
-		The prune command gets rid of both outdated and redundant snapshots. At
-		most one snapshot is removed per invocation. If --dry-run is given, the
-		subcommand only prints the snapshot that would be removed.
+		The subcommand fails if there is another dss "run" process.
 	[/description]
+	[option disk-space]
+		summary = act as if free disk space was high/low
+		arg_info = required_arg
+		arg_type = string
+		typestr = mode
+		values = {
+			FDS_CHECK = "check",
+			FDS_HIGH = "high",
+			FDS_LOW = "low"
+		}
+		default_val = check
+		[help]
+			By default, free disk space is checked and even regular snapshots
+			become candidates for removal if disk space is low. This option
+			overrides the result of the check.
+		[/help]
 [subcommand ls]
 	purpose = print the list of all snapshots
 	[description]
@@ -452,6 +511,35 @@ caption = Subcommands
 
 			Sending SIGHUP causes the running dss process to reload its config file.
 		[/help]
+	[option wait]
+		short_opt = w
+		summary = wait until the signalled process has terminated
+		[help]
+			This option is handy for system shutdown scripts which would like
+			to terminate the dss daemon process.
+
+			Without --wait the dss process which executes the kill subcommand
+			exits right after the kill(2) system call returns. At this point the
+			signalled process might still be alive (even if SIGKILL was sent).
+			If --wait is given, the process waits until the signalled process
+			has terminated or the timeout expires.
+
+			If --wait is not given, the kill subcommand exits successfully if
+			and only if the signal was sent (i.e., if there exists another dss
+			process to receive the signal). With --wait it exits successfully
+			if, additionally, the signalled process has terminated before the
+			timeout expires.
+
+			It makes only sense to use the option for signals which terminate dss.
+		[/help]
+[subcommand configtest]
+	purpose = run a configuration file syntax test
+	[description]
+		This command checks the command line options and the configuration
+		file for syntactic correctness. It either reports "Syntax Ok" and
+		exits successfully or prints information about the first syntax error
+		detected and terminates with exit code 1.
+	[/description]
 
 [section copyright]
 	Written by Andre Noll