Skip to content

MASQUE Server

Since sing-box 1.15.0

masque-server endpoint is an IP proxying over HTTP (RFC 9484, CONNECT-IP) server.

Structure

{
  "type": "masque-server",
  "tag": "masque-server",

  ... // Listen Fields

  "version": [],
  "users": [
    {
      "username": "",
      "password": ""
    }
  ],
  "tls": {},
  "path": "",
  "address": [],
  "advertise_routes": [],
  "system": false,
  "name": "",
  "mtu": 1280,

  ... // HTTP2 Fields / QUIC Fields
  ... // UDP NAT Fields
}

You can ignore the JSON Array [] tag when the content is only one item

Listen Fields

See Listen Fields for details. udp_timeout is part of the UDP NAT Fields below.

Fields

version

List of HTTP versions to serve.

Available values: 1, 2, 3.

All versions are used by default.

TLS is required for 3.

users

HTTP users, verified by the Authorization header.

No authentication required if empty.

tls

TLS configuration, see TLS.

IP proxying must be operated over TLS or QUIC. Leave it disabled only when the server is placed behind an HTTP intermediary that terminates TLS.

path

URI template path of the IP proxying resource, may contain the target and ipproto variables.

/.well-known/masque/ip/{target}/{ipproto}/ is used by default.

address

Required

List of IP prefixes of the tunnel network, at most one for each IP version.

The address of the prefix is used by the server itself, other addresses in the prefix are assigned to clients.

List of IP prefixes to advertise to clients, in addition to the tunnel network.

Traffic from clients to other destinations is rejected.

All addresses are advertised by default.

system

Use system interface.

Requires privilege and cannot conflict with existing system interfaces.

If disabled, sing-box uses the internal network stack.

name

Custom interface name for system interface.

An automatically generated masque interface name is used by default.

mtu

Tunnel MTU.

1280 will be used by default.

HTTP2 Fields

When version contains 2.

See HTTP2 Fields for details.

QUIC Fields

When version contains 3 (default), HTTP2 Fields are replaced by QUIC Fields.

See QUIC Fields for details.

UDP NAT Fields

See UDP NAT Fields for details.