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