dss.ggo

   1 #
   2 package "dss"
   3 version "0.0.3"
   4 purpose "the dyadic snapshot scheduler
   5
   6 dss creates hardlink-based snapshots of a given directory on a remote
   7 or local host using rsync's link-dest feature.
   8 "
   9
  10 #########################
  11 section "General options"
  12 #########################
  13
  14 option "config-file" c
  15 #~~~~~~~~~~~~~~~~~~~~~
  16 "(default='~/.dssrc')"
  17 string typestr="filename"
  18 optional
  19 details="
  20         Options may be given at the command line or in the
  21         configuration file. As usual, if an option is given both at
  22         the command line and in the configuration file, the command
  23         line option takes precedence.
  24 "
  25
  26 option "daemon" d
  27 #~~~~~~~~~~~~~~~~
  28 "run as background daemon"
  29 flag off
  30 dependon="logfile"
  31 details="
  32         Note that dss refuses to start in daemon mode if no logfile
  33         was specified.
  34 "
  35
  36 option "dry-run" D
  37 #~~~~~~~~~~~~~~~~~
  38 "only print what would be done"
  39 flag off
  40 details="
  41         This flag does not makes sense for all commands. The run
  42         command refuses to start if this option was given. The ls
  43         command silently ignores this flag.
  44 "
  45
  46 #################
  47 section "Logging"
  48 #################
  49
  50 option "loglevel" l
  51 #~~~~~~~~~~~~~~~~~~
  52 "set loglevel (0-6)"
  53 int typestr="level"
  54 default="3"
  55 optional
  56 details="
  57         Lower values mean less verbose logging.
  58 "
  59
  60 option "logfile" -
  61 #~~~~~~~~~~~~~~~~~
  62 "logfile for the dss daemon process"
  63 string typestr="filename"
  64 optional
  65 details="
  66         This option is mostly useful for the run command if --daemon
  67         is also given.
  68 "
  69
  70 defgroup "command"
  71 #=================
  72 groupdesc="
  73         dss supports a couple of commands each of which corresponds to a different
  74         command line option. Exactly one of these options must be given.
  75 "
  76 required
  77
  78 groupoption "create" C
  79 #~~~~~~~~~~~~~~~~~~~~~
  80 "create a new snapshot"
  81 group="command"
  82 details="
  83         Execute the rsync command to create a new snapshot.Mote that this
  84         command does not care about free disk space.
  85 "
  86 groupoption "prune" P
  87 #~~~~~~~~~~~~~~~~~~~~
  88 "remove a redundant snapshot"
  89 group="command"
  90 details="
  91         A snapshot is considered redundant if it ether belongs to
  92         an interval greater than the maximum number of intervals,
  93         or if it belongs to an interval that already contains more
  94         than the desired number of snapshots.
  95 "
  96
  97 groupoption "ls" L
  98 #~~~~~~~~~~~~~~~~~
  99 "print a list of all snapshots"
 100 group="command"
 101 details="
 102         The list will contain all snapshots not matter of their state,
 103         i.e. incomplete snapshots and snapshots being deleted will
 104         also be listed.
 105 "
 106
 107 groupoption "run" R
 108 #~~~~~~~~~~~~~~~~~~
 109 "start creating and pruning snapshots"
 110 group="command"
 111 details="
 112         This is the main mode of operation. Snapshots will be created
 113         as needed and pruned automatically.
 114 "
 115
 116 ###############################
 117 section "Rsync-related options"
 118 ###############################
 119
 120 option "remote-user" U
 121 #~~~~~~~~~~~~~~~~~~~~~
 122 "remote user name (default: current user)"
 123 string typestr="username"
 124 optional
 125 details="
 126         If a user is specified that differs from the user running
 127         dss, then rsync will use ssh for taking snapshots.  This will
 128         only work if you set up a key-pair to allow rsync to proceed
 129         without asking for passwords.
 130 "
 131
 132 option "remote-host" H
 133 #~~~~~~~~~~~~~~~~~~~~~
 134 "remote host"
 135 string typestr="hostname"
 136 default="localhost"
 137 optional
 138 details="
 139         If this option is given and its value differs from the local
 140         host, then rsync uses ssh, so make sure the user running dss
 141         does not need a password to connect to the remote host.
 142 "
 143
 144 option "source-dir" -
 145 #~~~~~~~~~~~~~~~~~~~~
 146 "the data directory"
 147 string typestr="dirname"
 148 optional
 149 details="
 150         The directory on the remote host from which snapshots are
 151         taken.  Of course, the user specified as --remote-user must
 152         have read access to this directory.
 153 "
 154
 155 option "dest-dir" -
 156 #~~~~~~~~~~~~~~~~~~
 157 "snapshot dir"
 158 string typestr="dirname"
 159 optional
 160 details="
 161         The destination directory on the local host where snapshots
 162         will be written. This must be writable by the user who runs
 163         dss.
 164 "
 165
 166 option "rsync-option" O
 167 #~~~~~~~~~~~~~~~~~~~~~~
 168 "further rsync options"
 169 string typestr="option"
 170 optional
 171 multiple
 172 details="
 173         These option may be given multiple times. The arguments passed
 174         to that option are passed verbatim to the rsync command.
 175 "
 176
 177 option "exclude-patterns" e
 178 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 179 "rsync exclude patterns"
 180 string typestr="path"
 181 optional
 182
 183 ###################
 184 section "Intervals"
 185 ###################
 186
 187 option "unit-interval" u
 188 #~~~~~~~~~~~~~~~~~~~~~~~
 189 "the duration of a unit interval"
 190 int typestr="days"
 191 default="4"
 192 optional
 193 details="
 194         dss snapshot aging is implemented in terms of intervals. There are
 195         two command line options related to intervals: the duration of a
 196         \"unit\" interval and the number of those unit intervals.
 197
 198         dss removes any snapshots older than the given number of intervals
 199         times the duration of an unit interval and tries to keep the following
 200         number of snapshots per interval:
 201
 202                 interval number         number of snapshots
 203                 ===============================================
 204                 0                       2 ^ (num-intervals - 1)
 205                 1                       2 ^ (num-intervals - 2)
 206                 2                       2 ^ (num-intervals - 3)
 207                 ...
 208                 num-intervals - 2                       2
 209                 num-intervals - 1                       1
 210                 num-intervals                           0
 211
 212         In other words, the oldest snapshot will at most be unit_interval *
 213         num_intervals old (= 5 days * 4 = 20 days if default values are used).
 214         Moreover, there are at most 2^num_intervals - 1 snapshots in total
 215         (i.e. 31 by default).  Observe that you have to create at least
 216         2 ^ (num_intervals - 1) snapshots each interval for this to work out.
 217 "
 218
 219 option "num-intervals" n
 220 #~~~~~~~~~~~~~~~~~~~~~~~
 221 "the number of unit intervals"
 222 int typestr="num"
 223 default="5"
 224 optional
 225
 226 ###############
 227 section "Hooks"
 228 ###############
 229
 230 option "pre-create-hook" r
 231 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 232 "Executed before snapshot creation"
 233 string typestr="command"
 234 default="/bin/true"
 235 optional
 236 details="
 237         Execute this command before trying to create a new snapshot.
 238         If this command returns with a non-zero exit status, do not
 239         perform the backup. One possible application of this is to
 240         return non-zero during office hours in order to not slow down
 241         the file systems by taking snapshots.
 242 "
 243
 244
 245 option "post-create-hook" o
 246 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 247 "Executed after snapshot creation"
 248 string typestr="command"
 249 default="/bin/true"
 250 optional
 251 details="
 252         Execute this after a snapshot has successfully been created
 253         The return value on the command is ignored. For instance one
 254         could count the number of files per user and/or the disk
 255         usage patterns in order to store them in a database for
 256         further treatment.
 257 "
 258
 259 ###############################
 260 section "disk space monitoring"
 261 ###############################
 262
 263 option "min-free-mb" m
 264 #~~~~~~~~~~~~~~~~~~~~~
 265 "minimal amount of free disk space"
 266 int typestr="megabytes"
 267 default="100"
 268 optional
 269 details="
 270         If less that this many megabytes of space is available on
 271         the file system containing the destination directory, \"dss
 272         --run\" will stop the currently running rsync process and will
 273         start to remove snapshots, starting from the oldest snapshot,
 274         until the free disk space exceeds this value.  See also the
 275         --min_free_percent option.
 276
 277         A value of zero deactivates this check.
 278
 279 "
 280
 281 option "min-free-percent" p
 282 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 283 "minimal percent of free disk space"
 284 int typestr="percent"
 285 default="2"
 286 optional
 287 details="
 288         See --min_free.  Note that it is not recommended to set both
 289         --min_fre_mb and --min_free_percent to zero as this will
 290         cause your file system to fill up quickly.
 291 "