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