Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

🎭 MASQUE proxies

MASQUE brings UDP and IP tunnelling to HTTP proxies. It is useful when traffic cannot travel through an ordinary TCP CONNECT tunnel: HTTP/3 is one example, because its QUIC connections use UDP.

Rama supports two MASQUE protocols:

  • CONNECT-UDP tunnels UDP payloads to a particular host and port. Use it to reach an HTTP/3 server or another UDP service through a proxy.
  • CONNECT-IP tunnels complete IPv4 or IPv6 packets. It is a building block for VPNs, access to private networks and tunnels between sites.
%3clientclientMASQUE proxy (rama)MASQUE proxy (rama)client->MASQUE proxy (rama) HTTP tunnel destination network or servicedestination network or serviceMASQUE proxy (rama)->destination network or service

The client asks the proxy to open a tunnel. The proxy authenticates and authorizes that request, then forwards the permitted traffic. The tunnel is carried over an encrypted HTTP connection; the application traffic inside can have its own end-to-end encryption too.

Quick start

Run a CONNECT-UDP proxy on loopback and send an HTTP/3 request through it:

rama serve proxy --bind 127.0.0.1:8443 --protocol masque
rama send -v --http3 -x masque://127.0.0.1:8443 --proxy-insecure https://cloudflare-quic.com/

The proxy generates a certificate for this local example, hence --proxy-insecure. For a deployed proxy, use a trusted certificate or configure its CA with --proxy-cacert FILE.

A proxy address can include credentials and a custom URI template. See rama send --help and rama serve proxy --help for configuration options. The masque_connect_udp_proxy example shows a client and server in Rust. The CLI currently exposes CONNECT-UDP; CONNECT-IP is available as a library API.

CONNECT-UDP

A CONNECT-UDP tunnel has one destination: a host and UDP port. The proxy resolves that destination and checks its access policy before accepting traffic. Rama’s default destination policy rejects private, loopback and link-local addresses; applications can explicitly allow the networks they intend to expose.

For an HTTP client, a masque:// proxy lets HTTP/3 use CONNECT-UDP while HTTP/1.1 and HTTP/2 use ordinary TCP CONNECT. A proxy serving both can therefore carry all three HTTP versions. Proxies can also be chained through a MASQUE upstream.

Start with rama::proxy::masque::connect_udp: ConnectUdpConnector opens a tunnel as a UDP socket, and ConnectUdpService serves tunnels with configurable destination policy and forwarding. For web requests, DefaultHttpWebClient::default_masque_with_scope provides the integrated client.

CONNECT-IP

CONNECT-IP works one level below UDP: each payload is a whole IP packet. That allows a tunnel to carry TCP, UDP, ICMP and other IP protocols. Peers can also exchange address assignments and advertise which destinations they can reach. Those advertisements describe connectivity; local policy still decides what traffic is allowed.

rama::proxy::masque::connect_ip provides ConnectIpRequestBuilder and ConnectIpConnector for clients, and ConnectIpService for servers. Your application supplies admission policy and a handler that sends and receives packets through a ConnectIpSession. Your application owns the packet engine and chooses where packets go.

Connecting ordinary applications to such a tunnel also needs an OS packet interface, such as Linux TUN, plus routing configuration. Rama’s CONNECT-IP module does not create interfaces, change host routes or configure DNS. These platform integrations are separate from the tunnel protocol.

The reusable rama::net::ip module handles IP packet parsing, construction, checksums and ICMP helpers. It can also be used independently of MASQUE.

How traffic travels

Both protocols can use HTTP/1.1, HTTP/2 or HTTP/3. When using Rama as a library, enable masque for the tunnel APIs and http-backend for the HTTP engines; HTTP/3 also requires quic (http-full includes all three). The HTTP layer handles the handshake and chooses the available delivery mechanism:

DeliveryWhat it means
Native HTTP/3 datagramsPackets may be lost or reordered, without waiting for retransmission of earlier packets.
Capsules on the HTTP streamPackets travel as framed messages over a reliable stream. Loss can delay later packets while the stream recovers.

HTTP/1.1 and HTTP/2 use capsules. HTTP/3 can use native datagrams when negotiated, with capsules providing compatibility otherwise. Native datagrams are a natural fit for UDP and for tunnelling QUIC; capsules let a tunnel work through paths that only support reliable HTTP streams.

Packet sizes matter too: encapsulation needs room around the original packet. Rama exposes tunnel limits, and CONNECT-IP requires a verified minimum link MTU before enabling IPv6. A packet that exceeds a native datagram limit is not silently switched to reliable delivery. See the session API docs for MTU, forwarding and timeout configuration.

Composing a proxy

MASQUE uses Rama’s usual services and layers. Authentication identifies the caller; admission and destination policy decide what they may reach. Tunnel and traffic budgets bound resource use. A custom packet handler or relay can inspect or transform permitted traffic.

The main entry points are:

PurposeModule
UDP clients, servers and target policyrama::proxy::masque::connect_udp
IP clients, servers and packet policyrama::proxy::masque::connect_ip
Shared HTTP datagram sessions and capsule framingrama::http::datagram
IP packet primitivesrama::net::ip

For interception of a client’s CONNECT-UDP proxy connection, see the connect_udp::mitm adapters and the MITM chapter. They allow the relay to preserve the client’s tunnel or apply a custom service. Selecting traffic for interception and authorizing that traffic are separate application decisions.

Tunnel statistics and optional OpenTelemetry integration are described in the API docs. For a quick look at CONNECT-UDP activity, enable RUST_LOG=rama_masque=debug. When a proxy refuses a tunnel, its Proxy-Status response header can help explain why.

For protocol details, see CONNECT-UDP (RFC 9298), CONNECT-IP (RFC 9484) and HTTP Datagrams and Capsules (RFC 9297).