-# Copyright (C) 2008-2010 Andre Noll <maan@systemlinux.org>
+# Copyright (C) 2008-2010 Andre Noll <maan@tuebingen.mpg.de>
#
# Licensed under the GPL v2. For licencing details see COPYING.
package "dss"
-version "0.1.4"
+version "0.1.7"
purpose "the dyadic snapshot scheduler
dss creates hardlink-based snapshots of a given directory on a remote
#~~~~~~~~~~~~~~~~
"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 conjuction
- with the -R option described below.
+ 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.
+ Note that it is not possible to change whether dss runs as background
+ daemon by sending SIGHUP.
"
option "dry-run" D
"Logfile for the dss daemon process"
string typestr="filename"
optional
+default="/dev/null"
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.
+ given. Otherwise it is silently ignored and log output is written
+ to stderr.
+
+ The default value means that nothing will be logged in daemon mode
+ unless this option is given.
"
##################
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"
--rsync-option --exclude --rsync-option /proc
"
+option "max-rsync-errors" -
+"Terminate after this many rsync failures"
+int typestr="count"
+default="10"
+optional
+details="
+ Only relevant when operating in --run mode (see above). If
+ the rsync process exits with a fatal error, dss restarts
+ the command in the hope that the problem is transient
+ and subsequent rsync runs succeed. After the given number
+ of consecutive rsync error exits, however, dss gives up,
+ executes the exit hook and terminates. Set this to zero if
+ dss should exit immediately on the first rsync error.
+
+ The only non-fatal error is when rsync exits with code 24. This
+ indicates a partial transfer due to vanished source files
+ and happens frequently when snapshotting a directory which
+ is concurrently being modified.
+"
+
###################
section "Intervals"
###################
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.
+ 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 of unit intervals, denoted n below.
+
+ dss removes 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 to n - 1, with zero being the most recent unit interval.
+
+ Hence the oldest snapshot will at most be u * n days old (4 days *
+ 5 intervals = 20 days, if default values are used). Moreover, there
+ are at most 2^n - 1 snapshots in total (2^5 - 1 = 31 by default). Note
+ that for this to work out your system must be fast enough to create at
+ least 2^(n - 1) snapshots per unit interval (16 snapshots in 4 days =
+ one snapshot in 6 hours), because this is the number of snapshots in
+ interval zero.
"
option "num-intervals" n
int typestr="num"
default="5"
optional
+details="
+ Note that increasing this number by one doubles the total number of
+ snapshots. See the documentation of --unit-interval above.
+"
###############
section "Hooks"
"Prune by disk space only"
flag off
details="
- If this flag is not given dss removes redundant and outdated
- snapshots automatically.
+ By default, redundant and outdated snapshots are removed automatically
+ to keep the number of snapshots in harmony with the configured
+ policy. If this flag is given, dss removes such snapshots only if
+ disk space or number of free inodes becomes low.
+"
+
+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.
- 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.
+ 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.
"