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