init: Introduce the peer database.

[tripe] / peerdb / peers.in.5.in

.\" -*-nroff-*-
.\".
.\" Manual for the peer configuration file
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man.in \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH peers.in 5 "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
peers.in \- source form for TrIPE peer database
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B peers.in
file is a plain text configuration file.  It is read by
.BR tripe-newpeers (8)
in order to produce the
.BR tripe.cdb (8)
database used by services and other tools.
.SS "General structure"
The configuration file is line-oriented.  Blank lines are ignored; lines
beginning with a hash
.RB ` # '
or semicolon
.RB ` ; '
are ignored.  The file is divided into sections by section headers,
which are lines of the form
.IP
.BI [ name ]
.PP
Within each section are a number of assignments, of the form
.IP
.IB key " = " value
.PP
or (entirely equivalent)
.IP
.IB key ": " value
.PP
The
.I key
must start in the left hand column.  The
.I value
may span multiple lines if subsequent lines begin with whitespace, in
the manner of RFC822 headers.
.PP
There is a special case to be aware of: if a section doesn't specify a
value for the key
.B name
then the section's own name is used as a default.
.PP
The following substitutions are made in the body of a value.
.hP \*o
An occurrence of
.BI $( key )
is replaced by the value assigned to the given
.IR key .
.hP \*o
An occurrence of
.BI $[ host ]
is replaced by the IP address of the named
.IR host .
Note that
.I host
may itself contain
.BI $( key )
substitutions.
.PP
There is a simple concept of
.I inheritance
for sections.  If a section contains an assignment
.IP
.BI "@inherits = " parent
.PP
then any lookups which can't be satisfied in that section will be
satisfied instead from the
.I parent
section (and, if necessary, its parent in turn, and so on).  Note that
.BI $( key )
substitutions in the resulting value will be satisfied from the original
section (though falling back to scanning the parent section).  For
example, given the sections
.VS
[parent]
detail = in parent
blurb = expand $(detail)

.PP
Apart from its effect on lookups, as just described, the
.B @inherits
key is entirely ignored.  In particular, it is never written to the
database.
.SS "Standard keys and their meanings"
The following keys have meanings to programs in the TrIPE suite.  Other
keys may be used by separately distributed extensions or for local use.
The descriptions given are summaries only; see the references for
details.
.TP
.B auto
If true, include the peer in the
.B %AUTO
record.  Used by
.BR tripe-newpeers (8);
described below.
.TP
.B user
Peer will make active connection as
.IR user .
Used by
.BR tripe-newpeers (8);
described below.
.SS "Conversion"
This section describes how the textual
.B peers.in
file is converted into the
.BR peers.cdb (5)
database.
.PP
The handling of each section depends on its name.
.hP \*o
Sections whose names have the form
.BI @ whatever
are ignored (though their contents may be relevant if the section is
named in another section's
.B @inherits
key).
.hP \*o
Sections whose names have the form
.BI $ whatever
are written to local-type database records with the same name.  The keys
and values defined in the section (and its parent section, if it
contains an
.B @inherits
key) are stored in the record using
.B form-urlencoding
as defined in RFC1822, except that the key-value pairs are separated by
semicolons
.RB ` ; '
rather than ampersands
.RB ` & '.
The
.B @inherits
key-value pair is not written to the database.
.hP \*o
Other sections are written to peer-type database records, named
.BI P name \fR,
in exactly the same way as for local-type records.  However, two special
actions are also taken.
.IP
Firstly, if there is a key
.B auto
in the section (or in its parent, etc.), and the value is
.BR y ,
.BR yes .
.BR t ,
.BR true ,
.BR 1 ,
or
.BR on ,
then the section's name is added in the special
.B %AUTO
record.
.IP
Secondly, if there is a key
.B user
in the section (or in its parent, etc.), then a user record
.BI U user
is created whose contents is the section name.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR cdb (5),
.BR tripe (8).
.PP
.BR tripe-newpeers (8),
.BR peers.cdb (5),
.BR tripe-ifup (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------