103 lines
7.8 KiB
Markdown
103 lines
7.8 KiB
Markdown
# 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 to NordVPN NordLynx server addresses 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{NordVPN NordLynx destination on UDP port 51820 and 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 to NordVPN NordLynx server addresses 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. |
|