kind/man/kind.conf.5

.ds d \-\^\-
.ds o \fR[\fP
.ds c \fR]\fP
.ds | \fR|\fP
.ds bank \fIbank\fP
.ds vault \fIvault\fP
.ds branch \fIbranch\fP
.ds image \fIimage\fP
.de D
\\.B \*d\\$1
..
.de Dr
\\.BR \*d\\$1 \\$2
..
.de Bi
\\.BR \\$1 \ =\ \\$2 " \fR\\$3"
..
.de Br
\\.BR "\\$1" " \\$2"
..
.de DI
\\.BI \*d\\$1 \\$2
..
.de Di
\\.BI \*d\\$1 " \\$2"
..
.de See
See \fB\\$1\fP for more details.
..
.de SeeIn
See \fB\\$1\fP in \fB\\$2\fP for more details.
..
.de multiple
Multiple \fB\\$1:\fP values will accumulate.
..
.de default
Default value: \fB\\$1\fP
..
.TH kind.conf 5
.SH NAME
kind.conf \- kind configuration file format.
.SH DESCRIPTION
The configuration files provide all information neccesary for backup to kind.

The file format is simple. Each line contains one value for one option. 

.BR "option=value" 
.br 
Using '=' as delimiter will set the option to this value 
and overwrite previous values.

.BR "option+=value" 
.br 
Using '+=' as delimiter will add the specified value to the existing 
values. If in subsequent lines values for the same option are added, 
the key value (option) may be omited in the subsequent lines.
.br
\fB
.in +.5i
.nf
option=value1
.in +.5i
+=value2
+=value3
\&.
\&.
\&.
+=valueN
.br
.fi
.in -1i
\fR
.br
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 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.

.SH KIND OPTIONS
Boolean values need to specified as
.B true
or
.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)
single value, (L) list.

.TP
.Bi bank path (L) 
Specify paths to directories containing vaults.

A \*[bank] is a directory containing one or more \*[vault]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
in list order until the \*[vault] is found.
This way \*[vault]s can be moved between \*[bank]s
or added without having to update a master index.

.multiple bank
.TP
.Bi host hostname (S)
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 client.

.TP
.Bi path path (S)
specify the path on client from which to back up. Use absolute path
starting with '/'.

.TP
.Bi exclude pattern (L)
Specify filename patterns to exclude.

Patterns are based on shell glob with some enhancements.

.See rsync(1)

.multiple exclude
.TP
.Bi userExcludeFile excludefilename (S)
Load a set of patterns from a file from client.

.TP
.Bi expireFailedImage time period (S)
Time an failed image is kept. Time periods can be specified as multiple
of sec, min, hour, day, week, month and year

.TP
.Bi expireRule expire-rule (L)
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 
not contain the '-' sign. The image name will
be complemented by the image time like
image\-2016-03-09-20.

.TP
.Bi longImageName true (B)
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

.TP
.Bi ignorePermissions true (B)
Ignore file permissions.  If this is set permissions
will not be checked or preserved.

.See rsync(1)

.default false

.TP
.Bi remoteShell command (S)
Remote shell utility.

This can be used to specify the location of
.B ssh
or
.B rsh
and/or to provide additional options like in
.Bi ssh \-p 2223
to use ssh on an alternative port number.

.default ssh

This remote shell command will be used not only as the
default rsync transport but also for loading user exclude file
and find excludes.

.TP
.Bi rsyncOption option[s] (L)
Specify additional options for the rsync command.

This allows to use rsync features that are not directly 
supported by kind.

.multiple rsyncOption

.TP
.Bi group_??? vault (L)
Specifies groups of vaults. If kind is called with a parameter 
as vault name like in "kind xyz", it first looks for a vaultgroup 
of this name. For this purpose a configuration option group_xyz is
searched and the given list of vaults is then handled. All images
created this way have the same image time.

.SH EXPIRE RULES
Expire rules is a list of rules used to determine an
expiration time for an \*[image].

The last rule that matches will apply so list order is significant.
This allows rules to be set in master configuration and 
rules in \*[vault] configuration files will override rules set in the
master configuration file.

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, 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).

Here are examples of a expire\-rules:

.nf
.ft CR
.ta .5i T 6m
                #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

.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/kind/master.conf
default master configuration file.
.TP
.B bank/vault/kind/vault.conf
default vault configuration file.
.TP
.B bank/vault/image/tree
actual image of source directory tree.
.TP
.B bank/vault/image/rsync-log
output from rsync

.SH SEE ALSO
.nf
kind(8)
ssh(1),
rsync(1)
.SH AUTHOR
kind was created by Wolfgang Ortmann.
.SH BUGS AND ISSUES
It is important to distinguish '=' from '+='. '+' overrides 
previously given values while '+=' adds new values to lists.