Tutorial: Learn to Install and Control the OpenVPN 3 Client⁠

Overview⁠

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:

A CloudConnexa account with an active subscription.
A downloaded .ovpn connection profile for your CloudConnexa network. See Download a Connection Profile for instructions.
A supported Linux distribution. See the table below.
Terminal access.

Distribution	Release	Release Name ($DISTRO)	Architecture
Debian	12	bookworm	amd64, arm64 ARM64/aarch64 architectures are in tech preview.
Debian	13	trixie	amd64, arm64
Fedora We support the most recent stable Fedora releases. Fedora release cadence information.	-	-	Recent stable releases
Red Hat Enterprise Linux	8	-	aarch64, ppc64le, s390x, x86_64 These aren't fully supported; they are only available via the Fedora Copr repositories. Consider them tech-preview.
Red Hat Enterprise Linux	9	-	aarch64, ppc64le, s390x, x86_64
Red Hat Enterprise Linux	10	-	aarch64, ppc64le, s390x, x86_64
Ubuntu	22.04	jammy	amd64, arm64
Ubuntu	24.04	noble	amd64, arm64
Ubuntu	25.04	plucky	amd64, arm64

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.

Open a terminal or connect to your server via SSH.

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

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.

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

Update the package list:
```
sudo apt update
```
Install the OpenVPN 3 client:
```
sudo apt install openvpn3
```

Open a terminal or connect to your server via SSH.

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
```

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
```

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⁠

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 CloudConnexa --persistent
```
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.
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.

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

Start a VPN session using your imported profile:
```
openvpn3 session-start --config CloudConnexa
```
Verify the session is running:
```
openvpn3 sessions-list
```
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.

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

Grant the root user access to the imported profile:
```
openvpn3 config-acl --show --lock-down true --grant root --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.
Enable and start the systemd session service:
```
sudo systemctl enable --now 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.
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⁠

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.

Check your active sessions and note the Path value:
```
sudo openvpn3 sessions-list
```

Disconnect the active session using the path from step 1:

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

Confirm no sessions are active:
```
sudo openvpn3 sessions-list
```
Disable the openvpn3-autoload service so it no longer starts at boot:
```
sudo systemctl disable --now openvpn3-autoload.service
```
Check your active configurations and note the configuration name:
```
sudo openvpn3 configs-list
```
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.
Confirm no configurations are active:
```
sudo openvpn3 configs-list
```
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.
Enable and start the session using the configuration name from step 8:
```
sudo systemctl enable --now openvpn3-session@YOUR_CONFIG_NAME.service
```
Confirm the new session is active and connected:
```
sudo openvpn3 sessions-list
```
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.