+# Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
#
+# Licensed under the GPL v2. For licencing details see COPYING.
+
package "dss"
-version "0.0.2"
-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')"
-
- 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
#~~~~~~~~~~~~~~~~
-"run as background daemon"
+"Run as background daemon"
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="
- 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.
"
+#################
+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="
- 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
#~~~~~~~~~~~~~~~~~~~~~
-"create a new snapshot"
+"Create a new snapshot"
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
#~~~~~~~~~~~~~~~~~~~~
-"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 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
#~~~~~~~~~~~~~~~~~
-"print a list of all snapshots"
+"Print a list of all snapshots"
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
#~~~~~~~~~~~~~~~~~~
-"start creating and pruning snapshots"
+"Start creating and pruning snapshots"
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"
-#~~~~~~~~~~~~~~~~~~
+###################
-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"
-#==============
+###############
-option "pre_create_hook" r
+option "pre-create-hook" r
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"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"
-
- string typestr="command"
- default="/bin/true"
- optional
-
+string typestr="command"
+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 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 "creation_sleep" s
-#~~~~~~~~~~~~~~~~~~~~~~~~
-"sleep interval"
-
- int typestr="minutes"
- default="60"
- optional
+option "exit-hook" e
+#~~~~~~~~~~~~~~~~~~~
+"Executed if run command exits"
+string typestr="command"
+optional
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.
+ 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 "min_free_mb" m
-#~~~~~~~~~~~~~~~~~~~~~
-
-"minimal amount of free disk space"
- int typestr="gigabytes"
- default="100"
- optional
+###############################
+section "Disk space monitoring"
+###############################
+option "min-free-mb" m
+#~~~~~~~~~~~~~~~~~~~~~
+"Minimal amount of free disk space"
+int typestr="megabytes"
+default="100"
+optional
details="
- If less that this many megabytes of space is available, \"dss
- --run\" dss will start to remove snapshots (starting from the
- oldest snapshot) until the free disk space exeecds 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" -
+option "min-free-percent" p
#~~~~~~~~~~~~~~~~~~~~~~~~~~
-"minimal percent of free disk space"
+"Minimal percent of free disk space"
int typestr="percent"
default="2"
optional
details="
- See --min_free. Note that it is not recommended to set both
- --min_fre_mb and --min_free_percent to zero as this will
+ 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 ext3 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 inode ratio
+ becomes low. Use this flag if the file system containing the
+ destination directory is used for snapshots only.
+"