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 ** random
 149
 150 Defines:
 151   randomsrc (closure => randomsrc closure)
 152
 153 ** udp
 154
 155 Defines:
 156   udp (closure => comm closure)
 157
 158 ** util
 159
 160 Defines:
 161   logfile (closure => log closure)
 162   sysbuffer (closure => buffer closure)
 163
 164 ** site
 165
 166 Defines:
 167   site (closure => site closure)
 168
 169 ** transform
 170
 171 Defines:
 172   serpent256-cbc (closure => transform closure)
 173
 174 ** netlink
 175
 176 Defines:
 177   userv-ipif (closure => netlink closure)
 178   tun (closure => netlink closure) [only on linux-2.4]
 179   tun-old (closure => netlink closure)
 180   null-netlink (closure => netlink closure)
 181
 182 ** rsa
 183
 184 Defines:
 185   rsa-private (closure => rsaprivkey closure)
 186   rsa-public (closure => rsapubkey closure)
 187
 188 ** dh
 189
 190 Defines:
 191   diffie-hellman (closure => dh closure)
 192
 193 ** md5
 194
 195 Defines:
 196   md5 (hash closure)