Introduce get_config_file_name().
[dss.git] / dss.ggo
diff --git a/dss.ggo b/dss.ggo
index 46b4271..1662e0d 100644 (file)
--- a/dss.ggo
+++ b/dss.ggo
@@ -1,6 +1,9 @@
+# Copyright (C) 2008-2010 Andre Noll <maan@systemlinux.org>
 #
+# Licensed under the GPL v2. For licencing details see COPYING.
+
 package "dss"
-version "0.0.3"
+version "0.1.4"
 purpose "the dyadic snapshot scheduler
 
 dss creates hardlink-based snapshots of a given directory on a remote
@@ -21,6 +24,14 @@ details="
        configuration file. As usual, if an option is given both at
        the command line and in the configuration file, the command
        line option takes precedence.
+
+       However, there is an important exception to this rule:
+       If the --run option was given (see below) then dss honors
+       SIGHUP and re-reads its configuration file whenever it
+       receives this 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 configuration of a
+       running dss process on the fly by sending SIGHUP.
 "
 
 option "daemon" d
@@ -32,6 +43,9 @@ details="
        Note that dss refuses to start in daemon mode if no logfile
        was specified. This option is mostly useful in conjuction
        with the -R option described below.
+
+       Note that it is not possible to change whether dss runs as
+       background daemon by sending SIGHUP.
 "
 
 option "dry-run" D
@@ -55,7 +69,7 @@ int typestr="level"
 default="3"
 optional
 details="
-       Lower values mean less verbose logging.
+       Lower values mean more verbose logging.
 "
 
 option "logfile" -
@@ -63,16 +77,23 @@ option "logfile" -
 "Logfile for the dss daemon process"
 string typestr="filename"
 optional
-details="
-       This option is mostly useful for the run command if --daemon
-       is also given.
+details = "
+       This option is only honored if both --run and --daemon are
+       given. Otherwise it is silently ignored and log output is
+       written to stderr.
 "
 
+##################
+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.
+       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
 
@@ -81,18 +102,26 @@ groupoption "create" C
 "Create a new snapshot"
 group="command"
 details="
-       Execute the rsync command to create a new snapshot. Note that this
-       command does not care about free disk space.
+       Execute the rsync command to create a new snapshot. Note that
+       this command does not care about free disk space.
 "
+
 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 its interval number
+       is greater or equal than the specified number of unit
+       intervals. See the \"Intervals\" section below for the precise
+       definition of these terms.
+
+       A snapshot is said to be redundant if it belongs to an
+       interval that already contains more than the desired number
+       of snapshots.
+
+       The prune command gets rid of both outdated and redundant
+       snapshots.
 "
 
 groupoption "ls" L
@@ -111,7 +140,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.
 "
 
 ###############################
@@ -146,7 +177,7 @@ option "source-dir" -
 #~~~~~~~~~~~~~~~~~~~~
 "The data directory"
 string typestr="dirname"
-optional
+required
 details="
        The directory on the remote host from which snapshots are
        taken.  Of course, the user specified as --remote-user must
@@ -157,13 +188,28 @@ option "dest-dir" -
 #~~~~~~~~~~~~~~~~~~
 "Snapshot dir"
 string typestr="dirname"
-optional
+required
 details="
        The destination directory on the local host where snapshots
        will be written. This must be writable by the user who runs
        dss.
 "
 
+option "no-resume" -
+#~~~~~~~~~~~~~~~~~~~
+"Do not try to resume from previous runs"
+flag off
+details = "
+       Starting from version 0.1.4, dss tries to resume from a
+       previously cancelled dss instance by default. It does so by
+       looking at the status of the most recently created snapshot. If
+       this snapshot status is incomplete, its directory is reused
+       as the destination directory for a subsequent rsync run.
+
+       The --no-resume option deactivates this feature so that a new
+       directory is always used as the rsync destination directory.
+"
+
 option "rsync-option" O
 #~~~~~~~~~~~~~~~~~~~~~~
 "Further rsync options"
@@ -171,15 +217,13 @@ 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:
 
-option "exclude-patterns" e
-#~~~~~~~~~~~~~~~~~~~~~~~~~~
-"Rsync exclude patterns"
-string typestr="path"
-optional
+               --rsync-option --exclude --rsync-option /proc
+"
 
 ###################
 section "Intervals"
@@ -192,29 +236,22 @@ int typestr="days"
 default="4"
 optional
 details="
-       dss snapshot aging is implemented in terms of intervals. There are
-       two command line options related to intervals: the duration of a
-       \"unit\" interval and the number of those unit intervals.
-
-       dss removes any snapshots older than the given number of intervals
-       times the duration of a unit interval and tries to keep the following
-       number of snapshots per interval:
-
-               interval number         number of snapshots
-               ===============================================
-               0                       2 ^ (num-intervals - 1)
-               1                       2 ^ (num-intervals - 2)
-               2                       2 ^ (num-intervals - 3)
-               ...
-               num-intervals - 2                       2
-               num-intervals - 1                       1
-               num-intervals                           0
-
-       In other words, the oldest snapshot will at most be unit_interval *
-       num_intervals old (= 5 days * 4 = 20 days if default values are used).
-       Moreover, there are at most 2^num_intervals - 1 snapshots in total
-       (i. e. 31 by default).  Observe that you have to create at least
-       2 ^ (num_intervals - 1) snapshots each interval for this to work out.
+       dss snapshot aging is implemented in terms of intervals. There
+       are two command line options related to intervals: the
+       duration u of a \"unit\" interval and the number n of those
+       unit intervals.
+
+       dss removes any snapshots older than n times u and tries to
+       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
+       each interval for this to work out because that is the number
+       of snapshots in interval zero.
 "
 
 option "num-intervals" n
@@ -232,29 +269,88 @@ option "pre-create-hook" r
 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed before snapshot creation"
 string typestr="command"
-default="/bin/true"
+default = "true"
 optional
 details="
        Execute this command before trying to create a new snapshot.
-       If this command returns with a non-zero exit status, do not
-       perform the backup. One possible application of this is to
-       return non-zero during office hours in order to not slow down
-       the file systems by taking snapshots.
-"
+       If this command returns with a non-zero exit status, no
+       snapshot is being created and the operation is retried later.
+
+       For example, one might want to execute a script that checks
+       whether all snapshot-related file systems are properly mounted.
 
+       Another possible application of this is to return non-zero
+       during office hours in order to not slow down the file systems
+       by taking snapshots.
+"
 
 option "post-create-hook" o
 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed after snapshot creation"
 string typestr="command"
-default="/bin/true"
+default = "true"
+optional
+details="
+       Execute this after a snapshot has successfully been
+       created. The full path of the newly created snapshot is
+       passed to the hook as the first argument.  The exit code of
+       this hook is ignored.
+
+       For instance this hook can be used to count the number of
+       files per user and/or the disk usage patterns in order to
+       store them in a database for further analysis.
+"
+
+option "pre-remove-hook" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Executed before snapshot removal"
+string typestr="command"
+default = "true"
 optional
 details="
-       Execute this after a snapshot has successfully been created
-       The return value on the command is ignored. For instance one
-       could count the number of files per user and/or the disk
-       usage patterns in order to store them in a database for
-       further treatment.
+       Execute this command before removing a snapshot. The full
+       path to the snapshot about to be deleted is passed to the
+       command as the first argument. If the 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"
+default = "true"
+optional
+details="
+       Execute this after a snapshot has successfully been removed. As
+       for the pre-remove hook, 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"
+default = "true"
+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.
 "
 
 ###############################
@@ -268,15 +364,15 @@ int typestr="megabytes"
 default="100"
 optional
 details="
-       If less than this many megabytes of space is available on
-       the file system containing the destination directory, \"dss
-       --run\" will suspend the currently running rsync process and will
-       start to remove snapshots, starting from the oldest snapshot,
-       until the free disk space exceeds this value.  See also the
-       --min_free_percent option.
+       If disk space on the file system containing the destination
+       directory gets low, \"dss --run\" will suspend the currently
+       running rsync process and will start to remove snapshots in
+       order to free disk space. This option specifies the minimal
+       amount of free disk space. If less than the given number of
+       megabytes is available, snapshots are being deleted. See also
+       the --min_free_percent and the min-free-percent-inodes options.
 
        A value of zero deactivates this check.
-
 "
 
 option "min-free-percent" p
@@ -286,7 +382,41 @@ int typestr="percent"
 default="2"
 optional
 details="
-       See --min-free-mb.  Note that it is not recommended to set both
+       See --min-free-mb. Note that 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.
 "
+option "min-free-percent-inodes" i
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Minimal percent of free inodes"
+int typestr="percent"
+default="0"
+optional
+details="
+       Specify the minimum amount of free inodes on the file system
+       containing the destination dir. If less than that many inodes
+       are free, snapshot removal kicks in just as in case of low
+       disk space.
+
+       Note that not every file system supports the concept of inodes.
+       Moreover it is not possible to reliably detect whether this is
+       the case. Therefore this feature is disabled by default. It's
+       safe to enable it for ext2/ext3/ext4 file systems on linux
+       though.
+
+       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.
+"