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         However, there is an important exception to this rule:
  26         If the --run option was given (see below) then dss honors
  27         SIGHUP and re-reads its configuration file whenever it
  28         receives this signal. In this case the options in the config
  29         file override any options that were previously given at the
  30         command line. This allows to change the configuration of a
  31         running dss process on the fly by sending SIGHUP.
  32
  33         Note that it is not possible to change whether dss runs as
  34         background daemon by sending SIGHUP.
  35 "
  36
  37 option "daemon" d
  38 #~~~~~~~~~~~~~~~~
  39 "Run as background daemon"
  40 flag off
  41 dependon="logfile"
  42 details="
  43         Note that dss refuses to start in daemon mode if no logfile
  44         was specified. This option is mostly useful in conjuction
  45         with the -R option described below.
  46 "
  47
  48 option "dry-run" D
  49 #~~~~~~~~~~~~~~~~~
  50 "Only print what would be done"
  51 flag off
  52 details="
  53         This flag does not make sense for all commands. The run
  54         command refuses to start if this option was given. The ls
  55         command silently ignores this flag.
  56 "
  57
  58 #################
  59 section "Logging"
  60 #################
  61
  62 option "loglevel" l
  63 #~~~~~~~~~~~~~~~~~~
  64 "Set loglevel (0-6)"
  65 int typestr="level"
  66 default="3"
  67 optional
  68 details="
  69         Lower values mean less verbose logging.
  70 "
  71
  72 option "logfile" -
  73 #~~~~~~~~~~~~~~~~~
  74 "Logfile for the dss daemon process"
  75 string typestr="filename"
  76 optional
  77 details="
  78         This option is mostly useful for the run command if --daemon
  79         is also given.
  80 "
  81
  82 defgroup "command"
  83 #=================
  84 groupdesc="
  85         dss supports a couple of commands each of which corresponds to a different
  86         command line option. Exactly one of these options must be given.
  87 "
  88 required
  89
  90 groupoption "create" C
  91 #~~~~~~~~~~~~~~~~~~~~~
  92 "Create a new snapshot"
  93 group="command"
  94 details="
  95         Execute the rsync command to create a new snapshot. Note that this
  96         command does not care about free disk space.
  97 "
  98 groupoption "prune" P
  99 #~~~~~~~~~~~~~~~~~~~~
 100 "Remove a redundant snapshot"
 101 group="command"
 102 details="
 103         A snapshot is considered redundant if it ether belongs to
 104         an interval greater than the maximum number of intervals,
 105         or if it belongs to an interval that already contains more
 106         than the desired number of snapshots.
 107 "
 108
 109 groupoption "ls" L
 110 #~~~~~~~~~~~~~~~~~
 111 "Print a list of all snapshots"
 112 group="command"
 113 details="
 114         The list will contain all snapshots no matter of their state,
 115         i. e. incomplete snapshots and snapshots being deleted will
 116         also be listed.
 117 "
 118
 119 groupoption "run" R
 120 #~~~~~~~~~~~~~~~~~~
 121 "Start creating and pruning snapshots"
 122 group="command"
 123 details="
 124         This is the main mode of operation. Snapshots will be created
 125         as needed and pruned automatically.
 126 "
 127
 128 ###############################
 129 section "Rsync-related options"
 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. Make sure there is no password
 141         needed for the ssh connection. To achieve that, use public key
 142         authentication for ssh and, if needed, set the remote user name
 143         by using the --remote-user option.
 144 "
 145
 146 option "remote-user" U
 147 #~~~~~~~~~~~~~~~~~~~~~
 148 "Remote user name (default: current user)"
 149 string typestr="username"
 150 optional
 151 details="
 152         Set this if the user running dss is different from the
 153         user at the remote host when using ssh.
 154 "
 155
 156 option "source-dir" -
 157 #~~~~~~~~~~~~~~~~~~~~
 158 "The data directory"
 159 string typestr="dirname"
 160 required
 161 details="
 162         The directory on the remote host from which snapshots are
 163         taken.  Of course, the user specified as --remote-user must
 164         have read access to this directory.
 165 "
 166
 167 option "dest-dir" -
 168 #~~~~~~~~~~~~~~~~~~
 169 "Snapshot dir"
 170 string typestr="dirname"
 171 required
 172 details="
 173         The destination directory on the local host where snapshots
 174         will be written. This must be writable by the user who runs
 175         dss.
 176 "
 177
 178 option "rsync-option" O
 179 #~~~~~~~~~~~~~~~~~~~~~~
 180 "Further rsync options"
 181 string typestr="option"
 182 optional
 183 multiple
 184 details="
 185         These option may be given multiple times. The arguments passed
 186         to that option are passed verbatim to the rsync command.
 187 "
 188
 189 option "exclude-patterns" e
 190 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 191 "Rsync exclude patterns"
 192 string typestr="path"
 193 optional
 194
 195 ###################
 196 section "Intervals"
 197 ###################
 198
 199 option "unit-interval" u
 200 #~~~~~~~~~~~~~~~~~~~~~~~
 201 "The duration of a unit interval"
 202 int typestr="days"
 203 default="4"
 204 optional
 205 details="
 206         dss snapshot aging is implemented in terms of intervals. There are
 207         two command line options related to intervals: the duration of a
 208         \"unit\" interval and the number of those unit intervals.
 209
 210         dss removes any snapshots older than the given number of intervals
 211         times the duration of a unit interval and tries to keep the following
 212         number of snapshots per interval:
 213
 214                 interval number         number of snapshots
 215                 ===============================================
 216                 0                       2 ^ (num-intervals - 1)
 217                 1                       2 ^ (num-intervals - 2)
 218                 2                       2 ^ (num-intervals - 3)
 219                 ...
 220                 num-intervals - 2                       2
 221                 num-intervals - 1                       1
 222                 num-intervals                           0
 223
 224         In other words, the oldest snapshot will at most be unit_interval *
 225         num_intervals old (= 5 days * 4 = 20 days if default values are used).
 226         Moreover, there are at most 2^num_intervals - 1 snapshots in total
 227         (i. e. 31 by default).  Observe that you have to create at least
 228         2 ^ (num_intervals - 1) snapshots each interval for this to work out.
 229 "
 230
 231 option "num-intervals" n
 232 #~~~~~~~~~~~~~~~~~~~~~~~
 233 "The number of unit intervals"
 234 int typestr="num"
 235 default="5"
 236 optional
 237
 238 ###############
 239 section "Hooks"
 240 ###############
 241
 242 option "pre-create-hook" r
 243 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 244 "Executed before snapshot creation"
 245 string typestr="command"
 246 optional
 247 details="
 248         Execute this command before trying to create a new snapshot.
 249         If this command returns with a non-zero exit status, no
 250         snapshot is being created and the operation is retried later.
 251
 252         For example, one might want to execute a script that checks
 253         whether all snapshot-related file systems are properly mounted.
 254
 255         Another possible application of this is to return non-zero
 256         during office hours in order to not slow down the file systems
 257         by taking snapshots.
 258 "
 259
 260 option "post-create-hook" o
 261 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 262 "Executed after snapshot creation"
 263 string typestr="command"
 264 optional
 265 details="
 266         Execute this after a snapshot has successfully been
 267         created. The full path of the newly created snapshot is passed
 268         to the hook as the first argument.  The return value of that
 269         hook is ignored.
 270
 271         For instance this hook can be used to count the number of
 272         files per user and/or the disk usage patterns in order to
 273         store them in a database for further treatment.
 274 "
 275
 276 ###############################
 277 section "Disk space monitoring"
 278 ###############################
 279
 280 option "min-free-mb" m
 281 #~~~~~~~~~~~~~~~~~~~~~
 282 "Minimal amount of free disk space"
 283 int typestr="megabytes"
 284 default="100"
 285 optional
 286 details="
 287         If less than this many megabytes of space is available on
 288         the file system containing the destination directory, \"dss
 289         --run\" will suspend the currently running rsync process and will
 290         start to remove snapshots, starting from the oldest snapshot,
 291         until the free disk space exceeds this value.  See also the
 292         --min_free_percent option.
 293
 294         A value of zero deactivates this check.
 295
 296 "
 297
 298 option "min-free-percent" p
 299 #~~~~~~~~~~~~~~~~~~~~~~~~~~
 300 "Minimal percent of free disk space"
 301 int typestr="percent"
 302 default="2"
 303 optional
 304 details="
 305         See --min-free-mb.  Note that it is not recommended to set both
 306         --min-free-mb and --min-free-percent to zero as this will
 307         cause your file system to fill up quickly.
 308 "