Configuration Reference

A WaterWall connection has two halves: the configuration file you write on the server, and the client chain the app builds from your choices. This page describes both, and what must match between them.

Where this page comes from

The server file below was read from our test server on 10 November 2026, after its move to WaterWall 1.5.42. The app side was read from the app's source code at commit e44cf11d, TestFlight build 41. The Android app builds the same chains; a test compares the two builders on the same configurations, see Android. Which combinations actually worked in our tests is on the Verified Test Scenarios pages; this page describes settings, not results.

Server configuration files

Each configuration is one JSON file in /etc/waterwall/configs/, listed in the configs array of /etc/waterwall/core.json (see Installation). WaterWall loads every listed file when it starts, so after adding or changing a file, restart the service:

systemctl restart waterwall.service
systemctl status waterwall.service --no-pager

What a file contains

A file has a name and a list of nodes. Each node has:

FieldMeaning
nameYour own name for the node, used by next.
typeThe kind of node, for example TcpListener or VlessServer.
settingsThe node's options.
nextThe name of the node that receives the traffic after this one. The last node has no next.

Our files also carry author, config-version and core-minimum-version.

Example: VLESS + TLS from our server

This is /etc/waterwall/configs/vless-tls.json from our server. Only the server name and the UUID are replaced with placeholders.

{
  "name": "vless-tls",
  "author": "SRP",
  "config-version": 1,
  "core-minimum-version": 0,
  "nodes": [
    {
      "name": "public-in",
      "type": "TcpListener",
      "settings": {
        "address": "0.0.0.0",
        "port": 18443,
        "nodelay": true,
        "initial-idle-timeout-ms": 15000,
        "active-idle-timeout-ms": 300000
      },
      "next": "tls"
    },
    {
      "name": "tls",
      "type": "TlsServer",
      "settings": {
        "cert-file": "/etc/waterwall/fullchain.pem",
        "key-file": "/etc/waterwall/privkey.pem",
        "sni": "<SERVER_HOST>",
        "min-version": "TLSv1.2",
        "max-version": "TLSv1.3",
        "select-alpns": ["http/1.1"],
        "handshake-timeout-ms": 15000
      },
      "next": "vless"
    },
    {
      "name": "vless",
      "type": "VlessServer",
      "settings": {
        "uuid": "<UUID>",
        "connect": true,
        "udp": true,
        "verbose": true
      },
      "next": "outbound"
    },
    {
      "name": "outbound",
      "type": "TcpUdpConnector",
      "settings": {
        "address": "dest_context->address",
        "port": "dest_context->port",
        "nodelay": true
      }
    }
  ]
}
NodeWhat it does here
TcpListenerAccepts TCP connections on port 18443 from any address. Idle connections close after 15 seconds before any data, or 5 minutes after.
TlsServerEnds the TLS layer with the Let's Encrypt certificate. It accepts TLS 1.2 and 1.3 and offers the ALPN http/1.1, which is what the app sends for TLS.
VlessServerChecks the client's UUID and reads where each connection should go. connect and udp allow TCP and UDP destinations.
TcpUdpConnectorConnects to the real destination. dest_context->address and dest_context->port mean "the destination the client asked for".

The full list of options for every node is in the official WaterWall documentation.

The server node for each app choice

For each layer you choose in the app, the server needs the matching node, in reverse order. Values in the last column must be the same on both sides; the app's own values are shown.

App choiceClient node the app buildsServer nodeMust match
Application VLESSVlessClientVlessServeruuid
Application VMessVmessClientVmessServeruuid; the app's security is aes-128-gcm unless you change it
Application TrojanTrojanClientTrojanServerpassword
Application SOCKS5Socks5ClientSocks5Serverusername and password, if used
Application HTTP CONNECTHttpProxyClientHttpProxyServerusername and password, if used
MUXMuxClientMuxServer—
ObfuscatorObfuscatorClientObfuscatorServermethod xor, xor_key 90
HTTP or WebSocketHttpClientHttpServerpath (the app sends /), http-version, websocket, and host if the server sets one: the app sends the SNI, or the Server field when SNI is empty or not shown (www.cloudflare.com for Reality with SNI empty)
BGP4 (framing or outer)Bgp4ClientBgp4Server—
Outer TLSTlsClientTlsServera certificate valid for the SNI (when verification is on); select-alpns must include the app's ALPN: http/1.1, or h2 with HTTP version 2
Outer RealityRealityClientRealityServerpassword, algorithm chacha20-poly1305, salt waterwall-reality, kdf-iterations 12000
Outer AEADEncryptionClientEncryptionServerpassword, algorithm chacha20-poly1305, salt waterwall-aead, kdf-iterations 12000, max-frame-size 16356
Outer QUICQuicClientQuicServerprotocol h3, carrier-mode (datagram or stream)
Carrier KCPKcpClientKcpServer—
Input Raw IPv4PacketsToStreamStreamToPackets, then PacketsToConnection—
Packet EncryptionEncryptionClient in packet modeEncryptionServer in packet mode, between StreamToPackets and PacketsToConnectionpassword, packet-mode true, algorithm xchacha20-poly1305, salt waterwall-packet, kdf-iterations 12000
Two values that are easy to miss

The first node depends on how the chain reaches the server:

The server chain ends with a connector to the internet, normally TcpUdpConnector as above. For Raw IPv4, the server turns the stream back into packets with StreamToPackets and PacketsToConnection before the connector.

Packet Encryption on a Raw IPv4 chain

With Input Raw IPv4, the app's Packet Encryption switch encrypts the TCP or UDP payload of each packet. This is the server side of our test chain, with no other layer; the address, certificate and password are examples. It needs the same password in the app's Packet Password field.

{
  "name": "rawip-packet",
  "nodes": [
    { "name": "public-in", "type": "TcpListener", "settings": { "address": "0.0.0.0", "port": 18480, "nodelay": true }, "next": "stream-in" },
    { "name": "stream-in", "type": "StreamToPackets", "settings": { "packet-validation-level": "hard" }, "next": "packet-crypto" },
    { "name": "packet-crypto", "type": "EncryptionServer", "settings": { "packet-mode": true, "algorithm": "xchacha20-poly1305", "password": "a-long-random-password", "salt": "waterwall-packet", "kdf-iterations": 12000 }, "next": "packet-out" },
    { "name": "packet-out", "type": "PacketsToConnection", "settings": { "mtu": 1420, "max-pending-bytes": 1048576 }, "next": "outbound" },
    { "name": "outbound", "type": "TcpUdpConnector", "settings": { "address": "dest_context->address", "port": "dest_context->port", "nodelay": true } }
  ]
}

The IP and TCP or UDP headers stay visible inside the chain and only TCP and UDP pass, so ping does not work through it. The app does not offer it together with Reality or AEAD, which encrypt the whole stream and use the same password field in the app.

The client chain the app builds

You never write the client file; the app builds it each time you connect. Knowing its shape helps when you write the server side.

Mode and inputClient chain, in order
Chain, Connectionspacket device → PacketsToConnection → DomainResolver (only with the DNS resolver on) → Router → application → MUX → Obfuscator → HTTP → BGP4 framing → outer → KCP → connector
Chain, Raw IPv4packet device → Packet Encryption → PacketsToStream → Obfuscator → HTTP → BGP4 framing → outer → KCP → connector
Directpacket device → PacketsToConnection → TcpUdpConnector to each destination
WireGuardpacket device → WireGuardDevice → UdpStatelessSocket: WaterWall's own WireGuard, not the app's WireGuard protocol; see WireGuard mode.

Layers you did not choose are left out. The last node, the connector, is UdpConnector for KCP and QUIC Datagram, TcpUdpConnector for SOCKS5 and for VLESS, VMess or Trojan over TLS without MUX, an HTTP layer or a fixed protocol in the application's settings, and TcpConnector otherwise.

Settings the app always uses

ItemValue
WaterWall workers1
MTU1420
Log levelWARN, INFO or DEBUG for the Normal, Expert and Debug log levels
Remote DNS (Fake IP) when onDNS answers from 198.18.0.2 port 53, placeholder addresses from 100.64.0.0/10, a cache of 10000 names, TTL 60 seconds
Direct LAN Routing when on10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 go to a direct connector
GeoIP routingSelected countries go to a direct connector. With the DNS resolver off, the router looks names up itself to match them, with the phone's network DNS, and uses the answer only for that choice: a connection that goes through the VPN still carries the site's name, which the server looks up
DNS resolverOff; see the DNS resolver
splice, tcp-tune, try-enabling-bbrOff: a phone's kernel settings are not WaterWall's to change

The DNS resolver

The DNS RESOLVER section of a Chain profile with Connections input puts WaterWall's DomainResolver node between PacketsToConnection and the router. It looks up the name of each connection on the phone before routing, so the router and GeoIP see real addresses and the server gets an address instead of a name. The names come from Remote DNS (Fake IP): with it off, the phone looks names up itself, connections arrive with addresses, and the node passes them on unchanged. The profile keeps it as domain-resolver, which becomes the node's settings unchanged.

ResolverNode settingsWhere the questions go
Off (default)no nodeThe server looks up the names the phone asks for. GeoIP still looks them up on the phone to choose the way, as above.
Native{"mode": "native"}The DNS of the network the phone is on, outside the VPN.
Direct{"mode": "direct", "servers": [...]}The DNS servers you list, straight from the phone, outside the VPN.
Through the VPN{"mode": "chain", "servers": [...]}The DNS servers you list, through the VPN: the router's first rule, {"resolver-dns": true, "target": <application>}, sends the resolver's own questions to the application, even to a server in a GeoIP country or the local network. The server must allow UDP and reach those DNS servers.

Addresses sets strategy: prefer-ipv4, prefer-ipv6, only-ipv4, only-ipv6 or accept-dns-returned-order; the default, Default (IPv4 First), leaves it out, so WaterWall's own default applies. DNS Servers takes 1 to 32 addresses, separated by commas, spaces or new lines: an IPv4 or IPv6 address, or IPv4:port or [IPv6]:port; without a port, 53. A name, an IPv6 scope such as %en0, a leading zero or port 0 is refused. Through the VPN needs an application that carries UDP: not HTTP CONNECT, and not a fixed TCP protocol in the application's settings. Raw IPv4 input, Direct and WireGuard have no DNS resolver.

Advanced node settings

These are the keys each ADVANCED NODE SETTINGS editor accepts. Any other key is refused with Unsupported <layer> setting: <key>. A setting you enter replaces the app's default for that key, except the values in the next box.

Values the app always sets itself Whatever you enter, the app sets the outer layer's sni, verify and password, the QUIC carrier-mode, the application's destination, UUID or password, and the HTTP host, port, http-version and websocket from the profile.

Each layer below lists its keys, the app's defaults, and the limits the app enforces. Times are in milliseconds and sizes in bytes.

Packet

KeyApp defaultAllowed
mtu142068 to 65535
max-pending-bytes655361024 to 67108864; see the note below
max-total-pending-bytes1677721665536 to 67108864; see the note below
udp-idle-timeout-msWaterWall's default1 or more
fake-dns (or mapdns, fake_dns)set by Remote DNStrue, false or an object with enabled, address, network, netmask, port, cache-size (1 to 262144) and ttl. Only one of the three names.
The two pending-bytes keys also limit TCP connections

Each TCP connection reserves max-pending-bytes of max-total-pending-bytes for as long as it lives, so the total divided by the per-connection value is how many can be open at once: 256 with the app's defaults. A new connection over that is refused, and iOS reports A TLS error caused the secure connection to fail. From the code only, not run: a max-pending-bytes above the total refuses every TCP connection, and the app's editor does not stop that. See Troubleshooting.

This limit is in the app only. The official server program has no such total: on a Raw IPv4 chain max-pending-bytes limits each TCP connection separately.

With Raw IPv4 input the Packet keys are instead packet-validation-level (none, loose or hard; the app uses hard), sensitive-mode, interval-ms and tolerance-ms. In Direct mode, Packet is the only layer.

Application

KeyApp defaultAllowed
protocol (or proto)dest_context->protocol (follow each connection)tcp, connect, udp, udp-associate, dest_context->protocol, line->dest_ctx->protocol
dns-behaviournot set: the application sends names to the server{"resolve": false}, or {"resolve": true} with an optional strategy: core-settings, prefer-ipv4, prefer-ipv6, only-ipv4, only-ipv6, accept-dns-returned-order. No other key. A profile saved with the older domain-strategy moves to it by itself: do-not-resolve-domains is dropped, and each resolve-domains-… value becomes {"resolve": true, "strategy": …}.
first-payload-timeout-msWaterWall's default0 or more
verboseWaterWall's defaulttrue or false

VMess also accepts:

KeyAllowed
securityaes-128-gcm (app default), chacha20-poly1305, auto, none, zero. zero works with a fixed TCP protocol only.
chunk-masking, global-padding, authenticated-length, send-terminationtrue or false. Padding needs masking; authenticated length needs encryption (not none or zero).
encrypted-counter-policywrap or strict
packet-encodingnone or packetaddr. packetaddr needs names looked up on the phone: dns-behaviour with resolve true, or the DNS resolver.

SOCKS5 accepts only protocol, proto, verbose and dns-behaviour. HTTP CONNECT accepts verbose, dns-behaviour, headers (extra request headers; Host, Proxy-Authorization, Content-Length, Transfer-Encoding, Connection, Proxy-Connection, Keep-Alive, TE, Trailer, Upgrade and Expect are reserved), max-header-bytes (1024 to 65536), header-timeout-ms, connect-response-timeout-ms and idle-timeout-ms.

MUX

KeyApp defaultAllowed
modecountercounter (takes connection-capacity), timer (needs connection-duration-ms, 61 or more), fixed-connections-count (needs per-worker-connections-count)
connection-capacity1281 or more; counter mode only
max-children2561 or more
parent-write-buffer-pause-threshold8388608Must keep resume < pause < limit
parent-write-buffer-resume-threshold1048576
parent-write-buffer-limit16777216
child-buffer-limit41943041 or more
parent-buffer-limit167772160 or more
detached-buffer-limit41943040 or more
detached-child-limit1280 or more
keepalive, ping-interval, tolerance-ms, child-buffer-resume-threshold, log-main-line-statsWaterWall's defaultsbooleans or 1 or more

Obfuscator

KeyApp defaultAllowed
methodxorxor only
xor_key900 to 255. Change the server's key too.
skipnoneMust stay none with Connections input.
tls_record_header (or tls_header)offtrue or false

HTTP

KeyApp defaultAllowed
path/text; must match the server's HttpServer path
schemehttps with TLS or Reality, otherwise httphttp or https
headers, upgrade-request-headers, upgrade-response-headersnoneobjects with text values
http1-modeWaterWall's defaultsingle or split; split needs HTTP version 1 without WebSocket
method, user-agent, content-type, upgrade, upgrade-protocol, websocket-origin, websocket-subprotocol, split, verboseWaterWall's defaultssee the WaterWall documentation for HttpClient

With HTTP on and Outer TLS or Reality, the app sets the TLS ALPN itself (http/1.1 or h2), so the Outer settings may not contain alpns. websocket-extensions is refused.

Outer

OuterKeysApp defaults and limits
TLSalpns, x25519mlkem768, fragment, tls13-record-shaping, ech-config-list, ech-sni-trick, verbosealpns ["http/1.1"]. ech-config-list and ech-sni-trick cannot be used together.
Realitythe TLS keys, plus algorithm (or method), salt, kdf-iterationschacha20-poly1305 (or aes-gcm), salt waterwall-reality (1 to 32 bytes), 12000 iterations (1 to 1000000). verbose is on only at the Debug log level.
AEADalgorithm (or method), salt, kdf-iterations, max-frame-sizechacha20-poly1305 (or aes-gcm), salt waterwall-aead, 12000 iterations, frame size 16356 (1 to 16356)
QUICca-file, protocol, handshake-timeout-ms, idle-timeout-ms, max-packet-size, max-buffered-bytes, max-buffered-buffers, receive-window-bytes, verboseprotocol h3; timeouts 1 to 86400000; packet size 1200 to 1452; buffered bytes 65536 to 67108864 (WaterWall default 2097152); receive window 16384 to 16777216 and no more than the buffered bytes
BGP4none—

The fragment object replaces the app's TLS Fragmentation option. It takes mode (counter with count, or timed with duration-ms), cuts (at most 64 entries of [offset, delay_ms, chance_percent] with increasing offsets), and optionally bypass_chance, wait-for-est, tls-hello-fragment and tls-hello-timeout-ms. When the app builds it from the TLS Fragmentation option, it uses counter mode, count 1, tls-hello-fragment on, a 1000 ms hello timeout, and a cut at the first-chunk size and then every following-chunk size, below 16384 bytes: 32 and 256 bytes for Auto, your First Chunk and Following Chunks for Manual.

KCP

KeyApp defaultAllowed
kcp-send-window, kcp-recv-window128, 1281 or more
kcp-initial-cwnd161 or more, and no more than the send window (128 unless you set kcp-send-window)
kcp-send-buffer-limit5120 or more
fec, fec-data-shards, fec-parity-shardsoffshards 1 to 255 each, 255 at most together
send-mtu1420, the app's misc.mtu118 to 65535 (126 with FEC)
ping-interval-ms, no-recv-timeout-msWaterWall's defaults (10000 and 30000)the timeout must be longer than the ping interval
kcp-nodelay, kcp-interval-ms (10 to 5000), kcp-resend, kcp-no-congestion-control, kcp-rx-minrto-msWaterWall's defaults—