1 # SPDX-License-Identifier: GPL-2.0
15 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
17 [option general-options-section]
18 summary = General options
21 summary = print help and exit
23 [option detailed-help]
24 summary = print help, including all details, and exit
26 summary = print version and exit
30 summary = use alternative config file (default: ~/.dssrc)
32 arg_info = required_arg
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.
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.
47 summary = set loglevel (0-6)
49 arg_info = required_arg
53 Lower values mean more verbose logging.
57 summary = only print what would be done
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.
64 summary = the remote directory to snapshot
66 arg_info = required_arg
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
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.
79 summary = where snapshots are stored
81 arg_info = required_arg
84 The destination directory on the local host where snapshots will be
85 written. This must be writable by the user who runs dss.
87 This option is mandatory for all subcommands except kill.
88 Unlike --source-dir, this option may only be given once.
91 summary = abort if destination directory is not a mountpoint
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.
99 This option is silently ignored for subcommands which do not depend
100 on the destination directory.
102 [option Rsync-options]
103 summary = Controlling how rsync is run
106 These options are only relevant to the run and the create subcommands.
110 summary = host to take snapshots from
112 arg_info = required_arg
114 default_val = localhost
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.
124 summary = Remote user name (default: current user)
125 arg_info = required_arg
129 Set this if the user that runs dss is different from the user on the
133 summary = run rsync with --checksum occasionally
135 arg_info = required_arg
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.
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.
155 [option rsync-option]
157 summary = further rsync options
159 arg_info = required_arg
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:
168 --rsync-option --exclude --rsync-option /proc
171 summary = Fine tuning the number of snapshots per time unit
174 Snapshot aging is implemented in terms of intervals. There are two
175 command line options related to intervals: the duration u of a unit
176 interval and the number of unit intervals, denoted n below.
178 dss removes snapshots older than n times u and tries to keep 2^(n -
179 k - 1) snapshots in interval k, where the interval number k counts
180 from zero to n - 1, with zero being the most recent unit interval.
182 Hence the oldest snapshot will at most be u * n days old (4 days *
183 5 intervals = 20 days, if default values are used). Moreover, there
184 are at most 2^n - 1 snapshots in total (2^5 - 1 = 31 by default). Note
185 that for this to work out your system must be fast enough to create at
186 least 2^(n - 1) snapshots per unit interval (16 snapshots in 4 days =
187 one snapshot in 6 hours), because this is the number of snapshots in
190 [option unit-interval]
192 summary = the duration of a unit interval
194 arg_info = required_arg
198 Increasing this number instructs dss to create fewer snapshots per
199 time unit while the number of snapshots to keep stays the same.
201 [option num-intervals]
203 summary = the number of unit intervals
205 arg_info = required_arg
209 Increasing this number by one doubles the total number of
213 summary = Commands to be run on certain events
216 All hooks default to "true". That is, the true(1) utility (which
217 always returns with exit code zero) is executed if the hook command
220 [option pre-create-hook]
222 summary = executed before a snapshot is created
224 arg_info = required_arg
228 This command is executed before dss runs rsync to create a new
229 snapshot. If the command returns with a non-zero exit status, no
230 snapshot will be created and the operation is retried later.
232 For example, the command could execute a script that checks whether
233 all snapshot-related file systems are mounted.
235 Another possible application of the pre-create hook is to return
236 non-zero during office hours in order to not slow down the file
237 systems by taking snapshots.
239 [option post-create-hook]
240 summary = executed after a snapshot has been created
242 arg_info = required_arg
246 This is only executed if a snapshot has successfully been created. The
247 full path of the newly created snapshot is passed to the hook as the
248 first argument. The exit code of this hook is ignored.
250 For instance this hook could count the number of files per user
251 and/or compute disk usage patterns to be stored in a database for
254 [option pre-remove-hook]
255 summary = executed before a snapshot is removed
257 arg_info = required_arg
261 The full path to the snapshot which is about to be removed is passed
262 to the command as the first argument. If the command returns with
263 a non-zero exit status, the snapshot is not going to be removed and
264 the operation is retried later.
266 For example, one could execute a script that checks whether the
267 snapshot to be deleted is currently used by another process, e.g. by
268 a tape-based backup system that runs concurrently to dss.
270 Another possible application of this is to record disk-usage
271 patterns before and after snapshot removal.
273 [option post-remove-hook]
274 summary = executed after snapshot removal
276 arg_info = required_arg
280 As for the pre-remove hook, the full path of the removed snapshot is
281 passed to the hook as the first argument. The exit code of this hook
285 summary = executed before the run command exits
287 arg_info = required_arg
291 This hook is only relevant to the run subcommand. It is executed just
292 before dss terminates. The reason for termination is passed as the
295 One possible application for this hook is to send email to the system
296 administrator to let her know that no more snapshots are going to
300 [option disk-space-monitoring]
301 summary = Disk space monitoring
304 The options of this section control the aggressiveness of snapshot
305 removal. That is, they define under which circumstances existing
306 snapshots are removed. These options are only relevant to the run
307 and the prune subcommands.
311 summary = minimal amount of free disk space
312 arg_info = required_arg
317 If disk space on the file system containing the destination
318 directory gets low, the run subcommand suspends the currently
319 running rsync process and starts to remove snapshots in order to
320 free disk space. This option specifies the minimal amount of free
321 disk space. If less than the given number of megabytes is available,
322 snapshots are being deleted. See also the --min_free_percent and the
323 min-free-percent-inodes options below.
325 A value of zero deactivates this check.
327 [option min-free-percent]
329 summary = minimal percentage of free disk space
330 arg_info = required_arg
335 This is like --min-free-mb but the amount of free disk space
336 is specified as a percentage. It is not recommended to set both
337 --min-free-mb and --min-free-percent to zero as this will cause your
338 file system to fill up quickly.
340 [option min-free-percent-inodes]
342 summary = minimal percent of free inodes
343 arg_info = required_arg
348 The minimum amount of free inodes on the file system containing the
349 destination dir. If the percentage of free inodes drops below the
350 given value, snapshot removal kicks in like in case of low disk space.
352 The number of free inodes is determined from the f_ffree field of
353 the statvfs structure. However, some file systems set this field to
354 zero, indicating that the number of inodes is basically unlimited.
355 Moreover it is not possible to reliably detect whether this is the
356 case. Therefore this feature is disabled by default. It's safe to
357 enable it for ext2/ext3/ext4 file systems on linux though.
359 A value of zero (the default) deactivates this check.
361 [option keep-redundant]
363 summary = prune by disk space only
365 By default, redundant and outdated snapshots are removed automatically
366 to keep the number of snapshots in harmony with the configured
367 policy. If this flag is given, dss removes such snapshots only if
368 disk space or number of free inodes becomes low.
370 [option min-complete]
371 summary = minimal number of complete snapshots to keep
372 arg_info = optional_arg
377 This option is only relevant if snapshots must be deleted because
380 dss refuses to remove old snapshots if there are fewer complete
381 snapshots left than the given number. The default value of one
382 guarantees that at least one complete snapshot is available at
385 If only <num> complete snapshots are left, and there is not enough
386 disk space available for another snapshot, the program terminates
387 with a "No space left on device" error.
391 dss supports the subcommands described below. If no subcommand is
392 given, the list of available subcommands is shown and the program
393 terminates successfully without performing any further action.
397 purpose = start creating and pruning snapshots
399 This is the main mode of operation. Snapshots are created in an endless
400 loop as needed and pruned automatically. The loop only terminates on
401 fatal errors or if a terminating signal was received. See also the
406 summary = run as background daemon
408 If this option is given, the dss command detaches from the console
409 and continues to run in the background. It is not possible to let
410 a daemonized process re-attach to the console by editing the config
411 file and sending SIGHUP. However, log output may be redirected to a
412 different file in this way.
418 summary = where to write log output
419 arg_info = required_arg
422 default_val = /dev/null
424 This option is only honored if --daemon is given, in which case
425 log messages go to the given file. Otherwise the option is silently
426 ignored and log output is written to stderr.
428 [option max-rsync-errors]
429 summary = terminate after this many rsync failures
431 arg_info = required_arg
435 If the rsync process exits with a fatal error, dss restarts the command
436 in the hope that the problem is transient and subsequent rsync runs
437 succeed. After the given number of consecutive rsync error exits,
438 however, dss gives up, executes the exit hook and terminates. Set
439 this to zero if dss should exit immediately on the first rsync error.
441 The only non-fatal error is when rsync exits with code 24. This
442 indicates a partial transfer due to vanished source files and happens
443 frequently when snapshotting a directory which is concurrently being
447 purpose = execute rsync once to create a new snapshot
449 This command does not check the amount free disk space. The pre-create
450 and post-create hooks are honored, however.
452 Specify --dry-run to see the rsync command which is executed to create
456 purpose = remove snapshots
458 A snapshot is said to be (a) outdated if its interval number is greater
459 or equal than the specified number of unit intervals, (b) redundant if
460 the interval it belongs to contains more than the configured number of
461 snapshots, and (c) orphaned if it is incomplete and not being created
462 or deleted. All other snapshots are called regular.
464 Unless --dry-run is given, which just prints the snapshot that would be
465 removed, this subcommand gets rid of non-regular snapshots. At most
466 one snapshot is removed per invocation. If no such snapshot exists
467 and disk space is low, the subcommand also removes regular snapshots,
468 always picking the oldest one.
470 The subcommand fails if there is another dss "run" process.
473 summary = act as if free disk space was high/low
474 arg_info = required_arg
484 By default, free disk space is checked and even regular snapshots
485 become candidates for removal if disk space is low. This option
486 overrides the result of the check.
489 purpose = print the list of all snapshots
491 The list contains all existing snapshots, no matter of their state.
492 Incomplete snapshots and snapshots being deleted will also be listed.
495 purpose = send a signal to a running dss process
497 This sends a signal to the dss process that corresponds to the given
498 config file. If --dry-run is given, the PID of the dss process is
499 written to stdout, but no signal is sent.
503 summary = send the given signal rather than SIGTERM
505 arg_info = required_arg
507 default_val = SIGTERM
509 Like for kill(1), alternate signals may be specified in three ways: as
510 a signal number (e.g., 9), the signal name (e.g., KILL), or the signal
511 name prefixed with "SIG" (e.g., SIGKILL). In the latter two forms,
512 the signal name and the prefix are case insensitive, so "sigkill"
515 Sending SIGHUP causes the running dss process to reload its config file.
519 summary = wait until the signalled process has terminated
521 This option is handy for system shutdown scripts which would like
522 to terminate the dss daemon process.
524 Without --wait the dss process which executes the kill subcommand
525 exits right after the kill(2) system call returns. At this point the
526 signalled process might still be alive (even if SIGKILL was sent).
527 If --wait is given, the process waits until the signalled process
528 has terminated or the timeout expires.
530 If --wait is not given, the kill subcommand exits successfully if
531 and only if the signal was sent (i.e., if there exists another dss
532 process to receive the signal). With --wait it exits successfully
533 if, additionally, the signalled process has terminated before the
536 It makes only sense to use the option for signals which terminate dss.
538 [subcommand configtest]
539 purpose = run a configuration file syntax test
541 This command checks the command line options and the configuration
542 file for syntactic correctness. It either reports "Syntax Ok" and
543 exits successfully or prints information about the first syntax error
544 detected and terminates with exit code 1.
550 Copyright (C) 2008 - present AUTHOR()
554 This is free software: you are free to change and redistribute it.
556 There is NO WARRANTY, to the extent permitted by law.
projects / dss.git / blob