Fix bad grammar "allows <infinitive>".
[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 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 the amount of free disk space
316 is specified 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]