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