Installation
This page installs a WaterWall server on Ubuntu the way our test server is set up, then installs the app on your phone.
Every file, path, version and setting below was read from our test server on 9 November 2026, after it moved to WaterWall 1.5.42: the official program and its checksum, the service unit, core.json, the NAT scripts, the firewall rules and the certificate renewal hook.
The shell history of the original installation was not kept. The commands below produce that same recorded result, but they are not a transcript of what was typed back then. We ran the commands of steps 1 to 3 on our test server on 9 November 2026; the other commands were not run again.
What you will end up with
| Item | Location on the server |
|---|---|
| WaterWall program | /opt/waterwall/Waterwall |
| Main settings file | /etc/waterwall/core.json |
| One file per configuration (chain) | /etc/waterwall/configs/*.json |
| TLS certificate copies used by WaterWall | /etc/waterwall/fullchain.pem, /etc/waterwall/privkey.pem |
| Service | waterwall.service (systemd) |
| Logs | /var/log/waterwall/, one file per log type and day, for example core.20261030.log |
Install the server
Run every command in this section on the server, as root, over SSH.
1. Download the official WaterWall program
Our server runs the official WaterWall 1.5.42 release for 64-bit Linux, unchanged. Every test result on this site was measured against this exact program. The checksum below is the one GitHub publishes for this file.
mkdir -p /opt/waterwall/staging-1.5.42
cd /opt/waterwall/staging-1.5.42
curl -fLO https://github.com/radkesvat/WaterWall/releases/download/v1.5.42/Waterwall-linux-gcc-x64.zip
echo "66248cb9f285880ddc7ff0f376516d0b5456d6586bffe91503e62469e71f1e8c Waterwall-linux-gcc-x64.zip" | sha256sum -c -
apt-get install -y unzip
unzip -o Waterwall-linux-gcc-x64.zip -d unpacked
chmod 755 unpacked/Waterwall
2. Check the program
unpacked/Waterwall --version
sha256sum unpacked/Waterwall
Waterwall version 1.5.42, and the SHA-256 is 38631081bd10347d840a9f068a349fd028aede57889f0ac77df441f9fe88bbaf, the same as on our server.
3. Install the program
install -m 0755 unpacked/Waterwall /opt/waterwall/Waterwall
/opt/waterwall/Waterwall --version
4. Get a TLS certificate
Skip this step if you will only use chains without TLS (for example Reality or the AEAD-only chains). Our server uses Let's Encrypt with certbot in standalone mode and an ECDSA key. Standalone mode briefly runs its own web server on port 80, so port 80 must be free and open.
apt-get install -y certbot
certbot certonly --standalone --key-type ecdsa -d <SERVER_HOST>
mkdir -p /etc/waterwall
install -m 0644 /etc/letsencrypt/live/<SERVER_HOST>/fullchain.pem /etc/waterwall/fullchain.pem
install -m 0600 /etc/letsencrypt/live/<SERVER_HOST>/privkey.pem /etc/waterwall/privkey.pem
Let's Encrypt certificates expire after 90 days and certbot renews them by itself. This hook copies each renewed certificate to WaterWall and restarts it. It is the exact file from our server; save it as /etc/letsencrypt/renewal-hooks/deploy/waterwall and make it executable with chmod +x.
#!/bin/sh
set -eu
install -m 0644 /etc/letsencrypt/live/<SERVER_HOST>/fullchain.pem /etc/waterwall/fullchain.pem
install -m 0600 /etc/letsencrypt/live/<SERVER_HOST>/privkey.pem /etc/waterwall/privkey.pem
systemctl reload-or-restart waterwall.service
5. Write the main settings file
core.json holds the settings for the whole server and lists the configuration files to load. This is the content of our file. The configs list is shortened: our server loads 44 files, and you list only the ones you use.
{
"log": {
"path": "/var/log/waterwall/",
"core": { "loglevel": "INFO", "file": "core.log", "console": true },
"network": { "loglevel": "INFO", "file": "network.log", "console": false },
"dns": { "loglevel": "INFO", "file": "dns.log", "console": false },
"internal": { "loglevel": "INFO", "file": "internal.log", "console": false }
},
"misc": {
"workers": 2,
"ram-profile": "server",
"mtu": 1420,
"try-enabling-bbr": true
},
"dns": {
"domain-strategy": "prefer-ipv4"
},
"configs": [
"/etc/waterwall/configs/vless-tls.json",
"/etc/waterwall/configs/vless-reality.json"
]
}
| Setting | What it does |
|---|---|
workers | The number of worker threads. Ours is 2, one per CPU. |
ram-profile | server lets WaterWall use larger buffers than on a phone. |
mtu | The packet size for packet tunnels (raw IP, WireGuard). 1420 leaves room for the tunnel's own headers. |
try-enabling-bbr | Asks Linux to use the BBR congestion control for faster TCP. |
domain-strategy | prefer-ipv4: when a site has both addresses, connect over IPv4. |
configs | The configuration files to load; each one is a complete chain on its own port. |
6. Add the configuration files
Each file in /etc/waterwall/configs/ describes one chain. Getting Started writes the first one, VLESS + TLS. Each page under Verified Test Scenarios shows the server file for its chain, and the Configuration Reference explains what goes in a file.
7. Packet tunnels only: the NAT scripts
Skip this step unless you run the raw IP or WireGuard configurations. Those give the phone an address in a private subnet on the server. These two scripts let traffic from that subnet reach the internet through the server's own address (NAT), and remove the rule again when WaterWall stops. They are our files, with our subnet replaced by <TUNNEL_SUBNET> (for example 10.66.0.0):
#!/bin/sh
set -eu
iptables -t nat -C POSTROUTING -s <TUNNEL_SUBNET>/24 ! -o ww-wg0 -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -s <TUNNEL_SUBNET>/24 ! -o ww-wg0 -j MASQUERADE
#!/bin/sh
iptables -t nat -D POSTROUTING -s <TUNNEL_SUBNET>/24 ! -o ww-wg0 -j MASQUERADE 2>/dev/null || true
chmod 0700 /opt/waterwall/nat-up /opt/waterwall/nat-down
8. Create the service
systemd starts WaterWall at boot and restarts it if it stops. This is our unit file, unchanged:
[Unit]
Description=WaterWall
After=network-online.target ufw.service
Wants=network-online.target
[Service]
Type=simple
WorkingDirectory=/etc/waterwall
ExecStartPre=/opt/waterwall/nat-up
ExecStart=/opt/waterwall/Waterwall --config:/etc/waterwall/core.json
ExecStopPost=/opt/waterwall/nat-down
Restart=on-failure
RestartSec=3s
LimitNOFILE=1048576
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
ExecStartPre and ExecStopPost lines. The service will not start when the scripts they name are missing.
9. Open the ports
Our server uses UFW, Ubuntu's firewall. Open SSH first so you do not lock yourself out, then port 80 for certificate renewals, then one rule per configuration port. These are three of our rules, with the comments we use:
ufw allow 22/tcp comment 'SSH management'
ufw allow 80/tcp comment 'ACME HTTP-01 renewal'
ufw allow 18443/tcp comment 'WaterWall VLESS TLS'
ufw enable
ufw status
ufw enable blocks every port without a rule, including SSH if it has none.
10. Start WaterWall
systemctl daemon-reload
systemctl enable --now waterwall.service
systemctl status waterwall.service
systemctl status shows active (running), and each listening port appears in ss -tulpn | grep -i waterwall, where the program shows as memfd:waterwall. If the service fails, read the newest file in /var/log/waterwall/ and see Troubleshooting.
Upgrading WaterWall
Each time our server changes its program, the previous program, core.json and the firewall rules are first copied to a backup folder such as /opt/waterwall/backup-before-1.5.42-20261110/. To upgrade:
- Download and check the new release as in steps 1 and 2.
- Copy the old program and
core.jsoninto a backup folder. - Install the new program as in step 3.
- Run
systemctl restart waterwall.service.
To go back, copy the backup program over /opt/waterwall/Waterwall and restart.
Keep the server and the app on the same WaterWall version. Every test result on this site was measured with WaterWall 1.5.42 on both.
Upgrading from 1.5.3
WaterWall 1.5.4 and later refuse names that 1.5.3 configuration files could use. One such name in any configuration file stops the whole program at start, with a FATAL line that names it (see Troubleshooting), so change every configuration file before you install the new program. Our server's files needed the first two changes:
| In 1.5.3 | From 1.5.4 |
|---|---|
"type": "TcpOverUdpServer" | "type": "KcpServer"; its settings, such as fec, stay as they are. The client node is now KcpClient. |
"domain-strategy" in a node's settings, for example "domain-strategy": "prefer-ipv4" on TcpUdpConnector or TcpConnector | Remove it. Without it a connector still looks names up, with dns.domain-strategy from core.json; to set it on the node, use "dns-behaviour": {"resolve": true, "strategy": "prefer-ipv4"}. |
"resolve-domains" | Use dns-behaviour as above; {"resolve": false} turns lookups off. |
dns.domain-strategy in core.json stays valid. With these changes all 45 configuration files of our server loaded, each on the port it had before.
1.5.3 raised the kernel's socket buffer limits to 128 MiB each time it started, and its TCP memory limits to 37.5% of the RAM. 1.5.42 no longer touches the socket buffers, and raises the TCP memory limits to 15% of the RAM (on Linux, while splice and tcp-tune are on, as they are by default); it never lowers a limit. What 1.5.3 raised stays until the next reboot. To put the kernel's defaults back without one, as we did on our server, run this before you start 1.5.42:
sysctl -w net.core.rmem_max=212992 net.core.wmem_max=212992
sysctl -w "net.ipv4.tcp_rmem=4096 131072 6291456" "net.ipv4.tcp_wmem=4096 16384 4194304"
Install the app
iPhone or iPad
SRP VPN Connect is distributed as a public TestFlight beta. You do not need a developer account.
- On your iPhone or iPad, install TestFlight from the App Store.
- Open the public beta link: testflight.apple.com/join/A1tAaYW4.
- Tap Accept, then Install.
Android
The Android app is not in a store yet. You build a test APK from the source on a computer with Android Studio, which brings Java and the Android SDK. Gradle downloads the NDK and CMake versions it needs. The APK is signed with your computer's debug key and is meant for testing.
- Build it. On macOS, Android Studio's Java and its SDK are at the paths below; on another system, use the ones on your computer.
git clone https://github.com/bigmoveus/SRP-VPN-Connect cd SRP-VPN-Connect/Android export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" export ANDROID_HOME="$HOME/Library/Android/sdk" ./gradlew :app:assembleDebug - Connect the phone with USB debugging on (in Developer options), or start an arm64 emulator in Android Studio, and install the APK:
"$ANDROID_HOME/platform-tools/adb" install -r app/build/outputs/apk/debug/app-debug.apk