--- title: 'Tutorial: Learn to Install and Control the OpenVPN 3 Client' canonical: https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors/operating-systems/linux/tutorial--learn-to-install-and-control-the-openvpn-3-client/ product: CloudConnexa Docs description: 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. keywords: OpenVPN 3 Client for Linux --- # Tutorial: Learn to Install and Control the OpenVPN 3 Client ## 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](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors/operating-systems/linux/tutorial--install-a-connector-on-linux.md). This tutorial shows you how to install the OpenVPN 3 Linux client, import your [CloudConnexa](https://openvpn.net/cloud-vpn/) 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](https://openvpn.net/cloud-docs/owner/get-started/create-a-cloudconnexa-account.md) with an active [subscription](https://openvpn.net/cloud-vpn/pricing/). - A downloaded `.ovpn` connection profile for your CloudConnexa network. See [Download a Connection Profile](https://openvpn.net/cloud-docs/owner/users/users---devices/download-connection-profile-as-a--ovpn-file-for-a-user-s-device.md) 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](https://docs.fedoraproject.org/en-US/releases/).) | - | - | Recent stable releases | | Red Hat Enterprise Linux | 8 | - | aarch64, ppc64le (These aren't fully supported; they are only available via the Fedora Copr repositories. Consider them tech-preview.), s390x, x86\_64 | | 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. ### 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](https://docs.fedoraproject.org/en-US/epel/): - **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 CloudConnexa --persistent ``` `--name CloudConnexa` assigns a name to the profile so you can reference it in later commands. `--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 true --grant root --config CloudConnexa ``` `--lock-down true` is optional but recommended. It prevents the root user from extracting the profile contents via `openvpn3` commands or D-Bus APIs. `--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 enable --now openvpn3-session@CloudConnexa.service ``` `enable` configures the service to start automatically at every boot. `--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** > > **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](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors/operating-systems/linux/tutorial--install-a-connector-on-linux.md) to get started, or [CloudConnexa Connectors](https://openvpn.net/cloud-docs/owner/get-started/about-cloudconnexa/cloudconnexa-connectors.md) to understand which deployment fits your needs. ## Related topics - [CloudConnexa Connector Tutorials](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors.md) — Set up a Connector to connect entire networks with tutorials found here. - [Download a Connection Profile](https://openvpn.net/cloud-docs/owner/users/users---devices/download-connection-profile-as-a--ovpn-file-for-a-user-s-device.md) — get your `.ovpn` file from the CloudConnexa portal. - [OpenVPN3 Linux project on Codeberg](https://codeberg.org/OpenVPN/openvpn3-linux/tags) — release notes. - [OpenVPN3 Linux source code](https://codeberg.org/OpenVPN/openvpn3-linux/) — source code - [OpenVPN Community Wiki](https://community.openvpn.net/Pages/OpenVPN3Linux) — additional community documentation. --- Prev: [Tutorial: Install a Connector on Linux](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors/operating-systems/linux/tutorial--install-a-connector-on-linux.md) Next: [Tutorial: Enable DCO for a Linux Connector](https://openvpn.net/cloud-docs/tutorials/configuration-tutorials/connectors/operating-systems/linux/tutorial--enable-dco-for-a-linux-connector.md) Index: https://openvpn.net/cloud-docs/llms.txt