+#
+package "dss"
+version "0.0.3"
+purpose "the dyadic snapshot scheduler
-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. "
-
-
+dss creates hardlink-based snapshots of a given directory on a remote
+or local host using rsync's link-dest feature.
+"
-package "dss"
-version "0.0.1"
+#########################
+section "General options"
+#########################
-option "config_file" c
+option "config-file" c
#~~~~~~~~~~~~~~~~~~~~~
"(default='~/.dssrc')"
+string typestr="filename"
+optional
+details="
+ Options may be given at the command line or in the
+ configuration file. As usual, if an option is given both at
+ the command line and in the configuration file, the command
+ line option takes precedence.
+
+ However, there is an important exception to this rule:
+ If the --run option was given (see below) then dss honors
+ SIGHUP and re-reads its configuration file whenever it
+ receives this signal. In this case the options in the config
+ file override any options that were previously given at the
+ command line. This allows to change the configuration of a
+ running dss process on the fly by sending SIGHUP.
+
+ Note that it is not possible to change whether dss runs as
+ background daemon by sending SIGHUP.
+"
+
+option "daemon" d
+#~~~~~~~~~~~~~~~~
+"Run as background daemon"
+flag off
+dependon="logfile"
+details="
+ Note that dss refuses to start in daemon mode if no logfile
+ was specified. This option is mostly useful in conjuction
+ with the -R option described below.
+"
- string typestr="filename"
- optional
+option "dry-run" D
+#~~~~~~~~~~~~~~~~~
+"Only print what would be done"
+flag off
+details="
+ This flag does not make sense for all commands. The run
+ command refuses to start if this option was given. The ls
+ command silently ignores this flag.
+"
+#################
section "Logging"
-#~~~~~~~~~~~~~~~~
+#################
option "loglevel" l
#~~~~~~~~~~~~~~~~~~
+"Set loglevel (0-6)"
+int typestr="level"
+default="3"
+optional
+details="
+ Lower values mean less verbose logging.
+"
-"set loglevel (0-6)"
+option "logfile" -
+#~~~~~~~~~~~~~~~~~
+"Logfile for the dss daemon process"
+string typestr="filename"
+optional
+details="
+ This option is mostly useful for the run command if --daemon
+ is also given.
+"
- int typestr="level"
- default="4"
- optional
+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
-option "logfile" L
-#~~~~~~~~~~~~~~~~~~
+groupoption "create" C
+#~~~~~~~~~~~~~~~~~~~~~
+"Create a new snapshot"
+group="command"
+details="
+ Execute the rsync command to create a new snapshot. Note 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 number of intervals,
+ or if it belongs to an interval that already contains more
+ than the desired number of snapshots.
+"
-"logfile for the dss daemon process"
+groupoption "ls" L
+#~~~~~~~~~~~~~~~~~
+"Print a list of all snapshots"
+group="command"
+details="
+ The list will contain all snapshots no matter of their state,
+ i. e. incomplete snapshots and snapshots being deleted will
+ also be listed.
+"
- string typestr="filename"
- optional
+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"
-#==============================
+###############################
+section "Rsync-related options"
+###############################
-option "remote_user" U
+option "remote-host" H
#~~~~~~~~~~~~~~~~~~~~~
+"Remote host"
+string typestr="hostname"
+default="localhost"
+optional
+details="
+ If this option is given and its value differs from the local
+ host, then rsync uses ssh. Make sure there is no password
+ needed for the ssh connection. To achieve that, use public key
+ authentication for ssh and, if needed, set the remote user name
+ by using the --remote-user option.
+"
-"remote user name (default: current user)"
-
- string typestr="username"
- optional
-
-option "remote_host" H
+option "remote-user" U
#~~~~~~~~~~~~~~~~~~~~~
+"Remote user name (default: current user)"
+string typestr="username"
+optional
+details="
+ Set this if the user running dss is different from the
+ user at the remote host when using ssh.
+"
-"remote host"
-
- string typestr="hostname"
- default="localhost"
- optional
-
-option "source_dir" S
+option "source-dir" -
#~~~~~~~~~~~~~~~~~~~~
+"The data directory"
+string typestr="dirname"
+optional
+details="
+ The directory on the remote host from which snapshots are
+ taken. Of course, the user specified as --remote-user must
+ have read access to this directory.
+"
-"directory to backup on the remote host"
-
- string typestr="dirname"
- optional
-
-option "dest_dir" D
+option "dest-dir" -
#~~~~~~~~~~~~~~~~~~
+"Snapshot dir"
+string typestr="dirname"
+optional
+details="
+ The destination directory on the local host where snapshots
+ will be written. This must be writable by the user who runs
+ dss.
+"
-"snapshots dir on the local host"
-
- string typestr="dirname"
- optional
-
-option "rsync_option" O
+option "rsync-option" O
#~~~~~~~~~~~~~~~~~~~~~~
+"Further rsync options"
+string typestr="option"
+optional
+multiple
+details="
+ These option may be given multiple times. The arguments passed
+ to that option are passed verbatim to the rsync command.
+"
-"further rsync options that are passed
-verbatim to the rsync command."
-
- string typestr="option"
- optional
- multiple
-
-
-option "exclude_patterns" e
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"rsync exclude patterns"
-
- string typestr="path"
- optional
-
+option "exclude-patterns" e
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Rsync exclude patterns"
+string typestr="path"
+optional
+###################
section "Intervals"
-#~~~~~~~~~~~~~~~~~~
-
+###################
-option "unit_interval" u
+option "unit-interval" u
#~~~~~~~~~~~~~~~~~~~~~~~
-"the duration of a unit interval"
-
- int typestr="days"
- default="4"
- optional
+"The duration of a unit interval"
+int typestr="days"
+default="4"
+optional
+details="
+ 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 a 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_intervals 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
+ 2 ^ (num_intervals - 1) snapshots each interval for this to work out.
+"
-option "num_intervals" n
+option "num-intervals" n
#~~~~~~~~~~~~~~~~~~~~~~~
-"the number of unit intervals"
-
- int typestr="num"
- default="5"
- optional
+"The number of unit intervals"
+int typestr="num"
+default="5"
+optional
+###############
section "Hooks"
-#==============
+###############
-option "pre_create_hook" r
+option "pre-create-hook" r
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed before snapshot creation"
-
- string typestr="command"
- default="/bin/true"
- optional
-
+string typestr="command"
+default="/bin/true"
+optional
details="
- Execute this command before trying to create a new snapshot
+ Execute this command before trying to create a new snapshot.
If this command returns with a non-zero exit status, do not
perform the backup. One possible application of this is to
return non-zero during office hours in order to not slow down
"
-option "post_create_hook" o
+option "post-create-hook" o
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed after snapshot creation"
-
- string typestr="command"
- default="/bin/true"
- optional
-
+string typestr="command"
+default="/bin/true"
+optional
details="
Execute this after a snapshot has successfully been created
The return value on the command is ignored. For instance one
usage patterns in order to store them in a database for
further treatment.
"
-option "creation_sleep" s
-#~~~~~~~~~~~~~~~~~~~~~~~~
-"sleep interval"
- int typestr="minutes"
- default="60"
- optional
+###############################
+section "Disk space monitoring"
+###############################
+option "min-free-mb" m
+#~~~~~~~~~~~~~~~~~~~~~
+"Minimal amount of free disk space"
+int typestr="megabytes"
+default="100"
+optional
details="
- The sleep interval for snapshot creation in minutes.
- The daemon will, in an endlees loop, create a snapshot and
- then sleep that many minutes.
-"
+ If less than this many megabytes of space is available on
+ the file system containing the destination directory, \"dss
+ --run\" will suspend the currently running rsync process and will
+ start to remove snapshots, starting from the oldest snapshot,
+ until the free disk space exceeds this value. See also the
+ --min_free_percent option.
+ A value of zero deactivates this check.
-option "min_free" m
-#~~~~~~~~~~~~~~~~~~
-
-"minimal amount of free space"
-
- int typestr="gigabytes"
- default="50"
- 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.
"
-
-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" p
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Minimal percent of free disk space"
+int typestr="percent"
+default="2"
+optional
+details="
+ See --min-free-mb. Note that it is not recommended to set both
+ --min-free-mb and --min-free-percent to zero as this will
+ cause your file system to fill up quickly.
"
projects / dss.git / blobdiff