dss.ggo

   1 #
   2 package "dss"
   3 version "0.0.1"
   4 purpose "the dyadic snapshot scheduler"
   5
   6
   7 option "config_file" c
   8 #~~~~~~~~~~~~~~~~~~~~~
   9 "(default='~/.dssrc')"
  10
  11         string typestr="filename"
  12         optional
  13
  14 section "Logging"
  15 #~~~~~~~~~~~~~~~~
  16
  17 option "loglevel" l
  18 #~~~~~~~~~~~~~~~~~~
  19
  20 "set loglevel (0-6)"
  21
  22         int typestr="level"
  23         default="4"
  24         optional
  25
  26 option "logfile" -
  27 #~~~~~~~~~~~~~~~~~
  28
  29 "logfile for the dss daemon process"
  30
  31         string typestr="filename"
  32         optional
  33
  34
  35 defgroup "command"
  36 #=================
  37 groupdesc="
  38         dss supports a couple of commands each of which corresponds to a different
  39         command line option. Exactly one of these options must be given.
  40 "
  41 required
  42
  43 groupoption "create" C
  44 #~~~~~~~~~~~~~~~~~~~~~
  45 "create a new snapshot"
  46 group="command"
  47 details="
  48         Execute the rsync command to create a new snapshot.Mote that this
  49         command does not care about free disk space.
  50 "
  51 groupoption "prune" P
  52 #~~~~~~~~~~~~~~~~~~~~
  53 "remove a redundant snapshot"
  54 group="command"
  55 details="
  56         A snapshot is considered redundant if it ether belongs to
  57         an interval greater than the maximum nuber of intervals,
  58         or if it belongs to an interval that already contains more
  59         than the desired number of snapshots.
  60 "
  61
  62 groupoption "ls" L
  63 #~~~~~~~~~~~~~~~~~
  64 "print a list of all snapshots"
  65 group="command"
  66 details="
  67         The list will contain all snapshots not matter of their state,
  68         i.e. incomplete snapshots and snapshots being deleted will
  69         also be listed.
  70 "
  71
  72 groupoption "run" R
  73 #~~~~~~~~~~~~~~~~~~
  74 "start creating and pruning snapshots"
  75 group="command"
  76 details="
  77         This is the main mode of operation. Snapshots will be created
  78         as needed and pruned automatically.
  79 "
  80
  81 section "rsync-related options"
  82 #==============================
  83
  84 option "remote_user" U
  85 #~~~~~~~~~~~~~~~~~~~~~
  86
  87 "remote user name (default: current user)"
  88
  89         string typestr="username"
  90         optional
  91
  92 option "remote_host" H
  93 #~~~~~~~~~~~~~~~~~~~~~
  94
  95 "remote host"
  96
  97         string typestr="hostname"
  98         default="localhost"
  99         optional
 100
 101 option "source_dir" S
 102 #~~~~~~~~~~~~~~~~~~~~
 103
 104 "directory to backup on the remote host"
 105
 106         string typestr="dirname"
 107         optional
 108
 109 option "dest_dir" D
 110 #~~~~~~~~~~~~~~~~~~
 111
 112 "snapshots dir on the local host"
 113
 114         string typestr="dirname"
 115         optional
 116
 117 option "rsync_option" O
 118 #~~~~~~~~~~~~~~~~~~~~~~
 119
 120 "further rsync options that are passed
 121 verbatim to the rsync command."
 122
 123         string typestr="option"
 124         optional
 125         multiple
 126
 127
 128 option "exclude_patterns" e
 129 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 130
 131 "rsync exclude patterns"
 132
 133         string typestr="path"
 134         optional
 135
 136
 137 section "Intervals"
 138 #~~~~~~~~~~~~~~~~~~
 139
 140 text "
 141 dss snapshot aging is implemented in terms of intervals. There are
 142 two command line options related to intervals: the duration of a
 143 'unit' interval and the number of those unit intervals.
 144
 145 dss removes any snapshots older than the given number of intervals
 146 times the duration of an unit interval and tries to keep the following
 147 number of snapshots per interval:
 148
 149         interval number         number of snapshots
 150         ===============================================
 151         0                       2 ^ (num_intervals - 1)
 152         1                       2 ^ (num_intervals - 2)
 153         2                       2 ^ (num_intervals - 3)
 154         ...
 155         num_intervals - 2                       2
 156         num_intervals - 1                       1
 157         num_intervals                           0
 158
 159 In other words, the oldest snapshot will at most be unit_interval *
 160 num_intervala old (= 5 days * 4 = 20 days if default values are used).
 161 Moreover, there are at most 2^num_intervals - 1 snapshots in total
 162 (i.e. 31 by default).  Observe that you have to create at least
 163 num_intervals snapshots each interval for this to work out.  "
 164
 165 option "unit_interval" u
 166 #~~~~~~~~~~~~~~~~~~~~~~~
 167 "the duration of a unit interval"
 168
 169         int typestr="days"
 170         default="4"
 171         optional
 172
 173 option "num_intervals" n
 174 #~~~~~~~~~~~~~~~~~~~~~~~
 175 "the number of unit intervals"
 176
 177         int typestr="num"
 178         default="5"
 179         optional
 180
 181 section "Hooks"
 182 #==============
 183
 184 option "pre_create_hook" r
 185 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 186 "Executed before snapshot creation"
 187
 188         string typestr="command"
 189         default="/bin/true"
 190         optional
 191
 192 details="
 193         Execute this command before trying to create a new snapshot
 194         If this command returns with a non-zero exit status, do not
 195         perform the backup. One possible application of this is to
 196         return non-zero during office hours in order to not slow down
 197         the file systems by taking snapshots.
 198 "
 199
 200
 201 option "post_create_hook" o
 202 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 203 "Executed after snapshot creation"
 204
 205         string typestr="command"
 206         default="/bin/true"
 207         optional
 208
 209 details="
 210         Execute this after a snapshot has successfully been created
 211         The return value on the command is ignored. For instance one
 212         could count the number of files per user and/or the disk
 213         usage patterns in order to store them in a database for
 214         further treatment.
 215 "
 216 option "creation_sleep" s
 217 #~~~~~~~~~~~~~~~~~~~~~~~~
 218 "sleep interval"
 219
 220         int typestr="minutes"
 221         default="60"
 222         optional
 223
 224 details="
 225         The sleep interval for snapshot creation in minutes.
 226         The daemon will, in an endlees loop, create a snapshot and
 227         then sleep that many minutes.
 228 "
 229
 230
 231 option "min_free" m
 232 #~~~~~~~~~~~~~~~~~~
 233
 234 "minimal amount of free space"
 235
 236         int typestr="gigabytes"
 237         default="50"
 238         optional
 239
 240 details="
 241         If less that this many gigabytes of space is available,
 242         dss will start to remove snapshots (starting from the oldest
 243         snapshot) until the free disk space exeecds this value.
 244 "