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