Document NordVPN failover plugin requirements
This commit is contained in:
commit
79acee98d3
2 changed files with 133 additions and 0 deletions
30
.gitignore
vendored
Normal file
30
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,30 @@
|
||||||
|
# Local configuration and secrets
|
||||||
|
.env
|
||||||
|
.secrets/
|
||||||
|
config.local.*
|
||||||
|
*.token
|
||||||
|
*.key
|
||||||
|
|
||||||
|
# OPNsense images and VM state
|
||||||
|
*.img
|
||||||
|
*.iso
|
||||||
|
*.qcow2
|
||||||
|
*.raw
|
||||||
|
*.vmdk
|
||||||
|
*.zvol
|
||||||
|
.vagrant/
|
||||||
|
.vm/
|
||||||
|
|
||||||
|
# Build and test output
|
||||||
|
work/
|
||||||
|
dist/
|
||||||
|
artifacts/
|
||||||
|
coverage/
|
||||||
|
*.log
|
||||||
|
|
||||||
|
# Editor and agent state
|
||||||
|
.claude/
|
||||||
|
.codex/
|
||||||
|
|
||||||
|
# Development journal
|
||||||
|
docs/journal
|
||||||
103
docs/spec/opnsense-nordvpn-plugin-spec.md
Normal file
103
docs/spec/opnsense-nordvpn-plugin-spec.md
Normal 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. |
|
||||||
Loading…
Reference in a new issue