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