#
package "dss"
version "0.0.4"
purpose "the dyadic snapshot scheduler

dss creates hardlink-based snapshots of a given directory on a remote
or local host using rsync's link-dest feature.
"

#########################
section "General options"
#########################

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.
"

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.

	Note that it is not possible to change whether dss runs as
	background daemon by sending SIGHUP.
"

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 more verbose logging.
"

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.
"

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. 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.
"

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.
"

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"
###############################

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.
"

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.
"

option "source-dir" -
#~~~~~~~~~~~~~~~~~~~~
"The data directory"
string typestr="dirname"
required
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.
"

option "dest-dir" -
#~~~~~~~~~~~~~~~~~~
"Snapshot dir"
string typestr="dirname"
required
details="
	The destination directory on the local host where snapshots
	will be written. This must be writable by the user who runs
	dss.
"

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.
"

###################
section "Intervals"
###################

option "unit-interval" u
#~~~~~~~~~~~~~~~~~~~~~~~
"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 u of a \"unit\" interval and the number n of those
	unit intervals.

	dss removes any snapshots older than n times u and tries to
	keep 2^(k-1) snapshots in interval k, where the interval number
	k counts from zero, zero being the most recent unit interval.

	In other words, the oldest snapshot will at most be u * n days
	(= 20 days if default values are used) old.  Moreover, there
	are at most 2^n - 1 snapshots in total (i. e. 31 by default).
	Observe that you have to create at least 2 ^ (n - 1) snapshots
	each interval for this to work out because that is the number
	of snapshots in interval zero.
"

option "num-intervals" n
#~~~~~~~~~~~~~~~~~~~~~~~
"The number of unit intervals"
int typestr="num"
default="5"
optional

###############
section "Hooks"
###############

option "pre-create-hook" r
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed before snapshot creation"
string typestr="command"
optional
details="
	Execute this command before trying to create a new snapshot.
	If this command returns with a non-zero exit status, no
	snapshot is being created and the operation is retried later.

	For example, one might want to execute a script that checks
	whether all snapshot-related file systems are properly mounted.

	Another possible application of this is to return non-zero
	during office hours in order to not slow down the file systems
	by taking snapshots.
"

option "post-create-hook" o
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed after snapshot creation"
string typestr="command"
optional
details="
	Execute this after a snapshot has successfully been
	created. The full path of the newly created snapshot is passed
	to the hook as the first argument.  The return value of that
	hook is ignored.

	For instance this hook can be used to count the number of
	files per user and/or the disk usage patterns in order to
	store them in a database for further treatment.
"

###############################
section "Disk space monitoring"
###############################

option "min-free-mb" m
#~~~~~~~~~~~~~~~~~~~~~
"Minimal amount of free disk space"
int typestr="megabytes"
default="100"
optional
details="
	If disk space on the file system containing the destination
	directory gets low, \"dss --run\" will suspend the currently
	running rsync process and will start to remove snapshots in
	order to free disk space. This option specifies the minimal
	amount of free disk space. If less than the given number of
	megabytes is available, snapshots are being deleted. See also
	the --min_free_percent and the min-free-percent-inodes options.

	A value of zero deactivates this check.
"

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.
"
option "min-free-percent-inodes" i
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Minimal percent of free inodes"
int typestr="percent"
default="0"
optional
details="
	Specify the minimum amount of free inodes on the file system
	containing the destination dir. If less than that many inodes
	are free, snatshot removal kicks in just as in case of low
	disk space.

	Note that not every file system supports the concept of inodes.
	Moreover it is not possible to reliably detect whether this is
	the case. Therefore this feature is disabled by default. It's
	safe to enable it for ext3 file systems on linux though.

	A value of zero (the default) deactivates this check.
"