← back to articles

VPN launcher

Written by främling in January 2026.

Text may be shared, with credit, and not for commercial use (CC BY-NC-SA).

Overview

vpn-launcher.sh is a lightweight, POSIX-compliant shell script that provides a unified command-line interface for launching and controlling OpenVPN connections using provider-organized profile directories.

It is designed to be simple, portable, and easy to extend.

Profiles are stored as standard OpenVPN configuration files inside:

~/vpn/<provider>/*.ovpn

Only one background OpenVPN process is tracked via a PID file.

Features

  • Provider-based profile organization
  • Profile selection by name or randomly
  • Background (daemon) mode
  • Auto-reconnect support
  • Automatic authentication file detection
  • Dry-run mode for debugging
  • POSIX-compliant shell script
  • Minimal dependencies

Usage

./vpn-launcher.sh [ACTION] [OPTIONS]

Options

Actions

  • --provider=NAME
    Select VPN provider (directory under ~/vpn).

  • --profile=NAME
    Select profile by filename or substring.

  • --random
    Connect using a random profile.

  • --list
    List available profiles for provider.

  • --connect-bg
    Connect in background (daemon mode).

  • --disconnect
    Disconnect VPN using PID file.

  • --status
    Show OpenVPN running status.

  • --auto-reconnect
    Automatically reconnect if connection drops.

General Options

  • --authfile=FILE
    Explicit authentication file.

  • --dir=DIR
    VPN base directory (default: ~/vpn).

  • --pid-file=FILE
    PID file path (default: ~/.vpn.pid).

  • --bin=BIN
    OpenVPN binary (default: openvpn).

  • --dry-run
    Print command without executing.

  • --version
    Show version information.

  • --help
    Show help text.

  • --config
    Use defaults from ~/.vpnrc.

Behavior

  • If --authfile is not specified and auth.txt exists inside the provider directory, it is used automatically.
  • Command-line options always override values found in ~/.vpnrc.
  • Only one background VPN connection is tracked at a time.
  • Profiles must be standard OpenVPN .ovpn files.
  • Auto-reconnect uses OpenVPN keepalive and ping-restart mechanisms.
  • If the OpenVPN binary is not named openvpn, change the OPENVPN_BIN="openvpn" line inside the .sh file.

Requirements

  • POSIX-compatible shell (/bin/sh)
  • OpenVPN
  • Standard UNIX utilities (find, awk, pgrep, kill)

Permissions

Root privileges may be required to establish VPN connections, depending on your OpenVPN configuration and system networking policies.

Examples

List ProtonVPN profiles:

./vpn-launcher.sh --provider=proton --list

Connect to a specific profile:

./vpn-launcher.sh --provider=riseup --profile=seattle

Connect using a random server in background:

./vpn-launcher.sh --provider=proton --random --connect-bg

Disconnect VPN:

./vpn-launcher.sh --disconnect

Show VPN status:

./vpn-launcher.sh --status

Dry-run example:

./vpn-launcher.sh --provider=proton --profile=nl --dry-run

Notes

  • This script does not manage firewall rules or act as a kill-switch.
  • Only one background VPN connection is tracked via PID file.
  • The script does not modify system routing beyond what OpenVPN performs.
  • ~/.vpnrc may contain default values in KEY=VALUE format.

License

This project was written by främling <http://framling.org> and is licensed under the GNU General Public License version 3 (or any later version).

See the LICENSE file for details.

Downloads

Old machines. New memories.