Manages the VPN: creates certificates for the clients, renew and revoke, prepares the OpenVPN and firewall configuration on the server based on the status of the database. Management is done using a JSON REST API.
Go to file
giomba b47a137616 Never restart the VPN manager.
For fuck's sake, that manages the fucking certificates.
2024-05-12 22:49:45 +02:00
easy-rsa@a9cecc747c second commit 2021-01-24 23:29:37 +01:00
script Add CI. 2023-04-10 17:50:55 +02:00
templates removed test ipv6 address 2021-03-07 13:52:10 +01:00
.drone.yml Add CI. 2023-04-10 17:50:55 +02:00
.gitignore first commit 2021-01-06 11:07:44 +01:00
.gitmodules second commit 2021-01-24 23:29:37 +01:00
Dockerfile.deploy Add CI. 2023-04-10 17:50:55 +02:00
Dockerfile.develop Add CI. 2023-04-10 17:50:55 +02:00 Add CI. 2023-04-10 17:50:55 +02:00
docker Add CI. 2023-04-10 17:50:55 +02:00
docker-compose.yml Never restart the VPN manager. 2024-05-12 22:49:45 +02:00 Add certificate renew endpoint. 2023-04-10 17:30:32 +02:00
pyproject.toml Add quality assurance tests. 2023-04-08 22:25:17 +02:00
requirements.txt Add quality assurance tests. 2023-04-08 22:25:17 +02:00


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::/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


  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


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.