chiark / gitweb /
Release 1.0.0pre16.2.
[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.\"--------------------------------------------------------------------------
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.
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
100.BI "@inherits = " parent
101.PP
102then any lookups which can't be satisfied in that section will be
103satisfied instead from the
104.I parent
105section (and, if necessary, its parent in turn, and so on). Note that
106.BI $( key )
107substitutions in the resulting value will be satisfied from the original
108section (though falling back to scanning the parent section). For
109example, given the sections
110.VS
111[parent]
112detail = in parent
113blurb = expand $(detail)
2273401c 114.VE
6005ef9b
MW
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.
d64ce4ae 119.
6005ef9b
MW
120.SS "Standard keys and their meanings"
121The following keys have meanings to programs in the TrIPE suite. Other
122keys may be used by separately distributed extensions or for local use.
123The descriptions given are summaries only; see the references for
124details.
125.TP
126.B auto
127If true, include the peer in the
128.B %AUTO
129record. Used by
a62f8e8a
MW
130.BR connect (8)
131and
6005ef9b
MW
132.BR tripe-newpeers (8);
133described below.
134.TP
a62f8e8a
MW
135.B connect
136Shell command for initiating connection to this peer. Used by
d64ce4ae 137.BR connect (8).
a62f8e8a
MW
138.TP
139.B cork
6411163d 140Don't initiate immediate key exchange. Used by
a62f8e8a
MW
141.BR connect (8).
142.TP
d3731285
MW
143.B disconnect
144Shell command for closing down connection to this peer. Used by
d64ce4ae 145.BR connect (8).
d3731285 146.TP
a62f8e8a
MW
147.B every
148Interval for checking that the peer is still alive and well. Used by
d64ce4ae 149.BR connect (8).
a62f8e8a
MW
150.TP
151.B ifdown
152Script to bring down tunnel interface connected to the peer. Used by
d64ce4ae 153.BR connect (8).
a62f8e8a
MW
154.TP
155.B ifname
156Interface name to set for the tunnel interface to the peer. Used by
157.BR tripe-ifup (8).
158.TP
159.B ifup
160Script to bring up tunnel interface connected to the peer. Used by
d64ce4ae 161.BR connect (8).
a62f8e8a
MW
162.TP
163.B ifupextra
164Script containing additional interface setup. Used by
165.BR tripe-ifup (8).
166.TP
167.B laddr
168Local address for the tunnel interface to the peer. Used by
169.BR tripe-ifup (8).
170.TP
171.B keepalive
172Interval for sending keepalive pings. Used by
173.BR connect (8).
174.TP
48b84569
MW
175.B key
176Key tag to use to authenticate the peer. Used by
177.BR connect (8).
178.TP
6411163d
MW
179.B mobile
180Peer's IP address is highly volatile. Used by
181.BR connect (8).
182.TP
a62f8e8a
MW
183.B mtu
184Maximum transmission unit for the tunnel interface. Used by
185.BR tripe-ifup (8).
186.TP
187.B nets
188Networks to be routed over the tunnel interface. Used by
189.BR tripe-ifup (8).
190.TP
191.B peer
192Network address for this peer, or
193.BR PASSIVE .
194Used by
195.BR connect (8).
196.TP
fe2a5dcf
MW
197.B priv
198Tag of the private key to use when communicating with the peer.
d64ce4ae
MW
199Used by
200.BR connect (8).
fe2a5dcf 201.TP
a62f8e8a
MW
202.B raddr
203Remote address for the tunnel interface to the peer. Used by
204.BR tripe-ifup (8).
205.TP
206.B retries
207Number of failed ping attempts before attempting reconnection. Used by
d64ce4ae 208.BR connect (8).
a62f8e8a
MW
209.TP
210.B timeout
211Timeout for ping probes. Used by
d64ce4ae 212.BR connect (8).
a62f8e8a
MW
213.TP
214.B tunnel
215Tunnel driver to use when adding the peer. Used by
216.BR connect (8)).
217.TP
6005ef9b
MW
218.B user
219Peer will make active connection as
220.IR user .
221Used by
a62f8e8a
MW
222.BR connect (8)
223and
6005ef9b
MW
224.BR tripe-newpeers (8);
225described below.
d64ce4ae 226.
6005ef9b
MW
227.SS "Conversion"
228This section describes how the textual
229.B peers.in
230file is converted into the
231.BR peers.cdb (5)
232database.
233.PP
234The handling of each section depends on its name.
235.hP \*o
236Sections whose names have the form
237.BI @ whatever
238are ignored (though their contents may be relevant if the section is
239named in another section's
240.B @inherits
241key).
242.hP \*o
243Sections whose names have the form
244.BI $ whatever
245are written to local-type database records with the same name. The keys
246and values defined in the section (and its parent section, if it
247contains an
248.B @inherits
249key) are stored in the record using
250.B form-urlencoding
251as defined in RFC1822, except that the key-value pairs are separated by
252semicolons
253.RB ` ; '
254rather than ampersands
255.RB ` & '.
256The
257.B @inherits
258key-value pair is not written to the database.
259.hP \*o
260Other sections are written to peer-type database records, named
261.BI P name \fR,
262in exactly the same way as for local-type records. However, two special
263actions are also taken.
264.IP
265Firstly, if there is a key
266.B auto
267in the section (or in its parent, etc.), and the value is
268.BR y ,
269.BR yes .
270.BR t ,
271.BR true ,
272.BR 1 ,
273or
274.BR on ,
275then the section's name is added in the special
276.B %AUTO
277record.
278.IP
279Secondly, if there is a key
280.B user
281in the section (or in its parent, etc.), then a user record
282.BI U user
283is created whose contents is the section name.
284.
285.\"--------------------------------------------------------------------------
286.SH "SEE ALSO"
287.
288.BR cdb (5),
289.BR tripe (8).
290.PP
291.BR tripe-newpeers (8),
292.BR peers.cdb (5),
a62f8e8a 293.BR connect (8),
6005ef9b
MW
294.BR tripe-ifup (8).
295.
296.\"--------------------------------------------------------------------------
297.SH "AUTHOR"
298.
299Mark Wooding, <mdw@distorted.org.uk>
300.
301.\"----- That's all, folks --------------------------------------------------