dss.suite

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