Documentation

Server 3.x

Portal Configuration#

This document explains all configuration options that do not belong to profile specific configuration as documented separately in Profile Config.

The default template for the configuration file of the VPN user portal can be found here.

It is this template that is used during installation and you can modify as an admin. It is available under /etc/vpn-user-portal/config.php.

Below we’ll discuss all the configuration options in their relevant sections. As mentioned, the VPN profile configuration is already documented here.

Style#

You can style the VPN portal by setting the styleName option. Currently, two styles are available, eduVPN for eduVPN and LC for Let’s Connect!.

The styles are not installed by default, but you can install them by installing the package vpn-portal-artwork-eduvpn / vpn-portal-artwork-lc on Debian/Ubuntu and vpn-portal-artwork-eduVPN / vpn-portal-artwork-LC on Fedora/EL.

Example:

'styleName' => 'eduVPN',

If you want to implement your own (custom) branding, you can look here on how to do that.

Session Expiry#

We have separate documentation for session expiry, look here.

Database#

You can switch to using another database if you do not want to use the default SQLite. We documented this separately.

Authentication#

We support various user authentication mechanisms. We document all of them separately:

Please follow the instructions there.

Permissions#

Access to the portal can be restricted in different ways. They are documented separately:

Portal Language#

The portal is translated in a wide number of languages. You can set the default language of the portal, and the available languages. The user can switch languages if more than one is configured.

Example:

'enabledLanguages' => ['nl-NL', 'en-US'],
'defaultLanguage' => 'en-US',

If you want to contribute translations, you can find out how to do that here.

Show Permissions#

Previous server versions would show the user’s permissions as conveyed through the authentication mechanism, e.g. SAML or LDAP attribute values.

This has been disabled by default now. You can enable it again:

'showPermissions' => true,

Maximum Number of Active Configurations#

Here you can configure how many configurations can be active at the same time, when the user manually downloads configurations through the VPN Portal. The default is 3. You can set it to 0 if you want to disable manual VPN configuration downloads and want to force the user to use the VPN client applications through the API.

Example:

'maxActiveConfigurations' => 5,

NOTE: this is independent from the maximum number of active configurations obtained through the API! See here for restricting the number of active configurations through the API.

Maximum Number of Active API Configurations#

Limit the number of active VPN configurations obtained through the API that is used by the eduVPN/Let’s Connect! VPN applications. Effectively this means that the user can have this many VPN apps connected simultaneously.

'Api' => [
    'maxActiveConfigurations' => 3,
],

The user can authorize as many VPN clients as they want, but the number of active simultaneous connections is limited by this value. If set to 3, and a 4th client attempts to connect, the client that was connected the longest will automatically be disconnected.

App Gone Interval#

When VPN clients use the API, they have to call the /disconnect API endpoint when disconnecting from the VPN. This does not always happen, and can result in “lingering” IP allocations for WireGuard. This is a problem when there is limited IP space for WireGuard clients, e.g. when using Public IPv4 addresses.

In order to mitigate this somewhat, we introduced the appGoneInterval API configuration setting which indicates when a VPN client can be considered “gone”. If no activity at all has been seen from a VPN client in (by default) 72 hours, the IP allocation will be released. If the client still is alive after 72 hours, the user will have to (currently) manually reconnect their VPN client.

'Api' => [
    'appGoneInterval' => 'PT72H',
],

NOTE: this ONLY applies when using eduVPN/Let’s Connect! clients, never for configuration files manually downloaded through the portal.

App Sets#

NOTE: available in vpn-user-portal >= 3.5.2

It is also possible to configure the (type) of applications that have access to your VPN server. By default both the official eduVPN and Let’s Connect! applications will be allowed with a server. You can configure which ones have access.

Set Description Enabled by Default
eduVPN eduVPN Yes
LC Let’s Connect! Yes
govVPN govVPN No

The default, if not specified, is this:

'Api' => [
    'appSets' => ['eduVPN', 'LC'],
],

To only allow the eduVPN applications:

'Api' => [
    'appSets' => ['eduVPN'],
],

WireGuard#

Option Type Default
listenPort int 51820
setMtu int N/A
enableProxy bool false
proxyUrl string See Below
onlyProxy bool false
allowExpiryExtension bool false

You can configure the WireGuard port over which VPN clients can connect to the WireGuard service. The default is 51820. Native WireGuard only supports UDP so there is no need to specify the IP protocol.

A good alternative would be to set it to port 443, which is also used by the new HTTP over QUIC protocol which may increase the chances the traffic is not blocked by firewalls.

Example:

'WireGuard' => [
    'listenPort' => 443,
],

NOTE: if you modify the listenPort and also use WireGuard over TCP, you MUST also update the ProxyGuard configuration key TO to point to the right port, e.g. TO=127.0.0.1:443. more information can be found here.

If you want to set the MTU for WireGuard connections, please go here to read about all details.

To enable WireGuard over TCP. You need to set enableProxy to true and (optionally) set the proxyUrl parameter. The default value of proxyUrl is the server name, with /proxyguard postfix. For example, if you server name is vpn.example.org, the default will be https://vpn.example.org/proxyguard.

See Wireguard over TCP for all details as to what is required to make WireGuard over TCP work.

In vpn-user-portal >= 3.7.0 you can disable WireGuard over UDP and require VPN clients to use the TCP Proxy. Use the onlyProxy configuration option for this.

In vpn-user-portal >= 3.9.3 you can allow users to “extend” the validity of their WireGuard manual portal configuration downloads when they log into the portal, without requiring them to download a new configuration file and re-configuring their VPN client.

See also App Gone Interval.

NOTE: make sure you update the firewall if you change the port!

Session Module#

If you are using a HA Portal setup configuration for your portal you should switch to a different session mechanism. This is documented here.

Script Connection Hook#

NOTE: this is a Preview Feature! It is NOT yet officially supported and meant for testing only!

Added: 3.0.4 (#84)

You can run a script after a VPN client connects and/or disconnects. This is documented here.

Remove Authorization on Disconnect#

NOTE: this is a Preview Feature! It is NOT yet officially supported and meant for testing only!

Added: 3.0.5 (#78)

The server can delete the OAuth authorization as used for server API access by the eduVPN/Let’s Connect! applications.

This would force the user to authorize (and thus authenticate) again the next time a VPN connection is established. This may be particularlly interesting for organization that have MFA enabled and want to force users to authenticate every time they connect to the VPN.

You can enable this in /etc/vpn-user-portal/config.php:

'Api' => [
    'deleteAuthorizationOnDisconnect' => true,
],

The authorization is ONLY deleted when the user manually disconnects, closes the VPN application, or reboots the system. System suspend, or (temporary) loss of network connectivity will NOT force the user to authorize the application again!

Caveats#

Last Modified: 2024-10-29

Source | History