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