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