mdw@git.distorted.org.uk Git - secnet/blob - 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
 169 ** util
 170
 171 Defines:
 172   logfile (closure => log closure)
 173   sysbuffer (closure => buffer closure)
 174
 175 ** site
 176
 177 Defines:
 178   site (closure => site closure)
 179
 180 site: dict argument
 181   local-name (string): this site's name for itself
 182   name (string): the name of the site's peer
 183   netlink (netlink closure)
 184   comm (comm closure)
 185   resolver (resolver closure)
 186   random (randomsrc closure)
 187   local-key (rsaprivkey closure)
 188   address (string): optional, DNS name used to find our peer
 189   port (integer): mandatory if 'address' is specified: the port used
 190     to contact our peer
 191   networks (string list): networks that our peer may claim traffic for
 192   key (rsapubkey closure): our peer's public key
 193   transform (transform closure): how to mangle packets sent between sites
 194   dh (dh closure)
 195   hash (hash closure)
 196   key-lifetime (integer): max lifetime of a session key, in ms [one hour]
 197   setup-retries (integer): max number of times to transmit a key negotiation
 198     packet [5]
 199   setup-timeout (integer): time between retransmissions of key negotiation
 200     packets, in ms [1000]
 201   wait-time (integer): after failed key setup, wait this long (in ms) before
 202     allowing another attempt [20000]
 203   renegotiate-time (integer): if we see traffic on the link after this time
 204     then renegotiate another session key immediately [depends on key-lifetime]
 205   keepalive (bool): if True then attempt always to keep a valid session key
 206   log-events (string list): types of events to log for this site
 207     unexpected: unexpected key setup packets (may be late retransmissions)
 208     setup-init: start of attempt to setup a session key
 209     setup-timeout: failure of attempt to setup a session key, through timeout
 210     activate-key: activation of a new session key
 211     timeout-key: deletion of current session key through age
 212     security: anything potentially suspicious
 213     state-change: steps in the key setup protocol
 214     packet-drop: whenever we throw away an outgoing packet
 215     dump-packets: every key setup packet we see
 216     errors: failure of name resolution, internal errors
 217     all: everything (too much!)
 218   netlink-options (string list): options to pass to netlink device when
 219     registering remote networks
 220     soft: create 'soft' routes that go away when there's no key established
 221       with the peer
 222     allow-route: allow packets from our peer to be sent down other tunnels,
 223       as well as to the host
 224
 225 ** transform
 226
 227 Defines:
 228   serpent256-cbc (closure => transform closure)
 229
 230 ** netlink
 231
 232 Defines:
 233   null-netlink (closure => netlink closure)
 234
 235 null-netlink: dict argument
 236   name (string): name for netlink device, used in log messages
 237   networks (string list): networks on the host side of the netlink device
 238   exclude-remote-networks (string list): networks that may never be claimed
 239     by any remote site using this netlink device
 240   local-address (string): IP address of host's tunnel interface
 241   secnet-address (string): IP address of this netlink device
 242   mtu (integer): MTU of host's tunnel interface
 243
 244 ** slip
 245
 246 Defines:
 247   userv-ipif (closure => netlink closure)
 248
 249 userv-ipif: dict argument
 250   userv-path (string): optional, where to find userv ["userv"]
 251   service-user (string): optional, username for userv-ipif service ["root"]
 252   service-name (string): optional, name of userv-ipif service ["ipif"]
 253   buffer (buffer closure): buffer for assembly of host->secnet packets
 254  plus generic netlink options, as for 'null-netlink'
 255
 256 ** tun
 257
 258 Defines:
 259   tun (closure => netlink closure) [only on linux-2.4]
 260   tun-old (closure => netlink closure)
 261
 262 tun: dict argument
 263   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
 264   interface (string): optional, name of tunnel network interface
 265   ifconfig-path (string): optional, path to ifconfig command
 266   route-path (string): optional, path to route command
 267   buffer (buffer closure): buffer for host->secnet packets
 268  plus generic netlink options, as for 'null-netlink'
 269
 270 tun-old: dict argument
 271   device (string): optional, path of TUN/TAP device file ["/dev/tun*"]
 272   interface (string): optional, name of tunnel network interface
 273   interface-search (bool): optional, whether to search for a free tunnel
 274     interface (True if 'device' not specified, otherwise False)
 275   ifconfig-path (string): optional, path to ifconfig command
 276   route-path (string): optional, path to route command
 277  plus generic netlink options, as for 'null-netlink'
 278
 279 ** rsa
 280
 281 Defines:
 282   rsa-private (closure => rsaprivkey closure)
 283   rsa-public (closure => rsapubkey closure)
 284
 285 rsa-private: string[,bool]
 286   arg1: filename of SSH private key file (version 1, no password)
 287   arg2: whether to check that the key is usable [default True]
 288
 289 rsa-public: string,string
 290   arg1: encryption key (decimal)
 291   arg2: modulus (decimal)
 292
 293 ** dh
 294
 295 Defines:
 296   diffie-hellman (closure => dh closure)
 297
 298 diffie-hellman: string,string[,bool]
 299   arg1: modulus (hex)
 300   arg2: generator (hex)
 301   arg3: whether to check that the modulus is prime [default True]
 302
 303 ** md5
 304
 305 Defines:
 306   md5 (hash closure)
 307
 308 ** sha1
 309
 310 Defines:
 311   sha1 (hash closure)