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
33 was specified. This option makes sense only in conjunction
34 with the -R option described below.
39 "Only print what would be done"
42 This flag does not make sense for all commands. The run
43 command refuses to start if this option was given. The ls
44 command silently ignores this flag.
58 Lower values mean less verbose logging.
63 "Logfile for the dss daemon process"
64 string typestr="filename"
67 This option is mostly useful for the run command if --daemon
74 dss supports a couple of commands each of which corresponds to a different
75 command line option. Exactly one of these options must be given.
79 groupoption "create" C
80 #~~~~~~~~~~~~~~~~~~~~~
81 "Create a new snapshot"
84 Execute the rsync command to create a new snapshot. Note that this
85 command does not care about free disk space.
89 "Remove a redundant snapshot"
92 A snapshot is considered redundant if it ether belongs to
93 an interval greater than the maximum number of intervals,
94 or if it belongs to an interval that already contains more
95 than the desired number of snapshots.
100 "Print a list of all snapshots"
103 The list will contain all snapshots no matter of their state,
104 i. e. incomplete snapshots and snapshots being deleted will
110 "Start creating and pruning snapshots"
113 This is the main mode of operation. Snapshots will be created
114 as needed and pruned automatically.
117 ###############################
118 section "Rsync-related options"
119 ###############################
121 option "remote-host" H
122 #~~~~~~~~~~~~~~~~~~~~~
124 string typestr="hostname"
128 If this option is given and its value differs from the local
129 host, then rsync uses ssh. Make sure there is no password
130 needed for the ssh connection. To achieve that, use public key
131 authentication for ssh and, if needed, set the remote user name
132 by using the --remote-user option.
135 option "remote-user" U
136 #~~~~~~~~~~~~~~~~~~~~~
137 "Remote user name (default: current user)"
138 string typestr="username"
141 Set this if the user running dss is different from the
142 user at the remote host when using ssh.
145 option "source-dir" -
146 #~~~~~~~~~~~~~~~~~~~~
148 string typestr="dirname"
151 The directory on the remote host from which snapshots are
152 taken. Of course, the user specified as --remote-user must
153 have read access to this directory.
159 string typestr="dirname"
162 The destination directory on the local host where snapshots
163 will be written. This must be writable by the user who runs
167 option "rsync-option" O
168 #~~~~~~~~~~~~~~~~~~~~~~
169 "Further rsync options"
170 string typestr="option"
174 These option may be given multiple times. The arguments passed
175 to that option are passed verbatim to the rsync command.
178 option "exclude-patterns" e
179 #~~~~~~~~~~~~~~~~~~~~~~~~~~
180 "Rsync exclude patterns"
181 string typestr="path"
188 option "unit-interval" u
189 #~~~~~~~~~~~~~~~~~~~~~~~
190 "The duration of a unit interval"
195 dss snapshot aging is implemented in terms of intervals. There are
196 two command line options related to intervals: the duration of a
197 \"unit\" interval and the number of those unit intervals.
199 dss removes any snapshots older than the given number of intervals
200 times the duration of a unit interval and tries to keep the following
201 number of snapshots per interval:
203 interval number number of snapshots
204 ===============================================
205 0 2 ^ (num-intervals - 1)
206 1 2 ^ (num-intervals - 2)
207 2 2 ^ (num-intervals - 3)
213 In other words, the oldest snapshot will at most be unit_interval *
214 num_intervals old (= 5 days * 4 = 20 days if default values are used).
215 Moreover, there are at most 2^num_intervals - 1 snapshots in total
216 (i. e. 31 by default). Observe that you have to create at least
217 2 ^ (num_intervals - 1) snapshots each interval for this to work out.
220 option "num-intervals" n
221 #~~~~~~~~~~~~~~~~~~~~~~~
222 "The number of unit intervals"
231 option "pre-create-hook" r
232 #~~~~~~~~~~~~~~~~~~~~~~~~~~
233 "Executed before snapshot creation"
234 string typestr="command"
238 Execute this command before trying to create a new snapshot.
239 If this command returns with a non-zero exit status, do not
240 perform the backup. One possible application of this is to
241 return non-zero during office hours in order to not slow down
242 the file systems by taking snapshots.
246 option "post-create-hook" o
247 #~~~~~~~~~~~~~~~~~~~~~~~~~~
248 "Executed after snapshot creation"
249 string typestr="command"
253 Execute this after a snapshot has successfully been created
254 The return value on the command is ignored. For instance one
255 could count the number of files per user and/or the disk
256 usage patterns in order to store them in a database for
260 ###############################
261 section "Disk space monitoring"
262 ###############################
264 option "min-free-mb" m
265 #~~~~~~~~~~~~~~~~~~~~~
266 "Minimal amount of free disk space"
267 int typestr="megabytes"
271 If less than this many megabytes of space is available on
272 the file system containing the destination directory, \"dss
273 --run\" will suspend the currently running rsync process and will
274 start to remove snapshots, starting from the oldest snapshot,
275 until the free disk space exceeds this value. See also the
276 --min_free_percent option.
278 A value of zero deactivates this check.
282 option "min-free-percent" p
283 #~~~~~~~~~~~~~~~~~~~~~~~~~~
284 "Minimal percent of free disk space"
285 int typestr="percent"
289 See --min-free-mb. Note that it is not recommended to set both
290 --min-free-mb and --min-free-percent to zero as this will
291 cause your file system to fill up quickly.