Bump version to 0.0.2.
[dss.git] / dss.ggo
1 #
2 package "dss"
3 version "0.0.2"
4 purpose "the dyadic snapshot scheduler"
5
6
7 option "config_file" c
8 #~~~~~~~~~~~~~~~~~~~~~
9 "(default='~/.dssrc')"
10
11 string typestr="filename"
12 optional
13
14 section "Logging"
15 #~~~~~~~~~~~~~~~~
16
17 option "loglevel" l
18 #~~~~~~~~~~~~~~~~~~
19
20 "set loglevel (0-6)"
21
22 int typestr="level"
23 default="4"
24 optional
25
26 option "logfile" -
27 #~~~~~~~~~~~~~~~~~
28
29 "logfile for the dss daemon process"
30
31 string typestr="filename"
32 optional
33
34 option "daemon" d
35 #~~~~~~~~~~~~~~~~
36 "run as background daemon"
37 flag off
38 dependon="logfile"
39 details="
40 Note that dsss refuses to start in daemon mode if no logfile
41 was specified.
42 "
43
44 option "dry_run" D
45 #~~~~~~~~~~~~~~~~~
46 "only print what would be done"
47 flag off
48 details="
49 This flag does not makes sense for all commands. The run
50 command refuses to start if this option was given. The ls
51 command silently ignores this flag.
52 "
53
54 defgroup "command"
55 #=================
56 groupdesc="
57 dss supports a couple of commands each of which corresponds to a different
58 command line option. Exactly one of these options must be given.
59 "
60 required
61
62 groupoption "create" C
63 #~~~~~~~~~~~~~~~~~~~~~
64 "create a new snapshot"
65 group="command"
66 details="
67 Execute the rsync command to create a new snapshot.Mote that this
68 command does not care about free disk space.
69 "
70 groupoption "prune" P
71 #~~~~~~~~~~~~~~~~~~~~
72 "remove a redundant snapshot"
73 group="command"
74 details="
75 A snapshot is considered redundant if it ether belongs to
76 an interval greater than the maximum nuber of intervals,
77 or if it belongs to an interval that already contains more
78 than the desired number of snapshots.
79 "
80
81 groupoption "ls" L
82 #~~~~~~~~~~~~~~~~~
83 "print a list of all snapshots"
84 group="command"
85 details="
86 The list will contain all snapshots not matter of their state,
87 i.e. incomplete snapshots and snapshots being deleted will
88 also be listed.
89 "
90
91 groupoption "run" R
92 #~~~~~~~~~~~~~~~~~~
93 "start creating and pruning snapshots"
94 group="command"
95 details="
96 This is the main mode of operation. Snapshots will be created
97 as needed and pruned automatically.
98 "
99
100 section "rsync-related options"
101 #==============================
102
103 option "remote_user" U
104 #~~~~~~~~~~~~~~~~~~~~~
105
106 "remote user name (default: current user)"
107
108 string typestr="username"
109 optional
110
111 option "remote_host" H
112 #~~~~~~~~~~~~~~~~~~~~~
113
114 "remote host"
115
116 string typestr="hostname"
117 default="localhost"
118 optional
119
120 option "source_dir" -
121 #~~~~~~~~~~~~~~~~~~~~
122
123 "directory to backup on the remote host"
124
125 string typestr="dirname"
126 optional
127
128 option "dest_dir" -
129 #~~~~~~~~~~~~~~~~~~
130
131 "snapshots dir on the local host"
132
133 string typestr="dirname"
134 optional
135
136 option "rsync_option" O
137 #~~~~~~~~~~~~~~~~~~~~~~
138
139 "further rsync options that are passed
140 verbatim to the rsync command."
141
142 string typestr="option"
143 optional
144 multiple
145
146
147 option "exclude_patterns" e
148 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149
150 "rsync exclude patterns"
151
152 string typestr="path"
153 optional
154
155
156 section "Intervals"
157 #~~~~~~~~~~~~~~~~~~
158
159 text "
160 dss snapshot aging is implemented in terms of intervals. There are
161 two command line options related to intervals: the duration of a
162 'unit' interval and the number of those unit intervals.
163
164 dss removes any snapshots older than the given number of intervals
165 times the duration of an unit interval and tries to keep the following
166 number of snapshots per interval:
167
168 interval number number of snapshots
169 ===============================================
170 0 2 ^ (num_intervals - 1)
171 1 2 ^ (num_intervals - 2)
172 2 2 ^ (num_intervals - 3)
173 ...
174 num_intervals - 2 2
175 num_intervals - 1 1
176 num_intervals 0
177
178 In other words, the oldest snapshot will at most be unit_interval *
179 num_intervala old (= 5 days * 4 = 20 days if default values are used).
180 Moreover, there are at most 2^num_intervals - 1 snapshots in total
181 (i.e. 31 by default). Observe that you have to create at least
182 num_intervals snapshots each interval for this to work out. "
183
184 option "unit_interval" u
185 #~~~~~~~~~~~~~~~~~~~~~~~
186 "the duration of a unit interval"
187
188 int typestr="days"
189 default="4"
190 optional
191
192 option "num_intervals" n
193 #~~~~~~~~~~~~~~~~~~~~~~~
194 "the number of unit intervals"
195
196 int typestr="num"
197 default="5"
198 optional
199
200 section "Hooks"
201 #==============
202
203 option "pre_create_hook" r
204 #~~~~~~~~~~~~~~~~~~~~~~~~~~
205 "Executed before snapshot creation"
206
207 string typestr="command"
208 default="/bin/true"
209 optional
210
211 details="
212 Execute this command before trying to create a new snapshot
213 If this command returns with a non-zero exit status, do not
214 perform the backup. One possible application of this is to
215 return non-zero during office hours in order to not slow down
216 the file systems by taking snapshots.
217 "
218
219
220 option "post_create_hook" o
221 #~~~~~~~~~~~~~~~~~~~~~~~~~~
222 "Executed after snapshot creation"
223
224 string typestr="command"
225 default="/bin/true"
226 optional
227
228 details="
229 Execute this after a snapshot has successfully been created
230 The return value on the command is ignored. For instance one
231 could count the number of files per user and/or the disk
232 usage patterns in order to store them in a database for
233 further treatment.
234 "
235 option "creation_sleep" s
236 #~~~~~~~~~~~~~~~~~~~~~~~~
237 "sleep interval"
238
239 int typestr="minutes"
240 default="60"
241 optional
242
243 details="
244 The sleep interval for snapshot creation in minutes.
245 The daemon will, in an endlees loop, create a snapshot and
246 then sleep that many minutes.
247 "
248
249
250 option "min_free" m
251 #~~~~~~~~~~~~~~~~~~
252
253 "minimal amount of free space"
254
255 int typestr="gigabytes"
256 default="50"
257 optional
258
259 details="
260 If less that this many gigabytes of space is available,
261 dss will start to remove snapshots (starting from the oldest
262 snapshot) until the free disk space exeecds this value.
263 "