+++ /dev/null
-# 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.7"
-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
-#~~~~~~~~~~~~~~~~~~~~~
-"(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.
-"
-
-option "daemon" d
-#~~~~~~~~~~~~~~~~
-"Run as background daemon"
-flag off
-details="
- 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="3"
-optional
-details="
- Lower values mean more verbose logging.
-"
-
-option "logfile" -
-#~~~~~~~~~~~~~~~~~
-"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.
-
- The default value means that nothing will be logged in daemon mode
- unless this option is 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.
-
-"
-required
-
-groupoption "create" C
-#~~~~~~~~~~~~~~~~~~~~~
-"Create a new snapshot"
-group="command"
-details="
- Execute the rsync command to create a new snapshot. Note that
- this command does not care about free disk space.
-"
-
-groupoption "prune" P
-#~~~~~~~~~~~~~~~~~~~~
-"Remove redundant and outdated snapshots"
-group="command"
-details="
- 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"
-group="command"
-details="
- 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"
-group="command"
-details="
- This is the main mode of operation. Snapshots will be created
- 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.
-"
-
-###############################
-section "Rsync-related options"
-###############################
-
-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.
-"
-
-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" -
-#~~~~~~~~~~~~~~~~~~~~
-"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.
-"
-
-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.
-"
-
-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:
-
- --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"
-###################
-
-option "unit-interval" u
-#~~~~~~~~~~~~~~~~~~~~~~~
-"The duration of a unit interval"
-int typestr="days"
-default="4"
-optional
-details="
- 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
-#~~~~~~~~~~~~~~~~~~~~~~~
-"The number of unit intervals"
-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"
-###############
-
-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.
-
- For example, one might want to execute a script that checks
- whether all snapshot-related file systems are properly mounted.
-
- 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
-#~~~~~~~~~~~~~~~~~~~~~~~~~~
-"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 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 "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.
-"
-
-###############################
-section "Disk space monitoring"
-###############################
-
-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.
-"
-
-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="
- 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.
-
- 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