X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/2fa800105a5897cad85c51c48d1970b9061a33f5..6005ef9bfba49124a25825a5b044d4f4cbf02792:/peerdb/peers.in.5.in diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in new file mode 100644 index 00000000..7b0127b1 --- /dev/null +++ b/peerdb/peers.in.5.in @@ -0,0 +1,211 @@ +.\" -*-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, +. +.\"----- That's all, folks --------------------------------------------------