From ea63d92f2e18fa9b1488c5eabc8333f84b5728cf Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Tue, 18 Mar 2008 23:59:01 +0100 Subject: [PATCH] dss.ggo: Add more documentation, and reformat help text. --- dss.ggo | 298 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 156 insertions(+), 142 deletions(-) diff --git a/dss.ggo b/dss.ggo index 8cd79ae..25b0d6b 100644 --- a/dss.ggo +++ b/dss.ggo @@ -1,35 +1,27 @@ # package "dss" version "0.0.2" -purpose "the dyadic snapshot scheduler" +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 - -section "Logging" -#~~~~~~~~~~~~~~~~ - -option "loglevel" l -#~~~~~~~~~~~~~~~~~~ - -"set loglevel (0-6)" - - int typestr="level" - default="4" - optional - -option "logfile" - -#~~~~~~~~~~~~~~~~~ - -"logfile for the dss daemon process" - - string typestr="filename" - optional +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. +" option "daemon" d #~~~~~~~~~~~~~~~~ @@ -37,11 +29,11 @@ option "daemon" d flag off dependon="logfile" details=" - Note that dsss refuses to start in daemon mode if no logfile + Note that dss refuses to start in daemon mode if no logfile was specified. " -option "dry_run" D +option "dry-run" D #~~~~~~~~~~~~~~~~~ "only print what would be done" flag off @@ -51,6 +43,30 @@ details=" command silently ignores this flag. " +################# +section "Logging" +################# + +option "loglevel" l +#~~~~~~~~~~~~~~~~~~ +"set loglevel (0-6)" +int typestr="level" +default="3" +optional +details=" + Lower values mean less 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. +" + defgroup "command" #================= groupdesc=" @@ -73,7 +89,7 @@ groupoption "prune" P group="command" details=" A snapshot is considered redundant if it ether belongs to - an interval greater than the maximum nuber of intervals, + 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. " @@ -97,119 +113,128 @@ details=" as needed and pruned automatically. " -section "rsync-related options" -#============================== +############################### +section "Rsync-related options" +############################### -option "remote_user" U +option "remote-user" U #~~~~~~~~~~~~~~~~~~~~~ - "remote user name (default: current user)" +string typestr="username" +optional +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. +" - string typestr="username" - optional - -option "remote_host" H +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, so make sure the user running dss + does not need a password to connect to the remote host. +" - string typestr="hostname" - default="localhost" - optional - -option "source_dir" - +option "source-dir" - #~~~~~~~~~~~~~~~~~~~~ +"the data directory" +string typestr="dirname" +optional +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" - +option "dest-dir" - #~~~~~~~~~~~~~~~~~~ +"snapshot dir" +string typestr="dirname" +optional +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 -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +option "exclude-patterns" e +#~~~~~~~~~~~~~~~~~~~~~~~~~~ "rsync exclude patterns" +string typestr="path" +optional - 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 +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. +" - int typestr="days" - default="4" - optional - -option "num_intervals" n +option "num-intervals" n #~~~~~~~~~~~~~~~~~~~~~~~ "the number of unit intervals" +int typestr="num" +default="5" +optional - 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" - default="/bin/true" - optional - +string typestr="command" +default="/bin/true" +optional details=" - Execute this command before trying to create a new snapshot + 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 @@ -217,14 +242,12 @@ details=" " -option "post_create_hook" o +option "post-create-hook" o #~~~~~~~~~~~~~~~~~~~~~~~~~~ "Executed after snapshot creation" - - string typestr="command" - default="/bin/true" - optional - +string typestr="command" +default="/bin/true" +optional details=" Execute this after a snapshot has successfully been created The return value on the command is ignored. For instance one @@ -232,39 +255,30 @@ details=" usage patterns in order to store them in a database for further treatment. " -option "creation_sleep" s -#~~~~~~~~~~~~~~~~~~~~~~~~ -"sleep interval" - int typestr="minutes" - default="60" - optional +############################### +section "disk space monitoring" +############################### -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. -" -option "min_free_mb" m +option "min-free-mb" m #~~~~~~~~~~~~~~~~~~~~~ - "minimal amount of free disk space" - - int typestr="gigabytes" - default="100" - optional - +int typestr="megabytes" +default="100" +optional details=" - If less that this many megabytes of space is available, \"dss - --run\" dss will start to remove snapshots (starting from the - oldest snapshot) until the free disk space exeecds this value. - See also the --min_free_percent option. + 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. A value of zero deactivates this check. " -option "min_free_percent" - +option "min-free-percent" p #~~~~~~~~~~~~~~~~~~~~~~~~~~ "minimal percent of free disk space" int typestr="percent" -- 2.39.2