+# SPDX-License-Identifier: GPL-2.0
+
[suite dss]
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
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
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 redundant if the interval it belongs to
- contains more than the configured number of snapshots.
-
- 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.
+ 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.
+
+ 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 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]
exits successfully or prints information about the first syntax error
detected and terminates with exit code 1.
[/description]
+[subcommand help]
+ purpose = list available subcommands or print subcommand-specific help
+ non-opts-name = [subcommand]
+ [description]
+ Without any arguments, help prints the list of available
+ subcommands. When called with a subcommand name argument, it prints
+ the help text of the given subcommand.
+ [/description]
+ [option long]
+ short_opt = l
+ summary = show the long help text
+ [help]
+ If the optional argument is supplied, the long help text contains the
+ synopsis, the purpose and the description of the specified subcommand,
+ followed by the option list including summary and help text of each
+ option. Without --long, the short help is shown instead. This omits
+ the description of the subcommand and the option help.
+
+ If no subcommand is supplied but --long is given, the list contains the
+ purpose of each subcommand.
+ [/help]
[section copyright]
Written by Andre Noll