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