How openvpn/openvpn-gui works
1. Project role and runtime
- This repository builds OpenVPN GUI for Windows, a native desktop utility written in C/C++ that lives in the Windows system tray and controls OpenVPN client sessions.
- The primary deliverable is the GUI executable, plus a PLAP/Pre-Logon Access Provider component for login-screen VPN access.
2. Top-level execution model
- main.c is the entry point for the tray application.
- The GUI runs as a long-lived Windows process, reacts to user commands, and coordinates child OpenVPN processes, Windows registry state, and external scripts.
- It also supports command-line control of an already-running instance (--command connect/disconnect/...), so the app has both interactive and remote-control entry paths.
3. Configuration discovery and command interpretation
- config_parser.c, options.c, and openvpn_config.c handle config parsing and option normalization.
- On startup and on tray-menu rescan, the GUI scans the user and machine OpenVPN config directories for .ovpn files and builds the list of available connections.
- registry.c and env_set.c bridge Windows registry settings and environment/setup values into the runtime configuration.
- openvpn-gui.exe can also import configs and responds to registry-defined defaults such as config directories, log directories, and OpenVPN binary path.
4. Tray UI and user interaction boundary
- tray.c, manage.c, viewlog.c, echo.c, and misc.c form the user-facing interaction layer.
- The tray icon/menu is the main control surface for connect/disconnect/reconnect, status inspection, rescanning configs, and settings.
- viewlog.c provides log/status display for a connection, while echo.c and localization.c support user-visible messages and translated UI text.
5. Connection lifecycle orchestration
- openvpn.c, service.c, proxy.c, and access.c coordinate how a selected profile is started, monitored, and stopped.
- The GUI launches openvpn.exe as a child process, supplies config and management parameters, and tracks process/state transitions.
- It also handles per-profile state such as connected, disconnected, reconnecting, or detached.
6. Management interface and persistent connections
- A major architectural boundary is the OpenVPN management interface: the GUI connects to OpenVPN instances via localhost management ports to observe state and issue commands.
- This is what enables control of persistent / pre-started connections started by OpenVPNService from config-auto.
- The GUI can auto-attach to these running sessions, or enumerate them without attaching, depending on user settings.
7. Script execution and per-profile side effects
- scripts.c runs the per-profile *_pre.bat, *_up.bat, and *_down.bat hooks described in the README.
- The data flow is: connection event → script invocation → captured output redirected to log files in the configured log directory.
- Script timeouts and log behavior are user-configurable through registry-backed settings.
8. Secrets, authentication, and PKCS#11
- save_pass.c manages password-saving behavior and credential persistence constraints.
- pkcs11.c integrates PKCS#11-based token support for certificate/private-key authentication flows.
- proxy.c and related auth handling support cases where OpenVPN needs additional user input during connection establishment.
9. Pre-Logon Access Provider (PLAP) subsystem
- The plap/ directory is a separate subsystem that builds a DLL/provider for Windows logon screen integration.
- It enables “Start Before Logon” behavior: users can initiate or manage certain persistent VPN profiles before Windows sign-in.
- plap/ui_glue.c, plap/plap_provider.c, plap/plap_connection.c, and plap/plap_dll.c form the provider/runtime boundary; qr.c and qrcodegen/ support QR-code-based web authentication for PLAP scenarios.
10. Windows integration and persistence
- registry.c is the main persistence layer for settings, split between machine-wide OpenVPN settings and per-user OpenVPN GUI preferences.
- The repo relies on Windows-specific APIs for tray integration, UAC/admin-group checks, service interaction, registry reads/writes, and manifest/resource handling.
- service.c is the bridge to the Windows service environment, especially relevant for interactive service behavior and automatic/persistent connections.
11. Localization and resource packaging
- res/ contains localized .rc resource files for many languages, plus manifests and bitmap assets.
- localization.c and chartable.h support translated UI strings and character handling.
- openvpn-gui-res.h, openvpn-gui-res.rc, and related resource files show that much of the UI chrome is resource-driven rather than code-driven.
12. Build and distribution shape
- The repository supports multiple build paths: CMake, Autotools/Makefile.am, and MSVC/GitHub Actions workflows.
- vcpkg.json indicates dependency management through vcpkg on Windows.
- Architecturally, this is a Windows-native desktop product with a main executable plus a companion PLAP DLL, both assembled from a mix of UI, process-control, registry, and service-integration code.
Main entry points: main.c Main app · openvpn.c OpenVPN control · tray.c Tray UI · plap_provider.c PLAP provider
Components 22
GUI runtime
Main tray application, config/state, and connection orchestration.
- Main app · Windows tray entry point and command dispatcher.
main.c - Tray UI · System tray icon, menu actions, and user commands.
tray.c - Session UI · Per-profile actions, status changes, and reconnect/disconnect flows.
manage.c - Log viewer · Displays connection logs and session output.
viewlog.c - Config parse · Reads and normalizes OpenVPN profile configuration.
config_parser.c - Options · Defines and normalizes runtime options.
options.c - Config scan · Finds available .ovpn profiles and related config locations.
openvpn_config.c - Registry · Stores GUI and machine-wide settings in Windows registry.
registry.c - Env setup · Bridges registry values and environment setup into runtime state.
env_set.c - OpenVPN control · Launches and monitors openvpn.exe child processes.
openvpn.c - Service bridge · Integrates with OpenVPNService and persistent sessions.
service.c - Proxy/auth · Handles proxy settings and interactive authentication flows.
proxy.c - Hook runner · Runs per-profile pre/up/down scripts and captures output.
scripts.c - Password save · Controls password persistence and save restrictions.
save_pass.c - PKCS#11 · Integrates certificate/token-based authentication support.
pkcs11.c
PLAP subsystem
Logon-screen provider and supporting DLL/runtime pieces.
- PLAP provider · Windows logon-screen provider runtime for start-before-logon VPN.
plap/plap_provider.c - PLAP conn · PLAP-side connection lifecycle and session handling.
plap/plap_connection.c - PLAP UI glue · Connects provider/runtime logic to UI and authentication workflow.
plap/ui_glue.c - PLAP DLL · DLL entry and provider packaging for the PLAP subsystem.
plap/plap_dll.c - QR auth · QR-code support for web authentication in PLAP flows.
qr.c
Resources & build
Localized resources, manifests, and build/distribution files.
- Localized UI · Resource scripts, manifests, and translated UI strings.
res/openvpn-gui-res.rc - Build system · CMake, Autotools, MSVC, and dependency packaging setup.
CMakeLists.txt
Connections 24
- Main app → Tray UI: starts · Main executable creates the tray UI and command surface.
- Main app → Config parse: loads · Initial startup parses profile and runtime configuration.
- Main app → Registry: reads/writes · Persists and restores GUI settings and defaults.
- Main app → Env setup: initializes · Applies environment and setup values at startup.
- Tray UI → Session UI: dispatches · Tray actions open or control per-profile sessions.
- Tray UI → Config scan: rescans · Menu actions refresh available VPN profiles.
- Session UI → Log viewer: opens · Session management can show the live log viewer.
- Config parse → Options: normalizes · Parsed config is converted into runtime options.
- Config scan → Registry: uses · Config discovery follows registry-defined paths and defaults.
- OpenVPN control → Proxy/auth: auth flow · Process orchestration handles proxy and interactive auth.
- OpenVPN control → Password save: credentials · Connection lifecycle consults password persistence rules.
- OpenVPN control → PKCS#11: token auth · Supports PKCS#11-based authentication paths.
- OpenVPN control → Hook runner: hooks · Connection events trigger per-profile scripts.
- Hook runner → Registry: configures · Timeouts and log behavior are driven by settings.
- Service bridge → OpenVPN control: hosts · Service-managed sessions are observed and controlled by GUI logic.
- Service bridge → Config scan: auto-start · Persistent sessions originate from auto-started profiles.
- PLAP provider → PLAP conn: manages · Provider runtime delegates connection/session state.
- PLAP provider → PLAP UI glue: bridges · Provider logic connects to UI/auth glue.
- PLAP conn → QR auth: auth support · PLAP scenarios can use QR-code web authentication.
- PLAP DLL → PLAP provider: exports · DLL packaging exposes the provider entry points.
- Localized UI → Tray UI: powers · Localized strings and UI assets feed the tray app.
- Localized UI → PLAP provider: powers · PLAP-specific resources support the login provider.
- Build system → Main app: builds · Project build files assemble the GUI executable.
- Build system → PLAP DLL: builds · Project build files assemble the PLAP DLL.