--- /dev/null
+.\" -*-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 --------------------------------------------------
~mdw / tripe / blobdiff