4 purpose "the dyadic snapshot scheduler
6 dss creates hardlink-based snapshots of a given directory on a remote
7 or local host using rsync's link-dest feature.
10 #########################
11 section "General options"
12 #########################
14 option "config-file" c
15 #~~~~~~~~~~~~~~~~~~~~~
16 "(default='~/.dssrc')"
17 string typestr="filename"
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.
28 "run as background daemon"
32 Note that dss refuses to start in daemon mode if no logfile
38 "only print what would be done"
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.
57 Lower values mean less verbose logging.
62 "logfile for the dss daemon process"
63 string typestr="filename"
66 This option is mostly useful for the run command if --daemon
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.
78 groupoption "create" C
79 #~~~~~~~~~~~~~~~~~~~~~
80 "create a new snapshot"
83 Execute the rsync command to create a new snapshot.Mote that this
84 command does not care about free disk space.
88 "remove a redundant snapshot"
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.
99 "print a list of all snapshots"
102 The list will contain all snapshots not matter of their state,
103 i.e. incomplete snapshots and snapshots being deleted will
109 "start creating and pruning snapshots"
112 This is the main mode of operation. Snapshots will be created
113 as needed and pruned automatically.
116 ###############################
117 section "Rsync-related options"
118 ###############################
120 option "remote-user" U
121 #~~~~~~~~~~~~~~~~~~~~~
122 "remote user name (default: current user)"
123 string typestr="username"
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.
132 option "remote-host" H
133 #~~~~~~~~~~~~~~~~~~~~~
135 string typestr="hostname"
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.
144 option "source-dir" -
145 #~~~~~~~~~~~~~~~~~~~~
147 string typestr="dirname"
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.
158 string typestr="dirname"
161 The destination directory on the local host where snapshots
162 will be written. This must be writable by the user who runs
166 option "rsync-option" O
167 #~~~~~~~~~~~~~~~~~~~~~~
168 "further rsync options"
169 string typestr="option"
173 These option may be given multiple times. The arguments passed
174 to that option are passed verbatim to the rsync command.
177 option "exclude-patterns" e
178 #~~~~~~~~~~~~~~~~~~~~~~~~~~
179 "rsync exclude patterns"
180 string typestr="path"
187 option "unit-interval" u
188 #~~~~~~~~~~~~~~~~~~~~~~~
189 "the duration of a unit interval"
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.
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:
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)
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.
219 option "num-intervals" n
220 #~~~~~~~~~~~~~~~~~~~~~~~
221 "the number of unit intervals"
230 option "pre-create-hook" r
231 #~~~~~~~~~~~~~~~~~~~~~~~~~~
232 "Executed before snapshot creation"
233 string typestr="command"
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.
245 option "post-create-hook" o
246 #~~~~~~~~~~~~~~~~~~~~~~~~~~
247 "Executed after snapshot creation"
248 string typestr="command"
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
259 ###############################
260 section "disk space monitoring"
261 ###############################
263 option "min-free-mb" m
264 #~~~~~~~~~~~~~~~~~~~~~
265 "minimal amount of free disk space"
266 int typestr="megabytes"
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.
277 A value of zero deactivates this check.
281 option "min-free-percent" p
282 #~~~~~~~~~~~~~~~~~~~~~~~~~~
283 "minimal percent of free disk space"
284 int typestr="percent"
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.