dss.suite

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