+[suite dss]
+caption = Subcommands
+
+[supercommand dss]
+ [description]
+ dss creates hardlink-based snapshots of a given directory on a remote
+ or local host using rsync's link-dest feature.
+ [/description]
+ purpose = the dyadic snapshot scheduler
+ synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
+
+ [option general-options-section]
+ summary = General options
+ flag ignored
+ [option help]
+ summary = print help and exit
+ short_opt = h
+ [option detailed-help]
+ summary = print help, including all details, and exit
+ [option version]
+ summary = print version and exit
+ short_opt = V
+ [option config-file]
+ short_opt = c
+ summary = use alternative config file (default: ~/.dssrc)
+ typestr = path
+ arg_info = required_arg
+ arg_type = string
+ [help]
+ 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 one exception to this rule: The run subcommand
+ re-reads the configuration file when it receives the HUP 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 by sending SIGHUP.
+ [/help]
+ [option loglevel]
+ short_opt = l
+ summary = set loglevel (0-6)
+ typestr = level
+ arg_info = required_arg
+ arg_type = uint32
+ default_val = 4
+ [help]
+ Lower values mean more verbose logging.
+ [/help]
+ [option dry-run]
+ short_opt = n
+ summary = only print what would be done
+ [help]
+ This flag does not make sense for all subcommands. The run subcommand
+ refuses to start if this option was given while the ls subcommand
+ silently ignores the flag.
+ [/help]
+ [option source-dir]
+ summary = the remote directory to snapshot
+ typestr = dirname
+ arg_info = required_arg
+ arg_type = string
+ [help]
+ 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.
+
+ This option is mandatory for the create and run subcommands: It must
+ be given at the command line or in the config file.
+ [/help]
+ [option dest-dir]
+ summary = where snapshots are stored
+ typestr = dirname
+ arg_info = required_arg
+ arg_type = string
+ [help]
+ The destination directory on the local host where snapshots will be
+ written. This must be writable by the user who runs dss.
+
+ This option is mandatory for all subcommands except kill.
+ [/help]
+ [option Rsync-options]
+ summary = Controlling how rsync is run
+ flag ignored
+ [help]
+ These options are only relevant to the run and the create subcommands.
+ [/help]
+ [option remote-host]
+ short_opt = H
+ summary = host to take snapshots from
+ typestr = hostname
+ arg_info = required_arg
+ arg_type = string
+ default_val = localhost
+ [help]
+ 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.
+ [/help]
+ [option remote-user]
+ short_opt = U
+ summary = Remote user name (default: current user)
+ arg_info = required_arg
+ typestr = username
+ arg_type = string
+ [help]
+ Set this if the user that runs dss is different from the user on the
+ remote host.
+ [/help]
+ [option rsync-option]
+ short_opt = O
+ summary = further rsync options
+ typestr = option
+ arg_info = required_arg
+ arg_type = string
+ flag multiple
+ [help]
+ 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
+ [/help]
+ [option intervals]
+ summary = Fine tuning the number of snapshots per time unit
+ flag ignored
+ [help]
+ 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.
+ [/help]
+ [option unit-interval]
+ short_opt = u
+ summary = the duration of a unit interval
+ typestr = days
+ arg_info = required_arg
+ arg_type = uint32
+ default_val = 4
+ [help]
+ Increasing this number instructs dss to create fewer snapshots per
+ time unit while the number of snapshots to keep stays the same.
+ [/help]
+ [option num-intervals]
+ short_opt = n
+ summary = the number of unit intervals
+ typestr = num
+ arg_info = required_arg
+ arg_type = uint32
+ default_val = 5
+ [help]
+ Increasing this number by one doubles the total number of
+ snapshots.
+ [/help]
+ [option hooks]
+ summary = Commands to be run on certain events
+ flag ignored
+ [help]
+ All hooks default to "true". That is, the true(1) utility (which
+ always returns with exit code zero) is executed if the hook command
+ is not specified.
+ [/help]
+ [option pre-create-hook]
+ short_opt = r
+ summary = executed before a snapshot is created
+ typestr = command
+ arg_info = required_arg
+ arg_type = string
+ default_val = true
+ [help]
+ This command is executed before dss runs rsync to create a new
+ snapshot. If the command returns with a non-zero exit status, no
+ snapshot will be created and the operation is retried later.
+
+ For example, the command could execute a script that checks whether
+ all snapshot-related file systems are mounted.
+
+ Another possible application of the pre-create hook is to return
+ non-zero during office hours in order to not slow down the file
+ systems by taking snapshots.
+ [/help]
+ [option post-create-hook]
+ summary = executed after a snapshot has been created
+ typestr = command
+ arg_info = required_arg
+ arg_type = string
+ default_val = true
+ [help]
+ This is only executed if 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 could count the number of files per user
+ and/or compute disk usage patterns to be stored in a database for
+ further analysis.
+ [/help]
+ [option pre-remove-hook]
+ summary = executed before a snapshot is removed
+ typestr = command
+ arg_info = required_arg
+ arg_type = string
+ default_val = true
+ [help]
+ The full path to the snapshot which is about to be removed is passed
+ to the command as the first argument. If the command returns with
+ a non-zero exit status, the snapshot is not going to be removed and
+ the operation is retried later.
+
+ For example, one could 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.
+ [/help]
+ [option post-remove-hook]
+ summary = executed after snapshot removal
+ typestr = command
+ arg_info = required_arg
+ arg_type = string
+ default_val = true
+ [help]
+ 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.
+ [/help]
+ [option exit-hook]
+ summary = executed before the run command exits
+ typestr = command
+ arg_info = required_arg
+ arg_type = string
+ default_val = true
+ [help]
+ This hook is only relevant to the run subcommand. It is executed just
+ before dss terminates. The reason for termination 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.
+ [/help]
+
+ [option disk-space-monitoring]
+ summary = Disk space monitoring
+ flag ignored
+ [help]
+ The options of this section control the aggressiveness of snapshot
+ removal. That is, they define under which circumstances existing
+ snapshots are removed. These options are only relevant to the run
+ and the prune subcommands.
+ [/help]
+ [option min-free-mb]
+ short_opt = m
+ summary = minimal amount of free disk space
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = megabytes
+ default_val = 100
+ [help]
+ If disk space on the file system containing the destination
+ directory gets low, the run subcommand suspends the currently
+ running rsync process and starts 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 below.
+
+ A value of zero deactivates this check.
+ [/help]
+ [option min-free-percent]
+ short_opt = p
+ summary = minimal percentage of free disk space
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = percent
+ default_val = 2
+ [help]
+ This is like --min-free-mb but allows to specify the amount of
+ free disk space as a percentage. 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.
+ [/help]
+ [option min-free-percent-inodes]
+ short_opt = i
+ summary = minimal percent of free inodes
+ arg_info = required_arg
+ arg_type = uint32
+ typestr = percent
+ default_val = 0
+ [help]
+ The minimum amount of free inodes on the file system containing the
+ destination dir. If the percentage of free inodes drops below the
+ given value, snapshot removal kicks in like in case of low disk space.
+
+ The number of free inodes is determined from the f_ffree field of
+ the statvfs structure. However, some file systems set this field to
+ zero, indicating that the number of inodes is basically unlimited.
+ 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.
+ [/help]
+ [option keep-redundant]
+ short_opt = k
+ summary = prune by disk space only
+ [help]
+ 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.
+ [/help]
+ [option min-complete]
+ summary = minimal number of complete snapshots to keep
+ arg_info = optional_arg
+ arg_type = uint32
+ typestr = num
+ default_val = 1
+ [help]
+ 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 snapshots are left, and there is not enough
+ disk space available for another snapshot, the program terminates
+ with a "No space left on device" error.
+ [/help]
+
+[introduction]
+ dss supports the subcommands described below. If no subcommand is
+ given, the list of available subcommands is shown and the program
+ terminates successfully without performing any further action.
+[/introduction]
+
+[subcommand run]
+ purpose = start creating and pruning snapshots
+ [description]
+ This is the main mode of operation. Snapshots are 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.
+ [/description]
+ [option daemon]
+ short_opt = d
+ summary = run as background daemon
+ [help]
+ If this option is given, the dss command detaches from the console
+ and continues to run in the background. It is not possible to let
+ a daemonized process re-attach to the console by editing the config
+ file and sending SIGHUP. However, log output may be redirected to a
+ different file in this way.
+
+ See --logfile.
+ [/help]
+ [option logfile]
+ short_opt = l
+ summary = where to write log output
+ arg_info = required_arg
+ arg_type = string
+ typestr = path
+ default_val = /dev/null
+ [help]
+ This option is only honored if --daemon is given, in which case
+ log messages go to the given file. Otherwise the option is silently
+ ignored and log output is written to stderr.
+ [/help]
+ [option max-rsync-errors]
+ summary = terminate after this many rsync failures
+ typestr = count
+ arg_info = required_arg
+ arg_type = uint32
+ default_val = 10
+ [help]
+ 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.
+ [/help]
+[subcommand create]
+ purpose = execute rsync once to create a new snapshot
+ [description]
+ This command does not check the amount free disk space. The pre-create
+ and post-create hooks are honored, however.
+
+ Specify --dry-run to see the rsync command which is executed to create
+ snapshots.
+ [/description]
+[subcommand prune]
+ purpose = remove redundant and outdated snapshots
+ [description]
+ A snapshot is considered outdated if its interval number is greater or
+ equal than the specified number of unit intervals. See --unit-interval
+ and --num-intervals above.
+
+ A snapshot is said to be redundant if the interval it belongs to
+ contains more than the configured number of snapshots.
+
+ The prune command gets rid of both outdated and redundant snapshots. At
+ most one snapshot is removed per invocation. If --dry-run is given, the
+ subcommand only prints the snapshot that would be removed.
+ [/description]
+[subcommand ls]
+ purpose = print the list of all snapshots
+ [description]
+ The list contains all existing snapshots, no matter of their state.
+ Incomplete snapshots and snapshots being deleted will also be listed.
+ [/description]
+[subcommand kill]
+ purpose = send a signal to a running dss process
+ [description]
+ This sends a signal 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.
+ [/description]
+ [option signal]
+ short_opt = s
+ summary = send the given signal rather than SIGTERM
+ typestr = signal
+ arg_info = required_arg
+ arg_type = string
+ default_val = SIGTERM
+ [help]
+ Like for kill(1), alternate signals may be specified in three ways: as
+ a signal number (e.g., 9), the signal name (e.g., KILL), or the signal
+ name prefixed with "SIG" (e.g., SIGKILL). In the latter two forms,
+ the signal name and the prefix are case insensitive, so "sigkill"
+ works as well.
+
+ Sending SIGHUP causes the running dss process to reload its config file.
+ [/help]
+
+[section copyright]
+ Written by Andre Noll
+ .br
+ Copyright (C) 2008 - present Andre Noll
+ .br
+ License: GNU GPL version 2
+ .br
+ This is free software: you are free to change and redistribute it.
+ .br
+ There is NO WARRANTY, to the extent permitted by law.
+ .br
+ Report bugs to
+ .MT <maan@tuebingen.mpg.de>
+ Andre Noll
+ .ME
+[/section]
+
+[section see also]
+ .BR ssh (1) ,
+ .BR rsync (1)
+[/section]