+# 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.4"
+version "0.1.5"
purpose "the dyadic snapshot scheduler
dss creates hardlink-based snapshots of a given directory on a remote
"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.
+
"
required
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
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.
+"
+
+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.
+"
+
+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.
"
###############################
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"
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"
unit intervals.
dss removes any snapshots older than n times u and tries to
- keep 2^(k-1) snapshots in interval k, where the interval number
- k counts from zero, zero being the most recent unit interval.
+ 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
+ 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.
"
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed before snapshot creation"
string typestr="command"
+default = "true"
optional
details="
Execute this command before trying to create a new snapshot.
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed after snapshot creation"
string typestr="command"
+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 return value of that
- hook is ignored.
+ 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 treatment.
+ 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 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.
"
###############################
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Minimal percent of free inodes"
int typestr="percent"
-default="2"
+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, snatshot removal kicks in just as in case of low
+ are free, snapshot removal kicks in just as in case of low
disk space.
- A value of zero deactivates this check.
+ 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.
+"
+
+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.
"
projects / dss.git / blobdiff