dss.suite

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