# openvpn/openvpn-gui architecture

> Architecture diagram of the GitHub repository openvpn/openvpn-gui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openvpn/openvpn-gui
- Repository: https://github.com/openvpn/openvpn-gui

## Overview

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`](https://github.com/openvpn/openvpn-gui/blob/master/main.c) (Main app), [`openvpn.c`](https://github.com/openvpn/openvpn-gui/blob/master/openvpn.c) (OpenVPN control), [`tray.c`](https://github.com/openvpn/openvpn-gui/blob/master/tray.c) (Tray UI), [`plap/plap_provider.c`](https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_provider.c) (PLAP provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["GUI runtime"]
  node_main["Main app<br/>tray executable<br/>[main.c]"]
  node_tray["Tray UI<br/>menu/status UI<br/>[tray.c]"]
  node_manage["Session UI<br/>connection management<br/>[manage.c]"]
  node_viewlog["Log viewer<br/>status window<br/>[viewlog.c]"]
  node_config_parser["Config parse<br/>[config_parser.c]"]
  node_options["Options<br/>config model<br/>[options.c]"]
  node_openvpn_config["Config scan<br/>profile discovery<br/>[openvpn_config.c]"]
  node_registry[("Registry<br/>persistence<br/>[registry.c]")]
  node_env_set["Env setup<br/>runtime setup<br/>[env_set.c]"]
  node_openvpn["OpenVPN control<br/>process orchestrator<br/>[openvpn.c]"]
  node_service["Service bridge<br/>windows service<br/>[service.c]"]
  node_proxy["Proxy/auth<br/>auth support<br/>[proxy.c]"]
  node_scripts["Hook runner<br/>script execution<br/>[scripts.c]"]
  node_save_pass["Password save<br/>credentials<br/>[save_pass.c]"]
  node_pkcs11["PKCS#11<br/>token auth<br/>[pkcs11.c]"]
end

subgraph group_group_plap["PLAP subsystem"]
  node_plap_provider["PLAP provider<br/>logon provider<br/>[plap_provider.c]"]
  node_plap_connection["PLAP conn<br/>session control<br/>[plap_connection.c]"]
  node_ui_glue["PLAP UI glue<br/>bridge layer<br/>[ui_glue.c]"]
  node_plap_dll["PLAP DLL<br/>dll entry<br/>[plap_dll.c]"]
  node_qr["QR auth<br/>[qr.c]"]
end

subgraph group_group_assets["Resources & build"]
  node_resources["Localized UI<br/>resources<br/>[openvpn-gui-res.rc]"]
  node_build["Build system<br/>build config<br/>[CMakeLists.txt]"]
end

node_main -->|"starts"| node_tray
node_main -->|"loads"| node_config_parser
node_main -->|"reads/writes"| node_registry
node_main -->|"initializes"| node_env_set
node_tray -->|"dispatches"| node_manage
node_tray -->|"rescans"| node_openvpn_config
node_manage -->|"opens"| node_viewlog
node_config_parser -->|"normalizes"| node_options
node_openvpn_config -->|"uses"| node_registry
node_openvpn -->|"auth flow"| node_proxy
node_openvpn -->|"credentials"| node_save_pass
node_openvpn -->|"token auth"| node_pkcs11
node_openvpn -->|"hooks"| node_scripts
node_scripts -->|"configures"| node_registry
node_service -->|"hosts"| node_openvpn
node_service -->|"auto-start"| node_openvpn_config
node_plap_provider -->|"manages"| node_plap_connection
node_plap_provider -->|"bridges"| node_ui_glue
node_plap_connection -->|"auth support"| node_qr
node_plap_dll -->|"exports"| node_plap_provider
node_resources -->|"powers"| node_tray
node_resources -->|"powers"| node_plap_provider
node_build -->|"builds"| node_main
node_build -->|"builds"| node_plap_dll

click node_main "https://github.com/openvpn/openvpn-gui/blob/master/main.c"
click node_tray "https://github.com/openvpn/openvpn-gui/blob/master/tray.c"
click node_manage "https://github.com/openvpn/openvpn-gui/blob/master/manage.c"
click node_viewlog "https://github.com/openvpn/openvpn-gui/blob/master/viewlog.c"
click node_config_parser "https://github.com/openvpn/openvpn-gui/blob/master/config_parser.c"
click node_options "https://github.com/openvpn/openvpn-gui/blob/master/options.c"
click node_openvpn_config "https://github.com/openvpn/openvpn-gui/blob/master/openvpn_config.c"
click node_registry "https://github.com/openvpn/openvpn-gui/blob/master/registry.c"
click node_env_set "https://github.com/openvpn/openvpn-gui/blob/master/env_set.c"
click node_openvpn "https://github.com/openvpn/openvpn-gui/blob/master/openvpn.c"
click node_service "https://github.com/openvpn/openvpn-gui/blob/master/service.c"
click node_proxy "https://github.com/openvpn/openvpn-gui/blob/master/proxy.c"
click node_scripts "https://github.com/openvpn/openvpn-gui/blob/master/scripts.c"
click node_save_pass "https://github.com/openvpn/openvpn-gui/blob/master/save_pass.c"
click node_pkcs11 "https://github.com/openvpn/openvpn-gui/blob/master/pkcs11.c"
click node_plap_provider "https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_provider.c"
click node_plap_connection "https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_connection.c"
click node_ui_glue "https://github.com/openvpn/openvpn-gui/blob/master/plap/ui_glue.c"
click node_plap_dll "https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_dll.c"
click node_qr "https://github.com/openvpn/openvpn-gui/blob/master/qr.c"
click node_resources "https://github.com/openvpn/openvpn-gui/blob/master/res/openvpn-gui-res.rc"
click node_build "https://github.com/openvpn/openvpn-gui/blob/master/CMakeLists.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_tray,node_manage,node_viewlog,node_config_parser,node_options,node_openvpn_config,node_registry,node_env_set,node_openvpn,node_service,node_proxy,node_scripts,node_save_pass,node_pkcs11 toneBlue
class node_plap_provider,node_plap_connection,node_ui_glue,node_plap_dll,node_qr toneAmber
class node_resources,node_build toneMint
```

## Components

### GUI runtime

Main tray application, config/state, and connection orchestration.

- [Main app](https://github.com/openvpn/openvpn-gui/blob/master/main.c): tray executable · Windows tray entry point and command dispatcher. · `main.c`
- [Tray UI](https://github.com/openvpn/openvpn-gui/blob/master/tray.c): menu/status UI · System tray icon, menu actions, and user commands. · `tray.c`
- [Session UI](https://github.com/openvpn/openvpn-gui/blob/master/manage.c): connection management · Per-profile actions, status changes, and reconnect/disconnect flows. · `manage.c`
- [Log viewer](https://github.com/openvpn/openvpn-gui/blob/master/viewlog.c): status window · Displays connection logs and session output. · `viewlog.c`
- [Config parse](https://github.com/openvpn/openvpn-gui/blob/master/config_parser.c): config parser · Reads and normalizes OpenVPN profile configuration. · `config_parser.c`
- [Options](https://github.com/openvpn/openvpn-gui/blob/master/options.c): config model · Defines and normalizes runtime options. · `options.c`
- [Config scan](https://github.com/openvpn/openvpn-gui/blob/master/openvpn_config.c): profile discovery · Finds available .ovpn profiles and related config locations. · `openvpn_config.c`
- [Registry](https://github.com/openvpn/openvpn-gui/blob/master/registry.c): persistence · Stores GUI and machine-wide settings in Windows registry. · `registry.c`
- [Env setup](https://github.com/openvpn/openvpn-gui/blob/master/env_set.c): runtime setup · Bridges registry values and environment setup into runtime state. · `env_set.c`
- [OpenVPN control](https://github.com/openvpn/openvpn-gui/blob/master/openvpn.c): process orchestrator · Launches and monitors openvpn.exe child processes. · `openvpn.c`
- [Service bridge](https://github.com/openvpn/openvpn-gui/blob/master/service.c): windows service · Integrates with OpenVPNService and persistent sessions. · `service.c`
- [Proxy/auth](https://github.com/openvpn/openvpn-gui/blob/master/proxy.c): auth support · Handles proxy settings and interactive authentication flows. · `proxy.c`
- [Hook runner](https://github.com/openvpn/openvpn-gui/blob/master/scripts.c): script execution · Runs per-profile pre/up/down scripts and captures output. · `scripts.c`
- [Password save](https://github.com/openvpn/openvpn-gui/blob/master/save_pass.c): credentials · Controls password persistence and save restrictions. · `save_pass.c`
- [PKCS#11](https://github.com/openvpn/openvpn-gui/blob/master/pkcs11.c): token auth · Integrates certificate/token-based authentication support. · `pkcs11.c`

### PLAP subsystem

Logon-screen provider and supporting DLL/runtime pieces.

- [PLAP provider](https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_provider.c): logon provider · Windows logon-screen provider runtime for start-before-logon VPN. · `plap/plap_provider.c`
- [PLAP conn](https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_connection.c): session control · PLAP-side connection lifecycle and session handling. · `plap/plap_connection.c`
- [PLAP UI glue](https://github.com/openvpn/openvpn-gui/blob/master/plap/ui_glue.c): bridge layer · Connects provider/runtime logic to UI and authentication workflow. · `plap/ui_glue.c`
- [PLAP DLL](https://github.com/openvpn/openvpn-gui/blob/master/plap/plap_dll.c): dll entry · DLL entry and provider packaging for the PLAP subsystem. · `plap/plap_dll.c`
- [QR auth](https://github.com/openvpn/openvpn-gui/blob/master/qr.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](https://github.com/openvpn/openvpn-gui/blob/master/res/openvpn-gui-res.rc): resources · Resource scripts, manifests, and translated UI strings. · `res/openvpn-gui-res.rc`
- [Build system](https://github.com/openvpn/openvpn-gui/blob/master/CMakeLists.txt): build config · CMake, Autotools, MSVC, and dependency packaging setup. · `CMakeLists.txt`

## Connections

- 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.
