X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=9587dd24c7b11a439b2c63335ba922361e1cf988;hp=849b40d102aa08ec31e2853dcd10b2330bb12839;hb=331602985a9b73157dfba5ceffd2c257e078c197;hpb=f8552c6c6a9178df3dc01b699fc46971dff2a18d diff --git a/dss.ggo b/dss.ggo index 849b40d..9587dd2 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.4" +version "0.1.5" purpose "the dyadic snapshot scheduler dss creates hardlink-based snapshots of a given directory on a remote @@ -74,17 +77,23 @@ option "logfile" - "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. +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. " +################## +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 @@ -99,13 +108,20 @@ details=" 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 @@ -124,7 +140,28 @@ groupoption "run" R 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. +" + +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. " ############################### @@ -177,6 +214,21 @@ details=" 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" @@ -184,15 +236,13 @@ 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: -option "exclude-patterns" e -#~~~~~~~~~~~~~~~~~~~~~~~~~~ -"Rsync exclude patterns" -string typestr="path" -optional + --rsync-option --exclude --rsync-option /proc +" ################### section "Intervals" @@ -211,13 +261,14 @@ details=" unit intervals. dss removes any snapshots older than n times u and tries to - keep 2^(k-1) snapshots in interval k, where the interval number - k counts from zero, zero being the most recent unit interval. + keep 2^(n - k - 1) snapshots in interval k, where the interval + number k counts from zero, zero being the most recent unit + interval. In other words, the oldest snapshot will at most be u * n days (= 20 days if default values are used) old. Moreover, there are at most 2^n - 1 snapshots in total (i. e. 31 by default). - Observe that you have to create at least 2 ^ (n - 1) snapshots + Observe that you have to create at least 2^(n - 1) snapshots each interval for this to work out because that is the number of snapshots in interval zero. " @@ -237,6 +288,7 @@ 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. @@ -255,16 +307,69 @@ 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 return value of that - hook is ignored. + 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 treatment. + 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. " ############################### @@ -304,13 +409,53 @@ option "min-free-percent-inodes" i #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "Minimal percent of free inodes" int typestr="percent" -default="2" +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, snatshot removal kicks in just as in case of low + are free, snapshot removal kicks in just as in case of low disk space. - A value of zero deactivates this check. + 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=" + If this flag is not given dss removes redundant and outdated + snapshots automatically. + + Otherwise, this feature is deactivated so that snapshots are + only being removed in case disk space or number of free inodes + becomes low. Use this flag if the file system containing the + destination directory is used for snapshots only. +" + +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. "