README

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