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