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