README

   1 secnet - flexible VPN software
   2
   3 * Copying
   4
   5 secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk>
   6 It is distributed under the terms of the GNU General Public License,
   7 version 2 or later.  See the file COPYING for more information.
   8
   9 The portable snprintf implementation in snprintf.c is Copyright (C)
  10 1999 Mark Martinec <mark.martinec@ijs.si> and is distributed under the
  11 terms of the Frontier Artistic License.  You can find the standard
  12 version of snprintf.c at http://www.ijs.si/software/snprintf/
  13
  14 The IP address handling library in ipaddr.py is Copyright (C)
  15 1996--2000 Cendio Systems AB, and is distributed under the terms of
  16 the GPL.
  17
  18 * Introduction
  19
  20 secnet allows large virtual private networks to be constructed
  21 spanning multiple separate sites.  It is designed for the case where a
  22 private network connecting many hosts is 'hidden' behind a single
  23 globally-routable IP address, but can also be applied in other
  24 circumstances.  It communicates entirely using UDP, and works well
  25 with gateways that implement network address translation.
  26
  27 If you are installing secnet to join an existing VPN, you should read
  28 the 'INSTALL' file and your particular VPN's documentation now.  You
  29 may need to refer back to this file for information on the netlink and
  30 comm sections of the configuration file.
  31
  32 If you are thinking about setting up a new VPN of any size (from one
  33 providing complete links between multiple sites to a simple
  34 laptop-to-host link), read the section in this file on 'Creating a
  35 VPN'.
  36
  37 * Mailing lists and bug reporting
  38
  39 There are two mailing lists associated with secnet: an 'announce' list
  40 and a 'discuss' list.  Their addresses are:
  41 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce
  42 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss
  43
  44 The -announce list receives one message per secnet release.  The
  45 -discuss list is for general discussion, including help with
  46 configuration, bug reports, feature requests, etc.
  47
  48 Bug reports should be sent to <steve@greenend.org.uk>; they will be
  49 forwarded to the -discuss list by me.
  50
  51 * Creating a VPN
  52
  53 XXX TODO
  54
  55 * secnet configuration file format
  56
  57 By default secnet on linux reads /etc/secnet/secnet.conf.  The default
  58 may be different on other platforms.
  59
  60 This file defines a dictionary (a mapping from keys to values) full of
  61 configuration information for secnet.  Two keys must be defined in
  62 this file for secnet to start.  One is "system", a dictionary
  63 containing systemwide control parameters.  The other is "sites", a
  64 list of all the sites that you intend to communicate with.
  65
  66 The configuration file has a very simple syntax; keys are defined as
  67 follows:
  68
  69 key definition;
  70 or
  71 key = definition;
  72
  73 (the "=" is optional)
  74
  75 Keys must match the following regular expression:
  76 [[:alpha:]_][[:alnum:]\-_]*
  77
  78 i.e. the first character must be an alpha or an underscore, and the
  79 remaining characters may be alphanumeric, '-' or '_'.
  80
  81 Keys can be defined to be a comma-separated list of any of the
  82 following types:
  83
  84   a boolean
  85   a string, in quotes
  86   a number, in decimal
  87   a dictionary of definitions, enclosed in { }
  88   a "closure", followed by arguments
  89   a path to a key that already exists, to reference that definition
  90
  91 Note that dictionaries can be nested: a key in one dictionary can
  92 refer to another dictionary. When secnet looks for a key in a
  93 particular directory and can't find it, it looks in the dictionary's
  94 lexical 'parents' in turn until it finds it (or fails to find it at
  95 all and stops with an error).
  96
  97 Definitions can refer to previous definitions by naming them with a
  98 path.  Paths are key1/key2/key3... (starting from wherever we find
  99 key1, i.e. in the current dictionary or any of its parents), or
 100 alternatively /key1/key2/key3... (to start from the root).
 101 Definitions cannot refer to future definitions.
 102
 103 Example:
 104
 105 a=1;
 106 b=2;
 107 c={ d=3; e=a; };
 108 f={ a=4; g=c; };
 109
 110 The following paths are valid:
 111 a is 1
 112 b is 2
 113 c is a dictionary:
 114  c/d is 3
 115  c/e is 1
 116 f is a dictionary:
 117  f/a is 4
 118  f/g is a dictionary:
 119   f/g/d is 3
 120   f/g/e is 1
 121
 122 Note that f/g/e is NOT 4.
 123
 124 Elements that are lists are inserted into lists in definitions, not
 125 referenced by them (i.e. you can't have lists of lists).
 126
 127 Some closures may be followed by an argument list in ( ), and may
 128 return any number of whatever type they like (including other
 129 closures).  Some types of closure (typically those returned from
 130 invokations of other closures) cannot be invoked.
 131
 132 closure { definitions } is short for closure({definitions}).
 133
 134 The main body of secnet, and all the additional modules, predefine
 135 some keys in the root dictionary.  The main ones are:
 136
 137   yes, true, True, TRUE, on:   the boolean value True
 138   no, false, False, FALSE, off: the boolean value False
 139   makelist:   turns a dictionary (arg1) into a list of definitions
 140               (ignoring the keys)
 141   readfile:   reads a file (arg1) and returns it as a string
 142   map:        applies the closure specified as arg1 to each of the
 143               remaining elements in the list in turn.  Returns a list
 144               made up of the outputs of the closure.
 145
 146 Keys defined by modules are described below, in the module
 147 documentation.
 148
 149 Other configuration files can be included inline by writing "include
 150 filename" at the start of a line.
 151
 152 After the configuration file is read, secnet looks for particular keys
 153 in configuration space to tell it what to do:
 154
 155  system: a dictionary which can contain the following keys:
 156    log (log closure): a destination for system messages
 157    userid (string): the userid for secnet to run as once it drops privileges
 158    pidfile (string): where to store its PID
 159
 160  sites: a list of closures of type 'site', which define other tunnel
 161         endpoints that secnet will attempt to communicate with
 162
 163 * secnet command line options
 164
 165 Usage: secnet [OPTION]...
 166
 167   -f, --silent, --quiet   suppress error messages
 168   -w, --nowarnings        suppress warnings
 169   -v, --verbose           output extra diagnostics
 170   -c, --config=filename   specify a configuration file
 171   -j, --just-check-config stop after reading configfile
 172   -n, --nodetach          do not run in background
 173   -d, --debug=item,...    set debug options
 174       --help              display this help and exit
 175       --version           output version information and exit
 176
 177 * secnet builtin modules
 178
 179 ** resolver
 180
 181 Defines:
 182   adns (closure => resolver closure)
 183
 184 adns: dict argument
 185   config (string): optional, a resolv.conf for ADNS to use
 186
 187 ** random
 188
 189 Defines:
 190   randomsrc (closure => randomsrc closure)
 191
 192 randomsrc: string[,bool]
 193   arg1: filename of random source
 194   arg2: if True then source is blocking
 195
 196 ** udp
 197
 198 Defines:
 199   udp (closure => comm closure)
 200
 201 udp: dict argument
 202   address (string): IP address to listen and send on
 203   port (integer): UDP port to listen and send on
 204   buffer (buffer closure): buffer for incoming packets
 205   authbind (string): optional, path to authbind-helper program
 206
 207 ** log
 208
 209 Defines:
 210   logfile (closure => log closure)
 211   syslog (closure => log closure)
 212
 213 logfile: dict argument
 214   filename (string): where to log to
 215   class (string list): what type of messages to log
 216     { "debug-config", M_DEBUG_CONFIG },
 217     { "debug-phase", M_DEBUG_PHASE },
 218     { "debug", M_DEBUG },
 219     { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
 220     { "info", M_INFO },
 221     { "notice", M_NOTICE },
 222     { "warning", M_WARNING },
 223     { "error", M_ERROR },
 224     { "security", M_SECURITY },
 225     { "fatal", M_FATAL },
 226     { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
 227     { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
 228     { "quiet", M_FATAL }
 229
 230 logfile will close and reopen its file upon receipt of SIGHUP.
 231
 232 syslog: dict argument
 233   ident (string): include this string in every log message
 234   facility (string): facility to log as
 235     { "authpriv", LOG_AUTHPRIV },
 236     { "cron", LOG_CRON },
 237     { "daemon", LOG_DAEMON },
 238     { "kern", LOG_KERN },
 239     { "local0", LOG_LOCAL0 },
 240     { "local1", LOG_LOCAL1 },
 241     { "local2", LOG_LOCAL2 },
 242     { "local3", LOG_LOCAL3 },
 243     { "local4", LOG_LOCAL4 },
 244     { "local5", LOG_LOCAL5 },
 245     { "local6", LOG_LOCAL6 },
 246     { "local7", LOG_LOCAL7 },
 247     { "lpr", LOG_LPR },
 248     { "mail", LOG_MAIL },
 249     { "news", LOG_NEWS },
 250     { "syslog", LOG_SYSLOG },
 251     { "user", LOG_USER },
 252     { "uucp", LOG_UUCP }
 253
 254 ** util
 255
 256 Defines:
 257   sysbuffer (closure => buffer closure)
 258
 259 sysbuffer: integer[,dict]
 260   arg1: buffer length
 261   arg2: options:
 262     lockdown (boolean): if True, mlock() the buffer
 263
 264 ** site
 265
 266 Defines:
 267   site (closure => site closure)
 268
 269 site: dict argument
 270   local-name (string): this site's name for itself
 271   name (string): the name of the site's peer
 272   link (netlink closure)
 273   comm (comm closure)
 274   resolver (resolver closure)
 275   random (randomsrc closure)
 276   local-key (rsaprivkey closure)
 277   address (string): optional, DNS name used to find our peer
 278   port (integer): mandatory if 'address' is specified: the port used
 279     to contact our peer
 280   key (rsapubkey closure): our peer's public key
 281   transform (transform closure): how to mangle packets sent between sites
 282   dh (dh closure)
 283   hash (hash closure)
 284   key-lifetime (integer): max lifetime of a session key, in ms [one hour]
 285   setup-retries (integer): max number of times to transmit a key negotiation
 286     packet [5]
 287   setup-timeout (integer): time between retransmissions of key negotiation
 288     packets, in ms [2000]
 289   wait-time (integer): after failed key setup, wait this long (in ms) before
 290     allowing another attempt [20000]
 291   renegotiate-time (integer): if we see traffic on the link after this time
 292     then renegotiate another session key immediately (in ms)
 293     [half key-lifetime, or key-lifetime minus 5 mins, whichever is longer].
 294   keepalive (bool): if True then attempt always to keep a valid session key.
 295     Not actually currently implemented. [false]
 296   log-events (string list): types of events to log for this site
 297     unexpected: unexpected key setup packets (may be late retransmissions)
 298     setup-init: start of attempt to setup a session key
 299     setup-timeout: failure of attempt to setup a session key, through timeout
 300     activate-key: activation of a new session key
 301     timeout-key: deletion of current session key through age
 302     security: anything potentially suspicious
 303     state-change: steps in the key setup protocol
 304     packet-drop: whenever we throw away an outgoing packet
 305     dump-packets: every key setup packet we see
 306     errors: failure of name resolution, internal errors
 307     all: everything (too much!)
 308
 309 ** transform
 310
 311 Defines:
 312   serpent256-cbc (closure => transform closure)
 313
 314 ** netlink
 315
 316 Defines:
 317   null-netlink (closure => closure or netlink closure)
 318
 319 null-netlink: dict argument
 320   name (string): name for netlink device, used in log messages
 321   networks (string list): networks on the host side of the netlink device
 322   remote-networks (string list): networks that may be claimed
 323     by the remote site using this netlink device
 324   local-address (string): IP address of host's tunnel interface
 325   secnet-address (string): IP address of this netlink device
 326   ptp-address (string): IP address of the other end of a point-to-point link
 327   mtu (integer): MTU of host's tunnel interface
 328
 329 Only one of secnet-address or ptp-address may be specified.  If
 330 point-to-point mode is in use then the "routes" option must also be
 331 specified, and netlink returns a netlink closure that should be used
 332 directly with the "link" option to the site closure.  If
 333 point-to-point mode is not in use then netlink returns a closure that
 334 may be invoked using a dict argument with the following keys to yield
 335 a netlink closure:
 336   routes (string list): networks reachable down the tunnel attached to
 337     this instance of netlink
 338   options (string list):
 339     allow-route: allow packets coming from this tunnel to be routed to
 340       other tunnels as well as the host (used for mobile devices like laptops)
 341     soft: remove these routes from the host's routing table when
 342       the tunnel link quality is zero
 343   mtu (integer): default MTU over this link; may be updated by tunnel code
 344
 345 Netlink will dump its current routing table to the system/log on
 346 receipt of SIGUSR1.
 347
 348 ** slip
 349
 350 Defines:
 351   userv-ipif (closure => netlink closure)
 352
 353 userv-ipif: dict argument
 354   userv-path (string): optional, where to find userv ["userv"]
 355   service-user (string): optional, username for userv-ipif service ["root"]
 356   service-name (string): optional, name of userv-ipif service ["ipif"]
 357   buffer (buffer closure): buffer for assembly of host->secnet packets
 358  plus generic netlink options, as for 'null-netlink'
 359
 360 ** tun
 361
 362 Defines:
 363   tun (closure => netlink closure) [only on linux-2.4]
 364   tun-old (closure => netlink closure)
 365
 366 tun: dict argument
 367   flavour (string): optional, type of TUN interface to use
 368     ("guess","linux","bsd","streams")
 369   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
 370   interface (string): optional, name of tunnel network interface
 371   ifconfig-path (string): optional, path to ifconfig command
 372   route-path (string): optional, path to route command
 373   ifconfig-type (string): optional, how to perform ifconfig
 374   route-type (string): optional, how to add and remove routes
 375    types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
 376   buffer (buffer closure): buffer for host->secnet packets
 377  plus generic netlink options, as for 'null-netlink'
 378
 379 I recommend you don't specify the 'interface' option unless you're
 380 doing something that requires the interface name to be constant.
 381
 382 ** rsa
 383
 384 Defines:
 385   rsa-private (closure => rsaprivkey closure)
 386   rsa-public (closure => rsapubkey closure)
 387
 388 rsa-private: string[,bool]
 389   arg1: filename of SSH private key file (version 1, no password)
 390   arg2: whether to check that the key is usable [default True]
 391
 392 rsa-public: string,string
 393   arg1: encryption key (decimal)
 394   arg2: modulus (decimal)
 395
 396 ** dh
 397
 398 Defines:
 399   diffie-hellman (closure => dh closure)
 400
 401 diffie-hellman: string,string[,bool]
 402   arg1: modulus (hex)
 403   arg2: generator (hex)
 404   arg3: whether to check that the modulus is prime [default True]
 405
 406 ** md5
 407
 408 Defines:
 409   md5 (hash closure)
 410
 411 ** sha1
 412
 413 Defines:
 414   sha1 (hash closure)
 415
 416 ** conffile
 417
 418 Defines:
 419   makelist (dictionary => list of definitions)
 420   readfile (string => string)
 421   map (closure,list => list)
 422
 423 makelist: dictionary
 424   returns a list consisting of the definitions in the dictionary. The keys
 425   are discarded.
 426
 427 readfile: string
 428   reads the named file and returns its contents as a string
 429
 430 map:
 431   applies the closure specified as arg1 to each of the elements in the list.
 432   Returns a list made up of the outputs of the closure.