ms2k/opnsense-nordvpn-plugin
SHA256
Watch
0
Code Releases Activity

Document NordVPN failover plugin requirements

Browse source
This commit is contained in:
ms2k 2026-08-02 21:00:08 +09:00
commit 79acee98d3
1 changed files with 133 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

103
docs/spec/opnsense-nordvpn-plugin-spec.md Normal file
View file

@ -0,0 +1,103 @@
# OPNsense NordVPN Plugin Specification
## Purpose
The plugin maintains a NordLynx WireGuard connection on OPNsense and changes to another eligible NordVPN server when the Managed Tunnel is unavailable.
```mermaid
flowchart LR
Operator[Operator] --> UI[OPNsense WebGUI]
UI --> Plugin[Plugin]
Plugin --> OPNsense[OPNsense WireGuard and firewall]
Plugin --> NordVPN[NordVPN APIs]
```
## Terminology
| Term | Meaning |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Managed Tunnel | The WireGuard connection maintained by the plugin. |
| Tunnel Availability | The Managed Tunnel health result. A healthy result is available; every other result is unavailable. |
| NordVPN Egress Enrollment | The operator-selected native OPNsense firewall criteria that identify IPv4 traffic for routing through the Managed Tunnel. |
| Direct Egress Gateway | The operator-selected OPNsense gateway used when traffic bypasses the Managed Tunnel. It defaults to the system default gateway. |
## Requirements
| Area | Requirement |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime | Health checking and reconciliation run on the OPNsense appliance. |
| Configuration | Plugin configuration is available through the OPNsense WebGUI. |
| Bootstrap | The WebGUI accepts a NordVPN Access Token to obtain the initial NordLynx private key. |
| Location | The operator can select an allowlist of countries. An empty allowlist permits every country returned by NordVPN recommendations. |
| Health | The plugin determines Tunnel Availability. |
| Failover | When the Managed Tunnel is unavailable, the plugin tries other eligible servers until the Managed Tunnel becomes available or no untried eligible server remains. |
| Traffic enrollment | The operator configures the NordVPN Egress Enrollment through native OPNsense firewall selectors. The plugin does not maintain a separate address-membership model. |
| Enrollment warning | The WebGUI warns when the NordVPN Egress Enrollment can include an RFC 1918 destination address. |
| Ownership | The operator owns referenced OPNsense aliases. The plugin owns the Managed Tunnel, its associated gateway, and its generated firewall rules. |
| Direct egress | The operator can select the Direct Egress Gateway. |
| Failure policy | Fail closed is the default. Fail open is an operator-selected option. |
| WireGuard exemption | An operator-selected toggle routes outbound UDP destination port `51820` traffic through the Direct Egress Gateway ahead of NordVPN policy routing. |
| Repository data | Committed content contains no secrets or configuration values that identify or distinguish an actual deployment. |
## Bootstrap
```mermaid
sequenceDiagram
actor Operator
participant UI as OPNsense WebGUI
participant Plugin
participant NordVPN
participant WireGuard as OPNsense WireGuard
Operator->>UI: Submit NordVPN Access Token
UI->>Plugin: Request NordLynx private key
Plugin->>NordVPN: Exchange NordVPN Access Token
NordVPN-->>Plugin: Return NordLynx private key
Plugin->>WireGuard: Configure Managed Tunnel
Plugin-->>UI: Report result
```
## Reconciliation
```mermaid
flowchart TD
Tick[Periodic reconciliation] --> Check{Managed Tunnel available?}
Check -->|yes| Keep[Retain current server]
Check -->|no| Discover[Discover recommended servers permitted by the country allowlist]
Discover --> Candidate{Untried eligible server remains?}
Candidate -->|yes| Update[Update Managed Tunnel]
Candidate -->|no| Apply[Apply Failure Policy]
Update --> Verify{Managed Tunnel available?}
Verify -->|yes| Keep
Verify -->|no| Candidate
```
## Traffic enrollment and failure policy
```mermaid
flowchart TD
Packet[Outbound IPv4 packet] --> Exemption{UDP destination port 51820 exemption enabled?}
Exemption -->|yes| Direct[Direct Egress Gateway]
Exemption -->|no| Enrolled{Matches NordVPN Egress Enrollment?}
Enrolled -->|no| Native[Continue native OPNsense rule evaluation]
Enrolled -->|yes| Rule[Plugin-generated firewall rule]
Rule --> Available{Managed Tunnel available?}
Available -->|yes| Nord[Managed Tunnel gateway]
Available -->|no| Policy{Failure Policy}
Policy -->|fail closed| Block[Block]
Policy -->|fail open| Direct
```
## Acceptance
| Capability | Required result |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| Bootstrap | The operator can obtain and configure the initial NordLynx private key through the WebGUI. |
| Stable operation | A healthy Managed Tunnel retains its current server. |
| Failover | An unavailable Managed Tunnel changes to another eligible server when one establishes availability. |
| Country selection | Selected servers satisfy the country allowlist when it is not empty. |
| Traffic enrollment | Matching IPv4 traffic uses the Managed Tunnel gateway while the Managed Tunnel is available. |
| Enrollment warning | The WebGUI warns when the NordVPN Egress Enrollment can include an RFC 1918 destination address. |
| WireGuard exemption | When enabled, outbound UDP destination port `51820` traffic uses the Direct Egress Gateway. |
| Fail closed | Matching IPv4 traffic is blocked while the Managed Tunnel is unavailable. |
| Fail open | Matching IPv4 traffic uses the Direct Egress Gateway while the Managed Tunnel is unavailable. |