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
 114 .PP
 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 .SS "Standard keys and their meanings"
 120 The following keys have meanings to programs in the TrIPE suite.  Other
 121 keys may be used by separately distributed extensions or for local use.
 122 The descriptions given are summaries only; see the references for
 123 details.
 124 .TP
 125 .B auto
 126 If true, include the peer in the
 127 .B %AUTO
 128 record.  Used by
 129 .BR tripe-newpeers (8);
 130 described below.
 131 .TP
 132 .B user
 133 Peer will make active connection as
 134 .IR user .
 135 Used by
 136 .BR tripe-newpeers (8);
 137 described below.
 138 .SS "Conversion"
 139 This section describes how the textual
 140 .B peers.in
 141 file is converted into the
 142 .BR peers.cdb (5)
 143 database.
 144 .PP
 145 The handling of each section depends on its name.
 146 .hP \*o
 147 Sections whose names have the form
 148 .BI @ whatever
 149 are ignored (though their contents may be relevant if the section is
 150 named in another section's
 151 .B @inherits
 152 key).
 153 .hP \*o
 154 Sections whose names have the form
 155 .BI $ whatever
 156 are written to local-type database records with the same name.  The keys
 157 and values defined in the section (and its parent section, if it
 158 contains an
 159 .B @inherits
 160 key) are stored in the record using
 161 .B form-urlencoding
 162 as defined in RFC1822, except that the key-value pairs are separated by
 163 semicolons
 164 .RB ` ; '
 165 rather than ampersands
 166 .RB ` & '.
 167 The
 168 .B @inherits
 169 key-value pair is not written to the database.
 170 .hP \*o
 171 Other sections are written to peer-type database records, named
 172 .BI P name \fR,
 173 in exactly the same way as for local-type records.  However, two special
 174 actions are also taken.
 175 .IP
 176 Firstly, if there is a key
 177 .B auto
 178 in the section (or in its parent, etc.), and the value is
 179 .BR y ,
 180 .BR yes .
 181 .BR t ,
 182 .BR true ,
 183 .BR 1 ,
 184 or
 185 .BR on ,
 186 then the section's name is added in the special
 187 .B %AUTO
 188 record.
 189 .IP
 190 Secondly, if there is a key
 191 .B user
 192 in the section (or in its parent, etc.), then a user record
 193 .BI U user
 194 is created whose contents is the section name.
 195 .
 196 .\"--------------------------------------------------------------------------
 197 .SH "SEE ALSO"
 198 .
 199 .BR cdb (5),
 200 .BR tripe (8).
 201 .PP
 202 .BR tripe-newpeers (8),
 203 .BR peers.cdb (5),
 204 .BR tripe-ifup (8).
 205 .
 206 .\"--------------------------------------------------------------------------
 207 .SH "AUTHOR"
 208 .
 209 Mark Wooding, <mdw@distorted.org.uk>
 210 .
 211 .\"----- That's all, folks --------------------------------------------------