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