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