OpenVPN CLI

OpenVPN CLI cheatsheet — connect with .ovpn files, manage connections, check status. openvpn --config file.ovpn, openvpn --status, openvpn --management. Full reference.

8 min read

What it is

The OpenVPN command-line interface (CLI) for establishing secure VPN connections. You reach for it when you need to connect to an OpenVPN server or manage OpenVPN client configurations.

Installation

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install openvpn

Linux (Fedora/CentOS/RHEL):

sudo dnf install openvpn
# or
sudo yum install openvpn

macOS: Install via Homebrew:

brew install openvpn

Note: On macOS, you might also use Tunnelblick or the official OpenVPN Connect client for a GUI experience. The CLI installation is for command-line usage.

Windows: Download the installer from the OpenVPN Community Downloads page. Run the installer and follow the prompts. The CLI openvpn.exe will be installed.

Core Concepts

  • Client Configuration File (.ovpn): This file contains all the necessary information for an OpenVPN client to connect to a server. It includes server address, port, protocol, certificates, keys, and various connection options.
  • Certificates and Keys: OpenVPN relies on TLS/SSL for authentication and encryption. This typically involves:
    • CA Certificate (ca.crt): The certificate of the Certificate Authority that signed the server’s certificate.
    • Client Certificate (client.crt): The certificate identifying the client.
    • Client Key (client.key): The private key corresponding to the client certificate.
    • TLS Auth Key (ta.key): An optional HMAC signature for added security against DoS attacks and port scanning.
  • TUN vs. TAP:
    • TUN (Network Tunnel): Operates at the IP layer (Layer 3). It creates a virtual point-to-point IP link. This is the most common and generally preferred mode for IP-based traffic.
    • TAP (Network Tap): Operates at the Ethernet layer (Layer 2). It creates a virtual Ethernet interface, allowing broadcast traffic and Ethernet frames to pass through. Useful for bridging networks or protocols that rely on Layer 2.

Commands / Usage

OpenVPN is typically run with a configuration file. The primary command is openvpn.

Establishing a Connection (Client Mode):

sudo openvpn --config /path/to/your/client.ovpn
  • sudo: Required on most systems to create virtual network interfaces and modify network routes.
  • --config /path/to/your/client.ovpn: Specifies the client configuration file to use. This is the most common way to start OpenVPN.

Running in the Background:

sudo openvpn --config /path/to/your/client.ovpn --daemon
  • --daemon: Runs the OpenVPN process in the background as a daemon.

Specifying a Configuration Directory:

sudo openvpn --configdir /etc/openvpn/client/
  • --configdir /etc/openvpn/client/: Tells OpenVPN to look for .conf or .ovpn files in the specified directory and attempt to start connections for each.

Overriding Configuration Options:

sudo openvpn --config /path/to/client.ovpn --remote vpn.example.com 1194 --proto udp --verb 4
  • --remote vpn.example.com 1194: Overrides the remote directive in the config file, specifying the server address and port.
  • --proto udp: Overrides the proto directive, forcing UDP.
  • --verb 4: Sets the verbosity level for logging (0=silent, 3=normal, 4=info, 5=debug).

Testing a Configuration (Non-daemon):

sudo openvpn --config /path/to/client.ovpn --test-config
  • --test-config: Checks the syntax and validity of the configuration file without actually establishing a connection.

Running in Client Mode with Inline Certificates/Keys:

If your .ovpn file has certificates and keys embedded within <ca>, <cert>, <key>, etc., tags, the above --config command is sufficient. If they are separate files, they must be referenced correctly within the .ovpn file (e.g., ca ca.crt, cert client.crt, key client.key).

Running as a Server (Less Common via CLI Directly):

While you can run OpenVPN as a server using a server configuration file, it’s more common to manage server setups via systemd services or init scripts that call openvpn --config /path/to/server.conf.

sudo openvpn --config /etc/openvpn/server/server.conf
  • --config /etc/openvpn/server/server.conf: Starts OpenVPN in server mode using the specified server configuration file.

Common Flags (can be used with --config or standalone):

  • --client: Explicitly run in client mode.
  • --server <net> <netmask>: Configure server mode with a virtual network. E.g., --server 10.8.0.0 255.255.255.0.
  • --dev tun: Use the TUN device (default).
  • --dev tap: Use the TAP device.
  • --port <port>: Set the server or client port. E.g., --port 1194.
  • --proto <udp|tcp>: Set the protocol (UDP is generally faster). E.g., --proto tcp.
  • --ca <file>: Path to the CA certificate.
  • --cert <file>: Path to the client/server certificate.
  • --key <file>: Path to the client/server private key.
  • --tls-auth <file> [direction]: Path to the TLS Auth key. Direction 1 for client, 0 for server. E.g., --tls-auth ta.key 1.
  • --auth-user-pass <file>: File containing username and password on two lines for user authentication. E.g., --auth-user-pass auth.txt.
  • --verb <level>: Set log verbosity level (0-6). E.g., --verb 3.
  • --log <file>: Redirect log output to a file. E.g., --log /var/log/openvpn.log.
  • --log-append <file>: Append log output to a file. E.g., --log-append /var/log/openvpn.log.
  • --mute <level>: Mute messages below a certain verbosity level.
  • --pull: In client mode, allow pulling options from the server (like routes, DNS).
  • --nobind: Don’t bind to a specific local port (useful when running multiple clients or for specific routing scenarios).
  • --route <net> [netmask] [gateway] [metric]: Manually add routes. E.g., --route 192.168.1.0 255.255.255.0 vpn_gateway.
  • --route-nopull: Prevent pulling routes from the server.
  • --redirect-gateway def1 [bypass-dhcp]: Redirect all client traffic through the VPN. bypass-dhcp is optional.
  • --ifconfig <local> <remote>: Manually set client IP address and server IP address for the tunnel interface. E.g., --ifconfig 10.9.0.2 10.9.0.1.
  • --tun-mtu <size>: Set the MTU for the TUN device. E.g., --tun-mtu 1500.
  • --ping <interval>: Set interval for pinging the remote peer. E.g., --ping 10.
  • --ping-restart <seconds>: Restart if pings fail for this duration. E.g., --ping-restart 60.
  • --resolv-retry infinite: Keep trying to resolve the server hostname indefinitely.
  • --persist-key: Don’t re-read the key file on restarts.
  • --persist-tun: Don’t close and reopen the TUN/TAP device on restarts.
  • --status <file> [pid] : Output connection status information to a file. E.g., --status /var/run/openvpn-client.status.
  • --verb 3: Set log verbosity to normal.
  • --daemon: Run in the background.
  • --management <host> <port>: Enable management interface.

Common Patterns

Connect using a standard client config file:

sudo openvpn --config ~/Downloads/myvpn.ovpn

Explanation: Start OpenVPN using a downloaded .ovpn file, prompts for username/password if configured.

Connect and run in the background:

sudo openvpn --config ~/Downloads/myvpn.ovpn --daemon

Explanation: Connects to the VPN and detaches from the terminal. Check logs for status.

Connect, redirect all traffic, and log to a file:

sudo openvpn --config ~/Downloads/myvpn.ovpn --log /tmp/openvpn.log --verb 4 --daemon

Explanation: Connects, redirects all internet traffic through the VPN, logs detailed information to /tmp/openvpn.log, and runs in the background.

Connect using username/password stored in a file: Create auth.txt with:

your_vpn_username
your_vpn_password

Then run:

sudo openvpn --config ~/Downloads/myvpn.ovpn --auth-user-pass auth.txt

Explanation: Uses credentials from auth.txt for authentication, avoiding interactive prompts. Ensure auth.txt has restricted read permissions (chmod 600 auth.txt).

Connect without redirecting gateway (only specific routes):

sudo openvpn --config ~/Downloads/myvpn.ovpn --route-nopull

Explanation: Connects but prevents OpenVPN from automatically adding routes learned from the server. You’d typically use --route flags or configure routes manually if needed.

Connect to a TCP port instead of UDP:

sudo openvpn --config ~/Downloads/myvpn.ovpn --proto tcp

Explanation: Forces the connection to use TCP port 443 (or whatever is specified in the config) instead of the default UDP.

Connect and keep connection alive:

sudo openvpn --config ~/Downloads/myvpn.ovpn --ping 10 --ping-restart 60 --persist-tun --persist-key --daemon

Explanation: Establishes a robust connection that periodically checks the peer, restarts if unresponsive, and maintains the tunnel and keys across reconnections.

Check configuration file syntax:

openvpn --config ~/Downloads/myvpn.ovpn --test-config

Explanation: Validates the syntax of your .ovpn file without attempting a connection. Useful for troubleshooting configuration errors.

Gotchas

  • Permissions: Running OpenVPN often requires root privileges (sudo) because it needs to manipulate network interfaces and routing tables.
  • Firewall: Ensure your firewall allows outgoing UDP/TCP traffic on the port specified by the OpenVPN server (commonly 1194).
  • redirect-gateway def1: This directive reroutes all traffic through the VPN. If the VPN disconnects, you might lose internet connectivity until it reconnects or you manually remove the routes. Use with caution.
  • DNS Resolution: By default, OpenVPN might not update your DNS servers when connecting. You might need scripts (up/down directives in the config) or specific client configurations to push DNS settings from the server or set them manually. The --pull option often handles this if the server pushes DNS info.
  • --daemon: When running with --daemon, OpenVPN detaches from the terminal. Errors or connection drops might not be immediately visible. Check logs (--log or system logs) for troubleshooting.
  • Multiple OpenVPN Instances: Running multiple OpenVPN clients simultaneously requires careful configuration, especially regarding IP addresses, ports, and routing. Using different config files and potentially different ports or --nobind might be necessary.
  • TAP vs. TUN: Using TAP creates a Layer 2 tunnel, which consumes more bandwidth and CPU than TUN (Layer 3). Ensure you’re using the correct device type (tun or tap) as required by your VPN provider or network setup. Most modern VPNs use TUN.
  • Username/Password Security: Storing credentials in a file (--auth-user-pass) is convenient but insecure if the file permissions are not properly restricted (use chmod 600 auth.txt).
  • Certificate/Key Paths: Ensure all paths to .crt, .key, and ta.key files are correct relative to where OpenVPN is run or are absolute paths. The --config file should reference them correctly.