A little clean-up in the imports
[re6stnet.git] / README
1 re6stnet is a daemon setting up a resilient virtual private network over the
2 internet
3
4 HOW TO:
5     re6stnet ( sic ) has three separate components : a setup (setup.py), a
6     server (registry.py) and a client (re6stnet.py.
7     Lambda users only have to launch the setup and then their client.
8     The server is meant to be started once on a node which also will be running
9     a client instance.
10
11 The organisation of the code
12     vifibnet.py         Just contain the main loop and the init
13     plib.py             To launch server/client/routing processes
14     utils.py            Small functions to do some useful job
15     db.py               Function to manage peers
16     tunnel.py           To choose wich connection delete/keep/...
17     upnpigd.py          To open a port
18
19 Note: On certain version of python (e.g. 2.7.3~rc2-2.1 ) dns lookup is
20       performed for each request, and cause a delay in response.
21       To avoid this, one can either upgrade python, fix their resolv.conf or use
22       the fix at the end of this file.
23
24 OPTIONS : REGISTRY.PY
25     usage : ./registry port [options...]
26     port
27             The port on which the server will listen
28
29     --private ip
30             Ipv6 address of the re6stnet client running on the machine. This
31             address will be advertised only to nodes having a valid
32             certificate.
33
34     --db path
35             Path to the server Database file. A new DB file will be created
36             and correctly initialized if the file doesn't exists.
37             One can give ":memory" as path, the database is then temporary
38
39     --ca path
40             Path to the certificate authority file. The certificate authority
41             MUST contain the VPN network prefix in its serial number. To
42             generate correct ca and key files for the 2001:db8:42:: prefix,
43             the following command can be used :
44             openssl req -nodes -new -x509 -key ca.key -set_serial \
45                     0x120010db80042 -days 365 -out ca.crt
46
47     --key path
48             Path to the server key file. To generate a key file, see the --ca
49             option
50
51     --bootstrap prefix ip port proto
52             Connection informations of a node given to other as a bootstrap
53             node to initiate connection with the network.
54             Prefix should be the prefix number of a node, given in binary and
55             with correct length. For instance the VPN address
56             2001:db8:42:1::/64 ( asusming a network prefix 2001:db8:42::/48 )
57             corresponds to a prefix 1/16 i.e 0000000000000001.
58
59     --mailhost mailhost
60             Mailhost to be used to send email containing token for registration
61
62 OPTIONS : SETUP.PY
63     usage : ./setup [options...]
64     --server address
65              Ip address of the machine running the re6stnet server. Both ipv4
66              and ipv6 addresses are supported.
67
68     --port port
69              Port to connect to on the machine running the re6stnet server.
70
71     -d, --dir directory
72             Path of a directory where will be stored the files generated by the
73             setup. The Setup genereates the following files, in the explicit
74             order :
75             - ca.pem : certificate authority file downloaded from the server
76             - peers.db : peers database initialized for re6stnet.py
77             - cert.key : private key generated by the script
78             - cert.crt : individual certificate file generated by the server
79             - dh2048.pem : dh file for oenvpn server
80
81     -r, --req name value
82             Specify an attribute to add to the certificate request sent to the
83             server. Can be used multiple times.
84             Each use of the --req name value, will add the attribute name with
85             the associated value in the sugbject of the certificate request.
86
87     --ca-only
88             Stop the script after downloading the certificate authority file
89             from the server
90
91     --db-only
92             Stop the script after creating the peers DB and downloading the
93             connection information of a bootstrap node of the VPN.
94
95     --no-boot
96             Does not re'quest a bootstrap peer to the peer discovery server
97             (useful in debug when the server does not have any peer in his
98             database). When requesting a bootstrap peer to a server whoch does
99             not have any, an execption will occur, and the script will stop
100
101
102 OPTIONS : RES6NET.PY
103     usage : ./re6stnet.py [options...]
104     --ip address port proto
105             Specify connection information to be advertised to other nodes.
106             address MUST be a ipv4 address since as of now openvpn does not
107             support ipv6 addresses.
108             Proto should be either udp or tcp-client
109
110     -i, --interface interface
111             Give one interface name for each use of the argument. The interface
112             will be used to detect other nodes on the local network.
113
114     --peers-db-refresh duration
115             Duration in seconds of the peers DB refresh interval.
116             Default : 3600  ( 1 hour )
117
118     -l, --log directory
119             Path to the directory used for log files. Will create one file
120             for babel logging and one file for each openvpn server and client
121             started.
122             Default : /var/log
123
124     -s, --state directory
125             Path to the directory used for state files. State files include :
126             - peers.db : the peers db used to establish connection
127             - re6stnet.babeld.state : babeld state file ( created if does not
128               exists, overriden if exists )
129               There must be a valid peers db file ( named peers.db ) in the
130               directory. A valid peers db file can be created with setup.py
131             Default : /var/lib/re6stnet
132
133     -v, --verbose level
134             Defines the verbose level, level should be an integer between 0
135             and 3 ( including ). There is no precise convention for verbode
136             level for now, except an increased number means more log messages.
137             This parameter is also given to babel for its log.
138             To adjust verbose level for openvpn, add an openvpn optional
139             arguments at the end of the command line
140             Default : 0
141
142     --registry address
143            Complete public ( reachable from the internet ) address of the machine
144            running a registry. Will be used to get the pirvate address of the
145            registry and/or bootstrap peers
146            Examples : http://192.0.2.42:80, http://[2001:db8:42::1]:80
147
148     --hello duration
149             Set hello interval, in seconds, for both wired and wireless
150             connections. Openvpn ping-exit option is set to 4 times the hello
151             interval. Argument passed down to the babel daemon, equivalent
152             to :
153             -h duration -H duration
154             in babeld ( for more information, see babeld man page )
155             It takes between 3 times and 4 times the hello interval for babel
156             to re-establish connection with a node for which the direct
157             connection has been cut
158             Default : 15
159
160     -w, --wireless
161             Consider all interfaces as being wireless interfaces. Argument
162             directly passed down to the babeld daemon
163
164     --pp port proto
165             Port and protocol used by the openvpn server(s). Start one openvpn
166             server for each couple port/protocol specified.
167             Additionally, if no external configuration is given in the command
168             line, re6stnet will attempt to forward a port with upnp for each
169             couple port/proto given.
170             Protocols should be either udp or tcp-server.
171             Default : (1194, udp), (1194, tcp-server)
172
173     --tunnel-refresh duration
174             Interval in seconds between two tunnel refresh. Refreshing tunnels
175             mean :
176             - killing all dead tunnels ( detected via the ping-exit option
177               if openvpn )
178             - killing the 'worst' tunnels, so that at least the ratio of
179               tunnels set by the --refresh-rate option have been killed
180             - creating new tunnels to other clients randomly choosen in the
181               peers database, to reach the number of connection specified by
182               the connection-count option ( There can be less tunnels if the
183               peers DB does not contain enough peers )
184             Default : 300
185
186     --dh path
187             Path to the dh file to be used by the openvpn server
188             (for more information see the openvpn man page)
189
190     --ca path
191             Path to the certificate authority file delivered by the re6stnet
192             server. The prefix of the VPN network is included in the serial
193             number of the file.
194
195     --cert path
196             Path to the individual certificate file delivered by the re6stnet
197             server. The prefix of the machine is included in the certificate's
198             subject common name.
199
200     --connection-count number
201             The maximum number of openvpn clients to start.
202             Default : 20
203
204     --refresh-rate ratio
205             The ratio of connection to kill each time we refresh tunnels.
206             For more information see the --tunnel-refresh option
207             ratio should be a float between 0 and 1 ( included )
208             Default : 0.05
209
210     openvpn_args
211             Additional arguments to be passed down to all openvpn processes
212             can be given at the end of the command line.
213             In that case, insert '--' to delimit re6stnet regular options
214             from the additional openvpn arguments. The list of arguments will
215             be passed down to ALL openvpn processes ( including servers )
216             exactly as they are given
217             One SHOULD give a --key argument with the key file delivered by the
218             re6stnet server
219
220     @file
221             You can give to re6stnet a config file as a regular argument
222             (meaning before giving optional openvpn arguments)
223             The file should contain one option per line, possibly ommitting
224             the '--'. Only long option are allowed (i.e "v 3" will not work
225             while "verbose 3" will)
226             You can give a file ( with the @ prefix ) as an argument within a
227             file
228
229
230 If you are using a version of python < 2.7.3-2, then you should include this at 
231 the beggining of registry.py
232
233 --------------------------------------------------------------------------------
234 # Fix for librpcxml to avoid doing reverse dns on each request
235 # it was causing a 10s delay on each request when no reverse DNS was avalaible
236 import BaseHTTPServer
237
238
239 def not_insane_address_string(self):
240     host, port = self.client_address[:2]
241     return '%s (reverse DNS disabled)' % host  # used to call: socket.getfqdn(host)
242
243 BaseHTTPServer.BaseHTTPRequestHandler.address_string = not_insane_address_string
244
245 --------------------------------------------------------------------------------
246
247 New log system :
248     we use the logging module now. There are three levels for log messages :
249     - info : give basic information about what re6stnet is doing
250     - debug : display internal work of the script (finished action, detailed
251               information about tunnels, etc... )
252     - trace : for intensive debug, display configuration, arguments given to
253               processes, all information pertinent to debug but not required
254               mot of the time
255     Additionally, warning, error and exception can be used.
256     Note : logging.exception prints informations similar to pdb.set_trace()
257            info, which is pretty heavy, so for exception we expect ( for
258            instance, connection problems to the registry ), one can print the
259            exception as warning. ( see db.refresh() ).