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