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