X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=7afa4ca94237c70b17563ce206d125372dfead7a;hp=171142eb1bc730d47d01437a78278af113ba1836;hb=7ce5c98850d6888586eaceb88da809286e751f96;hpb=301b9cccfc5de2489b70a46850933ff688ed9732 diff --git a/dss.ggo b/dss.ggo index 171142e..7afa4ca 100644 --- a/dss.ggo +++ b/dss.ggo @@ -1,6 +1,9 @@ +# Copyright (C) 2008 Andre Noll # +# Licensed under the GPL v2. For licencing details see COPYING. + package "dss" -version "0.0.3" +version "0.1.0" purpose "the dyadic snapshot scheduler dss creates hardlink-based snapshots of a given directory on a remote @@ -29,9 +32,6 @@ details=" 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. - - Note that it is not possible to change whether dss runs as - background daemon by sending SIGHUP. " option "daemon" d @@ -43,6 +43,9 @@ details=" Note that dss refuses to start in daemon mode if no logfile was specified. This option is mostly useful in conjuction 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 @@ -66,7 +69,7 @@ int typestr="level" default="3" optional details=" - Lower values mean less verbose logging. + Lower values mean more verbose logging. " option "logfile" - @@ -79,11 +82,17 @@ details=" is also 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 @@ -92,18 +101,20 @@ groupoption "create" C "Create a new snapshot" group="command" details=" - Execute the rsync command to create a new snapshot. Note 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 it belongs to an interval + greater than the maximum number of intervals. It is said to be + redundant if it belongs to an interval that already contains + more than the desired number of snapshots. This command gets + rid of such snapshots. " groupoption "ls" L @@ -122,7 +133,9 @@ 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. " ############################### @@ -186,12 +199,6 @@ details=" to that option are passed verbatim to the rsync command. " -option "exclude-patterns" e -#~~~~~~~~~~~~~~~~~~~~~~~~~~ -"Rsync exclude patterns" -string typestr="path" -optional - ################### section "Intervals" ################### @@ -203,29 +210,22 @@ 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 a 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. + dss 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 n of those + unit intervals. + + dss removes any 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, 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 + each interval for this to work out because that is the number + of snapshots in interval zero. " option "num-intervals" n @@ -264,13 +264,29 @@ string typestr="command" 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 "exit-hook" e +#~~~~~~~~~~~~~~~~~~~ +"Executed if run command exits" +string typestr="command" +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. " ############################### @@ -284,15 +300,15 @@ int typestr="megabytes" default="100" optional details=" - If less than this many megabytes of space is available on - the file system containing the destination directory, \"dss - --run\" will suspend 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 @@ -302,7 +318,40 @@ int typestr="percent" default="2" optional details=" - See --min-free-mb. Note that it is not recommended to set both + 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 ext3 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 inode ratio + becomes low. Use this flag if the file system containing the + destination directory is used for snapshots only. +"