ClueNet:ClueVPN
From ClueWiki
This page is about the home-grown VPN software that Cluenet uses. Only servers are allowed to connect directly into the mesh ClueVPN. To connect your home machine, you must use the OpenVPN gateway, openvpn.cluenet.org. See here. To connect a server, read on.
Contents |
Overview of the ClueVPN Protocol and Structure
From the HOWTO file in the cluevpn source:
ClueVPN is not designed to compete with typical VPN protocols such as OpenVPN or IPSec. These protocols establish point-to-point connections with an endpoint, and do so very well. ClueVPN is designed as a mesh routing VPN, where there are many peers in a network, all communicating with each other. Using usual methods, all communication goes through a central server, which is a bottleneck and a single point of failure. With ClueVPN, each peer communicates directly with each other peer. If you want to set up a VPN between two hosts, don't use ClueVPN - I recommend OpenVPN or vtun for that. Even with three hosts, you can establish mesh routing by running separate connections. But running multiple openvpn or vtun VPNs for mesh routing quickly gets unmanagable. For a mesh routing network to directly send data between peers, each peer needs to know about every other peer. With ClueVPN, this is accomplished with a list of peers called the Bootstrap Node List (BNL). The BNL contains data for each node in the network, including its "real" IP address(es) and the virtual subnet allocated to it. ClueVPN peers have the ability to automatically discover updated BNLs from peers, so adding a new node is as simple as updating the BNL on a single peer. There's no need to change configuration on every node to modify the network structure or routes. Each BNL is timestamped so each node knows when a BNL is newer. Since the BNL can be automatically discovered from other nodes, protection is built in to make sure that no "rogue" node introduces an incorrect BNL. The BNL is signed by the creator, and each node verifies the signature. BNLs are signed with DSA keys, which must be generated for the ClueVPN network to properly function. ClueVPN data is sent over UDP. It is encrypted (with an included sequence number and hash) and optionally compressed, then sent to the destination node. The encryption key as well as the encryption algorithm, compression algorithm (if any), and compression level, are kept for each pair of nodes. For example, in a 3-node network (nodes A, B, and C), nodes A<->B share encryption/comression parameters, nodes B<->C share parameters, and nodes A<->C share parameters. Each node stores its parameters for communicating with each other node. If two nodes have not agreed on encryption/compression parameters, they are automatically established via a process called negotiation. Negotiation occurs over TCP. One node makes a connection to the other node using SSL. Both nodes verify that the other node's certificate was signed by the VPN CA, and gets the identity of the node from the certificate's Common Name. They exchange supported algorithms and preferences, and both generate a random encryption key. From this information, an encryption key for both to use as well as the algorithms is determined. These are stored, so if the VPN daemon restarts, it doesn't need to renegotiate. BNLs can be shared via two methods - pushes and pulls. Periodically (every few minutes approximately - it varies depending on how many "spare" connections there are), each node asks every other node if it has an updated BNL. If the remote node does have an updated BNL, it is transmitted, the signature verified, and the daemon refreshed to use the new BNL. If BNL pulls are too slow, BNL pushes can also be used. A BNL push must be manually initiated by sending SIGUSR1 to a running ClueVPN daemon. This both causes the BNL to be reloaded from the disk and the BNL to be pushed to every other node (if the timestamp is newer).
Cluenet ClueVPN Extensions
Cluenet provides a remctl API which can be used to automatically gain signed certificates for Cluenet servers and the latest BNL for initial configuration. There is also a startup kit which contains many useful scripts.
Cluenet ClueVPN Nameserver Management
Using the Cluenet scripts, the VPN IPs of the Cluenet nameservers will automatically be prefixed to the resolv.conf file with the ClueVPN daemon starts. This causes large issues for systems when domain names can't be resolved if the VPN is nonfunctional, or the nameservers unreachable, for any reason. To fix this, the set of Cluenet scripts includes a nameserver checking program. It's added as a cron job to run every 5 minutes or so. It basically removes nameservers from resolv.conf which are not reachable via ping. If a nameserver becomes reachable again, it's readded to resolv.conf. The list of all possible nameservers is stored in a file /etc/resolv.conf-master. It's automatically created as a copy of /etc/resolv.conf the first time the script runs, or the first time the ClueVPN daemon runs with the Cluenet up script. Each time the nameserver checker script runs, it checks the availability of each server in the master file, and adds the ones that work, in order, to /etc/resolv.conf. If the VPN goes down for some reason and parts of the server stop functioning due to domain name resolution problems, just wait until the script runs on cron, and the issues should resolve themselves.
Integrating Your Server Into the VPN
First, get an admin to add your server to the BNL. After that's done, get the latest ClueVPN source code, and the package of Cluenet scripts. The README file in the ClueVPN source will tell you how to compile and install the daemon. The README file in the Cluenet script package will tell you everything you need to get it integrated into the Cluenet VPN.
Can I Use the ClueVPN Daemon For My Own VPN?
Yes, please do. But keep in mind that it's designed for networks where mesh routing is beneficial. See the HOWTO and README files in the ClueVPN source for more details. For a single point-to-point connection, ClueVPN is probably not what you want.
