Installation

This page installs a WaterWall server on Ubuntu the way our test server is set up, then installs the app on your phone.

Where this page comes from

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

ItemLocation 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
Servicewaterwall.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
Check It prints 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"
  ]
}
SettingWhat it does
workersThe number of worker threads. Ours is 2, one per CPU.
ram-profileserver lets WaterWall use larger buffers than on a phone.
mtuThe packet size for packet tunnels (raw IP, WireGuard). 1420 leaves room for the tunnel's own headers.
try-enabling-bbrAsks Linux to use the BBR congestion control for faster TCP.
domain-strategyprefer-ipv4: when a site has both addresses, connect over IPv4.
configsThe 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
Not running packet tunnels? If you skipped step 7, delete the 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
Allow SSH before you enable the firewall 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
Check 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:

  1. Download and check the new release as in steps 1 and 2.
  2. Copy the old program and core.json into a backup folder.
  3. Install the new program as in step 3.
  4. 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.3From 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 TcpConnectorRemove 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.

Use build 43 or later Build 43 contains WaterWall 1.5.42, the same as our server, the DNS Resolver option and GeoIP routing as the Configuration Reference describes it. If TestFlight still shows an older build, update the app. On Android, use APK 1.2.0 (10) or later.
  1. On your iPhone or iPad, install TestFlight from the App Store.
  2. Open the public beta link: testflight.apple.com/join/A1tAaYW4.
  3. 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.

  1. 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
  2. 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
Check SRP VPN Connect is in the app list and opens on its home screen. We ran these steps from a fresh clone, and installed on our test phone and the emulator.

Next: connect to your server for the first time.