| 1 | .TH secnet 8 |
| 2 | |
| 3 | .SH NAME |
| 4 | secnet \- VPN router daemon |
| 5 | |
| 6 | .SH SYNOPSIS |
| 7 | \fBsecnet\fR [\fIOPTIONS\fR] |
| 8 | |
| 9 | .SH DESCRIPTION |
| 10 | \fBsecnet\fR allows virtual private networks to be constructed |
| 11 | spanning multiple separate sites. |
| 12 | |
| 13 | .SH OPTIONS |
| 14 | .TP |
| 15 | .B --verbose\fR, \fB-v |
| 16 | Enable extra diagnostics. |
| 17 | .TP |
| 18 | .B --nowarnings\fR, \fB-w |
| 19 | Suppress warnings. |
| 20 | .TP |
| 21 | .B --help |
| 22 | Display usage message. |
| 23 | .TP |
| 24 | .B --version |
| 25 | Display version string. |
| 26 | .TP |
| 27 | .B --nodetach\fR, \fB-n |
| 28 | Don't go into background. |
| 29 | The default behaviour is to become a daemon during startup. |
| 30 | .TP |
| 31 | .B --silent\fR, \fB--quiet\fR, \fB-f |
| 32 | Suppress error messages. |
| 33 | .TP |
| 34 | .B --debug\fR, \fB-d |
| 35 | Enable debug messages. |
| 36 | .TP |
| 37 | .B --config\fR, \fB-c \fIPATH |
| 38 | Specify configuration file. |
| 39 | The default is \fI/etc/secnet/secnet.conf\fR. |
| 40 | .TP |
| 41 | .B --just-check-config\fR, \fB-j |
| 42 | Check configuration and exit. |
| 43 | .TP |
| 44 | .B --sites-key\fR, \fB-s \fIKEY |
| 45 | Configuration file key defining active sites. |
| 46 | The default is \fBsites\fR. |
| 47 | |
| 48 | .SH "CONFIGURATION FILE" |
| 49 | .SS Overview |
| 50 | The default configuration file is \fI/etc/secnet/secnet.conf\fR. |
| 51 | This can be overridden with the \fB--config\fR option. |
| 52 | .PP |
| 53 | The configuration file defines a dictionary (a mapping from keys to |
| 54 | values) of configuration information for secnet. |
| 55 | It is recursive in nature, i.e. values may themselves include dictionaries. |
| 56 | Any node in the nested structure thus defined can be identified by a |
| 57 | \fIpath\fR, which is the sequence of keys necessary to reach it from |
| 58 | the root, separated by "/" characters. |
| 59 | See \fBPaths\fR below for how this is used. |
| 60 | .PP |
| 61 | Furthermore, when a key is looked up in a dictionary, if it cannot be |
| 62 | found, it is sought in the parent dictionary, and so on back to the |
| 63 | root. |
| 64 | For instance, each \fIsite\fR must contain the \fBresolver\fR key, but |
| 65 | in a typical configuration there is no value in having different |
| 66 | resolvers for each site. |
| 67 | Therefore \fBresolver\fR is defined at the root and thus automatically |
| 68 | incorporated into all sites. |
| 69 | .SS Whitespace |
| 70 | Whitespace, including newlines, is ignored except to the extent that |
| 71 | it bounds other symbols. |
| 72 | .PP |
| 73 | Comment begin with "#" and continues to the end of the line. |
| 74 | Comments are ignored. |
| 75 | .SS Inclusion |
| 76 | A file may be recursively included into the configuration file using a |
| 77 | line of the form: |
| 78 | .IP |
| 79 | \fBinclude \fIPATH |
| 80 | .PP |
| 81 | This is handled at a higher level than the main parser and so |
| 82 | precludes the possibility of using the string \fBinclude\fR for any |
| 83 | other purpose. |
| 84 | .\" check if this is true. it's probably a bug! |
| 85 | .SS Assignments |
| 86 | The configuration file contains one or more assigments. |
| 87 | Each assignment is written: |
| 88 | .IP |
| 89 | \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR |
| 90 | .PP |
| 91 | i.e. the equals sign is optional. |
| 92 | The semicolon is mandatory in all contexts. |
| 93 | .PP |
| 94 | Keys start with a letter or "_" and continue with any numbers of |
| 95 | letters, digits, "_" and "-". |
| 96 | .PP |
| 97 | Each \fIkey\fR is a list of one or more \fIvalues\fR, separated by commas. |
| 98 | Possible values types are \fIboolean\fR, \fIstring\fR, \fInumber\fR, |
| 99 | \fIdictionary\fR, \fIpath\fR and \fIclosure evaluation\fR. |
| 100 | .\" This man page draws a distinction between a closure (the thing |
| 101 | .\" evaluated) and a closure evaluation (the closure plus is |
| 102 | .\" arguments). |
| 103 | .SS "Strings" |
| 104 | Strings are contained within "double quotes". |
| 105 | There is (currently) no escape syntax and no way to include quotes |
| 106 | inside strings. |
| 107 | .PP |
| 108 | Example: |
| 109 | .nf |
| 110 | filename "/var/log/secnet"; |
| 111 | .fi |
| 112 | .SS "Numbers" |
| 113 | Numbers are encoded in decimal and do not include a sign. |
| 114 | Numbers must lie in the range 0 to 4294967295. |
| 115 | .PP |
| 116 | Example: |
| 117 | .nf |
| 118 | mtu 1400; |
| 119 | .fi |
| 120 | .SS "Dictionaries" |
| 121 | .\" In conffile.y dictionaries can be preceded by a search path, but |
| 122 | .\" this is not implemented elsewhere, so not documented here. |
| 123 | Dictionaries consist of one or more assignments, in the same syntax as |
| 124 | given above, enclosed in "{" and "}". |
| 125 | .PP |
| 126 | Example: |
| 127 | .nf |
| 128 | system { |
| 129 | userid "secnet"; |
| 130 | pidfile "/var/run/secnet.pid"; |
| 131 | }; |
| 132 | .fi |
| 133 | .SS "Paths" |
| 134 | Paths allow a key already defined in the configuration to be aliased. |
| 135 | .PP |
| 136 | Paths consist of a sequence of keys separated by "/". |
| 137 | If the path starts with a "/" then it is an \fIabsolute path\fR and |
| 138 | the search starts at the root of the configuration. |
| 139 | Otherwise it is a \fIrelative path\fR and starts in the containing |
| 140 | dictionary or in any of its parents, down to and including the root. |
| 141 | If there is more than one match, the one furthest from the root "wins". |
| 142 | .PP |
| 143 | The value of a path is the list assigned to the key it refers to. |
| 144 | Lists are flattened; for example if a key is defined as a list of two |
| 145 | paths, and each of those refers to a list of two integers, the |
| 146 | original key is therefore defined to be a list of four integers, not |
| 147 | a list consisting of two lists. |
| 148 | .PP |
| 149 | It is not possible to refer to a \fIlater\fR key using a path. |
| 150 | .PP |
| 151 | Example: |
| 152 | .nf |
| 153 | vpn { |
| 154 | test { |
| 155 | kakajou vpn-data/test/kakajou/kakajou; |
| 156 | araminta vpn-data/test/araminta/araminta; |
| 157 | deodand vpn-data/test/deodand/deodand; |
| 158 | all-sites kakajou,araminta,deodand; |
| 159 | }; |
| 160 | }; |
| 161 | all-sites vpn/test/all-sites; |
| 162 | .fi |
| 163 | .PP |
| 164 | Here, each of \fBvpn/test/kakajou\fR, \fBvpn/test/araminta\fR and |
| 165 | \fBvpn/test/deodand\fR are defined as aliases to values defined |
| 166 | elsewhere. |
| 167 | \fBvpn/tests/all-sites\fR is defined as the list of all three of those |
| 168 | values, and \fBall-sites\fR is then defined to be an alias for that. |
| 169 | .SS "Booleans" |
| 170 | The (single-element) paths \fBfalse\fR, \fBno\fR and \fBnowise\fR are |
| 171 | predefined and refer to a boolean false value. |
| 172 | Similarly \fBtrue\fR, \fByes\fR and \fBverily\fR point at a boolean |
| 173 | true value. |
| 174 | .PP |
| 175 | In all six cases, variants with just the first letter capitalized, and |
| 176 | with all letters capitalized, are also provided. |
| 177 | .PP |
| 178 | Example: |
| 179 | .nf |
| 180 | random randomfile("/dev/urandom",no); |
| 181 | .fi |
| 182 | .SS "Closure Evaluation" |
| 183 | Closure evaluation uses the following syntax: |
| 184 | .IP |
| 185 | \fICLOSURE \fB( \fIARGUMENTS \fB) |
| 186 | .PP |
| 187 | \fICLOSURE\fR may be a path referring to a closure, or may itself be a |
| 188 | closure evaluation. |
| 189 | .PP |
| 190 | \fIARGUMENTS\fR is a list of zero or more values, separated by commas. |
| 191 | As a shortcut, if the arguments consist of a single dictionary, the |
| 192 | parentheses may be ommitted: |
| 193 | .IP |
| 194 | \fICLOSURE \fB{ \fR... \fB} |
| 195 | .PP |
| 196 | Example: |
| 197 | .nf |
| 198 | sites map(site, vpn/test/all-sites); |
| 199 | .fi |
| 200 | .PP |
| 201 | When a closure is evaluated it returns a value (a list, much as above) |
| 202 | and may also have side effects (which may be immediate or may be |
| 203 | deferred to some later phase of execution). |
| 204 | A list of built-in closures is given below. |
| 205 | .SS "Mandatory Keys" |
| 206 | Two keys are mandatory. |
| 207 | \fBsystem\fR must be a dictionary in which the following keys can be |
| 208 | looked up: |
| 209 | .TP |
| 210 | .B log |
| 211 | A \fIlog closure\fR; see the \fBlogfile\fR documentation below. |
| 212 | The destination for log messages. |
| 213 | Mandatory. |
| 214 | .TP |
| 215 | .B userid |
| 216 | A string. |
| 217 | The userid to run as after dropping privilege. |
| 218 | Optional. |
| 219 | .TP |
| 220 | .B pidfile |
| 221 | A string. |
| 222 | The path to write a pidfile. |
| 223 | Optional. |
| 224 | .PP |
| 225 | \fBsites\fR should be a list of \fIsite closures\fR; see the \fBsite\fR documentation below. |
| 226 | This defines the collection of tunnel endpoints that \fBsecnet\fR will |
| 227 | communicate with. |
| 228 | .PP |
| 229 | Recall the recursive lookup logic described in \fBOverview\fR above: |
| 230 | if (for instance) \fBlog\fR is defined in the top level dictionary but |
| 231 | not in \fBsystem\fR, it will nevertheless be found when looked up in |
| 232 | the latter. |
| 233 | |
| 234 | .SH CLOSURES |
| 235 | \fBsecnet\fR contains a collection of built-in closures |
| 236 | with names (i.e. single-element paths) given below. |
| 237 | .PP |
| 238 | Most of them return anonymous closures of various types, |
| 239 | which are described contextually. |
| 240 | |
| 241 | .SS adns |
| 242 | \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR |
| 243 | .TP |
| 244 | .I DICT |
| 245 | This either be empty or contain the single key \fBconfig\fR, with a |
| 246 | string value giving configuration to supply to ADNS. |
| 247 | This might be read from a file using \fBreadfile\fR. |
| 248 | .PP |
| 249 | A \fIresolver closure\fR is a means of converting hostnames into |
| 250 | network addresses. |
| 251 | |
| 252 | .SS diffie-hellman |
| 253 | .PP |
| 254 | \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR |
| 255 | .TP |
| 256 | .I MODULUS |
| 257 | String. |
| 258 | The prime modulus \fIp\fR in hex. |
| 259 | .TP |
| 260 | .I GENERATOR |
| 261 | String. |
| 262 | The generator \fIg\fR in hex. |
| 263 | .TP |
| 264 | .I CHECK |
| 265 | Boolean. |
| 266 | If \fBtrue\fR (the default) then check if \fIp\fR is prime. |
| 267 | .PP |
| 268 | A \fIdh closure\fR defines a group to be used for key exchange. |
| 269 | The same group must be used by all sites in the VPN. |
| 270 | |
| 271 | .SS logfile |
| 272 | \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR |
| 273 | .PP |
| 274 | Valid keys in the \fIDICT\fR argument are: |
| 275 | .TP |
| 276 | .B filename |
| 277 | The path to log to. |
| 278 | .TP |
| 279 | .B class |
| 280 | A list of strings defining which classes of message to log. |
| 281 | The possible message classes are \fBdebug-config\fR, |
| 282 | \fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR, |
| 283 | \fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR. |
| 284 | .IP |
| 285 | \fBall-debug\fR is the union of all the \fBdebug\fR... classes. |
| 286 | \fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR. |
| 287 | \fBverbose\fR is equivalent to \fBinfo, notice, warning, error, |
| 288 | security, fatal\fR. |
| 289 | \fBquiet\fR is equivalent to \fBfatal\fR. |
| 290 | .PP |
| 291 | A \fIlog closure\fR is a means of saving log messages. |
| 292 | See also \fBsyslog\fR below. |
| 293 | |
| 294 | .SS makelist |
| 295 | \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR |
| 296 | .PP |
| 297 | Returns the (flattened) list of values from the dictionary, discarding |
| 298 | the keys. |
| 299 | |
| 300 | .SS map |
| 301 | \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR |
| 302 | .PP |
| 303 | Applies \fICLOSURE\fR to all its additional input arguments and |
| 304 | returns the resulting list. |
| 305 | |
| 306 | .SS md5 |
| 307 | \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm. |
| 308 | |
| 309 | .SS null-netlink |
| 310 | \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 311 | .br |
| 312 | \fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR |
| 313 | .\" TODO pure closure is what it's called internally but this is a |
| 314 | .\" very opaque name to use in docs |
| 315 | .PP |
| 316 | Valid keys in the \fIDICT\fR argument are: |
| 317 | .TP |
| 318 | .B name |
| 319 | String. |
| 320 | The name for the netlink device. |
| 321 | The default is \fBnull-netlink\fR. |
| 322 | .TP |
| 323 | .B networks |
| 324 | List of strings. |
| 325 | The networks on the host side of the netlink device. |
| 326 | .TP |
| 327 | .B remote-networks |
| 328 | List of strings. |
| 329 | Networks that may be claimed by remote sites using this netlink device. |
| 330 | .TP |
| 331 | .B secnet-address |
| 332 | String. |
| 333 | IP address of this netlink. |
| 334 | Incompatible with \fBptp-address\fR. |
| 335 | .TP |
| 336 | .B ptp-address |
| 337 | String. |
| 338 | IP address of the other end of a point-to-point link. |
| 339 | Incompatible with \fBsecnet-address\fR. |
| 340 | .TP |
| 341 | .B mtu |
| 342 | Number. |
| 343 | The MTU of the netlink device. |
| 344 | The default is 1000. |
| 345 | .PP |
| 346 | If \fBptp-address\fR is used then the result is a \fInetlink closure\fR. |
| 347 | This can be used directly with the \fBlink\fR key in the \fBsites\fR |
| 348 | closure (see below). |
| 349 | .PP |
| 350 | If \fBsecnet-address\fR is used then the result is a \fIpure |
| 351 | closure\fR. |
| 352 | This must be evaluated to yield a \fInetlink closure\fR, using a |
| 353 | dictionary argument with the following keys: |
| 354 | .TP |
| 355 | .B routes |
| 356 | String list. |
| 357 | networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format. |
| 358 | .TP |
| 359 | .B options |
| 360 | String list. |
| 361 | A list of options: |
| 362 | .RS |
| 363 | .TP |
| 364 | .B allow-route |
| 365 | Allow packets received via this tunnel to be routed down other tunnels |
| 366 | (without this option only packets from the host will be routed). |
| 367 | .TP |
| 368 | .B soft |
| 369 | Remove these routes from the host routing table when the link quality |
| 370 | is 0. |
| 371 | .RE |
| 372 | .TP |
| 373 | .B mtu |
| 374 | Number. |
| 375 | Default MTU over this link. |
| 376 | The default is inherited from the \fIpure closure\fR. |
| 377 | .TP |
| 378 | .B priority |
| 379 | Number. |
| 380 | The priority of this link. |
| 381 | Higher values beat lower values. |
| 382 | The default is 0. |
| 383 | |
| 384 | .\" TODO ptp-address turns up in sites.conf, but why? I think this |
| 385 | .\" is a bug in make-secnet-sites; it is not used by |
| 386 | \" netlink_inst_create. |
| 387 | |
| 388 | .PP |
| 389 | A \fInetlink closure\fR is a virtual IP link, and is supplied to the |
| 390 | \fBlink\fR key of a \fIsite\fR closure. |
| 391 | .PP |
| 392 | The netlink created by \fBnull-netlink\fR has no connection to the |
| 393 | host. |
| 394 | See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives. |
| 395 | |
| 396 | |
| 397 | |
| 398 | .SS randomfile |
| 399 | \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR |
| 400 | .TP |
| 401 | .I FILENAME |
| 402 | String. |
| 403 | Path to random device, e.g. \fI/dev/urandom\fR. |
| 404 | .TP |
| 405 | .I BLOCKING |
| 406 | Boolean. |
| 407 | \fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default). |
| 408 | Blocking device support is not implemented so this must always be |
| 409 | \fBFalse\fR or absent. |
| 410 | .PP |
| 411 | A \fIrandomsource closure\fR is a source of random numbers. |
| 412 | |
| 413 | .SS readfile |
| 414 | \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR |
| 415 | .PP |
| 416 | Read the contents of the file \fIPATH\fR (a string) and return it as a string. |
| 417 | |
| 418 | .SS eax-serpent |
| 419 | \fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR |
| 420 | .PP |
| 421 | Valid keys in the \fIDICT\fR argument are: |
| 422 | .TP |
| 423 | .B max-sequence-skew |
| 424 | The maximum acceptable difference between the sequence number in a |
| 425 | received, decrypted message and the previous one. |
| 426 | The default is 10. |
| 427 | It may be necessary to increase this is if connectivity is poor. |
| 428 | .TP |
| 429 | .B tag-length-bytes |
| 430 | The length of the message authentication tag. The default is 16, |
| 431 | for a 128-bit tag length. It must be no longer than the Serpent |
| 432 | blocksize, 16. Must be have the same value at both ends. |
| 433 | .TP |
| 434 | .B padding-rounding |
| 435 | Messages are padded to a multiple of this many bytes. This |
| 436 | serves to obscure the exact length of messages. The default is 16, |
| 437 | .TP |
| 438 | .B capab-num |
| 439 | The transform capability number to use when advertising this |
| 440 | transform. Both ends must have the same meaning (or, at least, a |
| 441 | compatible transform) for each transform capability number they have |
| 442 | in common. The default for serpent-eax is 9. |
| 443 | .IP |
| 444 | Transform capability numbers in the range 8..15 are intended for |
| 445 | allocation by the implementation, and may be assigned as the default |
| 446 | for new transforms in the future. Transform capability numbers in the |
| 447 | range 0..7 are reserved for definition by the user. |
| 448 | .PP |
| 449 | A \fItransform closure\fR is a reversible means of transforming |
| 450 | messages for transmission over a (presumably) insecure network. |
| 451 | It is responsible for both confidentiality and integrity. |
| 452 | |
| 453 | .SS serpent256-cbc |
| 454 | \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR |
| 455 | .PP |
| 456 | This transform |
| 457 | is deprecated as its security properties are poor; it should be |
| 458 | specified only alongside a better transform such as eax-serpent. |
| 459 | .PP |
| 460 | Valid keys in the \fIDICT\fR argument are: |
| 461 | .TP |
| 462 | .B capab-num |
| 463 | As above. The default for serpent256-cbc is 8. |
| 464 | .TP |
| 465 | .B max-sequence-skew |
| 466 | As above. |
| 467 | .PP |
| 468 | Note that this uses a big-endian variant of the Serpent block cipher |
| 469 | (which is not compatible with most other Serpent implementations). |
| 470 | .SS rsa-private |
| 471 | \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR |
| 472 | .TP |
| 473 | .I PATH |
| 474 | String. |
| 475 | The path to a file containing an RSA private key in SSH format |
| 476 | (version 1). |
| 477 | There must be no passphrase. |
| 478 | .TP |
| 479 | .I CHECK |
| 480 | Boolean. |
| 481 | If \fBtrue\fR (the default) then check that the key is valid. |
| 482 | |
| 483 | .SS rsa-public |
| 484 | \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR |
| 485 | .TP |
| 486 | .I KEY |
| 487 | String. |
| 488 | The public key exponent (\fIe\fR), in decimal. |
| 489 | .TP |
| 490 | .I MODULUS |
| 491 | String. |
| 492 | The modulus (\fIn\fR), in decimal. |
| 493 | |
| 494 | .SS sha1 |
| 495 | \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm. |
| 496 | |
| 497 | .SS site |
| 498 | \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR |
| 499 | .PP |
| 500 | Valid keys in the \fIDICT\fR argument are: |
| 501 | .TP |
| 502 | .B local-name |
| 503 | String. |
| 504 | The site's name for itself. |
| 505 | .TP |
| 506 | .B name |
| 507 | String. |
| 508 | The name of the site's peer. |
| 509 | .TP |
| 510 | .B link |
| 511 | A \fInetlink closure\fR. |
| 512 | .TP |
| 513 | .B comm |
| 514 | A \fIcomm closure\fR. |
| 515 | .TP |
| 516 | .B resolver |
| 517 | A \fIresolver closure\fR. |
| 518 | .TP |
| 519 | .B random |
| 520 | A \fIrandomsource closure\fR. |
| 521 | .TP |
| 522 | .B local-key |
| 523 | An \fIrsaprivkey closure\fR. |
| 524 | The key used to prove our identity to the peer. |
| 525 | .TP |
| 526 | .B address |
| 527 | String. |
| 528 | The DNS name of the peer. |
| 529 | Optional, but if it is missing then it will not be possible to |
| 530 | initiate new connections to the peer. |
| 531 | .TP |
| 532 | .B port |
| 533 | Number. |
| 534 | The port to contact the peer. |
| 535 | .TP |
| 536 | .B key |
| 537 | An \fIrsapubkey closure\fR. |
| 538 | The key used to verify the peer's identity. |
| 539 | .TP |
| 540 | .B transform |
| 541 | One or more \fItransform closures\fR. |
| 542 | Used to protect packets exchanged with the peer. These should |
| 543 | all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR |
| 544 | value should refer to the same (or a compatible) transform at both |
| 545 | ends. The list should be in order of preference, most preferred |
| 546 | first. (The end which sends MSG1,MSG3 ends up choosing; the ordering |
| 547 | at the other end is irrelevant.) |
| 548 | .TP |
| 549 | .B dh |
| 550 | A \fIdh closure\fR. |
| 551 | The group to use in key exchange. |
| 552 | .TP |
| 553 | .B hash |
| 554 | The hash function used during setup. |
| 555 | .\" TODO clarify what we actually use it for! |
| 556 | .TP |
| 557 | .B key-lifetime |
| 558 | Number. |
| 559 | The maximum lifetime of a session key in milliseconds. |
| 560 | The default is one hour. |
| 561 | .TP |
| 562 | .B setup-retries |
| 563 | Number. |
| 564 | The maximum number of times a key negotiation packet will be |
| 565 | transmitted before giving up. |
| 566 | The default is 5. |
| 567 | .TP |
| 568 | .B setup-timeout |
| 569 | Number. |
| 570 | The time between retransmissions of key negotiation packets, in milliseconds. |
| 571 | The default is one second. |
| 572 | .TP |
| 573 | .B wait-time |
| 574 | Number. |
| 575 | The time to wait after a failed key setup before making another |
| 576 | attempt, in milliseconds. |
| 577 | The default is 20s. |
| 578 | .TP |
| 579 | .B renegotiate-time |
| 580 | Number. |
| 581 | The time after which a new session key will be negotiated, \fIif\fR |
| 582 | there is traffic on the link, in milliseconds. |
| 583 | It must not be greater than the \fBkey-lifetime\fR. |
| 584 | The default 5 minutes less than the key lifetime, unless the lifetime |
| 585 | is less than 10 minutes in which case the default is half the |
| 586 | lifetime. |
| 587 | .TP |
| 588 | .B keepalive |
| 589 | Boolean. |
| 590 | If \fBtrue\fR then attempt to always maintain a live session key. |
| 591 | Not implemented. |
| 592 | .TP |
| 593 | .B log-events |
| 594 | String list. |
| 595 | Types of event to log for this site. |
| 596 | .RS |
| 597 | .TP |
| 598 | .B unexpected |
| 599 | Unexpected key setup packets (including late retransmissions). |
| 600 | .TP |
| 601 | .B setup-init |
| 602 | Start of attempt to setup a session key. |
| 603 | .TP |
| 604 | .B setup-timeout |
| 605 | Failure of attempt to setup a session key, through timeout. |
| 606 | .TP |
| 607 | .B activate-key |
| 608 | Activation of a new session key. |
| 609 | .TP |
| 610 | .B timeout-key |
| 611 | Deletion of current session key through age. |
| 612 | .TP |
| 613 | .B security |
| 614 | Anything potentially suspicious. |
| 615 | .TP |
| 616 | .B state-change |
| 617 | Steps in the key setup protocol. |
| 618 | .TP |
| 619 | .B packet-drop |
| 620 | Whenever we throw away an outgoing packet. |
| 621 | .TP |
| 622 | .B dump-packets |
| 623 | Every key setup packet we see. |
| 624 | .TP |
| 625 | .B errors |
| 626 | Failure of name resolution, internal errors. |
| 627 | .TP |
| 628 | .B all |
| 629 | Everything (too much!) |
| 630 | .RE |
| 631 | .PP |
| 632 | A \fIsite closure\fR defines one site to communicate with. |
| 633 | \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site |
| 634 | closures. |
| 635 | |
| 636 | .SS sysbuffer |
| 637 | \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR |
| 638 | .TP |
| 639 | .I SIZE |
| 640 | Number. |
| 641 | The size of the buffer in bytes. |
| 642 | This must be between 64 and 131072. |
| 643 | The default is 4096. |
| 644 | .TP |
| 645 | .I OPTIONS |
| 646 | Dictionary. |
| 647 | Optional and presently unused. |
| 648 | .\" lockdown is accepted but ignored. |
| 649 | .PP |
| 650 | A \fIbuffer closure\fR is a means of buffering packets to send or that |
| 651 | have been received. |
| 652 | |
| 653 | .SS syslog |
| 654 | \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR |
| 655 | .PP |
| 656 | Valid keys in the \fIDICT\fR argument are: |
| 657 | .TP |
| 658 | .B ident |
| 659 | String. |
| 660 | The ident string to pass to \fBopenlog\fR(3); this value will appear |
| 661 | in each message. |
| 662 | .TP |
| 663 | .B facility |
| 664 | String. |
| 665 | The facility to log as. |
| 666 | The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR, |
| 667 | \fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR, |
| 668 | \fBsyslog\fR, \fBuser\fR and \fBuucp\fR. |
| 669 | .PP |
| 670 | See also \fBlogfile\fR above. |
| 671 | |
| 672 | .SS tun |
| 673 | \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 674 | .br |
| 675 | \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR |
| 676 | .PP |
| 677 | Valid keys in the \fIDICT\fR argument are those documented for |
| 678 | \fBnull-netlink\fR above, plus: |
| 679 | .TP |
| 680 | .B flavour |
| 681 | String. |
| 682 | The type of TUN interface to use. |
| 683 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR. |
| 684 | The default is \fBguess\fR. |
| 685 | .TP |
| 686 | .B device |
| 687 | String. |
| 688 | The path to the TUN/TAP device file. |
| 689 | The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and |
| 690 | \fI/dev/tun\fR for the others. |
| 691 | .TP |
| 692 | .B interface |
| 693 | String. |
| 694 | The interface to use. |
| 695 | The default is to pick one automatically. |
| 696 | This cannot be used with the \fBstreams\fR flavour. |
| 697 | .TP |
| 698 | .B local-address |
| 699 | String. |
| 700 | IP address of the host's tunnel interface. |
| 701 | .\" README says this belongs to netlink-null but actually it's |
| 702 | \" duplicated between slip & tun |
| 703 | .TP |
| 704 | .B ifconfig-path |
| 705 | String. |
| 706 | The name of the \fBifconfig\fR command. |
| 707 | The default is simply "ifconfig". |
| 708 | .TP |
| 709 | .B route-path |
| 710 | String. |
| 711 | The name of the \fBroute\fR command. |
| 712 | The default is simply "route". |
| 713 | .TP |
| 714 | .B ifconfig-type |
| 715 | String. |
| 716 | The syntax expected by the \fBifconfig\fR command. |
| 717 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR, |
| 718 | \fBsolaris-2.5\fR and \fBguess\fR. |
| 719 | The default is \fBguess\fR. |
| 720 | .TP |
| 721 | .B route-type |
| 722 | String. |
| 723 | The syntax expected by the \fBifconfig\fR command. |
| 724 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR, |
| 725 | \fBsolaris-2.5\fR and \fBguess\fR. |
| 726 | The default is \fBguess\fR. |
| 727 | .TP |
| 728 | .B buffer |
| 729 | A \fIbuffer closure\fR to use for packets transferred from the host to secnet. |
| 730 | The buffer size must be at least 60 greater than the MTU. |
| 731 | .\" TODO rumour has is that buffers are sometimes shareable between |
| 732 | .\" netlink devices - document that if the conditions are reasonable |
| 733 | .\" ones. |
| 734 | .PP |
| 735 | The \fBifconfig-type\fR and \fBroute-type\fR values determine how |
| 736 | those commands are executed. |
| 737 | If they are set to \fBioctl\fR then low-level system calls are used |
| 738 | directly instead of invoking the commands. |
| 739 | .PP |
| 740 | The netlink created by \fBtun\fR uses the \fBtun\fR device to |
| 741 | communicate with the host kernel. |
| 742 | |
| 743 | .SS udp |
| 744 | \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR |
| 745 | .PP |
| 746 | Valid keys in the \fIDICT\fR argument are: |
| 747 | .TP |
| 748 | .B address |
| 749 | String. |
| 750 | The IP address to bind on. |
| 751 | The default is 0.0.0.0, i.e. "any". |
| 752 | .TP |
| 753 | .B port |
| 754 | Number. |
| 755 | The port number to bind to. |
| 756 | The default is 0, i.e. the OS will choose one. |
| 757 | It is suggested that any given VPN agree a common port number. |
| 758 | .TP |
| 759 | .B buffer |
| 760 | A \fIbuffer closure\fR. |
| 761 | See the \fBsysbuffer\fR closure above. |
| 762 | .TP |
| 763 | .B authbind |
| 764 | String. |
| 765 | The path to a helper program to bind the socket. |
| 766 | Optional. |
| 767 | .IP |
| 768 | The program will be invoked with the address and port number as its |
| 769 | arguments, and with the socket to bind as file descriptor 0. |
| 770 | It should either bind the socket as requested, or exit with nonzero |
| 771 | status. |
| 772 | .PP |
| 773 | A \fIcomm closure\fR is a means of sending and receiving messages via |
| 774 | a network. |
| 775 | It does not provide confidentiality, reliablity or availability. |
| 776 | |
| 777 | .SS userv-ipif |
| 778 | \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 779 | .br |
| 780 | \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR |
| 781 | .PP |
| 782 | Valid keys in the \fIDICT\fR argument are those documented for |
| 783 | \fBnull-netlink\fR above, plus: |
| 784 | .TP |
| 785 | .B local-address |
| 786 | String. |
| 787 | IP address of the host's SLIP interface. |
| 788 | .\" README says this belongs to netlink-null but actually it's |
| 789 | \" duplicated between SLIP & tun |
| 790 | .TP |
| 791 | .B userv-path |
| 792 | String. |
| 793 | Where to find \fBuserv\fR(1). |
| 794 | The default is \fB"userv"\fR. |
| 795 | .TP |
| 796 | .B service-user |
| 797 | String. |
| 798 | The name of the user that owns the service. |
| 799 | The default is \fB"root"\fR. |
| 800 | .TP |
| 801 | .B service-name |
| 802 | String. |
| 803 | The name of the service to request. |
| 804 | The default is \fB"ipif"\fR. |
| 805 | .TP |
| 806 | .B buffer |
| 807 | A \fIbuffer closure\fR to use for packets transferred from the host to secnet. |
| 808 | .PP |
| 809 | The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output. |
| 810 | It uses SLIP to communicate with the host kernel via these pipes. |
| 811 | |
| 812 | .SH FILES |
| 813 | .TP |
| 814 | .I /etc/secnet/secnet.conf |
| 815 | Configuration file. |
| 816 | |
| 817 | .SH "SEE ALSO" |
| 818 | \fBuserv\fR(1) |