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