Important notices
Before you add a new report, we ask you kindly to acknowledge the following:
Is your feature request related to a problem? Please describe.
OPNsense currently has no integrated way to create and manage Cloudflare WARP / Cloudflare One tunnels using the MASQUE CONNECT-IP protocol on FreeBSD.
An independent native FreeBSD implementation already exists, but without an OPNsense plugin its use requires manual registration, configuration-file management, service supervision, TUN interface discovery, startup handling and route configuration. This makes persistent operation, secure secret management and multiple simultaneous tunnel instances unnecessarily difficult.
The proposed integration supports two distinct use cases:
- Egress client mode — selected hosts or networks can use Cloudflare as their Internet egress through standard OPNsense interface assignment, gateway, policy-routing, firewall and outbound NAT configuration.
- Ingress Mesh node mode — remote Cloudflare Mesh devices can reach networks published behind OPNsense.
These roles are kept separate and multiple instances of either role can run concurrently.
Describe the solution you'd like
I would like to propose a new os-usque plugin that integrates the independent usque-nativetun FreeBSD service with OPNsense.
A working development implementation is available here:
The proposed plugin provides:
- OPNsense-native MVC/API configuration pages.
configd and rc.d service integration.- Multiple independently supervised tunnel instances.
- Separate egress client and ingress Mesh node roles.
- Concurrent operation of both roles.
- Persistent startup and clean shutdown handling.
- Native FreeBSD TUN interface publication, allowing assignment through the standard OPNsense interface subsystem.
- Browser-assisted Cloudflare team enrollment for egress clients.
- Cloudflare Access service-token enrollment using an organization name, Client ID and Client Secret.
- Connector-token registration for Mesh nodes.
- Root-only storage of generated tunnel configurations and credentials.
- Service state and process reporting.
- Cleanup of generated configuration when a stopped instance is deleted.
- Optional and configurable IPv4/IPv6 Mesh return-route management.
- Standard OPNsense interface assignment, gateways, policy routing, outbound NAT and firewall rules for egress traffic.
The Rust tunnel engine remains tunnel-only. It does not take over firewall policy, policy routing, gateway management or general OPNsense responsibilities.
The network implementation uses native FreeBSD TUN interfaces, IPv4 and IPv6, QUIC/MASQUE CONNECT-IP, PMTUD, dynamic MTU handling and standards-based QUIC keepalive. The implementation uses quiche and tun-rs through their supported APIs.
No precompiled binary is embedded in the plugin. The tunnel engine is packaged separately. The current repository contains a reproducible, checksummed FreeBSD port overlay.
I understand that the OPNsense contribution guidelines require a new service binary to be available through the FreeBSD Ports Collection and prohibit embedding precompiled binaries in plugins. The proposed upstreaming sequence would therefore be:
- Prepare and submit the
usque-nativetun FreeBSD port.
- Address the resulting port review and packaging requirements.
- Submit the
os-usque plugin after, or in coordination with, acceptance of the service port.
I would appreciate guidance from the OPNsense maintainers regarding this sequence and the preferred category and naming for the service port.
Describe alternatives you've considered
- Running
usque-nativetun manually and maintaining shell scripts for service startup, routes and cleanup. This works, but it is fragile and is not integrated with OPNsense configuration, service management or interface assignment.
- Using WireGuard or IPsec. These are well-supported by OPNsense but do not provide Cloudflare WARP/Cloudflare One MASQUE registration or Cloudflare Mesh functionality.
- Running the official Cloudflare client on a separate supported host or router and forwarding traffic to it. This requires another system and separates routing and firewall policy from OPNsense.
- Adding the functionality directly to the OPNsense core. A plugin appears to be the appropriate integration point because the tunnel engine is an independent service.
Additional context
The current development version has been tested on OPNsense 26.7 / FreeBSD 15 amd64.
Verified functionality includes:
- simultaneous egress and Mesh tunnel instances;
- persistent native TUN interface creation;
- IPv4 and IPv6 operation;
- Cloudflare team, Access service-token and Mesh connector-token registration;
- policy-routing a single LAN host through an egress tunnel;
- outbound NAT through the assigned tunnel interface;
- Cloudflare trace results reporting
warp=on and gateway=on;
- remote Cloudflare Mesh devices reaching a network behind OPNsense;
- configurable IPv4 and IPv6 Mesh return routes;
- service stop/start and configuration reconciliation.
A development performance test through an OPNsense egress tunnel achieved approximately 470 Mbps download and 127 Mbps upload. This is only a test result from one environment and is not intended as a general performance guarantee.
The implementation is an independent project and is not affiliated with, endorsed by or reviewed by Cloudflare. It does not claim to be an official Cloudflare client and does not intentionally impersonate one. Device and connection information reported to Cloudflare is intended to be truthful.
The project is currently experimental and is not recommended for production use. Users are advised to create backups or snapshots and be prepared to recover or reinstall their OPNsense installation if necessary.
Licensing:
os-usque: BSD 2-Clauseusque-nativetun: MIT
AI disclosure: OpenAI Codex (GPT-5) was used as a development assistant for implementation support, code review, documentation and test orchestration. The maintainer reviewed the changes and performed the FreeBSD and OPNsense functional tests.
I am willing to maintain the plugin and its associated FreeBSD port, respond to review feedback and handle reported compatibility or security issues.
Important notices
Before you add a new report, we ask you kindly to acknowledge the following:
Is your feature request related to a problem? Please describe.
OPNsense currently has no integrated way to create and manage Cloudflare WARP / Cloudflare One tunnels using the MASQUE CONNECT-IP protocol on FreeBSD.
An independent native FreeBSD implementation already exists, but without an OPNsense plugin its use requires manual registration, configuration-file management, service supervision, TUN interface discovery, startup handling and route configuration. This makes persistent operation, secure secret management and multiple simultaneous tunnel instances unnecessarily difficult.
The proposed integration supports two distinct use cases:
These roles are kept separate and multiple instances of either role can run concurrently.
Describe the solution you'd like
I would like to propose a new
os-usqueplugin that integrates the independentusque-nativetunFreeBSD service with OPNsense.A working development implementation is available here:
The proposed plugin provides:
configdandrc.dservice integration.The Rust tunnel engine remains tunnel-only. It does not take over firewall policy, policy routing, gateway management or general OPNsense responsibilities.
The network implementation uses native FreeBSD TUN interfaces, IPv4 and IPv6, QUIC/MASQUE CONNECT-IP, PMTUD, dynamic MTU handling and standards-based QUIC keepalive. The implementation uses
quicheandtun-rsthrough their supported APIs.No precompiled binary is embedded in the plugin. The tunnel engine is packaged separately. The current repository contains a reproducible, checksummed FreeBSD port overlay.
I understand that the OPNsense contribution guidelines require a new service binary to be available through the FreeBSD Ports Collection and prohibit embedding precompiled binaries in plugins. The proposed upstreaming sequence would therefore be:
usque-nativetunFreeBSD port.os-usqueplugin after, or in coordination with, acceptance of the service port.I would appreciate guidance from the OPNsense maintainers regarding this sequence and the preferred category and naming for the service port.
Describe alternatives you've considered
usque-nativetunmanually and maintaining shell scripts for service startup, routes and cleanup. This works, but it is fragile and is not integrated with OPNsense configuration, service management or interface assignment.Additional context
The current development version has been tested on OPNsense 26.7 / FreeBSD 15 amd64.
Verified functionality includes:
warp=onandgateway=on;A development performance test through an OPNsense egress tunnel achieved approximately 470 Mbps download and 127 Mbps upload. This is only a test result from one environment and is not intended as a general performance guarantee.
The implementation is an independent project and is not affiliated with, endorsed by or reviewed by Cloudflare. It does not claim to be an official Cloudflare client and does not intentionally impersonate one. Device and connection information reported to Cloudflare is intended to be truthful.
The project is currently experimental and is not recommended for production use. Users are advised to create backups or snapshots and be prepared to recover or reinstall their OPNsense installation if necessary.
Licensing:
os-usque: BSD 2-Clauseusque-nativetun: MITAI disclosure: OpenAI Codex (GPT-5) was used as a development assistant for implementation support, code review, documentation and test orchestration. The maintainer reviewed the changes and performed the FreeBSD and OPNsense functional tests.
I am willing to maintain the plugin and its associated FreeBSD port, respond to review feedback and handle reported compatibility or security issues.