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