How to set up a reverse proxy

A reverse proxy accepts inbound ADNL connections and forwards HTTP requests to a local web server, enabling hosting for a TON Site. The TON Proxy overview covers the underlying bridge architecture.

Prerequisites

rldp-http-proxy binary from a TON monorepo release (v2024.01 or newer), or tonutils-reverse-proxy binary from the tonutils/reverse-proxy releases (v0.4.0 or newer)
generate-random-id binary (included in the TON monorepo release archive): required for the rldp-http-proxy key generation step
global.config.json: available from the TON monorepo
A public IPv4 address with an open UDP port (default: 3333) reachable from the internet

Use rldp-http-proxy

Step 1: generate an ADNL address

Create a keyring directory and generate a key pair:

mkdir keyring

generate-random-id -m keys -n liteserver

This produces liteserver (private key) and liteserver.pub (public key) in the current directory.

Move the private key into the keyring:

mv liteserver keyring/

The hex-encoded key ID printed by generate-random-id is the ADNL address (<ADNL_ADDRESS>).

Step 2: start the reverse proxy

rldp-http-proxy -a <PUBLIC_IP>:3333 -L '*' -C global.config.json -A <ADNL_ADDRESS> -d -l <LOG_FILE>

Flag	Description
`-a <PUBLIC_IP>:3333`	Public IP and UDP port for ADNL connections
`-L '*'`	Accept requests for any hostname
`-C global.config.json`	Path to TON global network configuration
`-A <ADNL_ADDRESS>`	ADNL address generated in step 1
`-d`	Run as daemon
`-l <LOG_FILE>`	Path to the log file

The reverse proxy forwards incoming HTTP requests to 127.0.0.1:80 by default. Point a local web server at that address.

Use tonutils-reverse-proxy

Install

Pick a current release tag from the releases page, then download and mark it executable:

TAG=v0.4.6
wget https://github.com/tonutils/reverse-proxy/releases/download/${TAG}/tonutils-reverse-proxy-linux-amd64
chmod +x tonutils-reverse-proxy-linux-amd64

Alternatively, build from source:

git clone https://github.com/tonutils/reverse-proxy.git
cd reverse-proxy
make build

Run the reverse proxy

Start with domain assignment:

./tonutils-reverse-proxy-linux-amd64 --domain <DOMAIN>

On first launch the binary generates an ADNL key pair automatically and prints a QR code linking to a TON DNS configuration transaction. Scan the QR code with a TON wallet to register the ADNL address in the domain record.

Response headers

The reverse proxy injects two headers into forwarded requests:

Header	Description
`X-Adnl-Ip`	Client ADNL IP (not the real client IP)
`X-Adnl-Id`	Client ADNL identity

Assign a domain

After the reverse proxy is running, register the ADNL address in a .ton domain via TON DNS. Set the site record of the domain to the ADNL address of the reverse proxy.

Verify

Confirm the ADNL address is reachable and DNS is active:

Use a forward proxy and request the .ton domain in a browser to confirm end-to-end routing.
Check that the ADNL address is registered in the domain’s site record via a TON DNS lookup tool such as dns.ton.org.
Inspect the reverse proxy log (-l <LOG_FILE>) for incoming connection entries to confirm traffic is arriving.

Troubleshoot

Firewall blocking UDP: the public UDP port (default 3333) must be open inbound. Verify with nc -u -zv <PUBLIC_IP> 3333 from an external host. Update firewall rules if the port is filtered.
Private key not loaded: the private key file must reside inside the keyring/ directory and the directory must be in the working directory where rldp-http-proxy is launched. Check that keyring/<KEY_FILE> exists.
DNS propagation delay: after the on-chain DNS transaction is confirmed, allow up to 60 seconds for the record to propagate across DHT nodes before testing.
tonutils-reverse-proxy QR code does not appear: ensure the terminal supports block characters. Run with a UTF-8 locale or redirect the output and scan the raw URL printed alongside the QR code.

TON Proxy: how the proxy bridge works
TON Sites: web services hosted over ADNL
TON Proxy reference: all CLI flags
TON DNS: domain registration and record types