[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-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 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 Andre Noll .ME [/section] [section see also] .BR ssh (1) , .BR rsync (1) [/section]