| 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) |