README

   1 secnet - flexible VPN software
   2
   3 * Copying
   4
   5 secnet is Copyright (C) 1995--2001 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 * Creating a VPN
  38
  39 XXX TODO
  40
  41 * secnet configuration file format
  42
  43 By default secnet on linux reads /etc/secnet/secnet.conf.  The default
  44 may be different on other platforms.
  45
  46 This file defines a dictionary (a mapping from keys to values) full of
  47 configuration information for secnet.  Two keys must be defined in
  48 this file for secnet to start.  One is "system", a dictionary
  49 containing systemwide control parameters.  The other is "sites", a
  50 list of all the sites that you intend to communicate with.
  51
  52 The configuration file has a very simple syntax; keys are defined as
  53 follows:
  54
  55 key definition;
  56 or
  57 key = definition;
  58
  59 (the "=" is optional)
  60
  61 Keys must match the following regular expression:
  62 [[:alpha:]_][[:alnum:]\-_]*
  63
  64 i.e. the first character must be an alpha or an underscore, and the
  65 remaining characters may be alphanumeric, '-' or '_'.
  66
  67 Keys can be defined to be a comma-separated list of any of the
  68 following types:
  69
  70   a boolean
  71   a string, in quotes
  72   a number, in decimal
  73   a dictionary of definitions, enclosed in { }
  74   a "closure", followed by arguments
  75   a path to a key that already exists, to reference that definition
  76
  77 Note that dictionaries can be nested: a key in one dictionary can
  78 refer to another dictionary. When secnet looks for a key in a
  79 particular directory and can't find it, it looks in the dictionary's
  80 lexical 'parents' in turn until it finds it (or fails to find it at
  81 all and stops with an error).
  82
  83 Definitions can refer to previous definitions by naming them with a
  84 path.  Paths are key1/key2/key3... (starting from wherever we find
  85 key1, i.e. in the current dictionary or any of its parents), or
  86 alternatively /key1/key2/key3... (to start from the root).
  87 Definitions cannot refer to future definitions.
  88
  89 Example:
  90
  91 a=1;
  92 b=2;
  93 c={ d=3; e=a; };
  94 f={ a=4; g=c; };
  95
  96 The following paths are valid:
  97 a is 1
  98 b is 2
  99 c is a dictionary:
 100  c/d is 3
 101  c/e is 1
 102 f is a dictionary:
 103  f/a is 4
 104  f/g is a dictionary:
 105   f/g/d is 3
 106   f/g/e is 1
 107
 108 Note that f/g/e is NOT 4.
 109
 110 In a future version of secnet it will also be permissible to list
 111 other dictionaries before a dictionary definition,
 112 eg. <defaults,otherdefaults>{definitions}.  These will be searched in
 113 order for keys, before the lexical parent.  (This is not yet
 114 implemented)
 115
 116 Elements that are lists are inserted into lists in definitions, not
 117 referenced by them (i.e. you can't have lists of lists).
 118
 119 Some closures may be followed by an argument list in ( ), and may
 120 return any number of whatever type they like (including other
 121 closures).  Some types of closure (typically those returned from
 122 invokations of other closures) cannot be invoked.
 123
 124 closure { definitions } is short for closure({definitions}).
 125
 126 The main body of secnet, and all the additional modules, predefine
 127 some keys in the root dictionary.  The main ones are:
 128
 129   yes, true, True, TRUE:   the boolean value True
 130   no, false, False, FALSE: the boolean value False
 131   makelist:   turns a dictionary (arg1) into a list of definitions
 132               (ignoring the keys)
 133   readfile:   reads a file (arg1) and returns it as a string
 134
 135 Keys defined by modules are described below, in the module
 136 documentation.
 137
 138 Other configuration files can be included inline by writing "include
 139 filename" at the start of a line.
 140
 141 After the configuration file is read, secnet looks for particular keys
 142 in configuration space to tell it what to do:
 143
 144  system: a dictionary which can contain the following keys:
 145    log (log closure): a destination for system messages
 146    userid (string): the userid for secnet to run as once it drops privileges
 147    pidfile (string): where to store its PID
 148
 149  sites: a list of closures of type 'site', which define other tunnel
 150         endpoints that secnet will attempt to communicate with
 151
 152 * secnet command line options
 153
 154 XXX TODO
 155
 156 * secnet builtin modules
 157
 158 ** resolver
 159
 160 Defines:
 161   adns (closure => resolver closure)
 162
 163 adns: dict argument
 164   config (string): optional, a resolv.conf for ADNS to use
 165
 166 ** random
 167
 168 Defines:
 169   randomsrc (closure => randomsrc closure)
 170
 171 randomsrc: string[,bool]
 172   arg1: filename of random source
 173   arg2: if True then source is blocking
 174
 175 ** udp
 176
 177 Defines:
 178   udp (closure => comm closure)
 179
 180 udp: dict argument
 181   port (integer): UDP port to listen and send on
 182   buffer (buffer closure): buffer for incoming packets
 183   authbind (string): optional, path to authbind-helper program
 184
 185 ** log
 186
 187 Defines:
 188   logfile (closure => log closure)
 189   syslog (closure => log closure)
 190
 191 logfile: dict argument
 192   filename (string): where to log to
 193   class (string list): what type of messages to log
 194     { "debug-config", M_DEBUG_CONFIG },
 195     { "debug-phase", M_DEBUG_PHASE },
 196     { "debug", M_DEBUG },
 197     { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
 198     { "info", M_INFO },
 199     { "notice", M_NOTICE },
 200     { "warning", M_WARNING },
 201     { "error", M_ERROR },
 202     { "security", M_SECURITY },
 203     { "fatal", M_FATAL },
 204     { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
 205     { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
 206     { "quiet", M_FATAL }
 207
 208 logfile will close and reopen its file upon receipt of SIGHUP.
 209
 210 syslog: dict argument
 211   ident (string): include this string in every log message
 212   facility (string): facility to log as
 213     { "authpriv", LOG_AUTHPRIV },
 214     { "cron", LOG_CRON },
 215     { "daemon", LOG_DAEMON },
 216     { "kern", LOG_KERN },
 217     { "local0", LOG_LOCAL0 },
 218     { "local1", LOG_LOCAL1 },
 219     { "local2", LOG_LOCAL2 },
 220     { "local3", LOG_LOCAL3 },
 221     { "local4", LOG_LOCAL4 },
 222     { "local5", LOG_LOCAL5 },
 223     { "local6", LOG_LOCAL6 },
 224     { "local7", LOG_LOCAL7 },
 225     { "lpr", LOG_LPR },
 226     { "mail", LOG_MAIL },
 227     { "news", LOG_NEWS },
 228     { "syslog", LOG_SYSLOG },
 229     { "user", LOG_USER },
 230     { "uucp", LOG_UUCP }
 231
 232 ** util
 233
 234 Defines:
 235   sysbuffer (closure => buffer closure)
 236
 237 sysbuffer: integer[,dict]
 238   arg1: buffer length
 239   arg2: options:
 240     lockdown (boolean): if True, mlock() the buffer
 241
 242 ** site
 243
 244 Defines:
 245   site (closure => site closure)
 246
 247 site: dict argument
 248   local-name (string): this site's name for itself
 249   name (string): the name of the site's peer
 250   netlink (netlink closure)
 251   comm (comm closure)
 252   resolver (resolver closure)
 253   random (randomsrc closure)
 254   local-key (rsaprivkey closure)
 255   address (string): optional, DNS name used to find our peer
 256   port (integer): mandatory if 'address' is specified: the port used
 257     to contact our peer
 258   networks (string list): networks that our peer may claim traffic for
 259   key (rsapubkey closure): our peer's public key
 260   transform (transform closure): how to mangle packets sent between sites
 261   dh (dh closure)
 262   hash (hash closure)
 263   key-lifetime (integer): max lifetime of a session key, in ms [one hour]
 264   setup-retries (integer): max number of times to transmit a key negotiation
 265     packet [5]
 266   setup-timeout (integer): time between retransmissions of key negotiation
 267     packets, in ms [1000]
 268   wait-time (integer): after failed key setup, wait this long (in ms) before
 269     allowing another attempt [20000]
 270   renegotiate-time (integer): if we see traffic on the link after this time
 271     then renegotiate another session key immediately [depends on key-lifetime]
 272   keepalive (bool): if True then attempt always to keep a valid session key
 273   log-events (string list): types of events to log for this site
 274     unexpected: unexpected key setup packets (may be late retransmissions)
 275     setup-init: start of attempt to setup a session key
 276     setup-timeout: failure of attempt to setup a session key, through timeout
 277     activate-key: activation of a new session key
 278     timeout-key: deletion of current session key through age
 279     security: anything potentially suspicious
 280     state-change: steps in the key setup protocol
 281     packet-drop: whenever we throw away an outgoing packet
 282     dump-packets: every key setup packet we see
 283     errors: failure of name resolution, internal errors
 284     all: everything (too much!)
 285   netlink-options (string list): options to pass to netlink device when
 286     registering remote networks
 287     soft: create 'soft' routes that go away when there's no key established
 288       with the peer
 289     allow-route: allow packets from our peer to be sent down other tunnels,
 290       as well as to the host
 291
 292 ** transform
 293
 294 Defines:
 295   serpent256-cbc (closure => transform closure)
 296
 297 ** netlink
 298
 299 Defines:
 300   null-netlink (closure => netlink closure)
 301
 302 null-netlink: dict argument
 303   name (string): name for netlink device, used in log messages
 304   networks (string list): networks on the host side of the netlink device
 305   exclude-remote-networks (string list): networks that may never be claimed
 306     by any remote site using this netlink device
 307   local-address (string): IP address of host's tunnel interface
 308   secnet-address (string): IP address of this netlink device
 309   ptp-address (string): IP address of the other end of a point-to-point link
 310   mtu (integer): MTU of host's tunnel interface
 311
 312 Only one of secnet-address or ptp-address may be specified. If
 313 point-to-point mode is in use then precisely one tunnel must register
 314 with the netlink device.
 315
 316 Netlink will dump its current routing table to the system/log on
 317 receipt of SIGUSR1.
 318
 319 ** slip
 320
 321 Defines:
 322   userv-ipif (closure => netlink closure)
 323
 324 userv-ipif: dict argument
 325   userv-path (string): optional, where to find userv ["userv"]
 326   service-user (string): optional, username for userv-ipif service ["root"]
 327   service-name (string): optional, name of userv-ipif service ["ipif"]
 328   buffer (buffer closure): buffer for assembly of host->secnet packets
 329  plus generic netlink options, as for 'null-netlink'
 330
 331 ** tun
 332
 333 Defines:
 334   tun (closure => netlink closure) [only on linux-2.4]
 335   tun-old (closure => netlink closure)
 336
 337 tun: dict argument
 338   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
 339   interface (string): optional, name of tunnel network interface
 340   ifconfig-path (string): optional, path to ifconfig command
 341   route-path (string): optional, path to route command
 342   buffer (buffer closure): buffer for host->secnet packets
 343  plus generic netlink options, as for 'null-netlink'
 344
 345 tun-old: dict argument
 346   device (string): optional, path of TUN/TAP device file ["/dev/tun*"]
 347   interface (string): optional, name of tunnel network interface
 348   interface-search (bool): optional, whether to search for a free tunnel
 349     interface (True if 'device' not specified, otherwise False)
 350   ifconfig-path (string): optional, path to ifconfig command
 351   route-path (string): optional, path to route command
 352  plus generic netlink options, as for 'null-netlink'
 353
 354  I recommend you don't specify the 'interface' option unless you're
 355  doing something that requires the interface name to be constant.
 356
 357 ** rsa
 358
 359 Defines:
 360   rsa-private (closure => rsaprivkey closure)
 361   rsa-public (closure => rsapubkey closure)
 362
 363 rsa-private: string[,bool]
 364   arg1: filename of SSH private key file (version 1, no password)
 365   arg2: whether to check that the key is usable [default True]
 366
 367 rsa-public: string,string
 368   arg1: encryption key (decimal)
 369   arg2: modulus (decimal)
 370
 371 ** dh
 372
 373 Defines:
 374   diffie-hellman (closure => dh closure)
 375
 376 diffie-hellman: string,string[,bool]
 377   arg1: modulus (hex)
 378   arg2: generator (hex)
 379   arg3: whether to check that the modulus is prime [default True]
 380
 381 ** md5
 382
 383 Defines:
 384   md5 (hash closure)
 385
 386 ** sha1
 387
 388 Defines:
 389   sha1 (hash closure)
 390
 391 ** conffile
 392
 393 Defines:
 394   makelist (dictionary => list of definitions)
 395   readfile (string => string)
 396   map (closure,list => list)
 397
 398 makelist: dictionary
 399   returns a list consisting of the definitions in the dictionary. The keys
 400   are discarded.
 401
 402 readfile: string
 403   reads the named file and returns its contents as a string
 404
 405 map:
 406   applies the closure specified as arg1 to each of the elements in the list.
 407   Returns a list made up of the outputs of the closure.