Skip to main content

Tutorial: Learn to Install and Control the OpenVPN 3 Client

Abstract

This tutorial shows how to install the OpenVPN 3 client on various Linux distributions. In addition, commands to control the client are documented.

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 for the 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 project's primary focus.

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).

Table 1. Supported Distributions

Distribution

Release

Release Name

($DISTRO)

Architecture

Debian

11

bullseye

amd64, arm64[a]

Debian

12

bookworm

amd64, arm64[a]

Fedora[b]

-

-

Recent stable releases

Red Hat Enterprise Linux

8

-

aarch64[a], ppc64le[c], s390x[c], x86_64

Red Hat Enterprise Linux

9

-

aarch64[a], ppc64le[c], s390x[c], x86_64

Ubuntu

20.04

focal

amd64, arm64[a]

Ubuntu

22.04

jammy

amd64, arm64[a]

Ubuntu

24.04

noble

amd64, arm64[a]

[a] ARM64/aarch64 architectures are in tech preview.

[b] We support the most recent stable Fedora releases. Fedora release cadence information.

[c] These aren't fully supported; they are only available via the Fedora Copr repositories. Consider them tech-preview.



Installation for Debian and Ubuntu

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

  1. Open the Terminal by pressing ctrl + alt + T and run the following commands in it.

  2. Install the OpenVPN repository key used by the OpenVPN 3 Linux packages:

    sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.openvpn.net/packages-repo.gpg | sudo tee /etc/apt/keyrings/openvpn.asc

  3. Run this command to obtain the Linux distribution-specific information and assign it to the DISTRO variable for use in the next step:

    DISTRO=$(lsb_release -c -s)

    Important

    We recommend that you're cautious about 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.

  4. Install the proper repository:

    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

  5. Fetch the latest package information:

    sudo apt update

  6. Install the OpenVPN 3 package:

    sudo apt install openvpn3

Installation for Fedora, Red Hat Enterprise Linux, AlmaLinux, or Rocky Linux

Packages for these distributions are provided via a Fedora Copr repository. For supported release versions, refer to the table above.

To install the OpenVPN 3 Client for Fedora, Red Hat Enterprise Linux, AlmaLinux, or Rocky Linux:

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

  2. For Red Hat Enterprise Linux, install the Fedora EPEL repository:

    • RHEL 8:

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

      And enable the codeready-builder-for-rhel-8-${ARCH}-rpms repository because some EPEL packages may depend on it:

      sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-$(/bin/arch)-rpms"

    • RHEL 9:

      sudo yum localinstall https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

    • Rocky/Alma:

      sudo yum install epel-release

      • Rocky 8 / Alma 8: And enable the PowerTools repository because some EPEL packages may depend on it:

        sudo yum config-manager --set-enabled powertools

  3. Install the OpenVPN 3 repository:

    • RHEL, AlmaLinux, and Rocky Linux:

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

    • Fedora:

      sudo yum copr enable dsommers/openvpn3

  4. Install the OpenVPN 3 Linux client:

    • RHEL, AlmaLinux, Rocky Linux, and Fedora:

      sudo yum install openvpn3-client

Using .ovpn Profile

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

Run these list items:

  1. Download a connection profile and import it into the Configuration Manager:

    $ openvpn3 config-import --config /file/to/profile.ovpn --name CloudConnexa1 --persistent2

    1

    This stores the file under the name CloudConnexa.

    2

    This flag ensures the connection profile is preserved when the system reboots.

    Tip

    This command can be run by an ordinary, unprivileged user on the system; the user who runs this command becomes the owner of the configuration profile.

  2. Grant the root user access to the imported CloudConnexa connection profile:

    $ openvpn3 config-acl --show --lock-down true1 --grant root --config CloudConnexa

    1

    The --lock-down true argument is optional, but restricts the root user from extracting the contents of the connection 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.

    Start the VPN session and create the necessary symlinks in system directories to ensure the service starts whenever the system reboots:

    $ sudo systemctl enable --now1 openvpn3-session2@CloudConnexa3.service

    1

    The --now arguments instructs systemd to start the session immediately.

    2

    This is the OpenVPN session service, openvpn3-session.

    3

    The connection profile name, CloudConnexa.

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 connection profile ACL has --transfer-owner-session enabled, the end-user can also manage the VPN session completely without needing root privileges.

Mandatory Commands

  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)

Optional Commands

  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.

Managing a Running Session

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

    openvpn3 sessions-list

  2. Using the openvpn3 session-manage, a few things can be done, but most typically, the --disconnect or --restart alternatives are most commonly used.

    • Disconnect and reconnect to the server, re-establishing the connection:

      openvpn3 session-manage --config ${CONFIGURATION_PROFILE_NAME1} --restart

      1

      The ${CONFIGURATION_PROFILE_NAME} is the configuration name displayed in the openvpn3 sessions-list.

  3. Use the D-Bus path to the session. Disconnect a running session:

    openvpn3 session-manage --session-path /net/openvpn/v3/sessions/..... --disconnect

    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.

    • Once this operation has been completed, it will be removed from the openvpn3 sessions-list overview.

  4. 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. Retrieve real-time log events as they occur:

    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

Changing the Profile of an Autoloading VPN Session

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!

In this section: