Cloudflare WARP for your OpenWrt router.

What it is

Cloudflare WARP is Cloudflare's consumer VPN-ish service. usque speaks its MASQUE transport directly and bridges it to a Linux TUN interface. This port wires the client into OpenWrt's service manager, firewall and web UI — and separates two things that used to be bundled together: connecting the tunnel and routing traffic into it.

Two states: connected vs. routed

Requirements

Before you start

Three quick checks tell you whether the packages will install and run:

# release + architecture (expect 25.12.x / arm_cortex-a7_neon-vfpv4)
grep -E '^(DISTRIB_RELEASE|DISTRIB_ARCH)=' /etc/openwrt_release

# free space in the overlay (want ~3 MB or more)
df -h /overlay

# TUN support (kmod-tun is installed as a dependency, but check the kernel module)
lsmod | grep tun

# optional: existing IPv6 default route (ipv6_route=auto leaves it alone)
ip -6 route show default

If lsmod prints nothing, the module is not loaded yet — installing the package pulls in kmod-tun. If your image has no TUN support at all, the tunnel cannot start; use a standard OpenWrt image.

Install

Run these on the router over SSH. The feed is a signed apk repository served from GitHub Pages. Installing the packages does not start a tunnel and does not change any routing — you configure and opt in afterwards.

Quick install

Trust the feed key, add the repository, refresh the index and install the LuCI app (which pulls in the usque daemon and kmod-tun):

wget -O /etc/apk/keys/usque.pem https://fmu.github.io/openwrt-usque/feed/usque.pem
echo "https://fmu.github.io/openwrt-usque/feed/packages.adb" >> /etc/apk/repositories.d/customfeeds.list
apk update
apk add luci-app-usque

Step by step

1. Install the feed's public key

   apk verifies every repository index against the keys installed in /etc/apk/keys/. In apk v3 the key is matched by its public-key identity, so the filename is not significant; we use usque.pem so it stays recognisable and matches the commands on this page.

   wget -O /etc/apk/keys/usque.pem https://fmu.github.io/openwrt-usque/feed/usque.pem

   If wget is missing or fails with a TLS error, use uclient-fetch -O /etc/apk/keys/usque.pem <same URL> instead.

2. Add the repository

   OpenWrt's apk keeps extra repositories in /etc/apk/repositories.d/*.list. Append the feed's index URL:

   echo "https://fmu.github.io/openwrt-usque/feed/packages.adb" >> /etc/apk/repositories.d/customfeeds.list

   Running this twice adds the line twice — harmless, but remove duplicates if you want a tidy file. The URL points directly at the packages.adb index (ndx repository type in apk v3); package files are then fetched from the same /feed/ directory, which is why the feed is flat.

3. Refresh and install

   apk update
   apk add luci-app-usque

   The luci-app-usque package depends on usque and kmod-tun, so one command installs the daemon, the init script, the UCI configuration and the LuCI view. For a CLI-only setup use apk add usque.

   Already installed? apk add luci-app-usque only installs missing packages. With apk-tools 3 it does not upgrade an existing installation — apk just reports the package as “upgradable from …” and keeps the old version. Use the upgrade steps below instead.

   Check what you got — the two packages are versioned independently:

   apk info -v usque            # usque-0.2.1-r1
   apk info -v luci-app-usque   # luci-app-usque-1.1.1-r1
   sha256sum /usr/bin/usque
   # 413515df54fe2376dd2948f31ed548477604d6bb351f4909e70b8a4658ae5c9a

4. Open LuCI

   Go to Services → usque and continue with First run. The direct URL is http://192.168.1.1/cgi-bin/luci/admin/services/usque (adjust the router IP).

Signature & trust

The feed index (packages.adb) is signed with an ECDSA P-256 key. The matching public key is what you downloaded to /etc/apk/keys/usque.pem and is also committed in the repository as keys/usque.pem. Verify the download if you want to be sure:

sha256sum /etc/apk/keys/usque.pem

The SHA-256 of the published key file (as served at https://fmu.github.io/openwrt-usque/feed/usque.pem and committed as keys/usque.pem in the repository) is:

f47c63b55e2b28f49d2ff1f751ea6401043cb30821620ad2ac9ad1c7561abe4f

If the two hashes match, the key you installed is the one the feed is signed with. If the feed is ever re-keyed, this page is updated with the new fingerprint. You can also verify an individual package file that you downloaded yourself with apk verify <file.apk>.

If the key is missing or does not match the index signature, apk refuses with an UNTRUSTED signature error. Fix the setup rather than bypassing it — but if you are stuck (for example, the key download was intercepted or the feed was rebuilt), you can install without verification as a last resort:

apk add --allow-untrusted luci-app-usque

--allow-untrusted disables signature checking for that transaction. Only use it with artifacts you obtained over a trusted connection, and remove the repository afterwards if you cannot restore proper verification.

Remove the repository again

To stop using the feed without touching the installed packages:

sed -i '\#fmu.github.io/openwrt-usque#d' /etc/apk/repositories.d/customfeeds.list
rm -f /etc/apk/keys/usque.pem
apk update

Then uninstall the packages if you no longer need them.

Upgrading an existing install

apk-tools 3 does not upgrade installed packages through apk add: with an older version already installed, apk update && apk add luci-app-usque leaves it in place and only mentions that it is “upgradable from …”. Upgrade in one of these ways:

# 1) upgrade just the two usque packages (recommended)
apk update
apk upgrade usque luci-app-usque

# 2) or upgrade every installed package
apk update
apk upgrade

# 3) or pin exact versions from the feed
apk policy usque luci-app-usque          # show versions available in the feed
apk add usque=<version> luci-app-usque=<version>
# e.g. apk add usque=0.2.1-r1 luci-app-usque=1.1.1-r1

The current feed provides usque 0.2.1-r1 and luci-app-usque 1.1.1-r1. A plain apk add luci-app-usque will only install it on a clean system; use one of the upgrade commands above on an existing install.

apk upgrade without package names upgrades all installed packages — convenient, but it can also update unrelated packages (and pull a new kernel on some systems). Naming the packages (apk upgrade usque luci-app-usque) or pinning versions with apk add <pkg>=<version> keeps the change targeted. Use apk policy to see the versions in the feed and apk info -v to check what is installed.

Coming from v0.1.x? The automatic route takeover is gone: after upgrading, check the Default route switch of each connection — it defaults to off — and enable it if you want the full-tunnel behaviour you had before. See Routing.

First run in LuCI

The LuCI app lists your connections, creates WARP identities, starts the service and shows live status. Routing stays off until you enable it.

1. Open Services → usque

   In the LuCI menu under Services, pick usque (Cloudflare WARP). The page shows a Connections table — initially one connection named warp0 — with its enabled checkbox, interface, mode, IPv4/IPv6 routing status and per-connection actions (Start / Stop / Restart / Test / Logs / Remove). Below it are the selected connection's settings, the WARP account / configuration file section, Global settings and diagnostics. Each connection is an independent tunnel with its own interface and config file.

2. Generate a WARP configuration for the connection

   For the default connection, the Account / configuration file section asks you to create an identity. Enter an optional device name (it shows up in your Cloudflare WARP device list), tick the box accepting Cloudflare's terms, and click Generate WARP configuration.

   Under the hood this runs, for that connection's config file:

   usque --config /etc/usque/warp0.json register --accept-tos --force -n "my-openwrt"

   The result is /etc/usque/warp0.json: an anonymous WARP device identity containing a private key and an access token. It is created with owner-only permissions — treat it like a password and never publish it. Ticking the box is what accepts Cloudflare's WARP terms; if you skip the UI and just start the service with auto_register=1, the init script registers a device for you and accepts the terms implicitly.

   Registration needs working internet. It happens over HTTPS to Cloudflare through your normal WAN before the tunnel exists, so the router must already be online (and its clock roughly correct) when you press the button.

3. Enable and start

   Tick Enabled for the connection (stored as its enabled option), click Save & Apply, then press the connection's Start action. The state should switch to running within a few seconds, and the connection's interface (warp0) appears with its tunnel address.

   The init script only starts connections whose enabled option is set: pressing Start on a disabled connection tells you to enable it and Save & Apply first. The same applies to /etc/init.d/usque start. If no connection is enabled at all, Save & Apply stops and disables the service.

4. Verify the tunnel

   With the service running, the connection shows its state, addresses and the last connection error (if any). The app's connection test runs a probe from the router:

   wget -qO- https://www.cloudflare.com/cdn-cgi/trace | grep -E '^(ip|loc|colo|warp)='

   With IPv4 routing still off, this reports warp=off — that is expected: the tunnel is up but no IPv4 traffic is routed into it yet. (On a WAN without native IPv6 the tunnel may already provide IPv6, because of ipv6_route=auto; see Routing.) The connection table labels this state IPv4: not routed; IPv4 route pending means the option was saved but the connection has not been restarted yet.

5. Choose whether traffic uses the tunnel

   Open the connection's settings. The routing switches are off/unset by default:

   • Default route (off): send all IPv4 traffic through the tunnel — the classic full-tunnel mode. Default route metric sets the route metric (lower wins).
   • IPv6 route (auto): install an IPv6 default route only if the router has no native/WAN IPv6 default route yet. always installs it regardless; off never does.
   • Enable IPv6 on this tunnel (on): the tunnel's own IPv6 address.
   • Global settings → Provide IPv6 to LAN hosts (NAT66 through the tunnel) (off) and LAN IPv6 prefix: give LAN devices IPv6 via ULA + router advertisements, NAT66ed through the tunnel.

   Save & Apply (which restarts the connection), then re-run the check above. With Default route on it should now report warp=on and a Cloudflare egress IP. Details and manual alternatives are in Routing.

Routing: what changes, and only when you ask

usque has two independent layers: establishing the tunnel (always) and sending traffic into it (opt-in). This section describes exactly what each switch changes on the network, so there are no surprises.

Routing options

How do I get traffic through the tunnel?

1. Recommended: enable Default route

   Turn on Default route in the connection's settings (or set default_route='1' in UCI) and save. That is the classic full-tunnel mode: forwarded LAN traffic and router-originated traffic use the tunnel, with the WAN kept as fallback.

   uci set usque.warp0.default_route='1'
   uci commit usque
   /etc/init.d/usque restart

   The UCI example assumes the default connection is called warp0; adjust the section name if you renamed it.

2. Route only selected prefixes yourself

   With Default route off, the tunnel device is a normal interface — add your own routes for the destinations you want tunneled. usque does not manage these, so re-add them after a restart (or script them in a hotplug file):

   ip route add 203.0.113.0/24 dev warp0
   ip route add 198.51.100.0/24 dev warp0
   ip route show | grep warp0

   This also makes the tunnel interface usable by other routing software (mwan3, VPN policy routing, custom nftables marks) without usque touching the main table.

3. Use policy routing

   For per-client or per-protocol tunnelling, combine the tunnel device with your own ip rule/nftables marks (or mwan3). Keep in mind that if you later enable Default route, usque installs the priority-1000 rule that makes the main table authoritative while the tunnel is up — stop the service if you need your own policy rules to win.

4. IPv6

   IPv6 needs no route to connect, but traffic needs one to be routed. With ipv6_route=auto (default) a tunnel IPv6 default route is installed only when the router has none. Use always to force it, or off to leave IPv6 routing untouched. To give LAN devices IPv6 on an IPv4-only WAN, see LAN IPv6.

LAN IPv6 (ULA + NAT66)

On an IPv4-only WAN (common with CGNAT, tethering or DS-Lite), LAN devices have no IPv6. With lan_ipv6=1 (global setting) usque gives the LAN a unique local address prefix, announces it via router advertisements and NAT66s it through the tunnel, so devices get working IPv6 to the internet. It only takes effect when a connection with IPv6 enabled provides the IPv6 default route (ipv6_route=auto or always).

mwan3 and other policy routing

By default, usque does not install any policy rule, so mwan3 keeps working normally. Only when Default route is enabled — or an IPv6 route is installed — does the hook add ip rule priority 1000 from all lookup main (and its IPv6 counterpart), because otherwise mwan3's fwmark rules can silently send traffic to the WAN while the tunnel looks healthy. The rule is removed when the tunnel stops. If you need mwan3's per-WAN policies while the tunnel is up, stop the service or leave Default route off and route only selected prefixes yourself.

Multiple connections

Every tunnel is a separate config usque '<name>' section in /etc/config/usque, with its own interface, config file, mode and routing switches. The default connection is warp0.

Managing connections in LuCI

The connection table lists every connection with its mode, interface, IPv4/IPv6 routing state and per-connection actions (Start / Stop / Restart / Test / Logs / Remove). Selecting a connection shows its settings: mode, config file, interface name, MTU, endpoint port, the routing switches and (Cloudflare mode) the account card with generate / re-register / delete configuration. Each enabled connection runs as its own procd instance; starting the service starts all of them.

Removing a connection stops it and deletes its UCI section but keeps its config file on disk — delete the file separately if you also want to drop the WARP registration.

Connection example

A minimal /etc/config/usque with the default Cloudflare connection and a second tunnel. The second section shows the shape of an additional connection (here a second Cloudflare identity; for non-Cloudflare endpoints see custom mode):

config usque 'warp0'
	option enabled '1'
	option mode 'cloudflare'
	option config_file '/etc/usque/warp0.json'
	option interface 'warp0'
	option mtu '1400'
	option endpoint_port '443'
	option default_route '0'
	option metric '0'
	option ipv6 '1'
	option endpoint_ipv6 '0'
	option ipv6_route 'auto'
	option always_reconnect '1'
	option auto_register '1'
	option device_name ''
	option log_level 'info'
	option sni ''
	option authority ''

config usque 'backup'
	option enabled '0'
	option mode 'cloudflare'
	option config_file '/etc/usque/backup.json'
	option interface 'warp1'
	option default_route '1'
	option metric '10'

The second connection is disabled in this example (enabled '0') — enable it when you need it. The default config_file is /etc/usque/<section>.json; each connection needs a unique interface. Option names, defaults and the global LAN IPv6 settings are listed in Advanced.

Custom MASQUE / Connect-IP endpoints

Set mode='custom' to skip Cloudflare registration and use credentials you already have — in LuCI choose Custom endpoint as the connection's mode, then paste the JSON into the Configuration JSON box and press Import, or write the file yourself. There is no registration in this mode. Required fields: private_key, endpoint_v4, endpoint_pub_key and ipv4; optional: ipv6, endpoint_v6.

{
  "endpoint_v4": "203.0.113.10",
  "endpoint_v6": "",
  "endpoint_pub_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "private_key": "<base64 DER EC P-256 private key>",
  "ipv4": "172.16.0.2",
  "ipv6": "fd00::2"
}

Shape only — get the real values from your provider. Importing writes the file atomically with mode 600. Provider-specific TLS settings are separate connection options (not part of the JSON): sni (-s; LuCI TLS SNI (custom mode)), authority (--authority; LuCI HTTP authority (custom mode)) and protocol (--protocol; LuCI CONNECT protocol (custom mode) — pick connect-ip for an RFC 9484 server, leave empty for Cloudflare's cf-connect-ip). logread -e usque reports the handshake result.

The endpoint must speak a compatible MASQUE/Connect-IP service. Custom connections are not registered or re-registered by the init script, and auto_register does nothing for them.

Advanced configuration

Everything the LuCI app sets is plain UCI in /etc/config/usque, so it can be scripted, versioned or set over SSH.

UCI options

Each config usque '<name>' section is one connection. The section name is the connection name used by LuCI, the procd instance name and the state directory (/var/run/usque/<name>/); the packaged default is warp0. Options are read as usque.<name>.option.

Global options

Two options live in the config settings 'settings' section and apply to the whole package rather than a single connection (UCI path usque.settings.*). In LuCI they are in Global settings.

Example: turn on full-tunnel routing for the default connection, force IPv6 through the tunnel and give LAN clients IPv6:

uci set usque.warp0.default_route='1'
uci set usque.warp0.ipv6_route='always'
uci set usque.settings.lan_ipv6='1'
uci commit usque
/etc/init.d/usque restart

Config files and identities

Each connection points at its own JSON file (for the default connection: /etc/usque/warp0.json). In Cloudflare mode it holds the device's private_key and access_token; in custom mode it holds the fields listed under custom mode. Files are written with mode 600 (root only).

The default path is /etc/usque/<section>.json (so the default connection uses warp0.json). If a file ever ends up with the wrong mode, LuCI offers Fix permissions (chmod 600) for the selected connection.

• Back one up off-device to keep the same WARP device across reinstalls: cp /etc/usque/warp0.json /tmp/ and copy it away.
• Delete it to force a fresh registration: rm -f /etc/usque/warp0.json then restart (with auto_register=1) or press Re-register in LuCI.
• Never share it — anyone with the file can use your WARP identity.

CLI

The daemon is also fully usable without LuCI. Registration is always per connection config file:

# register a new Cloudflare device for a specific connection
usque --config /etc/usque/warp0.json register --accept-tos --force -n "my-openwrt"

# run a tunnel in the foreground (what the init script does for each connection)
usque --config /etc/usque/warp0.json native-tun -n warp0 -m 1400 -P 443 --always-reconnect

# show help and version
usque --help
usque --version

Manual native-tun runs do not install routes by themselves — the packaged service adds the routing hook and applies the switches described above. Use the service for routed setups. The init script maps the UCI options to CLI flags: ipv6='0' → --no-tunnel-ipv6, endpoint_ipv6='1' → --ipv6, sni → -s, authority → --authority, protocol → --protocol.

Service commands and logs

/etc/init.d/usque start          # every enabled connection
/etc/init.d/usque start warp0    # one connection (section name)
/etc/init.d/usque stop warp0
/etc/init.d/usque restart warp0
/etc/init.d/usque stop
/etc/init.d/usque reload         # re-read UCI, restart the instances
/etc/init.d/usque status
/etc/init.d/usque enable         # start at boot
/etc/init.d/usque disable

logread -e usque                 # all connections (lines are prefixed with the section name)
logread -e usque -f              # follow live

If you edit UCI directly and only need the new options applied, run uci commit usque && /etc/init.d/usque restart. procd restarts a connection at most 5 times within an hour (10 s apart) — after that it stays stopped until you restart the service, so fix the underlying error first.

Status over ubus

The LuCI app is backed by an rpcd script, which is also handy for scripts and monitoring.

ubus call luci.usque status
ubus call luci.usque getConfig            '{"section":"warp0"}'   # public fields only
ubus call luci.usque test                 '{"section":"warp0"}'
ubus call luci.usque logs                 '{"section":"warp0"}'
ubus call luci.usque setInitAction        '{"action":"restart","section":"warp0"}'
ubus call luci.usque register             '{"section":"warp0","name":"my-openwrt","accept_tos":true}'
ubus call luci.usque registerStatus       '{"section":"warp0"}'
ubus call luci.usque importConfig         '{"section":"backup","json":"{...}"}'
ubus call luci.usque deleteConfig         '{"section":"backup"}'
ubus call luci.usque fixConfigPermissions '{"section":"warp0"}'

The private key and access token are never returned by getConfig; importConfig only works for connections in custom mode.

Troubleshooting

Start with logread -e usque | tail -n 40 — the daemon logs connection and routing decisions. The cases below cover most installs.

ip route show | grep -E 'warp|default'
wget -qO- https://www.cloudflare.com/cdn-cgi/trace | grep -E '^(ip|warp)='

ip rule show | grep '^1000:'
ip -6 rule show | grep '^1000:'

# if it is missing, add it for the current session:
ip rule add priority 1000 from all lookup main
ip -6 rule add priority 1000 from all lookup main   # only with IPv6 routing

ip -6 route show default
uci set usque.warp0.ipv6_route='always'   # force the tunnel
uci commit usque && /etc/init.d/usque restart

# or disable IPv6 for this connection entirely:
uci set usque.warp0.ipv6='0'

uci show usque.settings
uci show network.globals.ula_prefix
uci show network.lan | grep -E 'ip6assign|ip6addr'
uci show dhcp.lan | grep -E 'ra|dhcpv6'
ip -6 addr show br-lan
logread -e usque | tail -n 20

uci show usque | grep -E 'default_route|metric|interface'
ip route show default
ip -6 route show default

rm -f /tmp/luci-indexcache*
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

apk info -v usque
apk info -v luci-app-usque
apk policy usque luci-app-usque

ip rule show
ip route
# remove leftovers if any:
ip rule del priority 1000
ip route del default dev warp0
fw4 reload
/etc/init.d/network restart

df -h /overlay
du -sh /usr/bin/usque
apk cache clean

FAQ

Uninstall & cleanup

Stopping the service restores normal routing. Removing the packages cleans up everything except your saved configuration and identities.

/etc/init.d/usque stop
/etc/init.d/usque disable
apk del luci-app-usque usque

Source, builds & licences

Everything on this page is produced by GitHub Actions from the public repository — binary, apk packages, signed feed and this site.

Repository layout

Build pipeline

1. Build the binary — cross-compilation to armv7-unknown-linux-musleabihf with a static musl toolchain, LTO and opt-level="z", then stripped. See the workflows and build/build-usque.sh.
2. Package & sign — the OpenWrt 25.12.6 SDK builds usque and luci-app-usque; scripts/ assembles the feed and signs packages.adb with an ECDSA P-256 key (package.yml).
3. Publish — publish.yml copies docs/ to the site root, puts the public key and the signed feed into /feed/, and deploys the artifact to GitHub Pages.

Verification: the 0.2.1-r1 / 1.1.1-r1 packages were exercised on a live OpenWrt 25.12.6 ipq40xx router — signed-feed install, service lifecycle, opt-in IPv4 routing, IPv6 (auto and forced), multiple connections, custom MASQUE/Connect-IP mode and LAN IPv6/NAT66. Scripts, evidence and the check matrix are in tests/RESULTS.md.

Changes compared to upstream

The vendored client is trimmed and adapted to keep the binary small and make it manageable by procd/LuCI: TUN mode only (SOCKS5, HTTP proxy and port-forwarding code removed), QUIC-only transport (the HTTP/2 fallback is removed to save space), no BoringSSL (QUIC via ring, which supports 32-bit ARM), non-interactive register --accept-tos --force, and a size-optimised release profile. Multi-connection management, opt-in routing, IPv6 route selection and LAN IPv6/NAT66 are implemented in this repository's OpenWrt init script, routing hook and LuCI app rather than in the tunnel client. Details are recorded in build/PATCHES.md and UPSTREAM.md.

Credits & licence

• Tunnel client: FireMasterK/usque-rs, MIT licensed (upstream text kept at src/LICENSE.md).
• Packaging, init scripts, LuCI app and this site: MIT, same repository — see LICENSE.md.
• Cloudflare WARP, WARP and the Cloudflare logo are trademarks of Cloudflare, Inc.

Privacy

This site has no analytics, cookies or external resources — it is plain HTML, CSS and a tiny inline copy-to-clipboard script. GitHub Pages serves it and may log request metadata as described in GitHub's privacy statement. The packages themselves contain no telemetry; the tunnel's traffic goes to Cloudflare by design, and custom endpoints receive their traffic instead.