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.
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:
| Field | Meaning |
|---|---|
name | Your own name for the node, used by next. |
type | The kind of node, for example TcpListener or VlessServer. |
settings | The node's options. |
next | The 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
}
}
]
}
| Node | What it does here |
|---|---|
TcpListener | Accepts TCP connections on port 18443 from any address. Idle connections close after 15 seconds before any data, or 5 minutes after. |
TlsServer | Ends 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. |
VlessServer | Checks the client's UUID and reads where each connection should go. connect and udp allow TCP and UDP destinations. |
TcpUdpConnector | Connects 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 choice | Client node the app builds | Server node | Must match |
|---|---|---|---|
| Application VLESS | VlessClient | VlessServer | uuid |
| Application VMess | VmessClient | VmessServer | uuid; the app's security is aes-128-gcm unless you change it |
| Application Trojan | TrojanClient | TrojanServer | password |
| Application SOCKS5 | Socks5Client | Socks5Server | username and password, if used |
| Application HTTP CONNECT | HttpProxyClient | HttpProxyServer | username and password, if used |
| MUX | MuxClient | MuxServer | — |
| Obfuscator | ObfuscatorClient | ObfuscatorServer | method xor, xor_key 90 |
| HTTP or WebSocket | HttpClient | HttpServer | path (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) | Bgp4Client | Bgp4Server | — |
| Outer TLS | TlsClient | TlsServer | a 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 Reality | RealityClient | RealityServer | password, algorithm chacha20-poly1305, salt waterwall-reality, kdf-iterations 12000 |
| Outer AEAD | EncryptionClient | EncryptionServer | password, algorithm chacha20-poly1305, salt waterwall-aead, kdf-iterations 12000, max-frame-size 16356 |
| Outer QUIC | QuicClient | QuicServer | protocol h3, carrier-mode (datagram or stream) |
| Carrier KCP | KcpClient | KcpServer | — |
| Input Raw IPv4 | PacketsToStream | StreamToPackets, then PacketsToConnection | — |
| Packet Encryption | EncryptionClient in packet mode | EncryptionServer in packet mode, between StreamToPackets and PacketsToConnection | password, packet-mode true, algorithm xchacha20-poly1305, salt waterwall-packet, kdf-iterations 12000 |
- AEAD salt. WaterWall's own default salt for
EncryptionServeriswaterwall-encryption, but the app useswaterwall-aead. Write"salt": "waterwall-aead"in the server file, as our server does. - HTTP path. The app sends the path
/. If yourHttpServeruses another path (one of our server files uses/tunnel), set the same path in the app's HTTP advanced settings.
The first node depends on how the chain reaches the server:
TcpListenerfor the TCP carrier, including QUIC with the Stream carrier.UdpListenerfor the KCP carrier and for QUIC with the Datagram carrier.
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 input | Client chain, in order |
|---|---|
| Chain, Connections | packet device → PacketsToConnection → DomainResolver (only with the DNS resolver on) → Router → application → MUX → Obfuscator → HTTP → BGP4 framing → outer → KCP → connector |
| Chain, Raw IPv4 | packet device → Packet Encryption → PacketsToStream → Obfuscator → HTTP → BGP4 framing → outer → KCP → connector |
| Direct | packet device → PacketsToConnection → TcpUdpConnector to each destination |
| WireGuard | packet 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
| Item | Value |
|---|---|
| WaterWall workers | 1 |
| MTU | 1420 |
| Log level | WARN, INFO or DEBUG for the Normal, Expert and Debug log levels |
| Remote DNS (Fake IP) when on | DNS 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 on | 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 go to a direct connector |
| GeoIP routing | Selected 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 resolver | Off; see the DNS resolver |
splice, tcp-tune, try-enabling-bbr | Off: 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.
| Resolver | Node settings | Where the questions go |
|---|---|---|
| Off (default) | no node | The 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.
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
| Key | App default | Allowed |
|---|---|---|
mtu | 1420 | 68 to 65535 |
max-pending-bytes | 65536 | 1024 to 67108864; see the note below |
max-total-pending-bytes | 16777216 | 65536 to 67108864; see the note below |
udp-idle-timeout-ms | WaterWall's default | 1 or more |
fake-dns (or mapdns, fake_dns) | set by Remote DNS | true, false or an object with enabled, address, network, netmask, port, cache-size (1 to 262144) and ttl. Only one of the three names. |
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
| Key | App default | Allowed |
|---|---|---|
protocol (or proto) | dest_context->protocol (follow each connection) | tcp, connect, udp, udp-associate, dest_context->protocol, line->dest_ctx->protocol |
dns-behaviour | not 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-ms | WaterWall's default | 0 or more |
verbose | WaterWall's default | true or false |
VMess also accepts:
| Key | Allowed |
|---|---|
security | aes-128-gcm (app default), chacha20-poly1305, auto, none, zero. zero works with a fixed TCP protocol only. |
chunk-masking, global-padding, authenticated-length, send-termination | true or false. Padding needs masking; authenticated length needs encryption (not none or zero). |
encrypted-counter-policy | wrap or strict |
packet-encoding | none 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
| Key | App default | Allowed |
|---|---|---|
mode | counter | counter (takes connection-capacity), timer (needs connection-duration-ms, 61 or more), fixed-connections-count (needs per-worker-connections-count) |
connection-capacity | 128 | 1 or more; counter mode only |
max-children | 256 | 1 or more |
parent-write-buffer-pause-threshold | 8388608 | Must keep resume < pause < limit |
parent-write-buffer-resume-threshold | 1048576 | |
parent-write-buffer-limit | 16777216 | |
child-buffer-limit | 4194304 | 1 or more |
parent-buffer-limit | 16777216 | 0 or more |
detached-buffer-limit | 4194304 | 0 or more |
detached-child-limit | 128 | 0 or more |
keepalive, ping-interval, tolerance-ms, child-buffer-resume-threshold, log-main-line-stats | WaterWall's defaults | booleans or 1 or more |
Obfuscator
| Key | App default | Allowed |
|---|---|---|
method | xor | xor only |
xor_key | 90 | 0 to 255. Change the server's key too. |
skip | none | Must stay none with Connections input. |
tls_record_header (or tls_header) | off | true or false |
HTTP
| Key | App default | Allowed |
|---|---|---|
path | / | text; must match the server's HttpServer path |
scheme | https with TLS or Reality, otherwise http | http or https |
headers, upgrade-request-headers, upgrade-response-headers | none | objects with text values |
http1-mode | WaterWall's default | single or split; split needs HTTP version 1 without WebSocket |
method, user-agent, content-type, upgrade, upgrade-protocol, websocket-origin, websocket-subprotocol, split, verbose | WaterWall's defaults | see 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
| Outer | Keys | App defaults and limits |
|---|---|---|
| TLS | alpns, x25519mlkem768, fragment, tls13-record-shaping, ech-config-list, ech-sni-trick, verbose | alpns ["http/1.1"]. ech-config-list and ech-sni-trick cannot be used together. |
| Reality | the TLS keys, plus algorithm (or method), salt, kdf-iterations | chacha20-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. |
| AEAD | algorithm (or method), salt, kdf-iterations, max-frame-size | chacha20-poly1305 (or aes-gcm), salt waterwall-aead, 12000 iterations, frame size 16356 (1 to 16356) |
| QUIC | ca-file, protocol, handshake-timeout-ms, idle-timeout-ms, max-packet-size, max-buffered-bytes, max-buffered-buffers, receive-window-bytes, verbose | protocol 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 |
| BGP4 | none | — |
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
| Key | App default | Allowed |
|---|---|---|
kcp-send-window, kcp-recv-window | 128, 128 | 1 or more |
kcp-initial-cwnd | 16 | 1 or more, and no more than the send window (128 unless you set kcp-send-window) |
kcp-send-buffer-limit | 512 | 0 or more |
fec, fec-data-shards, fec-parity-shards | off | shards 1 to 255 each, 255 at most together |
send-mtu | 1420, the app's misc.mtu | 118 to 65535 (126 with FEC) |
ping-interval-ms, no-recv-timeout-ms | WaterWall'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-ms | WaterWall's defaults | — |