+# SPDX-License-Identifier: GPL-2.0
+
[suite dss]
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]
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
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
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]
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]
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
projects / dss.git / blobdiff