Server Upgrade from 2.x to 3.x#

This document will help you migrate your existing server from eduVPN / Let’s Connect! 2.x to 3.x.

Limitations#

All your users will need to reauthorize their eduVPN / Let’s Connect! applications with your server and/or re-download the configurations files they manually got through the portal once the upgrade is complete.

Requirements#

You MUST be running the server on Debian >= 11. If you are not running on Debian 12, it is highly recommended to upgrade to Debian 12 first:

You probably have to go first from Debian 10 to 11 and then to 12 if you are still running Debian 10. If you try to go in 1 step, be extra careful and read all upgrade instructions carefully to make sure this is actually possible.

When you already run Debian >= 11, make sure your system is fully up to date and freshly rebooted:

$ sudo vpn-maint-update-system
$ sudo reboot

Furthermore, we assume that you have documentation on the things you changed on your 2.x server installation, for example the TLS certificates.

Backup#

It is important to make backups of the configuration files and database as they will help you with configuring/restoring the 3.x server. Those files are:

/etc/vpn-user-portal/config.php
/etc/vpn-server-api/config.php
/etc/vpn-server-node/config.php

As for the database files:

/var/lib/vpn-user-portal/db.sqlite
/var/lib/vpn-server-api/db.sqlite

Copy them to a safe location. If you made any other manual changes to any of the configuration files, you MUST make a backup of this file as well, e.g.:

/etc/apache2/sites-available/vpn.example.org.conf (Apache)
/etc/iptables/rules.v4 (IPv4 firewall)
/etc/iptables/rules.v6 (IPv6 firewall)
/etc/sysctl.d/70-vpn.conf (sysctl)

You MAY also want to backup your TLS key, certificate and chain if you are not using Let’s Encrypt or any other ACME capable certificate authority.

Remove 2.x#

Now we’ll fully remove the 2.x software and deploy the 3.x server with the normal deploy script.

Repository#

Remove all files under /etc/apt/sources.list.d that reference eduVPN or Let’s Connect!. Also remove the files under /etc/apt/trusted.gpg.d that are related to eduVPN.

Software#

Delete all the software we will replace when running the new deploy:

$ sudo apt remove --purge vpn-user-portal vpn-server-api vpn-server-node vpn-maint-scripts vpn-daemon
$ sudo apt autoremove --purge

NOTE: if not all packages were installed, the above command will exit with an error. Remove the packages that you do not have installed from the list of packages to remove, the output of the command will tell you which are not installed, and run it again!

Make sure you also remove any lingering files from /etc/openvpn/server.

Install 3.x#

Now you are ready to follow the the steps to install 3.x. Continue reading below on things you have to consider after deploying 3.x.

Post Upgrade Steps#

Configuration#

This section will help you convert your 2.x configuration to a 3.x configuration. We’ll use the 2.x configuration to selectively update the 3.x configuration in the right place as needed. It is HIGHLY RECOMMENDED that you update the freshly installed configuration file selectively based on the instructions below.

In 3.x the vpn-server-api component no longer exists, and thus the configuration that was previously spread out over vpn-user-portal and vpn-server-api are now consolidated in vpn-user-portal.

In 2.x some credentials were directly specified in the configuration files, this has been replaced by files in 3.x, so the configuration files no longer contain secrets.

Profile Configuration#

You can also compare the “Profile Configuration” documentation for 2.x and 3.x in case you want to clarify some of the options. For completeness sake, there is also a list of configuration changes for the 2.x server since the release of 2.0.0.

In 3.x the vpnProfiles key has been renamed to ProfileList. The profileId is now an option inside the profile and no longer the array “key”. The profileNumber is no longer needed. In 2.x the configuration looks like this for example:

'vpnProfiles' => [
    'foo' => [
        'profileNumber' => 1,
        'displayName' => 'Foo Profile',
        ...
        ...
    ],
],

And in 3.x it will look like this, all other things equal:

'ProfileList' => [
    [
        'profileId' => 'foo',
        'displayName' => 'Foo Profile',
        ...
        ...
    ],
],

As for the individual options, the table below will help you make the conversion:

Option (in 2.x)	Type	Option (in 3.x)	Type
`profileNumber`	`int`	Obsolete	N/A
`displayName`	`string`	`displayName`	`string`
`range`	`string`	`oRangeFour`	`string`
`range6`	`string`	`oRangeSix`	`string`
`hostName`	`string`	`hostName`	`string`
`listen`	`string`	`oListenOn`	`string`
`managementIp`	`string`	`nodeUrl`	`string`
`defaultGateway`	`bool`	`defaultGateway`	`bool`
`blockLan`	`bool`	`oBlockLan`	`bool`
`routes`	`string[]`	`routeList`	`string[]`
`dns`	`string[]`	`dnsServerList`	`string[]`
`dnsDomain`	`string`	`dnsSearchDomainList`	`string[]`
`dnsDomainSearch`	`string[]`	`dnsSearchDomainList`	`string[]`
`clientToClient`	`bool`	Obsolete	N/A
`enableLog`	`bool`	`oEnableLog`	`bool`
`enableAcl`	`bool`	Obsolete	N/A
`aclPermissionList`	`string[]`	`aclPermissionList`	`string[]` or `null`
`vpnProtoPorts`	`string[]`	`oUdpPortList`, `oTcpPortList`	`int[]`
`exposedVpnProtoPorts`	`string[]`	`oExposedUdpPortList`, `oExposedTcpPortList`	`int[]`
`hideProfile`	`bool`	Obsolete	N/A
`tlsOneThree`	`bool`	Obsolete	N/A
`tlsProtection`	`string`	Obsolete	N/A

NOTE: clientToClient is now handled exclusively by the firewall on the VPN server.

Authentication#

The authentication modules have been renamed:

Name (in 2.x)	Name (in 3.x)
`FormPdoAuthentication`	`DbAuthModule`	Documentation
`FormLdapAuthentication`	`LdapAuthModule`	Documentation
`FormRadiusAuthentication`	`RadiusAuthModule`	Documentation
`MellonAuthentication`	`MellonAuthModule`	Documentation
`ShibAuthentication`	`ShibAuthModule`	Documentation
`PhpSamlSpAuthentication`	`PhpSamlSpAuthModule`	Documentation
`ClientCertAuthentication`	`ClientCertAuthModule`	Documentation
N/A	`OidcAuthModule`	Documentation

Please refer to the documentation links and compare your current authentication configuration with the 3.x documentation. There may be minor changes required, but that should be rather obvious. The configuration file itself, i.e. /etc/vpn-user-portal/config.php should also be very helpful and contains information about all options.

Miscellaneous#

Restore Local User Accounts#

Using the sqlite3 command line tool you can migrate your old users database to the new server. Install the sqlite3 package first.

$ sudo sqlite3 /var/lib/vpn-user-portal/db.sqlite

Now attach your 2.x database file:

ATTACH DATABASE "/path/to/2.x/vpn-user-portal/db.sqlite" AS v2;

Delete the user from your new installation that were created during installation:

DELETE FROM main.local_users;

And migrate over the users from the 2.x database to the new one:

INSERT INTO main.local_users SELECT * FROM v2.users;

Finally, detach the database:

DETACH v2

php-saml-sp#

The php-saml-sp software used to be part of the eduVPN / Let’s Connect! repository, but is NOT anymore. So if you want to keep using it, you MUST upgrade to the latest version. Fortunately, there are no configuration changes required and all that is needed is to perform the upgrade.

Add the new repository:

$ curl -s https://repo.php-saml-sp.eu/v2/deb/fkooman+repo@tuxed.net.gpg | sudo tee /usr/share/keyrings/fkooman+repo@tuxed.net.gpg >/dev/null
$ echo "deb [signed-by=/usr/share/keyrings/fkooman+repo@tuxed.net.gpg] https://repo.php-saml-sp.eu/v2/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/php-saml-sp_v2.list >/dev/null

Perform the upgrade:

$ sudo apt update
$ sudo apt dist-upgrade

The latest version makes some dependencies obsolete that can now be deleted as well:

$ sudo apt autoremove --purge