====== README ====== Campagnol VPN - distributed VPN over UDP/DTLS Copyright (c) 2007 Antoine Vianey 2008-2009 Florent Bondoux Campagnol is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. If you have any ideas, suggestions or if you need help, you can use the forums on the SourceForge project page: http://sourceforge.net/projects/campagnol/ Feel free to mail me any questions/comments that you may have at fbondoux@resel.fr especially since Campagnol is a young project. Introduction ------------ Campagnol is a distributed IP-layer VPN software over UDP and DTLS. It is able to open new connections through NATs or firewalls using UDP hole punching. This technique requires a dedicated server: the rendezvous server. This server is lightweight. It needs to have a UDP port (default 57888) reachable from Internet (either by using a public IP or by enabling port forwarding if NATted). This server is only used to open new connections and does not bear the VPN communications. Each participant of the VPN runs the client program. The communications between two peers are opened when needed and are fully authenticated and encrypted thanks to DTLS. Actually it is an X.509 certificate based security. Each client needs to own a valid certificate and its associated private key. Therefore a typical usage is to have a minimum PKI to manage the VPN. You will for instance generate: * a private key (your CA) and an associated trusted root certificate distributed to all the clients * one private key and one signed certificate per client * possibly a certificate revocation list to manage the old client's certificates To finish off, keep in mind that UDP hole punching has some limitations as the NATs involved need to meet some requirements and certain cases require UDP hairpin translation which is still not common. You can find a description and analysis of this technique here: http://www.bford.info/pub/net/p2pnat/. Use cases --------- * Intended setup [peer A] ---|NAT|---( )--- [peer C] ( NET ) [peer B] ---|NAT|---( )--- [RDV] Several clients are connected to Internet. They optionally lie behind a NAT and those NAT must accept UDP hole punching. The rendezvous server has a public IP or may also be configured behind a NAT. It sees the public address of the clients which is enough thanks to the hole punching. * Corner case 1: common NAT [peer A] ---| | ( )---|NAT|--- [peer C] |NAT|---( NET ) [peer B] ---| | ( )--- [RDV] Here the clients A and B are behind a common NAT. If A sends a packet to B using B's public address, it will fail unless the common NAT does hairpin translation. Sadly hairpin translation is not a widely spread feature. If both A and B enabled the option "use_local_addr" in their configuration file (which is the default), then the RDV server will tell them to use their local IP to reach each other (the RDV server sees that they both have the same public IP thus are behind the same NAT equipment). This works around the problem and the NAT doesn't need to do hairpin translation. If A wants to talk to C, they will still use their public address. * Corner case 2: multiple levels of NATs [peer A] ---|NAT_A|---| | ( ) |NAT_C|---( NET ) [peer B] ---|NAT_B|---| | ( )--- [RDV] This case involves a common NAT but also at least one peer lying behind another level of NAT. Here A and B can't talk to each other by using their private address. A first method to connect A and B is to disable their "use_local_addr" option (so that they won't try to use their private addresses). It will work only if NAT_C supports hairpin translation. Another method is to use the "override_local_addr" parameter in conjunction with the "use_local_addr" parameter explained above. It is used to send a fake local address to the RDV server instead of the real one. So you can define static port forwarding rules on NAT_A and NAT_B and use this parameter to publish the intermediate IP on NAT_A and NAT_B. * Corner case 3: RDV behind a NAT and client behind the same NAT ---( ) | |--- [RDV (+ peer)] ---( NET )---|NAT| ---( ) | |--- [peer] If the RDV server is behind a NAT, you can't run a client behind this NAT neither on the same host nor on another host. It is likely to fail since the RDV server will not be able to see its public address. Dependencies ------------ * Runtime dependencies: * OpenSSL library version >= 0.9.8j The latest 0.9.8* available is recommended, 1.0.0beta* should also work. http://www.openssl.org/ For Cygwin, install the Cygwin package. * A TUN/TAP driver For Linux and *BSD, it's the Universal TUN/TAP driver which is probably already compiled into the kernel (http://vtun.sourceforge.net/tun). For Cygwin, Campagnol uses the TAP-Win32 driver from the OpenVPN project. It can be downloaded from http://openvpn.net/ (Windows installer). * Additional build-time dependencies: * OpenSSL development package * If there is no ./configure script in the source tree (you checked out the sources via subversion), you will need: * autoconf >= 2.61 * automake 1.10 Compilation ----------- If the ./configure script is missing, you need to prepare the source tree by running: $ autoreconf -if You first need to use the 'configure' script. $ ./configure --help It will use pkg-config to configure OpenSSL. If you do not have pkg-config or if you have installed OpenSSL in a non standard directory, you should have a look at the '--with-openssl*' options for the 'configure' script. $ ./configure --with-openssl=/usr/local If you do not want to build the RDV server or the client, you can use the options '--disable-server' and '--disable-client'. Build Campagnol: $ make Install Campagnol: $ make install Creating the certificates ------------------------- To create a small certificate authority for Campagnol, you can use the ca_wrap.sh script from the "samples" directory. See its README file. This script enables you to create a configuration file for OpenSSL, create the CA structure, the root key and certificates, and the keys and signed certificates for the clients. It can also be used to revoke old client certificates and create certificate revocation lists. Configuration ------------- You need to create a configuration file for each client. The easiest way is to start with the sample configuration file which describes every option. A few options are mandatory. By default Campagnol uses /etc/campagnol.conf, an other config file might be used by giving its name as a command line argument. This file has an INI-like syntax. Comments start with a ';' or a '#' and continue to the end of the line. Values may be quoted between double quotation marks ("...") and special characters can be escaped with '\' (\\, \n, \# ...). See its man page campagnol.conf(5). !! important !! Be sure to set the same values for the following options on every clients: * "server_host" in the [NETWORK] section * "server_port" in the [NETWORK] section * "network" in the [VPN] section * "cipher_list" in the [SECURITY] section (or at least the values must be compatible) * "tun_mtu" in the [NETWORK] section * "timeout" in the [CLIENT] section (this one is actually not strictly required but it will run more smoothly if all the clients have the same value) Running ------- Run the rendezvous server on a publicly accessible computer (for every clients of the VPN). The server uses the default UDP port 57888. Be sure that this port is reachable. The server doesn't require superuser privileges if you do not ask for a privileged port (<1024). $ campagnol_rdv To start the server on another port: $ campagnol_rdv --port=34567 To limit the maximum number of connected clients (recommended): $ campagnol_rdv --max-clients=20 To start the server as a daemon: $ campagnol_rdv --daemon When the RDV server is started as a daemon, it will write its PID into /var/run/campagnol_rdv.pid (or another file defined with --pidfile). To start a client, run: $ campagnol conf_file.conf To start the client as a daemon: $ campagnol --daemon conf_file.conf Send a SIGTERM or SIGINT signal to the client to kill it cleanly. If no configuration file is given, campagnol will search for a default /etc/campagnol.conf file. When campagnol is launched as a daemon, it will write its PID into /var/run/campagnol.pid (or another file defined with --pidfile). See the man pages campagnol(8) and campagnol_rdv(8).