Updated documentation

README.md

@@ -19,13 +19,14 @@ to the clients without password (using public key authentication).
 If the client runs rsync as server it must be configured to allow the
 server to read the modules to backup. 
 
-**Windows** clients can backed up using **DeltaCopy** as rsync server.
+**Windows** clients can be backed up using **DeltaCopy** as rsync server on Windows.
 
 ##Installation
 
 Make sure, that rsync, ssh and find is installed correctly on server and clients.
 
-Make sure, that the backup user can login from server to the client host[s] without password (using public key authentication)
+Make sure, that the backup user (user running kind) can login from the 
+server to the client host[s] without password (using public key authentication)
 
 clone the repository and build kind using
 ```
@@ -46,13 +47,14 @@ copy man/kind.conf.5 to /usr/share/man/man5
 
 ##Usage
 - Create a directory used as "bank" on a filesystem with enough space
-- Create a master config file /etc/kind/master.conf, containing at least the bank:
+- Create a master config file /etc/kind/master.conf, containing at 
+least the bank:
 ```
     bank=/disk1/kind
 ```
-- Create a subdirectory of the bank as "vault" for one backup
-- Create a subdirectory kind in the vault directory
-- Create a vault config file /[bank]/[vault]/kind/vault.conf, containing
+- Create one or more subdirectories of the bank as "vault" for the backups
+- Create a subdirectory kind in each vault directory
+- Create a vault config files /[bank]/[vault]/kind/vault.conf, containing
 ```
     host=[client host]
     user=[backup user]

man/kind.8

@@ -40,27 +40,30 @@ kind \- kind is no dirvish
 [
 .I OPTIONS
 ]
-.I vault
+.I vault_or_group
 .SH DESCRIPTION
 .P
-Create a backup image of a client directory tree.
+Create a backup image of a client directory tree. If configured
+a group name may be given as parameter to backup all group members.
 .P
-Each image is a directory containing transfer
+Each image is a directory containing
 .BR rsync-log,
+.BR expires,
 .B tree
 and if errors were detected an
 .B error
 file.
 The 
 .B rsync-log
-retains the the output of rsync listing all files that were changed or added with some statistical information.
+retains the the output of rsync listing all files that were changed 
+or added with some statistical information.
 Tree is the copy of the client tree.
 .P
 The client directory tree is compared with an existing image
 to create a new image.
 Unchanged files are shared between images.
-For changed files
-only those parts that actually change are transfered over the network.
+For changed files only those parts that actually change are 
+transfered over the network.
 Unchanged portions of files are copied from the reference image.
 .P
 The resulting images contain complete copies of the original trees
@@ -94,11 +97,24 @@ Don't actually do anything.
 Process all configuration files, options and tests
 then produce a summary on standard output and exit.
 .TP
-.D backuponly
-Only backup, no expire
+.D backup
+Backup given vault[s]
 .TP
-.D expireonly
-Only expire, no backup
+.D expire
+Expire given vault[s]
+.TP
+.D listconfig
+Show configuration for vault.
+.TP
+.D listimages
+Show data about all images of vault[s].
+
+if neither of --backup, --expire, --listconfig or --listimages is 
+given, kind does backup and expire.
+
+.TP
+.D help
+Print help and all available options.
 .TP
 .D version
 Print version string and exit.
@@ -128,11 +144,11 @@ actual image of source directory tree.
 .nf
 ssh(1)
 rsync(1)
+kind.conf(5)
 .SH AUTHOR
 kind was created by Wolfgang Ortmann.
 .SH BUGS AND ISSUES
-In order to preserve permissions
-it is necessary for kind to run as root
+In order to preserve permissions it is necessary for kind to run as root
 on the backup server.
 
 For an automated backup process the root user must have 

man/kind.conf.5

@@ -75,8 +75,8 @@ Each value must be provided on its own line.
 Any leading and trailing whitespace is discarded for keys and values.
 Blank lines and lines starting with '#' are ignored.
 
-On startup disu will first load a master configuration file
-.B /etc/d2/master.conf
+On startup kind will first load a master configuration file
+.B /etc/kind/master.conf
 
 Each vault must have an own configuration file, which must specify 
 at least the host and path to backup.
@@ -85,7 +85,7 @@ at least the host and path to backup.
 Boolean values need to specified as
 .B true
 or
-.B false
+.B false .
 Specifying an boolean option with an empty value is also interpreted as true.
 
 Each option is marked here with one of (B) for Boolean, (S)
@@ -96,7 +96,7 @@ single value, (L) list.
 Specify paths to directories containing vaults.
 
 A \*[bank] is a directory containing one or more \*[vault]s.
-The system supports multiple \*[bank]s
+kind supports multiple \*[bank]s
 so that filesystem mount-points can be managed more effectively.
 
 When a \*[vault] is specified the \*[bank]s will be searched
@@ -107,15 +107,19 @@ or added without having to update a master index.
 .multiple bank
 .TP
 .Bi host hostname (S)
-specify a host from which to back up.
+specify a host to back up from using ssh. 
+
+.TP
+.Bi server hostname (S)
+specify a host running rsync as server to backup from.
 
 .TP
 .Bi user username (S)
-specify a user for login on host.
+specify a user for login on client.
 
 .TP
 .Bi path path (S)
-specify the path on host from which to back up. Use absolute path
+specify the path on client from which to back up. Use absolute path
 starting with '/'.
 
 .TP
@@ -129,7 +133,7 @@ Patterns are based on shell glob with some enhancements.
 .multiple exclude
 .TP
 .Bi userExcludeFile excludefilename (S)
-Load a set of patterns from a file from host:path.
+Load a set of patterns from a file from client.
 
 .TP
 .Bi expireFailedImage time period (S)
@@ -143,6 +147,13 @@ specify rules for expiration.
 .See "EXPIRE RULES"
 
 .multiple expire\-rule
+.TP
+.Bi setRule backup set rule (L)
+This defines a backup set, which is another way to describe images and
+their lifetime.
+
+.See "BACKUP SETS"
+
 .TP
 .Bi imageName name_of_images (S)
 Specify a name for the \*[image]. The name must 
@@ -152,7 +163,7 @@ image\-2016-03-09-20.
 
 .TP
 .Bi longImageName true (B)
-Image time is added to the image name as YEAR-MONTH-DAY-hour.
+Normally Image time is added to the image name as YEAR-MONTH-DAY-hour.
 If longImageName is true the values for minute and second are added.
 
 .default false
@@ -174,12 +185,9 @@ This can be used to specify the location of
 .B ssh
 or
 .B rsh
-and/or to provide additional options for said utility
-such as
-.Bi \-p port
-for
-.B ssh
-to use an alternate port number.
+and/or to provide additional options like in
+.Bi ssh \-p 2223
+to use ssh on an alternative port number.
 
 .default ssh
 
@@ -191,7 +199,7 @@ and find excludes.
 .Bi rsyncOption option[s] (L)
 Specify additional options for the rsync command.
 
-This allows you to use rsync features that are not directly 
+This allows to use rsync features that are not directly 
 supported by kind.
 
 .multiple rsyncOption
@@ -213,12 +221,16 @@ This allows rules to be set in master configuration and
 rules in \*[vault] configuration files will override rules set in the
 master configuration file.
 
-Each rule has an pattern expression against which the image
-time is compared followed by a time period specifier.
+Expire time is determined at time of creation. Image time is compared
+to a pattern defined in expire rules and if the image time matches, 
+the rule is applied giving a lifetime of the image.
 
 Values for the image time pattern are hour, day of week, day of month
-and month. Each of these may be a single value or a '*', where '*' 
+and month. Each of these may be a single value, a range or a '*', where '*' 
 means "any value". 
+Values for weekday or month may be given as word like "monday" or "july".
+Ranges are given as 2-7, possibly extended by a distance like /2. 
+E.g. 2-15/3 means values 2, 5, 8, 11, 14.
 Time periods for expiring may be given in seconds or multiple of
 minute, hour, day, week, month(=30 days) or year(=365 days).
 
@@ -227,30 +239,43 @@ Here are examples of a expire\-rules:
 .nf
 .ft CR
 .ta .5i T 6m
-	#hour	DayOfWeek DayOfMonth	Month	EXPIRE
-	*	*	1		1	5 years
-	*	sunday	*		*	1 month
-	*	*	16		*	1 year
-	10	*	*		*	1 days
-.ft R
+                #hour DayOfWeek DayOfMonth Month	EXPIRE
+expireRule =    20-5    *        1          1   5 years
+expireRule +=   *       sunday   *          *   1 month
+expireRule +=   *       *        */7        *   1 year
+expireRule +=   10      *        *          *   1 days
+.ft Rq
 .fi
 
-It should be noted that (if not disabled) after backup all images
-are compared to expire rules and last match gives expire period. 
-If the expire date is reached, the image will be removed.
+.SH BACKUP SETS
+Backup sets are another way to describe lifetime of images. It is
+possible to define a number of backup sets, e.g. as "daily", "weekly" and
+"monthly". A backup set has a value for then time between to backups  
+and a value for the time to keep the images.
+
+This is given as
+.nf
+.ft CR
+.ta .5i T 6m
+#          name      rate     keep
+setRule =  daily:   1 day:   1 week
+setRule += weekly:  1 week:  1 months
+setRule += monthly: 1 month: 1 year
+.ft Rq
+.fi
 
 .SH FILES
 .TP
-.B /etc/d2/master.conf
+.B /etc/kind/master.conf
 default master configuration file.
 .TP
-.IB bank/vault/ d2/vault.conf
+.B bank/vault/kind/vault.conf
 default vault configuration file.
 .TP
-.IB bank/vault/image/ tree
+.B bank/vault/image/tree
 actual image of source directory tree.
 .TP
-.IB bank/vault/image/ rsync-log
+.B bank/vault/image/rsync-log
 output from rsync
 
 .SH SEE ALSO