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