chiark / gitweb /
Upgrade licence to GPLv3+.
[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.\"
11ad66c2
MW
12.\" TrIPE is free software: you can redistribute it and/or modify it under
13.\" the terms of the GNU General Public License as published by the Free
14.\" Software Foundation; either version 3 of the License, or (at your
15.\" option) any later version.
6005ef9b 16.\"
11ad66c2
MW
17.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
18.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20.\" for more details.
6005ef9b
MW
21.\"
22.\" You should have received a copy of the GNU General Public License
11ad66c2 23.\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
6005ef9b
MW
24.
25.\"--------------------------------------------------------------------------
26.so ../defs.man.in \"@@@PRE@@@
27.
28.\"--------------------------------------------------------------------------
0647ba7c 29.TH peers.in 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
6005ef9b
MW
30.
31.\"--------------------------------------------------------------------------
32.SH "NAME"
33.
34peers.in \- source form for TrIPE peer database
35.
36.\"--------------------------------------------------------------------------
37.SH "DESCRIPTION"
38.
39The
40.B peers.in
41file is a plain text configuration file. It is read by
42.BR tripe-newpeers (8)
43in order to produce the
44.BR tripe.cdb (8)
45database used by services and other tools.
d64ce4ae 46.
6005ef9b
MW
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
833bdc38 99.BI "@inherit = " parent
bd3db76c
MW
100.RB [[,]
101.I parent
102\&...]
6005ef9b
MW
103.PP
104then any lookups which can't be satisfied in that section will be
bd3db76c 105satisfied instead from its
6005ef9b 106.I parent
bd3db76c
MW
107sections (and, if necessary, their parents in turn, and so on).
108.PP
109.hP \*o
110If a value can be found for a key via multiple parents then all of them
111must report the
112.I same
113value. This restriction may be relaxed somewhat, if it turns out that a
114more flexible notion of multiple inheritance is useful.
115.hP \*o
116It's not allowed for a section to inherit, possibly indirectly, from
117itself. Currently errors of this kind are only diagnosed when a cycle
118is encountered while looking up a key and none of the sections on the
119path from the original section up to and round the cycle define a value
120for it. Future versions of this program might be more picky.
121.PP
122Note that
6005ef9b
MW
123.BI $( key )
124substitutions in the resulting value will be satisfied from the original
bd3db76c 125section (though falling back to scanning parent sections). For
6005ef9b
MW
126example, given the sections
127.VS
128[parent]
f08fe72e 129detail = in $(name)
6005ef9b 130blurb = expand $(detail)
f08fe72e
MW
131
132[child]
133@inherit = parent
2273401c 134.VE
f08fe72e
MW
135the key
136.B blurb
137takes the value
138.RB ` "expand in parent" '
139in section
140.BR parent ,
141and
142.RB ` "expand in child" '
143in section
144.BR child .
145.PP
6005ef9b 146Apart from its effect on lookups, as just described, the
833bdc38 147.B @inherit
6005ef9b
MW
148key is entirely ignored. In particular, it is never written to the
149database.
d64ce4ae 150.
6005ef9b
MW
151.SS "Standard keys and their meanings"
152The following keys have meanings to programs in the TrIPE suite. Other
153keys may be used by separately distributed extensions or for local use.
154The descriptions given are summaries only; see the references for
155details.
156.TP
157.B auto
158If true, include the peer in the
159.B %AUTO
160record. Used by
a62f8e8a
MW
161.BR connect (8)
162and
6005ef9b
MW
163.BR tripe-newpeers (8);
164described below.
165.TP
a62f8e8a
MW
166.B connect
167Shell command for initiating connection to this peer. Used by
d64ce4ae 168.BR connect (8).
a62f8e8a
MW
169.TP
170.B cork
6411163d 171Don't initiate immediate key exchange. Used by
a62f8e8a
MW
172.BR connect (8).
173.TP
d3731285
MW
174.B disconnect
175Shell command for closing down connection to this peer. Used by
d64ce4ae 176.BR connect (8).
d3731285 177.TP
a62f8e8a
MW
178.B every
179Interval for checking that the peer is still alive and well. Used by
d64ce4ae 180.BR connect (8).
a62f8e8a
MW
181.TP
182.B ifdown
183Script to bring down tunnel interface connected to the peer. Used by
d64ce4ae 184.BR connect (8).
a62f8e8a
MW
185.TP
186.B ifname
187Interface name to set for the tunnel interface to the peer. Used by
188.BR tripe-ifup (8).
189.TP
190.B ifup
191Script to bring up tunnel interface connected to the peer. Used by
d64ce4ae 192.BR connect (8).
a62f8e8a
MW
193.TP
194.B ifupextra
195Script containing additional interface setup. Used by
196.BR tripe-ifup (8).
197.TP
198.B laddr
199Local address for the tunnel interface to the peer. Used by
200.BR tripe-ifup (8).
201.TP
202.B keepalive
203Interval for sending keepalive pings. Used by
204.BR connect (8).
205.TP
48b84569
MW
206.B key
207Key tag to use to authenticate the peer. Used by
208.BR connect (8).
209.TP
6411163d
MW
210.B mobile
211Peer's IP address is highly volatile. Used by
212.BR connect (8).
213.TP
a62f8e8a
MW
214.B mtu
215Maximum transmission unit for the tunnel interface. Used by
216.BR tripe-ifup (8).
217.TP
218.B nets
219Networks to be routed over the tunnel interface. Used by
220.BR tripe-ifup (8).
221.TP
222.B peer
223Network address for this peer, or
224.BR PASSIVE .
225Used by
226.BR connect (8).
227.TP
fe2a5dcf
MW
228.B priv
229Tag of the private key to use when communicating with the peer.
d64ce4ae
MW
230Used by
231.BR connect (8).
fe2a5dcf 232.TP
a62f8e8a
MW
233.B raddr
234Remote address for the tunnel interface to the peer. Used by
235.BR tripe-ifup (8).
236.TP
237.B retries
238Number of failed ping attempts before attempting reconnection. Used by
d64ce4ae 239.BR connect (8).
a62f8e8a
MW
240.TP
241.B timeout
242Timeout for ping probes. Used by
d64ce4ae 243.BR connect (8).
a62f8e8a
MW
244.TP
245.B tunnel
246Tunnel driver to use when adding the peer. Used by
247.BR connect (8)).
248.TP
6005ef9b
MW
249.B user
250Peer will make active connection as
251.IR user .
252Used by
a62f8e8a
MW
253.BR connect (8)
254and
6005ef9b
MW
255.BR tripe-newpeers (8);
256described below.
d64ce4ae 257.
6005ef9b
MW
258.SS "Conversion"
259This section describes how the textual
260.B peers.in
261file is converted into the
262.BR peers.cdb (5)
263database.
264.PP
265The handling of each section depends on its name.
266.hP \*o
267Sections whose names have the form
268.BI @ whatever
269are ignored (though their contents may be relevant if the section is
270named in another section's
833bdc38 271.B @inherit
6005ef9b
MW
272key).
273.hP \*o
274Sections whose names have the form
275.BI $ whatever
276are written to local-type database records with the same name. The keys
277and values defined in the section (and its parent section, if it
278contains an
833bdc38 279.B @inherit
6005ef9b
MW
280key) are stored in the record using
281.B form-urlencoding
282as defined in RFC1822, except that the key-value pairs are separated by
283semicolons
284.RB ` ; '
285rather than ampersands
286.RB ` & '.
287The
833bdc38 288.B @inherit
6005ef9b
MW
289key-value pair is not written to the database.
290.hP \*o
291Other sections are written to peer-type database records, named
292.BI P name \fR,
293in exactly the same way as for local-type records. However, two special
294actions are also taken.
295.IP
296Firstly, if there is a key
297.B auto
298in the section (or in its parent, etc.), and the value is
299.BR y ,
300.BR yes .
301.BR t ,
302.BR true ,
303.BR 1 ,
304or
305.BR on ,
306then the section's name is added in the special
307.B %AUTO
308record.
309.IP
310Secondly, if there is a key
311.B user
312in the section (or in its parent, etc.), then a user record
313.BI U user
314is created whose contents is the section name.
315.
316.\"--------------------------------------------------------------------------
317.SH "SEE ALSO"
318.
319.BR cdb (5),
320.BR tripe (8).
321.PP
322.BR tripe-newpeers (8),
323.BR peers.cdb (5),
a62f8e8a 324.BR connect (8),
6005ef9b
MW
325.BR tripe-ifup (8).
326.
327.\"--------------------------------------------------------------------------
328.SH "AUTHOR"
329.
330Mark Wooding, <mdw@distorted.org.uk>
331.
332.\"----- That's all, folks --------------------------------------------------