Merge commit 'remotes/meins/master'
[dss.git] / dss.ggo
1 #
2 package "dss"
3 version "0.0.3"
4 purpose "the dyadic snapshot scheduler
5
6 dss creates hardlink-based snapshots of a given directory on a remote
7 or local host using rsync's link-dest feature.
8 "
9
10 #########################
11 section "General options"
12 #########################
13
14 option "config-file" c
15 #~~~~~~~~~~~~~~~~~~~~~
16 "(default='~/.dssrc')"
17 string typestr="filename"
18 optional
19 details="
20 Options may be given at the command line or in the
21 configuration file. As usual, if an option is given both at
22 the command line and in the configuration file, the command
23 line option takes precedence.
24
25 However, there is an important exception to this rule:
26 If the --run option was given (see below) then dss honors
27 SIGHUP and re-reads its configuration file whenever it
28 receives this signal. In this case the options in the config
29 file override any options that were previously given at the
30 command line. This allows to change the configuration of a
31 running dss process on the fly by sending SIGHUP.
32
33 Note that it is not possible to change whether dss runs as
34 background daemon by sending SIGHUP.
35 "
36
37 option "daemon" d
38 #~~~~~~~~~~~~~~~~
39 "Run as background daemon"
40 flag off
41 dependon="logfile"
42 details="
43 Note that dss refuses to start in daemon mode if no logfile
44 was specified. This option is mostly useful in conjuction
45 with the -R option described below.
46 "
47
48 option "dry-run" D
49 #~~~~~~~~~~~~~~~~~
50 "Only print what would be done"
51 flag off
52 details="
53 This flag does not make sense for all commands. The run
54 command refuses to start if this option was given. The ls
55 command silently ignores this flag.
56 "
57
58 #################
59 section "Logging"
60 #################
61
62 option "loglevel" l
63 #~~~~~~~~~~~~~~~~~~
64 "Set loglevel (0-6)"
65 int typestr="level"
66 default="3"
67 optional
68 details="
69 Lower values mean less verbose logging.
70 "
71
72 option "logfile" -
73 #~~~~~~~~~~~~~~~~~
74 "Logfile for the dss daemon process"
75 string typestr="filename"
76 optional
77 details="
78 This option is mostly useful for the run command if --daemon
79 is also given.
80 "
81
82 defgroup "command"
83 #=================
84 groupdesc="
85 dss supports a couple of commands each of which corresponds to a different
86 command line option. Exactly one of these options must be given.
87 "
88 required
89
90 groupoption "create" C
91 #~~~~~~~~~~~~~~~~~~~~~
92 "Create a new snapshot"
93 group="command"
94 details="
95 Execute the rsync command to create a new snapshot. Note that this
96 command does not care about free disk space.
97 "
98 groupoption "prune" P
99 #~~~~~~~~~~~~~~~~~~~~
100 "Remove a redundant snapshot"
101 group="command"
102 details="
103 A snapshot is considered redundant if it ether belongs to
104 an interval greater than the maximum number of intervals,
105 or if it belongs to an interval that already contains more
106 than the desired number of snapshots.
107 "
108
109 groupoption "ls" L
110 #~~~~~~~~~~~~~~~~~
111 "Print a list of all snapshots"
112 group="command"
113 details="
114 The list will contain all snapshots no matter of their state,
115 i. e. incomplete snapshots and snapshots being deleted will
116 also be listed.
117 "
118
119 groupoption "run" R
120 #~~~~~~~~~~~~~~~~~~
121 "Start creating and pruning snapshots"
122 group="command"
123 details="
124 This is the main mode of operation. Snapshots will be created
125 as needed and pruned automatically.
126 "
127
128 ###############################
129 section "Rsync-related options"
130 ###############################
131
132 option "remote-host" H
133 #~~~~~~~~~~~~~~~~~~~~~
134 "Remote host"
135 string typestr="hostname"
136 default="localhost"
137 optional
138 details="
139 If this option is given and its value differs from the local
140 host, then rsync uses ssh. Make sure there is no password
141 needed for the ssh connection. To achieve that, use public key
142 authentication for ssh and, if needed, set the remote user name
143 by using the --remote-user option.
144 "
145
146 option "remote-user" U
147 #~~~~~~~~~~~~~~~~~~~~~
148 "Remote user name (default: current user)"
149 string typestr="username"
150 optional
151 details="
152 Set this if the user running dss is different from the
153 user at the remote host when using ssh.
154 "
155
156 option "source-dir" -
157 #~~~~~~~~~~~~~~~~~~~~
158 "The data directory"
159 string typestr="dirname"
160 optional
161 details="
162 The directory on the remote host from which snapshots are
163 taken. Of course, the user specified as --remote-user must
164 have read access to this directory.
165 "
166
167 option "dest-dir" -
168 #~~~~~~~~~~~~~~~~~~
169 "Snapshot dir"
170 string typestr="dirname"
171 optional
172 details="
173 The destination directory on the local host where snapshots
174 will be written. This must be writable by the user who runs
175 dss.
176 "
177
178 option "rsync-option" O
179 #~~~~~~~~~~~~~~~~~~~~~~
180 "Further rsync options"
181 string typestr="option"
182 optional
183 multiple
184 details="
185 These option may be given multiple times. The arguments passed
186 to that option are passed verbatim to the rsync command.
187 "
188
189 option "exclude-patterns" e
190 #~~~~~~~~~~~~~~~~~~~~~~~~~~
191 "Rsync exclude patterns"
192 string typestr="path"
193 optional
194
195 ###################
196 section "Intervals"
197 ###################
198
199 option "unit-interval" u
200 #~~~~~~~~~~~~~~~~~~~~~~~
201 "The duration of a unit interval"
202 int typestr="days"
203 default="4"
204 optional
205 details="
206 dss snapshot aging is implemented in terms of intervals. There are
207 two command line options related to intervals: the duration of a
208 \"unit\" interval and the number of those unit intervals.
209
210 dss removes any snapshots older than the given number of intervals
211 times the duration of a unit interval and tries to keep the following
212 number of snapshots per interval:
213
214 interval number number of snapshots
215 ===============================================
216 0 2 ^ (num-intervals - 1)
217 1 2 ^ (num-intervals - 2)
218 2 2 ^ (num-intervals - 3)
219 ...
220 num-intervals - 2 2
221 num-intervals - 1 1
222 num-intervals 0
223
224 In other words, the oldest snapshot will at most be unit_interval *
225 num_intervals old (= 5 days * 4 = 20 days if default values are used).
226 Moreover, there are at most 2^num_intervals - 1 snapshots in total
227 (i. e. 31 by default). Observe that you have to create at least
228 2 ^ (num_intervals - 1) snapshots each interval for this to work out.
229 "
230
231 option "num-intervals" n
232 #~~~~~~~~~~~~~~~~~~~~~~~
233 "The number of unit intervals"
234 int typestr="num"
235 default="5"
236 optional
237
238 ###############
239 section "Hooks"
240 ###############
241
242 option "pre-create-hook" r
243 #~~~~~~~~~~~~~~~~~~~~~~~~~~
244 "Executed before snapshot creation"
245 string typestr="command"
246 default="/bin/true"
247 optional
248 details="
249 Execute this command before trying to create a new snapshot.
250 If this command returns with a non-zero exit status, do not
251 perform the backup. One possible application of this is to
252 return non-zero during office hours in order to not slow down
253 the file systems by taking snapshots.
254 "
255
256
257 option "post-create-hook" o
258 #~~~~~~~~~~~~~~~~~~~~~~~~~~
259 "Executed after snapshot creation"
260 string typestr="command"
261 default="/bin/true"
262 optional
263 details="
264 Execute this after a snapshot has successfully been created
265 The return value on the command is ignored. For instance one
266 could count the number of files per user and/or the disk
267 usage patterns in order to store them in a database for
268 further treatment.
269 "
270
271 ###############################
272 section "Disk space monitoring"
273 ###############################
274
275 option "min-free-mb" m
276 #~~~~~~~~~~~~~~~~~~~~~
277 "Minimal amount of free disk space"
278 int typestr="megabytes"
279 default="100"
280 optional
281 details="
282 If less than this many megabytes of space is available on
283 the file system containing the destination directory, \"dss
284 --run\" will suspend the currently running rsync process and will
285 start to remove snapshots, starting from the oldest snapshot,
286 until the free disk space exceeds this value. See also the
287 --min_free_percent option.
288
289 A value of zero deactivates this check.
290
291 "
292
293 option "min-free-percent" p
294 #~~~~~~~~~~~~~~~~~~~~~~~~~~
295 "Minimal percent of free disk space"
296 int typestr="percent"
297 default="2"
298 optional
299 details="
300 See --min-free-mb. Note that it is not recommended to set both
301 --min-free-mb and --min-free-percent to zero as this will
302 cause your file system to fill up quickly.
303 "