dss.suite.m4

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