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