run: Don't kill children twice.
[dss.git] / 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]