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