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