Profile Configuration#

Profiles, are configured in /etc/vpn-user-portal/config.php or as a JSON file in /etc/vpn-user-portal/profiles and can contain many options to support various deployment scenarios. These are described in the table below.

The PHP configuration file itself also contains explanations of all options and their (default) value. This document has some additional explanation and discusses some considerations.

By default, the server only uses the config.php file. To modify any of the options, modify the file mentioned above and look for the ProfileList section, i.e.:

'ProfileList' => [
    [
        'profileId' => 'default',
        'displayName' => 'Default',
        ...
        ...
    ],
],

Every profile has an identifier (profileId) in this case default. It must be unique.

On Fedora you may also need to take a look at the SELinux instructions.

If you want to configure your profile(s) as JSON, only available in vpn-user-portal >= 3.9.7, look here.

Options#

This table describes all available profile configuration options. The “Default” column indicates what the value is if the option is missing from the configuration.

Be careful when changing configuration options. They MAY break existing VPN client connections when not using the native eduVPN / Let’s Connect! applications.

Common#

Common configuration options, independent of the VPN protocol. See WireGuard and OpenVPN for protocol specific options.

Profile ID#

The profile ID is used to uniquely identify a profile. It can only contain letters, [a-z], numbers [0-9] and the dash (-). Examples of valid profile IDs identifiers are employees, students, admin. It MUST NOT be numeric, e.g. 1, or 214.

Display Name#

Specify the name you want to give this profile. This will be visible to the users and allows them to determine which protocol to select if more than one is available.

Host Name#

This is the DNS name that VPN clients will use to connect to the VPN server. It is highly recommended that you make the profile ID part of the DNS name to allow for effective load balancing, or moving profiles to different servers. As an example, if your profile has the name employees, your DNS name could be employees.vpn.example.org. Obviously, you can make this a CNAME to vpn.example.org as long as you have only one server.

Default Gateway#

This option allows you to indicate to the VPN client that all their traffic needs to be sent over the VPN.

DNS Server List#

Provide a list of DNS servers to your VPN clients, as an example:

'dnsServerList' => ['9.9.9.9', '2620:fe::9'],

The DNS server list is provided to the VPN clients when either of the following conditions hold:

1. Default Gateway is set;
2. Default Gateway is not set, but DNS Search Domain List is.

NOTE: when Default Gateway is set and DNS servers are configured, on Windows, traffic to DNS servers outside the VPN will be explicitly blocked in order to prevent DNS leaks.

NOTE: make sure the DNS server(s) you provide are reachable by the clients, so you MAY have to add the addresses to Route List when they are not usable from outside the VPN.

NOTE: with vpn-user-portal >= 3.1.6 you can use the placeholder values @GW4@ and @GW6@ that will be replaced by the address of the VPN gateway. This is especially helpful if you have multiple OpenVPN processes in one profile that want to use the DNS resolver running on the VPN server. This restores behavior that was available in the 2.x server. In order to configure this see Local DNS.

Public DNS Providers#

If you are looking for public DNS providers, we are aware of the following ones. We can’t vouch for any of them, obviously.

• dns0.eu (Strictly EU based, claims GDPR compliancy)
• Quad9
• Cloudflare
• Google Public DNS
• DNS.WATCH

Route List#

If you are not using the VPN as a Default Gateway you can specify the routes for which the VPN client needs to use the VPN. You use this in the scenario that some internal services need to be reachable by your VPN clients, but you do not want all of the client’s traffic over the VPN.

Example:

'routeList' => ['10.223.140.0/24', 'fc5b:7c64:3001:a95f::/64'],

Exclude Route List#

This is the opposite of Route List. Here you list all prefixes that are not supposed to go over the VPN. There are two uses cases for this:

1. Route all traffic over VPN, i.e. Default Gateway, except the prefixes listed here. This can be used to e.g. not send traffic to a “cloud” video conferencing solution over the VPN, but send it direct;
2. Do not send traffic to a subset of the prefixes sent using Route List over the VPN.

Example: send all traffic over the VPN, except traffic to Quad9’s DNS:

'defaultGateway' => true,
'excludeRouteList` => ['9.9.9.9/32', '149.112.112.9/32', '2620:fe::9/128', '2620:fe::fe:9/128'],

As another, somewhat contrived, example that makes clear how it would work:

'defaultGateway' => false,
'routeList' => ['10.223.140.0/24', 'fc5b:7c64:3001:a95f::/64'],
'excludeRouteList' => ['10.223.140.5/32', 'fc5b:7c64:3001:a95f::1234/128'],

As of 2022-07-20 this does NOT work everywhere. It works only without issues on Windows (both OpenVPN and WireGuard). It does NOT work properly on the rest of the OSes:

• –route-ipv6 does not recognize net_gateway or net_gateway-ipv6 (OpenVPN)
• Add net_gateway / net_gateway_ipv6 gateway flag for –route and –route-ipv6 (OpenVPN)
• “excluded routes” does not work (WireGuard)

Permission List#

Restrict access to VPN profiles based on user permissions. The authentication module can make permissions available either through LDAP or SAML that can be used to restrict access to a profile. See Permissions for extensive documentation on the topic.

DNS Search Domain List#

Allow you to specify the “Connection-specific DNS Suffix Search List” for the VPN client, e.g.:

'dnsSearchDomainList' => ['example.org', 'example.com'],

NOTE: the search domains are ONLY sent when DNS servers are specified.

Node URL#

When using a separate system to handle VPN connections, i.e. when using a controller + node(s) setup. See Multi Node for extensive documentation on the topic.

On Node#

When deploying profile(s) to multiple nodes you may want to indicate to which specific node(s) the profile belongs. For example, if you have 4 nodes and you want to deploy a profile only to node 2 and 3, use the following:

'onNode' => [2, 3],

If you do NOT specify the onNode option, it will default to 0 if there is only one node defined, or if there are multiple nodes start counting from 0, i.e. if you have two nodes defined, the default will be [0, 1].

This option is available from vpn-user-portal >= 3.0.6. It was added due to a bug that did not allow deploying profiles to only a subset of nodes. Unfortunately we can not break existing configurations, so we needed to introduce a new option specifically for this case.

Preferred Protocol#

When your profile supports multiple protocols, this option can be used to set the preferred protocol. This allows for example to transitioning (the majority of users) from OpenVPN to WireGuard without breaking existing configurations.

The preferred protocol only makes sense when both OpenVPN and WireGuard are enabled. If only one protocol is enabled, that is automatically the preferred protocol.

OpenVPN is considered enabled when both oRangeFour and oRangeSix are set. WireGuard is considered enabled when both wRangeFour and wRangeSix are set.

Hide Profile#

It is possible to hide VPN profiles from the portal and from the API, i.e. do not show them to the users so they can’t download the VPN configuration.

The main use case for this is that you can use the Admin API to download VPN configurations, for example for managed devices, but that the users themselves can NOT download such profiles.

The profiles, once downloaded DO show up in the list of configurations in the portal on the “Home” page, and the user CAN revoke them.

WireGuard#

WireGuard specific configuration options.

We wrote some additional documentation on WireGuard here.

WireGuard Range Four#

Specify the IPv4 range for WireGuard VPN clients. As an example:

'wRangeFour' => '172.24.110.0/24',

Make sure the specified range is unique, and not used by any other profile/protocol, nor overlap the range specified in another profile/protocol! Look here if you want to generate a unique prefix.

NOTE: the UDP port used by WireGuard is 51820 and can be modified by changing the listenPort option under the WireGuard section in /etc/vpn-user-portal/config.php. This port is “global” and NOT per profile.

WireGuard Range Six#

Specify the IPv6 range for WireGuard VPN clients. As an example:

'wRangeSix' => 'fd99:ede1:b56d:f19e::/64',

Make sure the specified range is unique, and not used by any other profile/protocol, nor overlap the range specified in another profile/protocol! Look here if you want to generate a unique prefix.

WireGuard Keepalive#

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

This option allows VPN clients to keep the WireGuard connection “up”, even if there’s currently no traffic flowing.

When a device is behind NAT, or a firewall, it MAY not be possible to reach the client without the client actively sending traffic over the VPN. This occurs for example in “split tunnel” VPNs when only a subset of the client’s traffic is sent over the VPN.

If you want to remotely manage devices over the VPN, or you want VPN clients to be able to talk to each other, you want their VPN connection to be up as much as possible.

NOTE: this option MAY or MAY NOT override a device’s power management, i.e. the device can still decide to go to sleep, making the device unreachable.

NOTE: ONLY enable this when strictly necessary, i.e. if you MUST have the client be online as much as possible.

OpenVPN#

OpenVPN specific configuration options.

OpenVPN Range Four#

Specify the IPv4 range for OpenVPN VPN clients. As an example:

'oRangeFour' => '172.18.131.0/24',

Make sure the specified range is unique, and not used by any other profile/protocol, nor overlap the range specified in another profile/protocol! Look here if you want to generate a unique prefix.

OpenVPN Range Six#

Specify the IPv6 range for OpenVPN VPN clients. As an example:

'oRangeSix' => 'fdb4:2da1:2f15:a488::/64',

Make sure the specified range is unique, and not used by any other profile/protocol, nor overlap the range specified in another profile/protocol! Look here if you want to generate a unique prefix.

OpenVPN Block LAN#

This OpenVPN only option prevents the client from accessing devices on the local network. This is especially useful when the client is connected to a network that also contains clients that are not to be trusted, e.g. (semi) public WiFi.

'oBlockLan' => true,

OpenVPN Enable Log#

This OpenVPN only option enables OpenVPN server logging. This can be used to debug (some) connection issues with incompatible clients.

'oEnableLog' => true,

Once logging is enabled (and changes applied), you can follow the log like this:

$ sudo journalctl -f -t openvpn

NOTE: this option should probably only be enabled on test systems and not in production.

OpenVPN Port List#

List of UDP/TCP ports to be used by the OpenVPN processes. The IP ranges OpenVPN Range Four and OpenVPN Range Six will be evenly distributed over both UDP Port List and TCP Port List.

'oUdpPortList' => [1194, 1195, 1196],
'oTcpPortList' => [1194],

Assuming your oRangeFour is 172.18.131.0/24 and your oRangeSix is fdb4:2da1:2f15:a488::/64, four processes will be created that with the following IP ranges:

NOTE: depending on the expected VPN usage, you should aim for a /25 or /26 for every process.

NOTE: the provided oRangeSix is always split in networks of size /112, the “smallest” network supported by OpenVPN.

NOTE: the total number of ports combining oUdpPortList and oTcpPortList specified MUST be a power of 2, e.g. 1, 2, 4, 8, 16, 32 or 64.

NOTE: you should aim for around 75% UDP processes, and 25% TCP processes for optimal performance for most clients.

See also: Port Sharing, Multi Profile.

OpenVPN Exposed Port List#

TBD.

OpenVPN Listen Address#

You can configure the OpenVPN processes to listen on a specific IPv4 or IPv6 address. This MAY be helpful in certain network configurations where a proper configuration using Source Routing is not possible.

By using this option your VPN clients lose the ability to connect over IPv4 or IPv6 support. The default is :: which allows connecting over both IPv4 and IPv6.

Example:

'oListenOn' => '10.5.5.7',

NOTE: using this option is NOT recommended and should be avoided if possible.

NOTE: you can also specify an array of IP addresses when running >= 3.0.1, this allows you to specify an IP per node when using multiple nodes.

JSON#

In vpn-user-portal >= 3.9.7 you can also configure your VPN profiles in a JSON file. This has the advantage of being able easily generate the profile configuration from some other source and not having to fiddle with PHP. All options mentioned on this page translate directly to JSON as well. As an example, instead of having the default profile in /etc/vpn-user-portal/config.php, you can remove it from the ProfileList section, and put it in /etc/vpn-user-portal/profiles/default.json with the following content:

{
    "displayName": "Default",
    "dnsServerList": [
        "9.9.9.9",
        "2620:fe::fe"
    ],
    "hostName": "vpn.example",
    "oRangeFour": "10.42.42.0/24",
    "oRangeSix": "fd42::/64",
    "profileId": "default",
    "wRangeFour": "10.43.43.0/24",
    "wRangeSix": "fd43::/64"
}

Make sure the JSON syntax is correct, otherwise you will (for now) get a really bad error message like Syntax error without any additional context. To check the syntax of the JSON and sort + format it, you can e.g. use:

$ cat default.json | jq -S --indent 4

Apply Changes#

To apply the configuration changes:

$ sudo vpn-maint-apply-changes

Generate Prefix#

If you’d like to generate some random IP prefixes for VPN clients, you can use the following command:

/usr/libexec/vpn-user-portal/generate-prefix

The command supports the -4 and -6 flags to only generate an IPv4 (or IPv6) prefix. See --help for more flags.