X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=12871eaa9eabd78bb8006f2ca2b636b2c486dd92;hp=25b0d6bdc86ee00a5b487a30297907d511fd220d;hb=965855384d34b7f1c4730eb78f26d010adb9be42;hpb=ea63d92f2e18fa9b1488c5eabc8333f84b5728cf diff --git a/dss.ggo b/dss.ggo index 25b0d6b..12871ea 100644 --- a/dss.ggo +++ b/dss.ggo @@ -1,6 +1,9 @@ +# Copyright (C) 2008-2010 Andre Noll # +# Licensed under the GPL v2. For licencing details see COPYING. + package "dss" -version "0.0.2" +version "0.1.7" purpose "the dyadic snapshot scheduler dss creates hardlink-based snapshots of a given directory on a remote @@ -21,24 +24,34 @@ details=" 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" +"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 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" +"Only print what would be done" flag off details=" - This flag does not makes sense for all commands. The run + 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. " @@ -49,103 +62,143 @@ section "Logging" option "loglevel" l #~~~~~~~~~~~~~~~~~~ -"set loglevel (0-6)" +"Set loglevel (0-6)" int typestr="level" default="3" optional details=" - Lower values mean less verbose logging. + Lower values mean more verbose logging. " option "logfile" - #~~~~~~~~~~~~~~~~~ -"logfile for the dss daemon process" +"Logfile for the dss daemon process" string typestr="filename" optional -details=" - This option is mostly useful for the run command if --daemon - is also given. +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. + 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" +"Create a new snapshot" group="command" details=" - Execute the rsync command to create a new snapshot.Mote that this - command does not care about free disk space. + Execute the rsync command to create a new snapshot. Note that + this command does not care about free disk space. " + groupoption "prune" P #~~~~~~~~~~~~~~~~~~~~ -"remove a redundant snapshot" +"Remove redundant and outdated snapshots" group="command" details=" - A snapshot is considered redundant if it ether belongs to - an interval greater than the maximum number of intervals, - or if it belongs to an interval that already contains more - than the desired number of snapshots. + 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" +"Print a list of all snapshots" group="command" details=" - The list will contain all snapshots not matter of their state, - i.e. incomplete snapshots and snapshots being deleted will + 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" +"Start creating and pruning snapshots" group="command" details=" This is the main mode of operation. Snapshots will be created - as needed and pruned automatically. + 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. " -############################### -section "Rsync-related options" -############################### +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. +" -option "remote-user" U +groupoption "reload" - #~~~~~~~~~~~~~~~~~~~~~ -"remote user name (default: current user)" -string typestr="username" -optional +"force a running dss process to reload its config file" +group="command" details=" - If a user is specified that differs from the user running - dss, then rsync will use ssh for taking snapshots. This will - only work if you set up a key-pair to allow rsync to proceed - without asking for passwords. + 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" +"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, so make sure the user running dss - does not need a password to connect to the remote host. + 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" +"The data directory" string typestr="dirname" -optional +required details=" The directory on the remote host from which snapshots are taken. Of course, the user specified as --remote-user must @@ -154,31 +207,64 @@ details=" option "dest-dir" - #~~~~~~~~~~~~~~~~~~ -"snapshot dir" +"Snapshot dir" string typestr="dirname" -optional +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 "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" +"Further rsync options" string typestr="option" optional multiple details=" - These option may be given multiple times. The arguments passed - to that option are passed verbatim to the rsync command. + 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 "exclude-patterns" e -#~~~~~~~~~~~~~~~~~~~~~~~~~~ -"rsync exclude patterns" -string typestr="path" +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" @@ -186,42 +272,38 @@ section "Intervals" option "unit-interval" u #~~~~~~~~~~~~~~~~~~~~~~~ -"the duration of a unit interval" +"The duration of a unit interval" int typestr="days" default="4" optional details=" - dss snapshot aging is implemented in terms of intervals. There are - two command line options related to intervals: the duration of a - \"unit\" interval and the number of those unit intervals. - - dss removes any snapshots older than the given number of intervals - times the duration of an unit interval and tries to keep the following - number of snapshots per interval: - - interval number number of snapshots - =============================================== - 0 2 ^ (num-intervals - 1) - 1 2 ^ (num-intervals - 2) - 2 2 ^ (num-intervals - 3) - ... - num-intervals - 2 2 - num-intervals - 1 1 - num-intervals 0 - - In other words, the oldest snapshot will at most be unit_interval * - num_intervals old (= 5 days * 4 = 20 days if default values are used). - Moreover, there are at most 2^num_intervals - 1 snapshots in total - (i.e. 31 by default). Observe that you have to create at least - 2 ^ (num_intervals - 1) snapshots each interval for this to work out. + 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" +"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" @@ -231,61 +313,171 @@ option "pre-create-hook" r #~~~~~~~~~~~~~~~~~~~~~~~~~~ "Executed before snapshot creation" string typestr="command" -default="/bin/true" +default = "true" optional details=" Execute this command before trying to create a new snapshot. - If this command returns with a non-zero exit status, do not - perform the backup. One possible application of this is to - return non-zero during office hours in order to not slow down - the file systems by taking snapshots. -" + 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="/bin/true" +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=" - Execute this after a snapshot has successfully been created - The return value on the command is ignored. For instance one - could count the number of files per user and/or the disk - usage patterns in order to store them in a database for - further treatment. + 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" +section "Disk space monitoring" ############################### option "min-free-mb" m #~~~~~~~~~~~~~~~~~~~~~ -"minimal amount of free disk space" +"Minimal amount of free disk space" int typestr="megabytes" default="100" optional details=" - If less that this many megabytes of space is available on - the file system containing the destination directory, \"dss - --run\" will stop the currently running rsync process and will - start to remove snapshots, starting from the oldest snapshot, - until the free disk space exceeds this value. See also the - --min_free_percent option. + 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" +"Minimal percent of free disk space" int typestr="percent" default="2" optional details=" - See --min_free. Note that it is not recommended to set both - --min_fre_mb and --min_free_percent to zero as this will + 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 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. +"