X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=dss.suite;h=6d1ed4ab0dd4f5a47eb10c720f5fff5869ac5914;hb=refs%2Fheads%2Fpu;hp=95dd30ff9dc7ea5963957aad8e809a57d0277c52;hpb=50e03ce10c3bab1c43e1e68dca3b0471d63807d9;p=dss.git diff --git a/dss.suite b/dss.suite deleted file mode 100644 index 95dd30f..0000000 --- a/dss.suite +++ /dev/null @@ -1,507 +0,0 @@ -[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 changing 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 checksum] - summary = run rsync with --checksum occasionally - typestr = permille - arg_info = required_arg - arg_type = uint32 - default_val = 0 - [help] - If a file on the backup becomes corrupt in a way that file size - and modification time still match the original file, rsync will not - consider the file for transfer ("quick check"). Hence the corruption - stays on the backup until the file is modified on the source. - The --checksum option of rsync disables the quick check and compares - the contents of each file, fixing such corruptions. Since computing - the checksums adds a significant slowdown due to a lot of disk I/O, - the option is not enabled by default. - - The argument to the --checksum option of dss is a number between 0 - and 1000, inclusively, which determines the probability of adding - --checksum to the rsync options each time a snapshot is created. The - default value zero means to never add the option. The value 100 will - create every tenth snapshot (on average) using checksums, and the - value 1000 will always pass --checksum to rsync. - [/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 the amount of free disk space - is specified 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] -[subcommand configtest] - purpose = run a configuration file syntax test - [description] - This command checks the command line options and the configuration - file for syntactic correctness. It either reports "Syntax Ok" and - exits successfully or prints information about the first syntax error - detected and terminates with exit code 1. - [/description] - -[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]