How to Add a VPN in Linux NetworkManager

NetworkManager is the part of a Linux desktop that joins Wi-Fi, manages Ethernet cables and, if you ask it to, runs your VPN. Understanding how it thinks about a VPN is more useful than memorising menu names, because the menus differ between GNOME, KDE, Cinnamon and others, while the model underneath is the same everywhere. This article is about that model and about the specific choices you make while adding a profile.

It targets the question behind linux vpn networkmanager: how do I add a VPN so it behaves the way I expect on a laptop that moves between networks? It does not cover distribution-specific package names in depth, and it does not repeat the installer steps for the VPNclient app, which are in the Linux setup guide. The profile route here is for configuration files you already have from an employer, a university or a server you run.

What NetworkManager actually stores

A VPN in NetworkManager is a connection profile, a small text file with sections for general settings, the VPN itself, IPv4 and IPv6. It has four parts worth knowing:

• The plugin. NetworkManager does not speak VPN protocols itself. It hands the job to a plugin: one for OpenVPN, one for IPsec with strongSwan, one for L2TP, one for OpenConnect and so on. WireGuard is the exception because support is built in.
• The profile. It lists the server, the credentials method, the routes and the DNS. System connections live in /etc/NetworkManager/system-connections.
• The secrets. Passwords and keys may sit in the profile, in a keyring or be requested every time.
• The link. When you connect, a virtual interface such as tun0 or wg0 appears. Routes and DNS attach to that interface.

This matters because every symptom maps to one part. A missing menu entry is a plugin issue. A connection that works but loads nothing is a routing or DNS issue on the link. A prompt that keeps reappearing is a secrets issue.

Before you start: what you need

Gather three things first.

1. A configuration file or the values. For OpenVPN that is an .ovpn file, usually with certificates. For WireGuard it is a .conf file. For IPsec or L2TP it is a server address, a method such as a pre-shared key or certificate, and a username.
2. The matching plugin. Check your package manager for names beginning with NetworkManager- or network-manager- followed by the type.
3. A way to test. Know one internal address, or use an IP check, so you can tell whether traffic really goes through the tunnel.

VPN type	Needs a plugin?	Typical file
WireGuard	No, built in	.conf
OpenVPN	Yes	.ovpn
IPsec (IKEv2)	Yes, often strongSwan based	Values or a certificate
L2TP over IPsec	Yes	Values
OpenConnect	Yes	Gateway address

If you want a refresher on what distinguishes these, what a VPN protocol is gives the background in plain words. After installing a plugin, log out and in, or restart NetworkManager, so the settings program notices it.

Adding a profile in GNOME Settings

The steps vary by version, so treat the labels as approximate.

1. Open Settings and choose Network.
2. Next to VPN, press the plus button.
3. Choose Import from file and select your .ovpn or .conf file. For manual entry, pick the type instead.
4. Check the name, the gateway and the authentication method. Imported files often fill in most fields.
5. Open the IPv4 and IPv6 tabs and review routes and DNS, as described below.
6. Press Add, then use the switch to connect.

KDE Plasma offers the same in the network applet and System Settings under Connections; the plus button has an "Import VPN connection" option. Desktops without a settings program can run nm-connection-editor, which is the generic editor and shows every field.

Adding a profile with nmcli

The command line is quicker once you know it, and it works over SSH or on a server.

nmcli connection import type openvpn file ~/work.ovpn
nmcli connection import type wireguard file ~/home.conf
nmcli connection show
nmcli connection up work
nmcli connection down work

The name after up is the profile name, which nmcli connection show lists. To edit a field, use nmcli connection modify NAME followed by a property, for example nmcli connection modify work connection.autoconnect no. To read all current values, use nmcli connection show work. The command-line guide goes deeper into running tunnels directly without NetworkManager.

Settings that decide how it behaves

After importing, five settings do most of the work. Review them before you rely on the profile.

Setting	Where	What it does	Typical choice
Use only for resources on this network	IPv4 / IPv6, Routes (property never-default)	Keeps the tunnel from becoming the default route	On for office or lab access, off for full protection
Extra routes	IPv4 / IPv6, Routes	Sends chosen subnets through the tunnel	Add private ranges only, such as those in RFC 1918
DNS servers and search domains	IPv4 / IPv6, DNS	Decides who answers name lookups	Keep what the profile gives; add a search domain for internal names
DNS priority	ipv4.dns-priority	Lower number wins	Use a negative value if the tunnel DNS must answer first
Automatic connection	General	Brings the tunnel up by itself	Optional; see next section

A worked example. Priya, a student, needs her university's lab servers from a cafe but does not want her music streaming to pass through the campus network. She imports the university's profile, enables Use only for resources on this network, and checks that the profile adds a route for the university's private range. When she connects, only lab addresses use the tunnel. Streaming and web browsing keep using the cafe connection. That is exactly the behaviour described in what split tunneling is.

Now Tomás, who works remotely and wants everything protected on public Wi-Fi. He leaves that option off, so the tunnel becomes the default route. He sets DNS priority to a negative number so lookups go through the tunnel, and he reads split DNS to understand what to expect when a company name resolves differently inside and outside.

Auto-connect, triggers and shared computers

NetworkManager can connect the VPN without you touching it. There are two levels.

• Per VPN. In the general tab of the VPN profile, "Automatically connect" only has an effect if the system has a reason to connect it. On many versions it connects when any network comes up.
• Per Wi-Fi. NetworkManager can attach a "secondary connection" to a Wi-Fi profile. With nmcli connection modify "Home Wi-Fi" connection.secondaries work-vpn, the VPN starts every time that Wi-Fi connects, and stops when it disconnects. This is the clean way to say "only on this network".

Think about who else uses the machine. A profile saved as "all users" is available to everyone with an account. For a shared family computer, you may prefer a per-user profile with the secret requested every time. Auto-connect and a stored secret together mean anyone who opens the lid is already inside the work network.

If you want extra actions at connect time, NetworkManager runs scripts from /etc/NetworkManager/dispatcher.d/ with the interface name and the event (up, down, vpn-up, vpn-down). Typical uses are mounting a network share or changing a firewall rule. Keep these scripts short, make them executable and owned by root, and test them by watching journalctl -f while you connect.

Secrets: how passwords are kept

In the authentication section, a small icon next to the password field controls storage:

• Store the password only for this user. The secret goes to the desktop keyring.
• Store the password for all users. The secret is written into the system profile file, readable by administrators.
• Ask for this password every time. Nothing is saved.
• Not required. For certificate-only setups.

The choice matters most when something goes wrong. If a laptop is lost, a stored password protected only by a weak login gives a thief a head start, which is why disk encryption and a strong login password come first. If the profile uses a certificate and a private key, protect that key file with a passphrase as well, so that copying the file alone is not enough to use it.

For personal laptops with disk encryption, the first option is a fair balance. For shared computers, ask every time. Never put a VPN password into a script, and never email a profile file that contains a private key.

Reading the logs when something fails

Resist guessing and read the log.

journalctl -u NetworkManager --since "5 minutes ago"
nmcli connection show --active
ip route
resolvectl status

Match the symptom to a cause.

Symptom	Likely cause	Check
Type missing in the Add list	Plugin not installed or not loaded	Package list; restart NetworkManager
Prompt returns after typing the password	Wrong credentials or secrets not saved	Retype carefully; check the storage option
Connected, no web pages	Missing default route or DNS	ip route, resolvectl status
Internal names fail, IPs work	DNS or search domain missing	Add the search domain; check priority
Dropped after resume from sleep	Link needs a new handshake	Reconnect; consider the auto-connect setting
Works at home, not at the office	Network blocks the VPN port	Try another network such as mobile data to confirm

For a wider checklist see VPN not connecting.

Common mistakes

• Importing a file twice and ending up with two profiles that compete over the same interface name.
• Turning on "use only for resources on this network" and then wondering why the whole internet is not protected.
• Using a negative DNS priority on a profile whose DNS servers are unreachable, which makes every lookup fail.
• Saving a password for all users on a shared machine.
• Setting auto-connect on a laptop that often joins hotel networks that block the VPN, then thinking the network is broken.
• Editing the profile file by hand while NetworkManager is running, without reloading it with nmcli connection reload.

Summary

NetworkManager treats a VPN as a profile built from a plugin, a server definition, routes, DNS and a way to keep secrets. Add the profile through Settings, nm-connection-editor or nmcli connection import, then spend a few minutes on the settings that decide behaviour: whether the tunnel is the default route, who answers DNS, when it connects and where the password lives. Read the journal when something fails and match symptoms to the part that owns them.

If you would rather use a ready-made app, the download page lists the supported platforms, and the pricing page shows the prepaid options.