Skip to main content

OpenVPN 3 Client for Linux

Abstract

General reference guide for installing and operating openvpn3 client on various Linux distributions.

Note

This document is a reference document for OpenVPN 3 Linux client. CloudConnexa Connector for Linux uses OpenVPN 3. Deploying Connector for CloudConnexa is covered separately here.

The OpenVPN 3 Linux project is a new client built on top of the OpenVPN 3 Core Library, which is also used in the various OpenVPN Connect clients. For more information on the project, refer to the Community Wiki.

This client is built around a completely different architecture regarding usage. It builds heavily on D-Bus and allows unprivileged users to start and manage their own VPN tunnels out-of-the-box. System Administrators wanting more control can also control and restrict this access both by hardening the default OpenVPN 3 D-Bus policy or facilitating features in OpenVPN 3 Linux.

Even though the project name carries “Linux,” it doesn’t mean it is restricted to Linux only. Any platform with D-Bus available should be capable of running this client theoretically. However, since D-Bus is most commonly used in Linux environments, this will naturally be the primary focus of the project.

The release notes are stored in git tags in the project git repository. They can also be viewed here: https://github.com/OpenVPN/openvpn3-linux/releases (expand the tag to see the full text).

Follow these steps to install OpenVPN 3 Client on Linux for Debian and Ubuntu:

  1. Open the Terminal by pressing ctrl + alt + T.

  2. Type the following command into the Terminal: sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.openvpn.net/packages-repo.gpg | sudo tee /etc/apt/keyrings/openvpn.asc. This will install the OpenVPN repository key used by the OpenVPN 3 Linux packages.

  3. Type the following command into the Terminal: DISTRO=$(lsb_release -c | awk '{print $2}'). This will detect the OS distribution and automatically be used in the following command.

    Important

    It is recommended to be cautious of the distribution and release you are running. Distribution and version should preferably be retrieved using the hostnamectl command, where the User needs to link the Operating System field with the table of the supported distribution.

    Table 1. Debian and Ubuntu Supported Distributions

    Distribution

    Release

    Release Name

    ($DISTRO)

    Debian

    10

    buster

    Debian

    11

    bullseye

    Ubuntu

    18.04

    bionic

    Ubuntu

    20.04

    focal

    Ubuntu

    22.04

    jammy



  4. Type the following command into the Terminal. echo "deb [signed-by=/etc/apt/keyrings/openvpn.asc] https://packages.openvpn.net/openvpn3/debian $DISTRO main" | sudo tee /etc/apt/sources.list.d/openvpn-packages.list This will install the proper repository.

  5. Type the following command into the Terminal: sudo apt update

  6. Type the following command into the Terminal: sudo apt install openvpn3. This will finally install the OpenVPN 3 package.

Packages for these distributions are provided via a Fedora Copr repository. Supported release versions for Fedora are releases 30, 31, and 32. Supported release versions for Red Hat Enterprise Linux / CentOS are releases 7 and 8.

To install the OpenVPN 3 Client for Fedora, Red Hat Enterprise Linux, CentOS, or Scientific Linux, follow the list items below:

  1. Open Terminal by typing Terminal into the search bar.

  2. If you are running Red Hat Enterprise Linux or its clones, you must install the Fedora EPEL repository first. Here is the list of commands for each version: (The original article on Fedora EPEL can be found here.)

    RHEL/CentOS 7: sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

    On RHEL 7, it is also recommended to enable the optional, extras, and HA repositories since EPEL packages may depend on packages from these repositories: sudo subscription-manager repos --enable "rhel-*-optional-rpms" --enable "rhel-*-extras-rpms" --enable "rhel-ha-for-rhel-*-server-rpms

    RHEL/CentOS 8: sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

    On RHEL 8, it is required to also enable the codeready-builder-for-rhel-8-${ARCH}-rpms repository since EPEL packages may depend on packages from it: sudo ARCH=$( /bin/arch ) followed by sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms

    On CentOS 8, it is also recommended to enable the PowerTools repository since EPEL packages may depend on packages from it: sudo dnf config-manager --set-enabled PowerTools

  3. RHEL7:

    sudo yum install -y https://packages.openvpn.net/openvpn-openvpn3-rhel7-repo-1-1.noarch.rpm

  4. RHEL 8, RHEL 9, CentOS 7, CentOS Stream 8, CentOS Stream 9:

    sudo yum install -y https://packages.openvpn.net/openvpn-openvpn3-epel-repo-1-1.noarch.rpm

  5. Finally, the OpenVPN 3 Linux client can be installed by running the following command: sudo yum install openvpn3-client

Please note that by this point, you should have downloaded a .ovpn profile to your machine.

Run these list items:

  1. $ openvpn3 config-import --config /file/to/profile.ovpn --name CloudConnexa --persistent

    This takes a downloaded configuration file and imports it into the Configuration Manager, storing it under the name CloudConnexa. The --persistent flag ensures the configuration file is preserved when the system is rebooted. This command can be run as an ordinary, unprivileged user on the system; the User running this command becomes the owner of the configuration profile.

  2. $ openvpn3 config-acl --show --lock-down true --grant root --config CloudConnexa

    This grants the root user access to the imported CloudConnexa configuration profile. The --lock-down true argument is optional, but it restricts the root user from extracting the content of the configuration profile via the openvpn3 commands (or via D-Bus APIs).

    By adding --transfer-owner-session true to the command above, the current User running this command (the owner of the Profile) also becomes the “VPN session owner” if the root is the User starting the VPN session (typically via the systemd openvpn3-session@.service).

  3. $ sudo systemctl enable --now openvpn3-session@CloudConnexa.service

    This tells systemd to enable an OpenVPN session service (openvpn3-session) to be started when the system is booting, using the configuration profile name CloudConnexa. The --now argument also instructs systemd to start the session instantly.

At this point, the OpenVPN session can be managed via either the systemctl command using the openvpn3-session@CloudConnexa.service or using the openvpn3 session-manage, openvpn3 session-acl and openvpn3 sessions-list commands.

If the configuration profile ACL has --transfer-owner-session enabled, the end-user will also be able to manage the VPN session completely without needing root privileges.

  1. To start a one-shot configuration Profile, type the following command into the Terminal: openvpn3 session-start --config ${MY_CONFIGURATION_FILE}

    Important

    A one-shot configuration Profile means that the configuration file is parsed, loaded, and deleted from the configuration manager as soon as the VPN session has been started. No configuration file is available for re-use after this approach. This is achieved by giving the configuration file to the openvpn3 session-start command directly.

  2. To import a configuration file for re-use and start a VPN session, type the following command into the Terminal: openvpn3 config-import --config ${MY_CONFIGURATION_FILE}.

    Note

    Using this approach, an imported configuration file can be used several times, and access to the configuration file itself is not needed to start VPN tunnels. By default, configuration profiles imported are only available to the User who imported the configuration file. But OpenVPN 3 Linux also provides an Access Control List feature via openvpn3 config-acl to grant access to specific or all users on the system.

    Important

    This loads the configuration Profile and stores it in memory only. That means if the system is rebooted, the configuration Profile is not preserved. If the –persistent argument is added to the command line above, the configuration Profile will be saved to disk in a directory only accessible by the User. Whenever the Configuration Manager is started, configuration files imported with –persistent will be automatically loaded as well.

  3. To start a new VPN session from an imported configuration Profile, run the following command: openvpn3 session-start --config ${CONFIGURATION_PROFILE_NAME}

    Note

    When a configuration Profile is available via openvpn3 configs-list, it can quickly be started via openvpn3 session-start using the configuration Profile name (typically the filename used during the import)

  1. To list all available configuration profiles, run this command: openvpn3 configs-list.

    Important

    A configuration file typically contains generic options to connect to a specific server, regardless of the Device itself. OpenVPN 3 Linux also supports setting more Host-specific settings on a configuration Profile. This is handled via the openvpn3 config-manage interface. Any settings here will also be preserved across boots if the configuration Profile was imported with the --persistent argument.

  2. Note that it is possible to use the D-Bus path to the configuration Profile: openvpn3 session-start --config-path /net/openvpn/v3/configuration/..

    Note

    In either of these cases, it is necessary to have access to the configuration Profile on disk. As long as configuration profiles are available via openvpn3 configs-list, all needed to start a VPN session should be present.

  1. Once a VPN session has started, it should be seen in the session list: openvpn3 sessions-list.

  2. Using the openvpn3 session-manage , there are a few things that can be done, but most typically, it is the –disconnect or –restart alternatives that are most commonly used. openvpn3 session-manage --config ${CONFIGURATION_PROFILE_NAME} --restart. This disconnects and re-connects to the server again, re-establishing the connection. The ${CONFIGURATION_PROFILE_NAME} is the configuration name displayed in the openvpn3 sessions-list.

  3. It is also possible to use the D-Bus path to the session: openvpn3 session-manage --session-path /net/openvpn/v3/sessions/..... --disconnect. This command above will disconnect a running session. Once this operation has been completed, it will be removed from the openvpn3 sessions-list overview.

    Important

    You can start a new session with this or another OpenVPN Profile only after disconnecting from the current session using the command in this listitem.

  4. It is also possible to retrieve real-time tunnel statistics from running sessions: openvpn3 session-stats --config ${CONFIGURATION_PROFILE_NAME} or openvpn3 session-stats --session-path /net/openvpn/v3/sessions/...

  5. To retrieve real-time log events as they occur, run the following command: openvpn3 log --config ${CONFIGURATION_PROFILE_NAME}. This might be quite silent, as it does not provide any log events from the past. Issue an openvpn3 session-manage –restart from a different terminal, and log events will occur. You may want to boost the log-level with –log-level 6. Valid log levels are from 0 to 6, where 6 is the most verbose.

    Note

    VPN sessions are also owned by the User who started them. But the Session Manager also provides its own Access Control List feature via openvpn3 session-acl

Note

This section is valid only for RHEL-7. Please refer to Using .ovpn Profile for all other distributions.

Please note that every time you start a session, it will load automatically on the system start-up. To change the Profile of a VPN Session that is autoloaded, follow the list items below:

  1. Run the command: sudo openvpn3 sessions-list. It will show information about your active session. Check the value of the Path parameter.

  2. Run the command: sudo openvpn3 session-manage --session-path YOUR_PATH --disconnect, where YOUR_PATH is the value of the Path parameter from list item 1.

  3. Run the command: sudo openvpn3 sessions-list. You shouldn’t see any active sessions.

  4. Run the command: sudo openvpn3 configs-list. It will show information about your active configurations. Check the name assigned to your active config.

  5. Run the command: sudo openvpn3 config-remove --config "YOUR_CONFIG_NAME", where YOUR_CONFIG_NAME is the name of the configuration file from list item 4. You will be asked to confirm the removal of the configuration. Type YES (in uppercase) to confirm.

  6. Run the command: sudo openvpn3 configs-list. You shouldn’t see any active configurations.

  7. Run the command: sudo nano /etc/openvpn3/autoload/Connector.conf. This is the Profile that will be replaced.

  8. Press Ctrl + End, then hold ctrl + shift + ↑ until the whole file is highlighted, and finally, press ctrl + K.

  9. Open the Profile you wish to use instead of the existing one. Press Ctrl + A and then ctrl + C.

  10. Then go back to the Terminal, press the right mouse button, and choose Paste. Notice the difference between the old and the new Profile.

  11. Once you’ve replaced the Profile, press ctrl + X and confirm changes by typing y and pressing Enter.

  12. You can run cat /etc/openvpn3/autoload/Connector.conf to check the changes are saved.

  13. Run the command: sudo openvpn3 config-import --config /etc/openvpn3/autoload/Connector.conf --name "YOUR_CONFIG_NAME"

  14. Run the command: sudo openvpn3 session-start --config "YOUR_CONFIG_NAME."

  15. Run the command: sudo openvpn3 sessions-list. It will show that a new session is active and connected.

  16. Restart the computer and check if the autostart Profile has indeed been changed. Just run the sudo openvpn3 sessions-list command once again. Certainly, the autoload is now set for the new Profile!