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 ` * '
 101 returns all of the found addresses, separated by spaces, rather than
 102 just the first one.
 103 .PP
 104 There is a simple concept of
 105 .I inheritance
 106 for sections.  If a section contains an assignment
 107 .IP
 108 .BI "@inherit = " parent
 109 .RB [[,]
 110 .I parent
 111 \&...]
 112 .PP
 113 then any lookups which can't be satisfied in that section will be
 114 satisfied instead from its
 115 .I parent
 116 sections (and, if necessary, their parents in turn, and so on).
 117 .PP
 118 .hP \*o
 119 If a value can be found for a key via multiple parents then all of them
 120 must report the
 121 .I same
 122 value.  This restriction may be relaxed somewhat, if it turns out that a
 123 more flexible notion of multiple inheritance is useful.
 124 .hP \*o
 125 It's not allowed for a section to inherit, possibly indirectly, from
 126 itself.  Currently errors of this kind are only diagnosed when a cycle
 127 is encountered while looking up a key and none of the sections on the
 128 path from the original section up to and round the cycle define a value
 129 for it.  Future versions of this program might be more picky.
 130 .PP
 131 Note that
 132 .BI $( key )
 133 substitutions in the resulting value will be satisfied from the original
 134 section (though falling back to scanning parent sections).  For
 135 example, given the sections
 136 .VS
 137 [parent]
 138 detail = in $(name)
 139 blurb = expand $(detail)
 140
 141 [child]
 142 @inherit = parent
 143 .VE
 144 the key
 145 .B blurb
 146 takes the value
 147 .RB ` "expand in parent" '
 148 in section
 149 .BR parent ,
 150 and
 151 .RB ` "expand in child" '
 152 in section
 153 .BR child .
 154 .PP
 155 Apart from its effect on lookups, as just described, the
 156 .B @inherit
 157 key is entirely ignored.  In particular, it is never written to the
 158 database.
 159 .
 160 .SS "Standard keys and their meanings"
 161 The following keys have meanings to programs in the TrIPE suite.  Other
 162 keys may be used by separately distributed extensions or for local use.
 163 The descriptions given are summaries only; see the references for
 164 details.
 165 .TP
 166 .B auto
 167 If true, include the peer in the
 168 .B %AUTO
 169 record.  Used by
 170 .BR connect (8)
 171 and
 172 .BR tripe-newpeers (8);
 173 described below.
 174 .TP
 175 .B connect
 176 Shell command for initiating connection to this peer.  Used by
 177 .BR connect (8).
 178 .TP
 179 .B cork
 180 Don't initiate immediate key exchange.  Used by
 181 .BR connect (8).
 182 .TP
 183 .B disconnect
 184 Shell command for closing down connection to this peer.  Used by
 185 .BR connect (8).
 186 .TP
 187 .B every
 188 Interval for checking that the peer is still alive and well.  Used by
 189 .BR connect (8).
 190 .TP
 191 .B ifdown
 192 Script to bring down tunnel interface connected to the peer.  Used by
 193 .BR connect (8).
 194 .TP
 195 .B ifname
 196 Interface name to set for the tunnel interface to the peer.  Used by
 197 .BR tripe-ifup (8).
 198 .TP
 199 .B ifup
 200 Script to bring up tunnel interface connected to the peer.  Used by
 201 .BR connect (8).
 202 .TP
 203 .B ifupextra
 204 Script containing additional interface setup.  Used by
 205 .BR tripe-ifup (8).
 206 .TP
 207 .B laddr
 208 Local address for the tunnel interface to the peer.  Used by
 209 .BR tripe-ifup (8).
 210 .TP
 211 .B keepalive
 212 Interval for sending keepalive pings.  Used by
 213 .BR connect (8).
 214 .TP
 215 .B key
 216 Key tag to use to authenticate the peer.  Used by
 217 .BR connect (8).
 218 .TP
 219 .B mobile
 220 Peer's IP address is highly volatile.  Used by
 221 .BR connect (8).
 222 .TP
 223 .B mtu
 224 Maximum transmission unit for the tunnel interface.  Used by
 225 .BR tripe-ifup (8).
 226 .TP
 227 .B nets
 228 Networks to be routed over the tunnel interface.  Used by
 229 .BR tripe-ifup (8).
 230 .TP
 231 .B peer
 232 Network address for this peer, or
 233 .BR PASSIVE .
 234 Used by
 235 .BR connect (8).
 236 .TP
 237 .B priv
 238 Tag of the private key to use when communicating with the peer.
 239 Used by
 240 .BR connect (8).
 241 .TP
 242 .B raddr
 243 Remote address for the tunnel interface to the peer.  Used by
 244 .BR tripe-ifup (8).
 245 .TP
 246 .B retries
 247 Number of failed ping attempts before attempting reconnection.  Used by
 248 .BR connect (8).
 249 .TP
 250 .B timeout
 251 Timeout for ping probes.  Used by
 252 .BR connect (8).
 253 .TP
 254 .B tunnel
 255 Tunnel driver to use when adding the peer.  Used by
 256 .BR connect (8)).
 257 .TP
 258 .B user
 259 Peer will make active connection as
 260 .IR user .
 261 Used by
 262 .BR connect (8)
 263 and
 264 .BR tripe-newpeers (8);
 265 described below.
 266 .
 267 .SS "Conversion"
 268 This section describes how the textual
 269 .B peers.in
 270 file is converted into the
 271 .BR peers.cdb (5)
 272 database.
 273 .PP
 274 The handling of each section depends on its name.
 275 .hP \*o
 276 Sections whose names have the form
 277 .BI @ whatever
 278 are ignored (though their contents may be relevant if the section is
 279 named in another section's
 280 .B @inherit
 281 key).
 282 .hP \*o
 283 Sections whose names have the form
 284 .BI $ whatever
 285 are written to local-type database records with the same name.  The keys
 286 and values defined in the section (and its parent section, if it
 287 contains an
 288 .B @inherit
 289 key) are stored in the record using
 290 .B form-urlencoding
 291 as defined in RFC1822, except that the key-value pairs are separated by
 292 semicolons
 293 .RB ` ; '
 294 rather than ampersands
 295 .RB ` & '.
 296 Keys whose names begin with
 297 .RB ` @ '
 298 are not written to the database.
 299 .hP \*o
 300 Other sections are written to peer-type database records, named
 301 .BI P name \fR,
 302 in exactly the same way as for local-type records.  However, two special
 303 actions are also taken.
 304 .IP
 305 Firstly, if there is a key
 306 .B auto
 307 in the section (or in its parent, etc.), and the value is
 308 .BR y ,
 309 .BR yes .
 310 .BR t ,
 311 .BR true ,
 312 .BR 1 ,
 313 or
 314 .BR on ,
 315 then the section's name is added in the special
 316 .B %AUTO
 317 record.
 318 .IP
 319 Secondly, if there is a key
 320 .B user
 321 in the section (or in its parent, etc.), then a user record
 322 .BI U user
 323 is created whose contents is the section name.
 324 .
 325 .\"--------------------------------------------------------------------------
 326 .SH "SEE ALSO"
 327 .
 328 .BR cdb (5),
 329 .BR tripe (8).
 330 .PP
 331 .BR tripe-newpeers (8),
 332 .BR peers.cdb (5),
 333 .BR connect (8),
 334 .BR tripe-ifup (8).
 335 .
 336 .\"--------------------------------------------------------------------------
 337 .SH "AUTHOR"
 338 .
 339 Mark Wooding, <mdw@distorted.org.uk>
 340 .
 341 .\"----- That's all, folks --------------------------------------------------