#
package "dss"
version "0.0.3"
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.
"

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 makes sense only in conjuction
	with the -R option described below.
"

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

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

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

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

option "exclude-patterns" e
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Rsync exclude patterns"
string typestr="path"
optional

###################
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 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
#~~~~~~~~~~~~~~~~~~~~~~~
"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"
default="/bin/true"
optional
details="
	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
	the file systems by taking snapshots.
"


option "post-create-hook" o
#~~~~~~~~~~~~~~~~~~~~~~~~~~
"Executed after snapshot creation"
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
	could 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 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-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.
"