VPNUnit

Manages our VPN. Lot of details can be found on this page in Italian.

VPNUnit exposes a REST API interface, and endpoints can be used to administer users and their gateways.

• user: an user corresponds to a member of GOLEM, and is identified by her nickname. (this could enable future integrations with argento)
• gateway: a gateway corresponds to an user device, which can act as a leaf end (eg. her smartphone) or a network router (eg. her scatolotto).

An user can have up to 16 gateways. Each gateway is reserved up to 16 /64 networks.

Addresses are given in the following form:

2001:470:c844:uugn:xxxx:xxxx:xxxx:xxxx

where

• 2001:470:c844::/48: GOLEM prefix, courtesy of Hurrican Electric
• uu: user id, from 00 to ff. 00 and 01 are reserved, 02 is for the Officina Informatica.
• g: gateway of the user, from 0 to f
• n: network n of gateway g of user uu

Using the REST API, the system administrator can manage the uug part of the issued addresses:

• create new users
• create and delete (revoke cert) gateways
• obtain the OpenVPN configuration file for the gateways

Since the whole 2001:470:c844:uug0::/60 network will be forwared to/from the user gateway, then she has to manage the n part of the address (if she wants), for example using forwarding again and DHCPv6 or SLAAC with radv.

REST API endpoints

endpoint	method	body	description
/users	GET		get list of users
/users	POST	{ "name": "johndoe" }	create new user
/gateways	GET		get list of gateways
/gateways	POST	{ "name": "fqdn.domain.tld", "user": "johndoe" }	create new gateway for user
/gateway/$fqdn	GET		get info about gateway
/gateway/$fqdn	DELETE		delete gateway
/gateway/$fqdn/config	GET		get client config file for gateway
/gateway/$fqdn/renew	POST		generate new certificate for gateway (min 30 days before expiration)

Technical details

VPNUnit runs inside a Docker container, and stores its data in the /data subvolume (which is usually mounted on /srv/vpnunit on the physical machine).

/data contains:

• database.sqlite3: users and gateways info
• pki/: Public Key Infrastructure for easy-rsa
• ovpn/: server config file, and static clients addresses
• ip/: static routes

Example:

1. system administrator creates a new user, database.sqlite3 is updated
2. system administrator creates a new gateway for an user:
   • database.sqlite3 is updated
   • new certificate is issued using easyrsa pki
   • new static client address is registered in ovpn/clients in the mentioned form
   • new static route is added in ip/routes

Note: the OpenVPN process is actually run on the physical machine! It uses:

• the server configuration file in ovpn/
• the static clients configurations in ovpn/clients

Moreover, a cronjob should periodically:

• check for routes in ip/routes and update them accordingly on the physical machine.

A possible cronjob could be:

while [ true ]; do

		while read line; do
			COMMAND="ip -6 route add $line"
			eval $COMMAND
		done < /srv/vpnunit/ip/routes

	sleep 60
done

Develop

Dockerfile.develop contains instructions to build a container for assessing this project's quality, and script/qa is automatically run inside that container by the CI system. Give a look at it.