Add dss.1 and dss.1.html to .gitignore.

[dss.git] / dss.ggo

diff --git a/dss.ggo b/dss.ggo
index 8dd7090b19c857aeb83c4ecd4cfda8d86f8f7a7b..7afa4ca94237c70b17563ce206d125372dfead7a 100644 (file)
--- a/dss.ggo
+++ b/dss.ggo
@@ -1,263 +1,357 @@
+# Copyright (C) 2008 Andre Noll <maan@systemlinux.org>

 #
 #

+# Licensed under the GPL v2. For licencing details see COPYING.
+

 package "dss"
 package "dss"

-version "0.0.1"
-purpose "the dyadic snapshot scheduler"
+version "0.1.0"
+purpose "the dyadic snapshot scheduler
+
+dss creates hardlink-based snapshots of a given directory on a remote
+or local host using rsync's link-dest feature.
+"

 
 

+#########################
+section "General options"
+#########################

 
 

-option "config_file" c
+option "config-file" c

 #~~~~~~~~~~~~~~~~~~~~~
 "(default='~/.dssrc')"
 #~~~~~~~~~~~~~~~~~~~~~
 "(default='~/.dssrc')"

-
-       string typestr="filename"
-       optional
-
-section "Logging"
-#~~~~~~~~~~~~~~~~
-
-option "loglevel" l
-#~~~~~~~~~~~~~~~~~~
-
-"set loglevel (0-6)"
-
-       int typestr="level"
-       default="4"
-       optional
-
-option "logfile" -
-#~~~~~~~~~~~~~~~~~
-
-"logfile for the dss daemon process"
-
-       string typestr="filename"
-       optional
+string typestr="filename"
+optional
+details="
+       Options may be given at the command line or in the
+       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
 #~~~~~~~~~~~~~~~~
 
 option "daemon" d
 #~~~~~~~~~~~~~~~~

-"run as background daemon"
+"Run as background daemon"

 flag off
 dependon="logfile"
 details="
 flag off
 dependon="logfile"
 details="

-       Note that dsss refuses to start in daemon mode if no logfile
-       was specified.
+       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
+option "dry-run" D

 #~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~

-"only print what would be done"
+"Only print what would be done"

 flag off
 details="
 flag off
 details="

-       This flag does not makes sense for all commands. The run
+       This flag does not make sense for all commands. The run

        command refuses to start if this option was given. The ls
        command silently ignores this flag.
 "
 
        command refuses to start if this option was given. The ls
        command silently ignores this flag.
 "
 

+#################
+section "Logging"
+#################
+
+option "loglevel" l
+#~~~~~~~~~~~~~~~~~~
+"Set loglevel (0-6)"
+int typestr="level"
+default="3"
+optional
+details="
+       Lower values mean more verbose logging.
+"
+
+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.
+"
+
+##################
+section "Commands"
+##################
+

 defgroup "command"
 #=================
 groupdesc="
 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
 
 groupoption "create" C
 #~~~~~~~~~~~~~~~~~~~~~
 "
 required
 
 groupoption "create" C
 #~~~~~~~~~~~~~~~~~~~~~

-"create a new snapshot"
+"Create a new snapshot"

 group="command"
 details="
 group="command"
 details="

-       Execute the rsync command to create a new snapshot.Mote 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
 #~~~~~~~~~~~~~~~~~~~~
 groupoption "prune" P
 #~~~~~~~~~~~~~~~~~~~~

-"remove a redundant snapshot"
+"Remove redundant and outdated snapshots"

 group="command"
 details="
 group="command"
 details="

-       A snapshot is considered redundant if it ether belongs to
-       an interval greater than the maximum nuber 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 it belongs to an interval
+       greater than the maximum number of intervals. It is said to be
+       redundant if it belongs to an interval that already contains
+       more than the desired number of snapshots. This command gets
+       rid of such snapshots.

 "
 
 groupoption "ls" L
 #~~~~~~~~~~~~~~~~~
 "
 
 groupoption "ls" L
 #~~~~~~~~~~~~~~~~~

-"print a list of all snapshots"
+"Print a list of all snapshots"

 group="command"
 details="
 group="command"
 details="

-       The list will contain all snapshots not matter of their state,
-       i.e. incomplete snapshots and snapshots being deleted will
+       The list will contain all snapshots no matter of their state,
+       i. e. incomplete snapshots and snapshots being deleted will

        also be listed.
 "
 
 groupoption "run" R
 #~~~~~~~~~~~~~~~~~~
        also be listed.
 "
 
 groupoption "run" R
 #~~~~~~~~~~~~~~~~~~

-"start creating and pruning snapshots"
+"Start creating and pruning snapshots"

 group="command"
 details="
        This is the main mode of operation. Snapshots will be created
 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.

 "
 
 "
 

-section "rsync-related options"
-#==============================
+###############################
+section "Rsync-related options"
+###############################

 
 

-option "remote_user" U
+option "remote-host" H

 #~~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~~

+"Remote host"
+string typestr="hostname"
+default="localhost"
+optional
+details="
+       If this option is given and its value differs from the local
+       host, then rsync uses ssh. Make sure there is no password
+       needed for the ssh connection. To achieve that, use public key
+       authentication for ssh and, if needed, set the remote user name
+       by using the --remote-user option.
+"

 
 

-"remote user name (default: current user)"
-
-       string typestr="username"
-       optional
-
-option "remote_host" H
+option "remote-user" U

 #~~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~~

+"Remote user name (default: current user)"
+string typestr="username"
+optional
+details="
+       Set this if the user running dss is different from the
+       user at the remote host when using ssh.
+"

 
 

-"remote host"
-
-       string typestr="hostname"
-       default="localhost"
-       optional
-
-option "source_dir" -
+option "source-dir" -

 #~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~

+"The data directory"
+string typestr="dirname"
+required
+details="
+       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.
+"

 
 

-"directory to backup on the remote host"
-
-       string typestr="dirname"
-       optional
-
-option "dest_dir" -
+option "dest-dir" -

 #~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~

+"Snapshot dir"
+string typestr="dirname"
+required
+details="
+       The destination directory on the local host where snapshots
+       will be written. This must be writable by the user who runs
+       dss.
+"

 
 

-"snapshots dir on the local host"
-
-       string typestr="dirname"
-       optional
-
-option "rsync_option" O
+option "rsync-option" O

 #~~~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~~~

+"Further rsync options"
+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.
+"

 
 

-"further rsync options that are passed
-verbatim to the rsync command."
-
-       string typestr="option"
-       optional
-       multiple
-
-
-option "exclude_patterns" e
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"rsync exclude patterns"
-
-       string typestr="path"
-       optional
-
-
+###################

 section "Intervals"
 section "Intervals"

-#~~~~~~~~~~~~~~~~~~
+###################

 
 

-text "
-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 an 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_intervala 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
-num_intervals snapshots each interval for this to work out.  "
-
-option "unit_interval" u
+option "unit-interval" u

 #~~~~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~~~~

-"the duration of a unit interval"
-
-       int typestr="days"
-       default="4"
-       optional
+"The duration of a unit interval"
+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 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
+option "num-intervals" n

 #~~~~~~~~~~~~~~~~~~~~~~~
 #~~~~~~~~~~~~~~~~~~~~~~~

-"the number of unit intervals"
-
-       int typestr="num"
-       default="5"
-       optional
+"The number of unit intervals"
+int typestr="num"
+default="5"
+optional

 
 

+###############

 section "Hooks"
 section "Hooks"

-#==============
+###############

 
 

-option "pre_create_hook" r
+option "pre-create-hook" r

 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed before snapshot creation"
 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed before snapshot creation"

+string typestr="command"
+optional
+details="
+       Execute this command before trying to create a new snapshot.
+       If this command returns with a non-zero exit status, no
+       snapshot is being created and the operation is retried later.

 
 

-       string typestr="command"
-       default="/bin/true"
-       optional
+       For example, one might want to execute a script that checks
+       whether all snapshot-related file systems are properly mounted.

 
 

-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.
+       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
+option "post-create-hook" o

 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed after snapshot creation"
 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 "Executed after snapshot creation"

+string typestr="command"
+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.
+"

 
 

-       string typestr="command"
-       default="/bin/true"
-       optional
-
+option "exit-hook" e
+#~~~~~~~~~~~~~~~~~~~
+"Executed if run command exits"
+string typestr="command"
+optional

 details="
 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.
+       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.

 "
 "

-option "creation_sleep" s
-#~~~~~~~~~~~~~~~~~~~~~~~~
-"sleep interval"

 
 

-       int typestr="minutes"
-       default="60"
-       optional
+###############################
+section "Disk space monitoring"
+###############################

 
 

+option "min-free-mb" m
+#~~~~~~~~~~~~~~~~~~~~~
+"Minimal amount of free disk space"
+int typestr="megabytes"
+default="100"
+optional

 details="
 details="

-       The sleep interval for snapshot creation in minutes.
-       The daemon will, in an endlees loop, create a snapshot and
-       then sleep that many minutes.
+       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
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Minimal percent of free disk space"
+int typestr="percent"
+default="2"
+optional
+details="
+       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.

 
 

-option "min_free" m
-#~~~~~~~~~~~~~~~~~~
-
-"minimal amount of free 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 ext3 file systems on linux though.

 
 

-       int typestr="gigabytes"
-       default="50"
-       optional
+       A value of zero (the default) deactivates this check.
+"

 
 

+option "keep-redundant" k
+#~~~~~~~~~~~~~~~~~~~~~~~~
+"Prune by disk space only"
+flag off

 details="
 details="

-       If less that this many gigabytes of space is available,
-       dss will start to remove snapshots (starting from the oldest
-       snapshot) until the free disk space exeecds this value.
+       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 inode ratio
+       becomes low. Use this flag if the file system containing the
+       destination directory is used for snapshots only.

 "
 "