chiark / gitweb /
init: Introduce the peer database.
[tripe] / peerdb / peers.in.5.in
... / ...
CommitLineData
1.\" -*-nroff-*-
2.\".
3.\" Manual for the peer configuration file
4.\"
5.\" (c) 2008 Straylight/Edgeware
6.\"
7.
8.\"----- Licensing notice ---------------------------------------------------
9.\"
10.\" This file is part of Trivial IP Encryption (TrIPE).
11.\"
12.\" TrIPE is free software; you can redistribute it and/or modify
13.\" it under the terms of the GNU General Public License as published by
14.\" the Free Software Foundation; either version 2 of the License, or
15.\" (at your option) any later version.
16.\"
17.\" TrIPE is distributed in the hope that it will be useful,
18.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20.\" GNU General Public License for more details.
21.\"
22.\" You should have received a copy of the GNU General Public License
23.\" along with TrIPE; if not, write to the Free Software Foundation,
24.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25.
26.\"--------------------------------------------------------------------------
27.so ../defs.man.in \"@@@PRE@@@
28.
29.\"--------------------------------------------------------------------------
30.TH peers.in 5 "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31.
32.\"--------------------------------------------------------------------------
33.SH "NAME"
34.
35peers.in \- source form for TrIPE peer database
36.
37.\"--------------------------------------------------------------------------
38.SH "DESCRIPTION"
39.
40The
41.B peers.in
42file is a plain text configuration file. It is read by
43.BR tripe-newpeers (8)
44in order to produce the
45.BR tripe.cdb (8)
46database used by services and other tools.
47.SS "General structure"
48The configuration file is line-oriented. Blank lines are ignored; lines
49beginning with a hash
50.RB ` # '
51or semicolon
52.RB ` ; '
53are ignored. The file is divided into sections by section headers,
54which are lines of the form
55.IP
56.BI [ name ]
57.PP
58Within each section are a number of assignments, of the form
59.IP
60.IB key " = " value
61.PP
62or (entirely equivalent)
63.IP
64.IB key ": " value
65.PP
66The
67.I key
68must start in the left hand column. The
69.I value
70may span multiple lines if subsequent lines begin with whitespace, in
71the manner of RFC822 headers.
72.PP
73There is a special case to be aware of: if a section doesn't specify a
74value for the key
75.B name
76then the section's own name is used as a default.
77.PP
78The following substitutions are made in the body of a value.
79.hP \*o
80An occurrence of
81.BI $( key )
82is replaced by the value assigned to the given
83.IR key .
84.hP \*o
85An occurrence of
86.BI $[ host ]
87is replaced by the IP address of the named
88.IR host .
89Note that
90.I host
91may itself contain
92.BI $( key )
93substitutions.
94.PP
95There is a simple concept of
96.I inheritance
97for sections. If a section contains an assignment
98.IP
99.BI "@inherits = " parent
100.PP
101then any lookups which can't be satisfied in that section will be
102satisfied instead from the
103.I parent
104section (and, if necessary, its parent in turn, and so on). Note that
105.BI $( key )
106substitutions in the resulting value will be satisfied from the original
107section (though falling back to scanning the parent section). For
108example, given the sections
109.VS
110[parent]
111detail = in parent
112blurb = expand $(detail)
113
114.PP
115Apart from its effect on lookups, as just described, the
116.B @inherits
117key is entirely ignored. In particular, it is never written to the
118database.
119.SS "Standard keys and their meanings"
120The following keys have meanings to programs in the TrIPE suite. Other
121keys may be used by separately distributed extensions or for local use.
122The descriptions given are summaries only; see the references for
123details.
124.TP
125.B auto
126If true, include the peer in the
127.B %AUTO
128record. Used by
129.BR tripe-newpeers (8);
130described below.
131.TP
132.B user
133Peer will make active connection as
134.IR user .
135Used by
136.BR tripe-newpeers (8);
137described below.
138.SS "Conversion"
139This section describes how the textual
140.B peers.in
141file is converted into the
142.BR peers.cdb (5)
143database.
144.PP
145The handling of each section depends on its name.
146.hP \*o
147Sections whose names have the form
148.BI @ whatever
149are ignored (though their contents may be relevant if the section is
150named in another section's
151.B @inherits
152key).
153.hP \*o
154Sections whose names have the form
155.BI $ whatever
156are written to local-type database records with the same name. The keys
157and values defined in the section (and its parent section, if it
158contains an
159.B @inherits
160key) are stored in the record using
161.B form-urlencoding
162as defined in RFC1822, except that the key-value pairs are separated by
163semicolons
164.RB ` ; '
165rather than ampersands
166.RB ` & '.
167The
168.B @inherits
169key-value pair is not written to the database.
170.hP \*o
171Other sections are written to peer-type database records, named
172.BI P name \fR,
173in exactly the same way as for local-type records. However, two special
174actions are also taken.
175.IP
176Firstly, if there is a key
177.B auto
178in the section (or in its parent, etc.), and the value is
179.BR y ,
180.BR yes .
181.BR t ,
182.BR true ,
183.BR 1 ,
184or
185.BR on ,
186then the section's name is added in the special
187.B %AUTO
188record.
189.IP
190Secondly, if there is a key
191.B user
192in the section (or in its parent, etc.), then a user record
193.BI U user
194is created whose contents is the section name.
195.
196.\"--------------------------------------------------------------------------
197.SH "SEE ALSO"
198.
199.BR cdb (5),
200.BR tripe (8).
201.PP
202.BR tripe-newpeers (8),
203.BR peers.cdb (5),
204.BR tripe-ifup (8).
205.
206.\"--------------------------------------------------------------------------
207.SH "AUTHOR"
208.
209Mark Wooding, <mdw@distorted.org.uk>
210.
211.\"----- That's all, folks --------------------------------------------------