dss.ggo

   1 # Copyright (C) 2008-2010 Andre Noll <maan@tuebingen.mpg.de>
   2 #
   3 # Licensed under the GPL v2. For licencing details see COPYING.
   4
   5 package "dss"
   6 version "0.1.7"
   7 purpose "the dyadic snapshot scheduler
   8
   9 dss creates hardlink-based snapshots of a given directory on a remote
  10 or local host using rsync's link-dest feature.
  11 "
  12
  13 #########################
  14 section "General options"
  15 #########################
  16
  17 option "config-file" c
  18 #~~~~~~~~~~~~~~~~~~~~~
  19 "(default='~/.dssrc')"
  20 string typestr="filename"
  21 optional
  22 details="
  23         Options may be given at the command line or in the
  24         configuration file. As usual, if an option is given both at
  25         the command line and in the configuration file, the command
  26         line option takes precedence.
  27
  28         However, there is an important exception to this rule:
  29         If the --run option was given (see below) then dss honors
  30         SIGHUP and re-reads its configuration file whenever it
  31         receives this signal. In this case the options in the config
  32         file override any options that were previously given at the
  33         command line. This allows to change the configuration of a
  34         running dss process on the fly by sending SIGHUP.
  35 "
  36
  37 option "daemon" d
  38 #~~~~~~~~~~~~~~~~
  39 "Run as background daemon"
  40 flag off
  41 details="
  42         This option is mostly useful in conjunction with the -R option
  43         described below.
  44
  45         Note that it is not possible to change whether dss runs as background
  46         daemon by sending SIGHUP.
  47 "
  48
  49 option "dry-run" D
  50 #~~~~~~~~~~~~~~~~~
  51 "Only print what would be done"
  52 flag off
  53 details="
  54         This flag does not make sense for all commands. The run
  55         command refuses to start if this option was given. The ls
  56         command silently ignores this flag.
  57 "
  58
  59 #################
  60 section "Logging"
  61 #################
  62
  63 option "loglevel" l
  64 #~~~~~~~~~~~~~~~~~~
  65 "Set loglevel (0-6)"
  66 int typestr="level"
  67 default="3"
  68 optional
  69 details="
  70         Lower values mean more verbose logging.
  71 "
  72
  73 option "logfile" -
  74 #~~~~~~~~~~~~~~~~~
  75 "Logfile for the dss daemon process"
  76 string typestr="filename"
  77 optional
  78 default="/dev/null"
  79 details = "
  80         This option is only honored if both --run and --daemon are
  81         given. Otherwise it is silently ignored and log output is written
  82         to stderr.
  83
  84         The default value means that nothing will be logged in daemon mode
  85         unless this option is given.
  86 "
  87
  88 ##################
  89 section "Commands"
  90 ##################
  91
  92 defgroup "command"
  93 #=================
  94 groupdesc="
  95         dss supports a couple of commands each of which corresponds
  96         to a different command line option. Exactly one of these
  97         options must be given.
  98
  99 "
 100 required
 101
 102 groupoption "create" C
 103 #~~~~~~~~~~~~~~~~~~~~~
 104 "Create a new snapshot"
 105 group="command"
 106 details="
 107         Execute the rsync command to create a new snapshot. Note that
 108         this command does not care about free disk space.
 109 "
 110
 111 groupoption "prune" P
 112 #~~~~~~~~~~~~~~~~~~~~
 113 "Remove redundant and outdated snapshots"
 114 group="command"
 115 details="
 116         A snapshot is considered outdated if its interval number
 117         is greater or equal than the specified number of unit
 118         intervals. See the \"Intervals\" section below for the precise
 119         definition of these terms.
 120
 121         A snapshot is said to be redundant if it belongs to an
 122         interval that already contains more than the desired number
 123         of snapshots.
 124
 125         The prune command gets rid of both outdated and redundant
 126         snapshots.
 127 "
 128
 129 groupoption "ls" L
 130 #~~~~~~~~~~~~~~~~~
 131 "Print a list of all snapshots"
 132 group="command"
 133 details="
 134         The list will contain all snapshots no matter of their state,
 135         i. e. incomplete snapshots and snapshots being deleted will
 136         also be listed.
 137 "
 138
 139 groupoption "run" R
 140 #~~~~~~~~~~~~~~~~~~
 141 "Start creating and pruning snapshots"
 142 group="command"
 143 details="
 144         This is the main mode of operation. Snapshots will be created
 145         in an endless loop as needed and pruned automatically. The loop
 146         only terminates on fatal errors or if a terminating signal was
 147         received. See also the --exit-hook option.
 148 "
 149
 150 groupoption "kill" K
 151 #~~~~~~~~~~~~~~~~~~~
 152 "Kill a running dss process"
 153 group="command"
 154 details="
 155         This sends SIGTERM to the dss process that corresponds to the
 156         given config file. If --dry-run is given, the PID of the dss
 157         process is written to stdout, but no signal is sent.
 158 "
 159
 160 groupoption "reload" -
 161 #~~~~~~~~~~~~~~~~~~~~~
 162 "force a running dss process to reload its config file"
 163 group="command"
 164 details="
 165         This differs from --kill only in that SIGHUP rather than SIGTERM
 166         is sent to the dss process.
 167 "
 168
 169 ###############################
 170 section "Rsync-related options"
 171 ###############################
 172
 173 option "remote-host" H
 174 #~~~~~~~~~~~~~~~~~~~~~
 175 "Remote host"
 176 string typestr="hostname"
 177 default="localhost"
 178 optional
 179 details="
 180         If this option is given and its value differs from the local
 181         host, then rsync uses ssh. Make sure there is no password
 182         needed for the ssh connection. To achieve that, use public key
 183         authentication for ssh and, if needed, set the remote user name
 184         by using the --remote-user option.
 185 "
 186
 187 option "remote-user" U
 188 #~~~~~~~~~~~~~~~~~~~~~
 189 "Remote user name (default: current user)"
 190 string typestr="username"
 191 optional
 192 details="
 193         Set this if the user running dss is different from the
 194         user at the remote host when using ssh.
 195 "
 196
 197 option "source-dir" -
 198 #~~~~~~~~~~~~~~~~~~~~
 199 "The data directory"
 200 string typestr="dirname"
 201 required
 202 details="
 203         The directory on the remote host from which snapshots are
 204         taken.  Of course, the user specified as --remote-user must
 205         have read access to this directory.
 206 "
 207
 208 option "dest-dir" -
 209 #~~~~~~~~~~~~~~~~~~
 210 "Snapshot dir"
 211 string typestr="dirname"
 212 required
 213 details="
 214         The destination directory on the local host where snapshots
 215         will be written. This must be writable by the user who runs
 216         dss.
 217 "
 218
 219 option "rsync-option" O
 220 #~~~~~~~~~~~~~~~~~~~~~~
 221 "Further rsync options"
 222 string typestr="option"
 223 optional
 224 multiple
 225 details="
 226         This option may be given multiple times. The given argument is
 227         passed verbatim to the rsync command. Note that in order to use
 228         rsync options that require an argument, you have to specify the
 229         option and its argument as separate --rsync-options, like this:
 230
 231                 --rsync-option --exclude --rsync-option /proc
 232 "
 233
 234 option "max-rsync-errors" -
 235 "Terminate after this many rsync failures"
 236 int typestr="count"
 237 default="10"
 238 optional
 239 details="
 240         Only relevant when operating in --run mode (see above). If
 241         the rsync process exits with a fatal error, dss restarts
 242         the command in the hope that the problem is transient
 243         and subsequent rsync runs succeed. After the given number
 244         of consecutive rsync error exits, however, dss gives up,
 245         executes the exit hook and terminates. Set this to zero if
 246         dss should exit immediately on the first rsync error.
 247
 248         The only non-fatal error is when rsync exits with code 24. This
 249         indicates a partial transfer due to vanished source files
 250         and happens frequently when snapshotting a directory which
 251         is concurrently being modified.
 252 "
 253
 254 ###################
 255 section "Intervals"
 256 ###################
 257
 258 option "unit-interval" u
 259 #~~~~~~~~~~~~~~~~~~~~~~~
 260 "The duration of a unit interval"
 261 int typestr="days"
 262 default="4"
 263 optional
 264 details="
 265         Snapshot aging is implemented in terms of intervals. There are two
 266         command line options related to intervals: the duration u of a unit
 267         interval and the number of unit intervals, denoted n below.
 268
 269         dss removes snapshots older than n times u and tries to keep 2^(n -
 270         k - 1) snapshots in interval k, where the interval number k counts
 271         from zero to n - 1, with zero being the most recent unit interval.
 272
 273         Hence the oldest snapshot will at most be u * n days old (4 days *
 274         5 intervals = 20 days, if default values are used). Moreover, there
 275         are at most 2^n - 1 snapshots in total (2^5 - 1 = 31 by default). Note
 276         that for this to work out your system must be fast enough to create at
 277         least 2^(n - 1) snapshots per unit interval (16 snapshots in 4 days =
 278         one snapshot in 6 hours), because this is the number of snapshots in
 279         interval zero.
 280 "
 281
 282 option "num-intervals" n
 283 #~~~~~~~~~~~~~~~~~~~~~~~
 284 "The number of unit intervals"
 285 int typestr="num"
 286 default="5"
 287 optional
 288 details="
 289         Note that increasing this number by one doubles the total number of
 290         snapshots. See the documentation of --unit-interval above.
 291 "
 292
 293 ###############
 294 section "Hooks"
 295 ###############
 296
 297 option "pre-create-hook" r
 298 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 299 "Executed before snapshot creation"
 300 string typestr="command"
 301 default = "true"
 302 optional
 303 details="
 304         Execute this command before trying to create a new snapshot.
 305         If this command returns with a non-zero exit status, no
 306         snapshot is being created and the operation is retried later.
 307
 308         For example, one might want to execute a script that checks
 309         whether all snapshot-related file systems are properly mounted.
 310
 311         Another possible application of this is to return non-zero
 312         during office hours in order to not slow down the file systems
 313         by taking snapshots.
 314 "
 315
 316 option "post-create-hook" o
 317 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 318 "Executed after snapshot creation"
 319 string typestr="command"
 320 default = "true"
 321 optional
 322 details="
 323         Execute this after a snapshot has successfully been
 324         created. The full path of the newly created snapshot is
 325         passed to the hook as the first argument.  The exit code of
 326         this hook is ignored.
 327
 328         For instance this hook can be used to count the number of
 329         files per user and/or the disk usage patterns in order to
 330         store them in a database for further analysis.
 331 "
 332
 333 option "pre-remove-hook" -
 334 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 335 "Executed before snapshot removal"
 336 string typestr="command"
 337 default = "true"
 338 optional
 339 details="
 340         Execute this command before removing a snapshot. The full
 341         path to the snapshot about to be deleted is passed to the
 342         command as the first argument. If the command returns with
 343         a non-zero exit status, no snapshot is being removed and the
 344         operation is retried later.
 345
 346         For example, one might want to execute a script that checks
 347         whether the snapshot to be deleted is currently used by
 348         another process, e.g. by a tape-based backup system that runs
 349         concurrently to dss.
 350
 351         Another possible application of this is to record disk-usage
 352         patterns before and after snapshot removal.
 353 "
 354
 355 option "post-remove-hook" -
 356 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 357 "Executed after snapshot removal"
 358 string typestr="command"
 359 default = "true"
 360 optional
 361 details="
 362         Execute this after a snapshot has successfully been removed. As
 363         for the pre-remove hook, the full path of the removed snapshot
 364         is passed to the hook as the first argument. The exit code
 365         of this hook is ignored.
 366 "
 367
 368 option "exit-hook" e
 369 #~~~~~~~~~~~~~~~~~~~
 370 "Executed if run command exits"
 371 string typestr="command"
 372 default = "true"
 373 optional
 374 details="
 375         This hook is only used if the --run command was given which
 376         instructs dss to run in an endless loop. The exit-hook gets
 377         executed whenever this endless loop terminates. The reason
 378         for terminating the loop is passed as the first argument.
 379
 380         One possible application for this hook is to send email to the
 381         system administrator to let her know that no more snapshots
 382         are going to be created.
 383 "
 384
 385 ###############################
 386 section "Disk space monitoring"
 387 ###############################
 388
 389 option "min-free-mb" m
 390 #~~~~~~~~~~~~~~~~~~~~~
 391 "Minimal amount of free disk space"
 392 int typestr="megabytes"
 393 default="100"
 394 optional
 395 details="
 396         If disk space on the file system containing the destination
 397         directory gets low, \"dss --run\" will suspend the currently
 398         running rsync process and will start to remove snapshots in
 399         order to free disk space. This option specifies the minimal
 400         amount of free disk space. If less than the given number of
 401         megabytes is available, snapshots are being deleted. See also
 402         the --min_free_percent and the min-free-percent-inodes options.
 403
 404         A value of zero deactivates this check.
 405 "
 406
 407 option "min-free-percent" p
 408 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 409 "Minimal percent of free disk space"
 410 int typestr="percent"
 411 default="2"
 412 optional
 413 details="
 414         See --min-free-mb. Note that it is not recommended to set both
 415         --min-free-mb and --min-free-percent to zero as this will
 416         cause your file system to fill up quickly.
 417 "
 418 option "min-free-percent-inodes" i
 419 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 420 "Minimal percent of free inodes"
 421 int typestr="percent"
 422 default="0"
 423 optional
 424 details="
 425         Specify the minimum amount of free inodes on the file system
 426         containing the destination dir. If less than that many inodes
 427         are free, snapshot removal kicks in just as in case of low
 428         disk space.
 429
 430         Note that not every file system supports the concept of inodes.
 431         Moreover it is not possible to reliably detect whether this is
 432         the case. Therefore this feature is disabled by default. It's
 433         safe to enable it for ext2/ext3/ext4 file systems on linux
 434         though.
 435
 436         A value of zero (the default) deactivates this check.
 437 "
 438
 439 option "keep-redundant" k
 440 #~~~~~~~~~~~~~~~~~~~~~~~~
 441 "Prune by disk space only"
 442 flag off
 443 details="
 444         By default, redundant and outdated snapshots are removed automatically
 445         to keep the number of snapshots in harmony with the configured
 446         policy. If this flag is given, dss removes such snapshots only if
 447         disk space or number of free inodes becomes low.
 448 "
 449
 450 option "min-complete" -
 451 #~~~~~~~~~~~~~~~~~~~~~~
 452 "Minimal number of complete snapshots to keep"
 453 int typestr = "num"
 454 default = "1"
 455 optional
 456 details = "
 457         This option is only relevant if snapshots must be deleted
 458         because disk space gets low.
 459
 460         dss refuses to remove old snapshots if there are fewer complete
 461         snapshots left than the given number. The default value of one
 462         guarantees that at least one complete snapshot is available
 463         at all times.
 464
 465         If only <num> complete snapshot are left, and there is not
 466         enough disk space available for another snapshot, the program
 467         terminates with a \"No space left on device\" error.
 468 "