+# Copyright (C) 2008-2010 Andre Noll <maan@tuebingen.mpg.de>
#
+# Licensed under the GPL v2. For licencing details see COPYING.
+
package "dss"
-version "0.0.1"
-purpose "the dyadic snapshot scheduler"
+version "0.1.5"
+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
+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.
+"
- string typestr="filename"
- optional
+option "daemon" d
+#~~~~~~~~~~~~~~~~
+"Run as background daemon"
+flag off
+dependon="logfile"
+details="
+ Note that dss refuses to start in daemon mode if no logfile
+ was specified. This option is mostly useful in conjunction
+ 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
+#~~~~~~~~~~~~~~~~~
+"Only print what would be done"
+flag off
+details="
+ 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="4"
- optional
+"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
-
-option "daemon" d
-#~~~~~~~~~~~~~~~~
-"run as background daemon"
-flag off
-dependon="logfile"
-details="
- Note that dsss refuses to start in daemon mode if no logfile
- was specified.
+"Logfile for the dss daemon process"
+string typestr="filename"
+optional
+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
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 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
#~~~~~~~~~~~~~~~~~
-"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"
-#==============================
+groupoption "kill" K
+#~~~~~~~~~~~~~~~~~~~
+"Kill a running dss process"
+group="command"
+details="
+ This sends SIGTERM to the dss process that corresponds to the
+ given config file. If --dry-run is given, the PID of the dss
+ process is written to stdout, but no signal is sent.
+"
-option "remote_user" U
+groupoption "reload" -
#~~~~~~~~~~~~~~~~~~~~~
+"force a running dss process to reload its config file"
+group="command"
+details="
+ This differs from --kill only in that SIGHUP rather than SIGTERM
+ is sent to the dss process.
+"
-"remote user name (default: current user)"
-
- string typestr="username"
- optional
+###############################
+section "Rsync-related options"
+###############################
-option "remote_host" H
+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 host"
-
- string typestr="hostname"
- default="localhost"
- optional
+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.
+"
-option "source_dir" S
+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" D
+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 "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
+option "rsync-option" O
#~~~~~~~~~~~~~~~~~~~~~~
+"Further rsync options"
+string typestr="option"
+optional
+multiple
+details="
+ 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:
-"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
-
+ --rsync-option --exclude --rsync-option /proc
+"
+###################
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"
+default = "true"
+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"
+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 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 "pre-remove-hook" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Executed before snapshot removal"
+string typestr="command"
+default = "true"
+optional
+details="
+ 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="
- The sleep interval for snapshot creation in minutes.
- The daemon will, in an endlees loop, create a snapshot and
- then sleep that many minutes.
+ 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.
+"
-option "min_free" m
-#~~~~~~~~~~~~~~~~~~
+###############################
+section "Disk space monitoring"
+###############################
-"minimal amount of free space"
+option "min-free-mb" m
+#~~~~~~~~~~~~~~~~~~~~~
+"Minimal amount of free disk space"
+int typestr="megabytes"
+default="100"
+optional
+details="
+ 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.
+"
- int typestr="gigabytes"
- default="50"
- optional
+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.
+
+ 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 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 number of free inodes
+ becomes low. Use this flag if the file system containing the
+ destination directory is used for snapshots only.
+"
+
+option "min-complete" -
+#~~~~~~~~~~~~~~~~~~~~~~
+"Minimal number of complete snapshots to keep"
+int typestr = "num"
+default = "1"
+optional
+details = "
+ This option is only relevant if snapshots must be deleted
+ because disk space gets low.
+
+ dss refuses to remove old snapshots if there are fewer complete
+ snapshots left than the given number. The default value of one
+ guarantees that at least one complete snapshot is available
+ at all times.
+
+ If only <num> complete snapshot are left, and there is not
+ enough disk space available for another snapshot, the program
+ terminates with a \"No space left on device\" error.
"