3 .\" Manual for the peer configuration file
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
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.
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
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \"@@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH peers.in 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 peers.in \- source form for TrIPE peer database
36 .\"--------------------------------------------------------------------------
41 file is a plain text configuration file. It is read by
42 .BR tripe-newpeers (8)
43 in order to produce the
45 database used by services and other tools.
47 .SS "General structure"
48 The configuration file is line-oriented. Blank lines are ignored; lines
53 are ignored. The file is divided into sections by section headers,
54 which are lines of the form
58 Within each section are a number of assignments, of the form
62 or (entirely equivalent)
68 must start in the left hand column. The
70 may span multiple lines if subsequent lines begin with whitespace, in
71 the manner of RFC822 headers.
73 There is a special case to be aware of: if a section doesn't specify a
76 then the section's own name is used as a default.
78 The following substitutions are made in the body of a value.
82 is replaced by the value assigned to the given
87 is replaced by the IP address of the named
95 consist of zero or more of the following characters:
106 returns all of the found addresses, separated by spaces, rather than
107 just the first one. If neither address family is requested, then
109 is assumed. IPv6 address lookup of names, rather than address literals,
110 depends on the external
112 program; if it is not present then only IPv4 lookups will be performed.
114 There is a simple concept of
116 for sections. If a section contains an assignment
118 .BI "@inherit = " parent
123 then any lookups which can't be satisfied in that section will be
124 satisfied instead from its
126 sections (and, if necessary, their parents in turn, and so on).
129 If a value can be found for a key via multiple parents then all of them
132 value. This restriction may be relaxed somewhat, if it turns out that a
133 more flexible notion of multiple inheritance is useful.
135 It's not allowed for a section to inherit, possibly indirectly, from
136 itself. Currently errors of this kind are only diagnosed when a cycle
137 is encountered while looking up a key and none of the sections on the
138 path from the original section up to and round the cycle define a value
139 for it. Future versions of this program might be more picky.
143 substitutions in the resulting value will be satisfied from the original
144 section (though falling back to scanning parent sections). For
145 example, given the sections
149 blurb = expand $(detail)
157 .RB ` "expand in parent" '
161 .RB ` "expand in child" '
165 Apart from its effect on lookups, as just described, the
167 key is entirely ignored. In particular, it is never written to the
170 .SS "Standard keys and their meanings"
171 The following keys have meanings to programs in the TrIPE suite. Other
172 keys may be used by separately distributed extensions or for local use.
173 The descriptions given are summaries only; see the references for
177 If true, include the peer in the
182 .BR tripe-newpeers (8);
186 Shell command for initiating connection to this peer. Used by
190 Don't initiate immediate key exchange. Used by
194 Shell command for closing down connection to this peer. Used by
198 Mark the peer as ephemeral: see
200 for what this means. Used by
204 Interval for checking that the peer is still alive and well. Used by
208 Script to bring down tunnel interface connected to the peer. Used by
212 Interface name to set for the tunnel interface to the peer. Used by
216 Script to bring up tunnel interface connected to the peer. Used by
220 Script containing additional interface setup. Used by
224 Local address for the tunnel interface to the peer. Used by
228 Interval for sending keepalive pings. Used by
232 Key tag to use to authenticate the peer. Used by
236 Knock string to send when establishing a dynamic connection. Used by
240 Peer's IP address is highly volatile. Used by
244 Maximum transmission unit for the tunnel interface. Used by
248 Networks to be routed over the tunnel interface. Used by
252 Network address for this peer, or
258 Tag of the private key to use when communicating with the peer.
263 Remote address for the tunnel interface to the peer. Used by
267 Number of failed ping attempts before attempting reconnection. Used by
271 Timeout for ping probes. Used by
275 Tunnel driver to use when adding the peer. Used by
279 Peer will make active connection as
284 .BR tripe-newpeers (8);
288 This section describes how the textual
290 file is converted into the
294 The handling of each section depends on its name.
296 Sections whose names have the form
298 are ignored (though their contents may be relevant if the section is
299 named in another section's
303 Sections whose names have the form
305 are written to local-type database records with the same name. The keys
306 and values defined in the section (and its parent section, if it
309 key) are stored in the record using
311 as defined in RFC1822, except that the key-value pairs are separated by
314 rather than ampersands
316 Keys whose names begin with
318 are not written to the database.
320 Other sections are written to peer-type database records, named
322 in exactly the same way as for local-type records. However, two special
323 actions are also taken.
325 Firstly, if there is a key
327 in the section (or in its parent, etc.), and the value is
335 then the section's name is added in the special
339 Secondly, if there is a key
341 in the section (or in its parent, etc.), then a user record
343 is created whose contents is the section name.
345 .\"--------------------------------------------------------------------------
351 .BR tripe-newpeers (8),
356 .\"--------------------------------------------------------------------------
359 Mark Wooding, <mdw@distorted.org.uk>
361 .\"----- That's all, folks --------------------------------------------------