Skip to main content

Tutorial: Learn to Install and Control the OpenVPN 3 Client

Abstract

Install the OpenVPN 3 Linux client on your distribution, import your CloudConnexa connection profile, and connect — either as a one-time session or as a persistent autostarting service.

Overview

Important

This tutorial is for end users connecting an individual Linux device to CloudConnexa. If you're setting up a CloudConnexa Connector on a headless Linux server to connect an entire network, use the openvpn-connector-setup tool instead. Refer to Tutorial: Install a Connector on Linux.

This tutorial shows you how to install the OpenVPN 3 Linux client, import your CloudConnexa connection profile, and establish a VPN connection — either as a manual session or as a persistent service that starts automatically at boot.

Before you begin

Ensure you have the following to start this tutorial:

Which setup is right for you?

I want to...

Go to...

Connect my device to CloudConnexa manually or occasionally

Steps 1-3, then Option A

Set up an always-on connection that starts automatically at boot

Steps 1-3, then Option B

Step 1: Install the OpenVPN 3 client

Select the instructions for your Linux distribution.

Debian and Ubuntu

  1. Open a terminal or connect to your server via SSH.

  2. Install the OpenVPN repository key:

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

  3. Detect your distribution and assign it to a variable:

    DISTRO=$(lsb_release -c -s)

    Important

    Verify your distribution and release before proceeding. We recommend using hostnamectl to confirm your OS details and cross-reference with the supported distributions table above.

  4. Add the OpenVPN 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. Update the package list:

    sudo apt update

  6. Install the OpenVPN 3 client:

    sudo apt install openvpn3

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

  1. Open a terminal or connect to your server via SSH.

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

    • RHEL 8:

      sudo yum localinstall https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
   sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-$(/bin/arch)-rpms"

    • RHEL 9:

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

    • Rocky Linux or AlmaLinux:

      sudo dnf install epel-release

    • Rocky 8 or AlmaLinux 8 only — also enable the PowerTools repository:

      sudo dnf config-manager --set-enabled powertools

  3. Install the OpenVPN 3 repository:

    • RHEL 8:

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

    • RHEL 9, AlmaLinux, and Rocky Linux:

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

    • Fedora:

      sudo dnf copr enable dsommers/openvpn3

  4. Install the OpenVPN 3 client:

    • RHEL 8:

      sudo yum install openvpn3-client

    • RHEL 9+, Fedora:

      sudo dnf install openvpn3-client

Step 2: Import your connection profile

  1. Import your .ovpn connection profile into the OpenVPN 3 configuration manager, replacing /file/to/profile.ovpn with the path to your profile file:

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

    1

    --name CloudConnexa assigns a name to the profile so you can reference it in later commands.

    2

    --persistent saves the profile to disk so it's available after a reboot. Without this flag, the profile is stored in memory only and is lost when the system restarts.

    Tip

    This command can be run as an ordinary, unprivileged user. The user who runs this command becomes the owner of the connection profile. By default, the profile is only accessible to that user. To grant other users access, including root for autostart setups, use openvpn3 config-acl. See Step 3, Option B for details.

  2. Verify the profile was imported successfully:

    openvpn3 configs-list

    • Your profile should appear in the list.

Step 3: Connect to CloudConnexa

Choose the option that fits your needs.

Option A — Manual connection (single user)

Use this option if you want to manually start and stop the VPN connection.

  1. Start a VPN session using your imported profile:

    openvpn3 session-start --config CloudConnexa

  2. Verify the session is running:

    openvpn3 sessions-list

  3. To disconnect when you're done:

    openvpn3 session-manage --config CloudConnexa --disconnect

    Note

    Once disconnected, the session is removed from openvpn3 session-list. You can start a new session at any time by repeating step 1.

Option B — Persistent autostart connection (administrator)

Use this option to set up an always-on connection that starts automatically when the system boots. This requires root access.

  1. Grant the root user access to the imported profile:

    openvpn3 config-acl --show --lock-down true1 --grant root2 --config CloudConnexa

    1

    --lock-down true is optional but recommended. It prevents the root user from extracting the profile contents via openvpn3 commands or D-Bus APIs.

    2

    --grant root gives the root user access to the profile, which is required for the systemd service to start it at boot.

    Tip

    To allow the current user to manage the VPN session even when root starts it, add --transfer-owner-session true to the command above.

  2. Enable and start the systemd session service:

    sudo systemctl enable1 --now2 openvpn3-session@CloudConnexa.service

    1

    enable configures the service to start automatically at every boot.

    2

    --now starts the service immediately without requiring a reboot.

    Important

    Don't use --now if you've already started the session manually using openvpn3 session-start. In that case, use sudo systemctl enable openvpn3-session@CloudConnexa.service without --now to configure autostart without attempting to start a duplicate session.

  3. Verify the connection is active:

    sudo systemctl status openvpn3-session@CloudConnexa.service

    • The VPN connection is now active and will restart automatically whenever the system boots.

Managing the autostart service

After setup, use the following commands to manage the connection:

Task

Command

Check service status

sudo systemctl status openvpn3-session@CloudConnexa.service

Stop the connection

sudo systemctl stop openvpn3-session@CloudConnexa.service

Restart the connection

sudo systemctl restart openvpn3-session@CloudConnexa.service

Disable autostart

sudo systemctl disable openvpn3-session@CloudConnexa.service

Migrate from openvpn3-autoload to systemd unit files

Note

The openvpn3-autoload utility was deprecated in v20 and is planned for removal in a future release. If you're currently using openvpn3-autoload to start your VPN session at boot, follow these steps to migrate to the recommended openvpn3-session@.service approach used in Option B of this tutorial. After completing these steps, your session will be managed directly by systemd, and you'll no longer depend on openvpn3-autoload.

Use these steps if your VPN session is currently configured to start automatically at boot via openvpn3-autoload and you want to migrate to the recommended systemd approach.

  1. Check your active sessions and note the Path value:

    sudo openvpn3 sessions-list

  2. Disconnect the active session using the path from step 1:

    sudo openvpn3 session-manage --session-path YOUR_PATH --disconnect

  3. Confirm no sessions are active:

    sudo openvpn3 sessions-list

  4. Disable the openvpn3-autoload service so it no longer starts at boot:

    sudo systemctl disable --now openvpn3-autoload.service

  5. Check your active configurations and note the configuration name:

    sudo openvpn3 configs-list

  6. Remove the existing configuration, replacing YOUR_CONFIG_NAME with the name from step 5:

    sudo openvpn3 config-remove --config "YOUR_CONFIG_NAME"

    • You'll be prompted to confirm. Type YES in uppercase to confirm removal.

  7. Confirm no configurations are active:

    sudo openvpn3 configs-list

  8. Import the profile from the openvpn3-autoload directory as a persistent configuration, replacing YOUR_CONFIG_NAME with the name you want to assign in the configuration manager:

    sudo openvpn3 config-import --config /etc/openvpn3/autoload/connector.conf --name "YOUR_CONFIG_NAME" --persistent

    Tip

    connector.conf is the default configuration filename used by openvpn3-autoload. When you import it, OpenVPN 3's Configuration Manager registers it under the --name you specify. After that, you work with the name, not the file. Use the name you noted in step 5 to keep things consistent.

  9. Enable and start the session using the configuration name from step 8:

    sudo systemctl enable --now openvpn3-session@YOUR_CONFIG_NAME.service

  10. Confirm the new session is active and connected:

    sudo openvpn3 sessions-list

  11. Restart your system and run sudo openvpn3 sessions-list again to confirm the new profile loads automatically at boot.

Step 4: Manage your VPN session

The following commands are useful for monitoring and troubleshooting a running session:

  • Check active sessions:

    openvpn3 sessions-list

  • Restart the connection:

    openvpn3 session-manage --config CloudConnexa --restart

  • View real-time tunnel statistics:

    openvpn3 session-stats --config CloudConnexa

  • View real-time log events:

    openvpn3 log --config CloudConnexa

    Tip

    Log output may appear quiet at first since it only shows events as they occur. To see activity, run openvpn3 session-manage --restart from a second terminal window while this command is running. For more detail, add --log-level 6 to the command. Valid log levels are 0 (minimal) to 6 (most verbose).

  • To disconnect a session using its D-Bus path instead of the profile name:

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

    Important

    You need to disconnect from the current session before starting a new one with a different profile.

Tip — Connect more than just this device

The OpenVPN 3 Linux client you just installed can also be used to connect an entire private network to CloudConnexa — not just this machine. A CloudConnexa Network Connector lets any device on your network reach CloudConnexa resources without installing a client on each one. See Tutorial: Install a Connector on Linux to get started, or CloudConnexa Connectors to understand which deployment fits your needs.

In this section: