Support local make files.

[dss.git] / dss.suite

diff --git a/dss.suite b/dss.suite
index e69cc28630c8a39359cba3aead33ab3b847011a8..f9cf8af5993345452fddc7b3d9790d0d7e6d7a13 100644 (file)
--- a/dss.suite
+++ b/dss.suite
@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: GPL-2.0
+

 [suite dss]
 caption = Subcommands
 
 [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
                        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]
                        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
                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.
 
                [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
                [/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.
                        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
                [/help]
        [option Rsync-options]
                summary = Controlling how rsync is run


@@ -312,8 +329,8 @@ caption = Subcommands
                typestr = percent
                default_val = 2
                [help]
                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]
                        --min-free-mb and --min-free-percent to zero as this will cause your
                        file system to fill up quickly.
                [/help]


@@ -433,19 +450,38 @@ caption = Subcommands
                snapshots.
        [/description]
 [subcommand prune]
                snapshots.
        [/description]
 [subcommand prune]

-       purpose = remove redundant and outdated snapshots
+       purpose = remove snapshots

        [description]
        [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]
        [/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]
 [subcommand ls]
        purpose = print the list of all snapshots
        [description]


@@ -475,6 +511,35 @@ caption = Subcommands
 
                        Sending SIGHUP causes the running dss process to reload its config file.
                [/help]
 
                        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
 
 [section copyright]
        Written by Andre Noll