chiark / gitweb /
uslip/uslip.c: Be consistent about `VERB_NOUN' function naming.
[tripe] / peerdb / peers.in.5.in
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 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 peers.in \- source form for TrIPE peer database
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "DESCRIPTION"
39 .
40 The
41 .B peers.in
42 file is a plain text configuration file.  It is read by
43 .BR tripe-newpeers (8)
44 in order to produce the
45 .BR tripe.cdb (8)
46 database used by services and other tools.
47 .
48 .SS "General structure"
49 The configuration file is line-oriented.  Blank lines are ignored; lines
50 beginning with a hash
51 .RB ` # '
52 or semicolon
53 .RB ` ; '
54 are ignored.  The file is divided into sections by section headers,
55 which are lines of the form
56 .IP
57 .BI [ name ]
58 .PP
59 Within each section are a number of assignments, of the form
60 .IP
61 .IB key " = " value
62 .PP
63 or (entirely equivalent)
64 .IP
65 .IB key ": " value
66 .PP
67 The
68 .I key
69 must start in the left hand column.  The
70 .I value
71 may span multiple lines if subsequent lines begin with whitespace, in
72 the manner of RFC822 headers.
73 .PP
74 There is a special case to be aware of: if a section doesn't specify a
75 value for the key
76 .B name
77 then the section's own name is used as a default.
78 .PP
79 The following substitutions are made in the body of a value.
80 .hP \*o
81 An occurrence of
82 .BI $( key )
83 is replaced by the value assigned to the given
84 .IR key .
85 .hP \*o
86 An occurrence of
87 .BI $[ host ]
88 is replaced by the IP address of the named
89 .IR host .
90 Note that
91 .I host
92 may itself contain
93 .BI $( key )
94 substitutions.
95 .PP
96 There is a simple concept of
97 .I inheritance
98 for sections.  If a section contains an assignment
99 .IP
100 .BI "@inherit = " parent
101 .RB [[,]
102 .I parent
103 \&...]
104 .PP
105 then any lookups which can't be satisfied in that section will be
106 satisfied instead from its
107 .I parent
108 sections (and, if necessary, their parents in turn, and so on).
109 .PP
110 .hP \*o
111 If a value can be found for a key via multiple parents then all of them
112 must report the
113 .I same
114 value.  This restriction may be relaxed somewhat, if it turns out that a
115 more flexible notion of multiple inheritance is useful.
116 .hP \*o
117 It's not allowed for a section to inherit, possibly indirectly, from
118 itself.  Currently errors of this kind are only diagnosed when a cycle
119 is encountered while looking up a key and none of the sections on the
120 path from the original section up to and round the cycle define a value
121 for it.  Future versions of this program might be more picky.
122 .PP
123 Note that
124 .BI $( key )
125 substitutions in the resulting value will be satisfied from the original
126 section (though falling back to scanning parent sections).  For
127 example, given the sections
128 .VS
129 [parent]
130 detail = in parent
131 blurb = expand $(detail)
132 .VE
133 Apart from its effect on lookups, as just described, the
134 .B @inherit
135 key is entirely ignored.  In particular, it is never written to the
136 database.
137 .
138 .SS "Standard keys and their meanings"
139 The following keys have meanings to programs in the TrIPE suite.  Other
140 keys may be used by separately distributed extensions or for local use.
141 The descriptions given are summaries only; see the references for
142 details.
143 .TP
144 .B auto
145 If true, include the peer in the
146 .B %AUTO
147 record.  Used by
148 .BR connect (8)
149 and
150 .BR tripe-newpeers (8);
151 described below.
152 .TP
153 .B connect
154 Shell command for initiating connection to this peer.  Used by
155 .BR connect (8).
156 .TP
157 .B cork
158 Don't initiate immediate key exchange.  Used by
159 .BR connect (8).
160 .TP
161 .B disconnect
162 Shell command for closing down connection to this peer.  Used by
163 .BR connect (8).
164 .TP
165 .B every
166 Interval for checking that the peer is still alive and well.  Used by
167 .BR connect (8).
168 .TP
169 .B ifdown
170 Script to bring down tunnel interface connected to the peer.  Used by
171 .BR connect (8).
172 .TP
173 .B ifname
174 Interface name to set for the tunnel interface to the peer.  Used by
175 .BR tripe-ifup (8).
176 .TP
177 .B ifup
178 Script to bring up tunnel interface connected to the peer.  Used by
179 .BR connect (8).
180 .TP
181 .B ifupextra
182 Script containing additional interface setup.  Used by
183 .BR tripe-ifup (8).
184 .TP
185 .B laddr
186 Local address for the tunnel interface to the peer.  Used by
187 .BR tripe-ifup (8).
188 .TP
189 .B keepalive
190 Interval for sending keepalive pings.  Used by
191 .BR connect (8).
192 .TP
193 .B key
194 Key tag to use to authenticate the peer.  Used by
195 .BR connect (8).
196 .TP
197 .B mobile
198 Peer's IP address is highly volatile.  Used by
199 .BR connect (8).
200 .TP
201 .B mtu
202 Maximum transmission unit for the tunnel interface.  Used by
203 .BR tripe-ifup (8).
204 .TP
205 .B nets
206 Networks to be routed over the tunnel interface.  Used by
207 .BR tripe-ifup (8).
208 .TP
209 .B peer
210 Network address for this peer, or
211 .BR PASSIVE .
212 Used by
213 .BR connect (8).
214 .TP
215 .B priv
216 Tag of the private key to use when communicating with the peer.
217 Used by
218 .BR connect (8).
219 .TP
220 .B raddr
221 Remote address for the tunnel interface to the peer.  Used by
222 .BR tripe-ifup (8).
223 .TP
224 .B retries
225 Number of failed ping attempts before attempting reconnection.  Used by
226 .BR connect (8).
227 .TP
228 .B timeout
229 Timeout for ping probes.  Used by
230 .BR connect (8).
231 .TP
232 .B tunnel
233 Tunnel driver to use when adding the peer.  Used by
234 .BR connect (8)).
235 .TP
236 .B user
237 Peer will make active connection as
238 .IR user .
239 Used by
240 .BR connect (8)
241 and
242 .BR tripe-newpeers (8);
243 described below.
244 .
245 .SS "Conversion"
246 This section describes how the textual
247 .B peers.in
248 file is converted into the
249 .BR peers.cdb (5)
250 database.
251 .PP
252 The handling of each section depends on its name.
253 .hP \*o
254 Sections whose names have the form
255 .BI @ whatever
256 are ignored (though their contents may be relevant if the section is
257 named in another section's
258 .B @inherit
259 key).
260 .hP \*o
261 Sections whose names have the form
262 .BI $ whatever
263 are written to local-type database records with the same name.  The keys
264 and values defined in the section (and its parent section, if it
265 contains an
266 .B @inherit
267 key) are stored in the record using
268 .B form-urlencoding
269 as defined in RFC1822, except that the key-value pairs are separated by
270 semicolons
271 .RB ` ; '
272 rather than ampersands
273 .RB ` & '.
274 The
275 .B @inherit
276 key-value pair is not written to the database.
277 .hP \*o
278 Other sections are written to peer-type database records, named
279 .BI P name \fR,
280 in exactly the same way as for local-type records.  However, two special
281 actions are also taken.
282 .IP
283 Firstly, if there is a key
284 .B auto
285 in the section (or in its parent, etc.), and the value is
286 .BR y ,
287 .BR yes .
288 .BR t ,
289 .BR true ,
290 .BR 1 ,
291 or
292 .BR on ,
293 then the section's name is added in the special
294 .B %AUTO
295 record.
296 .IP
297 Secondly, if there is a key
298 .B user
299 in the section (or in its parent, etc.), then a user record
300 .BI U user
301 is created whose contents is the section name.
302 .
303 .\"--------------------------------------------------------------------------
304 .SH "SEE ALSO"
305 .
306 .BR cdb (5),
307 .BR tripe (8).
308 .PP
309 .BR tripe-newpeers (8),
310 .BR peers.cdb (5),
311 .BR connect (8),
312 .BR tripe-ifup (8).
313 .
314 .\"--------------------------------------------------------------------------
315 .SH "AUTHOR"
316 .
317 Mark Wooding, <mdw@distorted.org.uk>
318 .
319 .\"----- That's all, folks --------------------------------------------------