DOCSEARCHbyAlgolia
Submit Docs

usque

repository·main·Indexed 22 days ago

https://github.com/diniboy1123/usque

An open-source reimplementation of the Cloudflare WARP client's MASQUE mode. Using the Connect-IP (RFC 9484) protocol, usque provides various proxy and tunneling modes including Native Tunnel (TUN device), SOCKS5, HTTP, L4 TCP-only proxies, and port forwarding. It supports Cloudflare ZeroTrust registration, HTTP/2 TCP fallback, and custom SNI configuration.

Tokens
8.2K
Snippets
17
Records
53
Agent score
76%

What's inside usque

  1. Understand the limitations of using usque as a library

    main
    While usque exposes certain functions in the api/ package, it is primarily designed as a CLI tool. The current implementation is considered unstable, the API is subject to change, and the abstractions are not optimized for library usage. It is recommended to fork the repository and integrate functionality directly rather than using it as a dependency.

  2. Optimize UDP buffer sizes on Linux/BSD

    main

    Because usque uses the quic-go library, the default Linux UDP buffer size may be too small for optimal performance. You can increase the maximum receive and send buffer sizes using sysctl to improve throughput.

    $ sudo sysctl -w net.core.rmem_max=7500000
$ sudo sysctl -w net.core.wmem_max=7500000

  3. Use L4 Proxy Modes (TCP-only)

    main

    L4 modes are lightweight, high-performance alternatives to the full SOCKS5/HTTP proxy modes. They use direct HTTP/3 CONNECT streams and skip the heavy user-space networking stack. They are strictly for TCP-only workloads.

    Available Commands:

    • l4-http-proxy: Expose Warp as an L4 TCP-only HTTP proxy with CONNECT support.
    • l4-socks: Expose Warp as an L4 TCP-only SOCKS5 proxy.

    Both modes support the same -b, -p, -u, and -w flags as the standard proxy modes.

    $ ./usque l4-http-proxy
$ ./usque l4-socks

  4. Build usque from source

    main

    To build usque from source, ensure you have Go 1.26.3 or later installed.

    1. Clone the repository and navigate to the root directory.
    2. Run the build command to produce the usque binary.
    CGO_ENABLED=0 go build -ldflags="-s -w" .

  5. Cross-compile usque for other platforms

    main

    You can cross-compile the binary by setting the GOOS and GOARCH environment variables. For example, to build a Windows amd64 binary from a Linux system:

    GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" .

  6. Configure ZeroTrust support

    main

    To use usque with Cloudflare ZeroTrust, you must manually provide authentication credentials because SSO is required for login.

    1. Obtain credentials: Use the register command to generate a personal WARP configuration file.
    2. Modify config: Keep all fields unchanged except for access_token and id. You can find these values in /var/lib/cloudflare-warp/reg.json if you have the official WARP client installed on Linux, or by checking existing device IDs in the ZeroTrust dashboard.
    3. Enroll: Run the enroll command to refresh the configuration with your new credentials. Note that the license field will appear empty; this is expected behavior for ZeroTrust.

    Note: For any mode involving a tunnel connection, it is recommended to set the SNI to zt-masque.cloudflareclient.com using the -s flag.

  7. Register a new Cloudflare Warp account

    main

    Before using usque, you must register a device. The register subcommand creates a fresh Warp account, performs device registration, and handles MASQUE device enrollment. It generates a config.json file required for all other modules.

    Options:

    • -n <device-name>: Specify a custom name for the device.
    • --jwt <team-token>: Use this for ZeroTrust registration. To obtain a token, visit https://<team-domain>/warp, authenticate, and extract the token from the success page's source code or via the browser console: console.log(document.querySelector("meta[http-equiv='refresh']").content.split("=")[2]).

  8. Re-enroll a device key

    main

    The enroll command refreshes your existing configuration with data downloaded from Cloudflare servers. This is useful for:

    • Migrating to a new device while the old key is still enrolled.
    • Switching from WireGuard to MASQUE.
    • Updating ZeroTrust configurations with newly assigned IPv4/IPv6 addresses.

    Warning: This command refreshes your config.json with new data; ensure you have backups of your current configuration before running it.

    $ ./usque enroll

  9. Install usque via pre-built binaries

    main

    Download the latest release from the GitHub releases page. Supported platforms include:

    • Android: arm64
    • Linux: armv5, armv6, armv7, arm64, amd64 (Note: only amd64 has been tested)
    • Windows: arm64, amd64, 386
    • Darwin: arm64, amd64

    After downloading, extract the archive and move the usque binary to a directory in your PATH to run it from anywhere.

  10. Use SOCKS5 Proxy Mode

    main

    Exposes the Warp tunnel as a SOCKS5 proxy. This mode is cross-platform, requires no root privileges, and supports both IPv4 and IPv6, as well as TCP and UDP. It emulates a user-space network stack.

    Configuration:

    • -b <address>: Bind to a specific address (default 0.0.0.0).
    • -p <port>: Bind to a specific port (default 1080).
    • -u <username>: Enable authentication with a username.
    • -w <password>: Enable authentication with a password.

    Note: Local SOCKS5 traffic is not encrypted. Use with caution on public networks.

  11. Use Native Tunnel Mode (TUN device)

    main

    Native tunnel mode creates a real network interface (e.g., tun0 on Linux or usque on Windows) and injects traffic directly into the kernel's network stack. This is one of the fastest modes and supports Layer 3 (IP) traffic.

    Requirements:

    • Linux: Requires the TUN device module (tun.ko) and iproute2. Usually requires sudo privileges.
    • Windows: Requires wintun.dll to be present in the same directory as usque.exe. Usually requires administrative privileges.

    Important: usque does not set system routes automatically. You must manually add routes to direct traffic through the tunnel interface.

    Example (Linux): To route all traffic through tun0 (assuming eth0 is your physical interface and 192.168.1.1 is your gateway):

    1. Route the tunnel endpoint (found in config.json as endpoint_v4) through your physical interface: sudo ip route add 162.159.198.1/32 via 192.168.1.1 dev eth0
    2. Add default routes for the tunnel: sudo ip route add default dev tun0 && sudo ip -6 route add default dev tun0
    $ sudo ./usque nativetun

# Testing the interface
$ ping -I tun0 1.1
$ curl --interface tun0 https://cloudflare.com/cdn-cgi/trace

  12. Use Port Forwarding Mode

    main

    Allows forwarding specific ports between the host and the WARP network. This is intended for advanced users with ZeroTrust networks where devices can communicate with each other via their internal WARP IPs.

    Syntax: Use -R for remote forwarding (WARP to host) and -L for local forwarding (host to WARP).

    Example: If your device's internal IPv4 is 100.96.0.3 and you want to forward host port 8080 to the WARP network, and forward WARP device 100.96.0.2:8081 to your host port 8081:

    $ ./usque portfw -R 100.96.0.3:8080:localhost:8080 -L localhost:8081:100.96.0.2:8081