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