X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=7afa4ca94237c70b17563ce206d125372dfead7a;hp=9af79d7b39217087580216483a1e4d2ec431b7d5;hb=7ce5c98850d6888586eaceb88da809286e751f96;hpb=0ff8f4b1fe02af09e36680844619323bebeb067b diff --git a/dss.ggo b/dss.ggo index 9af79d7..7afa4ca 100644 --- a/dss.ggo +++ b/dss.ggo @@ -1,244 +1,357 @@ +# Copyright (C) 2008 Andre Noll # +# Licensed under the GPL v2. For licencing details see COPYING. + package "dss" -version "0.0.1" -purpose "the dyadic snapshot scheduler" +version "0.1.0" +purpose "the dyadic snapshot scheduler + +dss creates hardlink-based snapshots of a given directory on a remote +or local host using rsync's link-dest feature. +" +######################### +section "General options" +######################### -option "config_file" c +option "config-file" c #~~~~~~~~~~~~~~~~~~~~~ "(default='~/.dssrc')" +string typestr="filename" +optional +details=" + 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 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. +" - string typestr="filename" - optional +option "daemon" d +#~~~~~~~~~~~~~~~~ +"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 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 +#~~~~~~~~~~~~~~~~~ +"Only print what would be done" +flag off +details=" + 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. +" + +################# section "Logging" -#~~~~~~~~~~~~~~~~ +################# option "loglevel" l #~~~~~~~~~~~~~~~~~~ - -"set loglevel (0-6)" - - int typestr="level" - default="4" - optional +"Set loglevel (0-6)" +int typestr="level" +default="3" +optional +details=" + Lower values mean more verbose logging. +" 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. +" -"logfile for the dss daemon process" - - string typestr="filename" - optional - +################## +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 nuber 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 #~~~~~~~~~~~~~~~~~ -"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" -#============================== +############################### +section "Rsync-related options" +############################### -option "remote_user" U +option "remote-host" H #~~~~~~~~~~~~~~~~~~~~~ +"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. 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. +" -"remote user name (default: current user)" - - string typestr="username" - optional - -option "remote_host" H +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. +" -"remote host" - - string typestr="hostname" - default="localhost" - optional - -option "source_dir" S +option "source-dir" - #~~~~~~~~~~~~~~~~~~~~ +"The data directory" +string typestr="dirname" +required +details=" + 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. +" -"directory to backup on the remote host" - - string typestr="dirname" - optional - -option "dest_dir" D +option "dest-dir" - #~~~~~~~~~~~~~~~~~~ +"Snapshot dir" +string typestr="dirname" +required +details=" + The destination directory on the local host where snapshots + will be written. This must be writable by the user who runs + dss. +" -"snapshots dir on the local host" - - string typestr="dirname" - optional - -option "rsync_option" O +option "rsync-option" O #~~~~~~~~~~~~~~~~~~~~~~ +"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. +" -"further rsync options that are passed -verbatim to the rsync command." - - string typestr="option" - optional - multiple - - -option "exclude_patterns" e -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -"rsync exclude patterns" - - string typestr="path" - optional - - +################### section "Intervals" -#~~~~~~~~~~~~~~~~~~ +################### -text " -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_intervala 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 -num_intervals snapshots each interval for this to work out. " - -option "unit_interval" u +option "unit-interval" u #~~~~~~~~~~~~~~~~~~~~~~~ -"the duration of a unit interval" - - int typestr="days" - default="4" - optional +"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 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 +option "num-intervals" n #~~~~~~~~~~~~~~~~~~~~~~~ -"the number of unit intervals" - - int typestr="num" - default="5" - optional +"The number of unit intervals" +int typestr="num" +default="5" +optional +############### section "Hooks" -#============== +############### -option "pre_create_hook" r +option "pre-create-hook" r #~~~~~~~~~~~~~~~~~~~~~~~~~~ "Executed before snapshot creation" +string typestr="command" +optional +details=" + Execute this command before trying to create a new snapshot. + If this command returns with a non-zero exit status, no + snapshot is being created and the operation is retried later. - string typestr="command" - default="/bin/true" - optional + For example, one might want to execute a script that checks + whether all snapshot-related file systems are properly mounted. -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. + 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 +option "post-create-hook" o #~~~~~~~~~~~~~~~~~~~~~~~~~~ "Executed after snapshot creation" +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 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. +" - string typestr="command" - default="/bin/true" - optional - +option "exit-hook" e +#~~~~~~~~~~~~~~~~~~~ +"Executed if run command exits" +string typestr="command" +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. " -option "creation_sleep" s -#~~~~~~~~~~~~~~~~~~~~~~~~ -"sleep interval" - int typestr="minutes" - default="60" - optional +############################### +section "Disk space monitoring" +############################### +option "min-free-mb" m +#~~~~~~~~~~~~~~~~~~~~~ +"Minimal amount of free disk space" +int typestr="megabytes" +default="100" +optional details=" - The sleep interval for snapshot creation in minutes. - The daemon will, in an endlees loop, create a snapshot and - then sleep that many minutes. + 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" +int typestr="percent" +default="2" +optional +details=" + 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. -option "min_free" m -#~~~~~~~~~~~~~~~~~~ - -"minimal amount of free 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. - int typestr="gigabytes" - default="50" - optional + A value of zero (the default) deactivates this check. +" +option "keep-redundant" k +#~~~~~~~~~~~~~~~~~~~~~~~~ +"Prune by disk space only" +flag off details=" - If less that this many gigabytes of space is available, - dss will start to remove snapshots (starting from the oldest - snapshot) until the free disk space exeecds this value. + 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. "