-
-text "
-dss snapshot aging is implemented in terms of intervals. There are
-two command line options related to intervals: the duration of a
-'unit' interval and the number of those intervals.
-
-dss removes any snapshots older than the given number of intervals
-times the duration of an unit interval and tries to keep the following
-amount of snapshots per interval:
-
- interval number number of snapshots
- ===============================================
- 0 2 ^ (num_intervals - 1)
- 1 2 ^ (num_intervals - 2)
- 2 2 ^ (num_intervals - 3)
- ...
- num_intervals - 2 2
- num_intervals - 1 1
- num_intervals 0
-
-In other words, the oldest snapshot will at most be unit_interval *
-num_intervala old (= 5 days * 4 = 20 days if default values are used).
-Moreover, there are at most 2^num_intervals - 1 snapshots in total
-(i.e. 31 by default). Observe that you have to create at least
-num_intervals snapshots each interval for this to work out. "
-
-
-
+#
package "dss"
-version "0.0.1"
+version "0.0.2"
+purpose "the dyadic snapshot scheduler"
+
option "config_file" c
#~~~~~~~~~~~~~~~~~~~~~
default="4"
optional
-option "logfile" L
-#~~~~~~~~~~~~~~~~~~
+option "logfile" -
+#~~~~~~~~~~~~~~~~~
"logfile for the dss daemon process"
string typestr="filename"
optional
+option "daemon" d
+#~~~~~~~~~~~~~~~~
+"run as background daemon"
+flag off
+dependon="logfile"
+details="
+ Note that dsss refuses to start in daemon mode if no logfile
+ was specified.
+"
+
+option "dry_run" D
+#~~~~~~~~~~~~~~~~~
+"only print what would be done"
+flag off
+details="
+ This flag does not makes sense for all commands. The run
+ command refuses to start if this option was given. The ls
+ command silently ignores this flag.
+"
+
+defgroup "command"
+#=================
+groupdesc="
+ dss supports a couple of commands each of which corresponds to a different
+ command line option. Exactly one of these options must be given.
+"
+required
+
+groupoption "create" C
+#~~~~~~~~~~~~~~~~~~~~~
+"create a new snapshot"
+group="command"
+details="
+ Execute the rsync command to create a new snapshot.Mote that this
+ command does not care about free disk space.
+"
+groupoption "prune" P
+#~~~~~~~~~~~~~~~~~~~~
+"remove a redundant snapshot"
+group="command"
+details="
+ A snapshot is considered redundant if it ether belongs to
+ an interval greater than the maximum nuber of intervals,
+ or if it belongs to an interval that already contains more
+ than the desired number of snapshots.
+"
+
+groupoption "ls" L
+#~~~~~~~~~~~~~~~~~
+"print a list of all snapshots"
+group="command"
+details="
+ The list will contain all snapshots not matter of their state,
+ i.e. incomplete snapshots and snapshots being deleted will
+ also be listed.
+"
+
+groupoption "run" R
+#~~~~~~~~~~~~~~~~~~
+"start creating and pruning snapshots"
+group="command"
+details="
+ This is the main mode of operation. Snapshots will be created
+ as needed and pruned automatically.
+"
+
section "rsync-related options"
#==============================
default="localhost"
optional
-option "source_dir" S
+option "source_dir" -
#~~~~~~~~~~~~~~~~~~~~
"directory to backup on the remote host"
string typestr="dirname"
optional
-option "dest_dir" D
+option "dest_dir" -
#~~~~~~~~~~~~~~~~~~
"snapshots dir on the local host"
section "Intervals"
#~~~~~~~~~~~~~~~~~~
+text "
+dss snapshot aging is implemented in terms of intervals. There are
+two command line options related to intervals: the duration of a
+'unit' interval and the number of those unit intervals.
+
+dss removes any snapshots older than the given number of intervals
+times the duration of an unit interval and tries to keep the following
+number of snapshots per interval:
+
+ interval number number of snapshots
+ ===============================================
+ 0 2 ^ (num_intervals - 1)
+ 1 2 ^ (num_intervals - 2)
+ 2 2 ^ (num_intervals - 3)
+ ...
+ num_intervals - 2 2
+ num_intervals - 1 1
+ num_intervals 0
+
+In other words, the oldest snapshot will at most be unit_interval *
+num_intervala old (= 5 days * 4 = 20 days if default values are used).
+Moreover, there are at most 2^num_intervals - 1 snapshots in total
+(i.e. 31 by default). Observe that you have to create at least
+num_intervals snapshots each interval for this to work out. "
option "unit_interval" u
#~~~~~~~~~~~~~~~~~~~~~~~
The daemon will, in an endlees loop, create a snapshot and
then sleep that many minutes.
"
+option "min_free_mb" m
+#~~~~~~~~~~~~~~~~~~~~~
-
-option "min_free" m
-#~~~~~~~~~~~~~~~~~~
-
-"minimal amount of free space"
+"minimal amount of free disk space"
int typestr="gigabytes"
- default="50"
+ default="100"
optional
details="
- If less that this many gigabytes of space is available,
- dss will start to remove snapshots (starting from the oldest
- snapshot) until the free disk space exeecds this value.
-"
+ If less that this many megabytes of space is available, \"dss
+ --run\" dss will start to remove snapshots (starting from the
+ oldest snapshot) until the free disk space exeecds this value.
+ See also the --min_free_percent option.
+ A value of zero deactivates this check.
-text "
-subcommands:
-
-ls:
-
- Print list of existing snapshots.
-
- Usage: ls
-
-free:
-
- Remove old snapshots in order to free space.
-
- Usage: free [size]
-
- Without size parameter, print the amount of free space on the file system
- in human-readable format.
+"
- Otherwise, remove snapshots (starting from the oldest one) until the number of
- free space exceeds the given number of gigabytes.
- Use with caution!
+option "min_free_percent" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"minimal percent of free disk space"
+int typestr="percent"
+default="2"
+optional
+details="
+ See --min_free. Note that it is not recommended to set both
+ --min_fre_mb and --min_free_percent to zero as this will
+ cause your file system to fill up quickly.
"