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