Added small doc in README

README

 Vifibnet is a daemon setting up a resilient virtual private network over the
 internet
 
-To use vifibnet, you need to launch the registry.py on a server to provide the
-certificates. Then you should run setup.py on each clients tu prepare the
-clients and then run vifibnet.py on each client
+HOW TO:
+    Vifibnet ( sic ) has three separate components : a setup, a server and
+    a client.
+    Lambda users only have to launch the setup and then their client.
+    The server is meant to be started once on a node which also will be running
+    a client instance.
 
 The organisation of the code
     vifibnet.py         Just contain the main loop and the init
@@ -13,3 +16,184 @@ The organisation of the code
     tunnel.py           To choose wich connection delete/keep/...
     upnpigd.py          To open a port
 
+OPTIONS : REGISTRY.PY
+    usage : ./registry port [options...]
+    port
+            The port on which the server will listen
+
+    --db path
+            Path to the server Database file. A new DB file will be created
+            and correctly initialized if the file doesn't exists.
+            One can give ":memory" as path, the database is then temporary
+
+    --ca path
+            Path to the certificate authority file. The certificate authority
+            MUST contain the VPN network prefix in its serial number. To
+            generate correct ca and key files for the 2001:db8:42:: prefix,
+            the following command can be used :
+            openssl req -nodes -new -x509 -key ca.key -set_serial
+                    0x120010db80042 -days 365 -out ca.crt
+
+    --key path
+            Path to the server key file. To generate a key file, see the --ca
+            option
+
+    --mailhost mailhost
+            Mailhost to be used to send email containing token for registration
+
+OPTIONS : SETUP.PY
+    usage : ./setup [options...]
+    --server address
+             Ip address of the machine running the vifibnet server. Both ipv4
+             and ipv6 addresses are supported.
+
+    --port port
+             Port to connect to on the machine running the vifibnet server.
+
+    -d, --dir directory
+            Path of a directory where will be stored the files generated by the
+            setup. The Setup genereates the following files, in the explicit
+            order :
+            - ca.pem : certificate authority file downloaded from the server
+            - peers.db : peers database initialized for vifibnet.py
+            - cert.key : private key generated by the script
+            - cert.crt : individual certificate file generated by the server
+            - dh2048.pem : dh file for oenvpn server
+
+    -r, --req name value
+            Specify an attribute to add to the certificate request sent to the
+            server. Can be used multiple times.
+            Each use of the --req name value, will add the attribute name with
+            the associated value in the sugbject of the certificate request.
+
+    --ca-only
+            Stop the script after downloading the certificate authority file
+            from the server
+
+    --db-only
+            Stop the script after creating the peers DB and downloading the
+            connection information of a bootstrap node of the VPN.
+
+    --no-boot
+            Does not re'quest a bootstrap peer to the peer discovery server
+            (useful in debug when the server does not have any peer in his
+            database). When requesting a bootstrap peer to a server whoch does
+            not have any, an execption will occur, and the script will stop
+
+
+OPTIONS : VIFIBNET.PY
+    usage : ./vifibnet.py [options...]
+    --ip address port proto
+            Specify connection information to be advertised to other nodes.
+            address MUST be a ipv4 address since as of now openvpn does not
+            support ipv6 addresses.
+            proto should be either udp or tcp-client
+
+    --internal-port port
+            Specify the port on which will be launched the openvpn server(s)
+            Can differ from port given in the --ip option.
+            Default : 1194
+
+    --peers-db-refresh duration
+            Duration in seconds of the peers DB refresh interval.
+            Default : 3600  ( 1 hour )
+
+    -l, --log directory
+            Path to the directory used for log files. Will create one file
+            for babel logging and one file for each openvpn server and client
+            started.
+            Default : /var/log
+
+    -s, --state directory
+            Path to the directory used for state files. State files include :
+            - peers.db : the peers db used to establish connection
+            - vifibnet.babeld.state : babeld state file
+            Default : /var/lib/vifibnet
+
+    -v, --verbose level
+            Defines the verbose level, level should be an integer between 0
+            and 5 ( including ). There is no precise convention for verbode
+            level for now, except an increased number means more log messages.
+            This parameter is also given to openvpn and babel for their log.
+            Default : 0
+
+    --server address
+             Ip address of the peer discovery server. SHOULD be an ipv6 address
+             belonging to the VPN network, as the server only allows requests
+             from inside the VPN (feature not used now for debugging purposes)
+
+    --server-port port
+            Port number on the peer discovery server to which we connect
+
+    --hello duration
+            Set hello interval, in seconds, for both wired and wireless
+            connections. Openvpn ping-exit option is set to 4 times the hello
+            interval. Argument passed down to the babel daemon, equivalent
+            to :
+            -h duration -H duration
+            in babeld ( for more information, see babeld man page )
+            Default : 30
+
+    -w, --wireless
+            Consider all interfaces as being wireless interfaces. Argument
+            directly passed down to the babeld daemon
+
+    --proto p [p']
+            Protocol used by the openvpn server(s). Start one openvpn server
+            for each protocl specified.
+            p (and p') should be either udp or tcp-server
+            Default : udp
+
+    --tunnel-refresh duration
+            Interval in seconds between two tunnel refresh. Refreshing tunnels
+            mean :
+            - killing all dead tunnels ( detected via the ping-exit option
+              if openvpn )
+            - killing the 'worst' tunnels, so that at least the ratio of
+              tunnels set by the --refresh-rate option have been killed
+            - creating new tunnels to other clients randomly choosen in the
+              peers database, to reach the number of connection specified by
+              the connection-count option ( There can be less tunnels if the
+              peers DB does not contain enough peers )
+            Default : 300
+
+    --dh path
+            Path to the dh file to be used by the openvpn server
+            (for more information see the openvpn man page)
+
+    --ca path
+            Path to the certificate authority file delivered by the vifibnet
+            server. The prefix of the VPN network is included in the serial
+            number of the file.
+
+    --cert path
+            Path to the individual certificate file delivered by the vifibnet
+            server. The prefix of the machine is included in the certificate's
+            subject common name.
+
+    --connection-count number
+            The maximum number of openvpn clients to start.
+            Default : 20
+
+    --refresh-rate ratio
+            The ratio of connection to kill each time we refresh tunnels.
+            For more information see the --tunnel-refresh option
+            ratio should be a float between 0 and 1 ( included )
+            Default : 0.05
+
+    openvpn_args
+            Additional arguments to be passed down to all openvpn processes
+            can be given at the end of the command line.
+            In that case, insert '--' to delimit vifibnet regular options
+            from the additional openvpn arguments. The list of arguments will
+            be passed down to ALL openvpn processes ( including servers )
+            exactly as they are given
+            One SHOULD give a --key argument with the key file delivered by the
+            vifibnet server
+
+    @file
+            You can give to vifibnet a config file as a regular argument
+            (meaning before giving optional openvpn arguments)
+            The file should contain one option per line, possibly ommitting
+            the '--'. Only long option are allowed (i.e "v 3" will not work
+            while "verbose 3" will)

TODO

+G : We should focus on clearing the TODO List, then go to testing phase,
+    since the end is nearing... ( I finish on august, 3 )
+
 To be done :
     Catch a more precise exception thant Exception at line 108 in vifibnet.py
     ( UPnP forwarding )
@@ -6,9 +9,8 @@ To be done :
     "Refreshing peers DB ... done", or add log messages to specify that an
     action advertised by a previous log message has been completed
 
-    Add options to start udp server, tcp server or both
-
-    use the server as a bootstrap node
+    use the server as a bootstrap node -> switch peer discovery to be done
+    by vifibnet directly ?
 
     Use an algorithm to choose which connections to keep and/or establish
     instead of pure randomness
@@ -20,9 +22,6 @@ To be done :
     Replace comments at the beginning of functions with docstrings & give all
     fn docstrings
 
-    Use the server events ( client connection/deconnection ) to do something
-    useful
-
     In peers DB, flag the dead peers so we only choose them if necessary and we
     can remove them if we have enought peers
 
@@ -32,6 +31,7 @@ To be done :
     Specify a lease duration in ForwardViaUPnP
 
     Handle LAN internally in order not to have catastrophic results ....
+    ( avahi could be used )
 
 To be discussed:
     G, J : To get traffic stats ( bytes in/out ), you can use

tunnel.py

@@ -5,6 +5,7 @@ log = None
 smooth = 0.3
 
 class Connection:
+
     def __init__(self, address, write_pipe, hello, iface, prefix,
             ovpn_args):
         self.process = plib.client(address, write_pipe, hello, '--dev', iface,

utils.py

@@ -41,5 +41,5 @@ def address_list(address_set):
     return ';'.join(map(','.join, address_set))
 
 def address_set(address_list):
-    return set(tuple(address.split(','))
+    return list(tuple(address.split(','))
         for address in address_list.split(';'))

vifibnet.py

@@ -34,7 +34,7 @@ def getConfig():
             help='Port on the machine to listen on for incomming connections')
     _('--peers-db-refresh', default=3600, type=int,
             help='the time (seconds) to wait before refreshing the peers db')
-    _('-log', '-l', default='/var/log',
+    _('-l', '-log', default='/var/log',
             help='Path to vifibnet logs directory')
     _('-s', '--state', default='/var/lib/vifibnet',
             help='Path to VPN state directory')
@@ -44,7 +44,6 @@ def getConfig():
     #        help='Path to babeld state-file')
     #_('--db', default='/var/lib/vifibnet/peers.db',
     #        help='Path to peers database')
-    # Server address SHOULD be a vifib address ( else requests will be denied )
     _('--server', required=True,
             help="VPN address of the discovery peer server")
     _('--server-port', required=True, type=int,
@@ -126,7 +125,8 @@ def main():
     server_process = list(plib.server(internal_ip, network,
         config.connection_count, config.dh, write_pipe, config.internal_port,
         proto, config.hello, '--dev', 'vifibnet', *openvpn_args,
-        stdout=os.open(os.path.join(config.log, 'vifibnet.server.log'),
+        stdout=os.open(os.path.join(config.log,
+            'vifibnet.server.%s.log' % (proto,)),
             os.O_WRONLY | os.O_CREAT | os.O_TRUNC)) for proto in config.proto)
     tunnel_manager.refresh()