DEV Community

Lia
Lia

Posted on

How to Preserve the Real Client IP When Proxy Protocol Is Not Documented

#proxy #clientip #reverseproxy #checklist

If you searched for how to preserve the real client IP with PROXY protocol, you probably want the browser address to survive every hop and show up in both the firewall and the origin logs. The SafeLine materials used here do not give that recipe. The product overview at https://docs.waf.chaitin.com/en/home describes a reverse proxy that filters HTTP and HTTPS traffic. The deploy guide at https://docs.waf.chaitin.com/en/GetStarted/Deploy covers installation. The application guide at https://docs.waf.chaitin.com/en/GetStarted/AddApplication covers domain, port, SSL, and upstream. None of those pages documents PROXY protocol, a trusted-proxy list, or a client-IP header control. The numbered steps below install and place the documented proxy. The checklist tells you what not to assume after that.

A reverse proxy changes which machine the origin accepts a connection from. SafeLine sits in front of the web app, receives traffic for the original site, drops malicious requests, and forwards the remaining traffic to the upstream you configure. The overview also lists IP-based rate limiting and a web access control list among core capabilities. Those controls can only act on the client identity the WAF actually observes. That is a different question from whether the origin application later records the browser address. Keep those two questions separate, or you will fix the wrong hop.

Map the path before you touch protocol settings

Draw the path you will really use: client, any outer load balancer, the SafeLine host, then the origin. PROXY protocol is a TCP preamble that some proxies send so the next hop can learn the original client address and port. Because the cited SafeLine pages never mention that preamble, do not enable it on the device that connects to SafeLine. A sender without a matching listener often fails the connection. It does not quietly fill in a log field.

Write down which system is authoritative for each decision. Rate limits and access-control choices belong to the address SafeLine sees on the connection it accepts. Application audit logs belong to whatever the origin records after the forward. The application guide states that SafeLine forwards safe traffic to the original app. It does not state that the forward includes a PROXY protocol header or any particular client-IP header. Until you have version-specific documentation that says otherwise, treat both as unsupported.

Numbered setup from the official guides

Complete the documented install and site setup first. Test observations only after the WAF is actually on the path. Do not add PROXY protocol keys to .env or to the application dialog.

  1. Match the host to the deploy guide. Use Linux on x86_64 or arm64, Docker 20.10.14 or newer, and Docker Compose 2.0.0 or newer. Plan for at least 1 CPU core, 1 GB of memory, and 5 GB of disk, and confirm that the CPU exposes ssse3. If you choose arm64, the same guide says SafeLine on ARM requires a Pro license and that the Personal Edition is not supported on ARM. Settle that before installation. It is a platform constraint, not a client-IP feature.

  2. Confirm the machine with the commands published in the deploy guide: uname -m, docker version, docker compose version, cat /proc/cpuinfo | grep "processor", free -h, df -h, and lscpu | grep ssse3. If Docker is missing or free disk is below 5 GB, fix that before you continue. A failed install cannot tell you anything about client addresses.

  3. Prefer the documented automatic install when you do not need to inspect each file. With root privileges, run bash -c "$(curl -fsSLk https://waf.chaitin.com/release/latest/manager.sh)" -- --en. The guide says that when the command finishes, installation has succeeded and you should open the web UI. Use the manual sequence only if you want the files on disk yourself. Do not run both and then merge them by hand.

  4. For a manual install, install Docker if the host does not already have it, using curl -sSL "https://get.docker.com/" | bash. Create /data/safeline, change into that directory, and download https://waf.chaitin.com/release/latest/compose.yaml. Create .env with the keys listed in the deploy guide, including SAFELINE_DIR, IMAGE_TAG, MGT_PORT, POSTGRES_PASSWORD, SUBNET_PREFIX, IMAGE_PREFIX, ARCH_SUFFIX, RELEASE, REGION, and MGT_PROXY. MGT_PORT is the web console port. The sample uses 9443. MGT_PROXY is the number of console proxy layers. The guide says to use it only when configuring a proxy for the console, and that the default 0 means no proxy is configured. Read that name carefully: it is not a documented PROXY protocol switch for the sites you protect.

  5. Generate the secrets the deploy guide requires before the first start. It shows how to fill DETECTOR_MGMT_TOKEN and MGT_INTERNAL_TOKEN from 32 random bytes, and DETECTOR_AES_KEY from 16 alphanumeric characters, then restrict .env with chmod 600. Create the resource directories in the guide, apply the listed permissions, and add the safeline.sock link under /var/run. On an ARM server, set ARCH_SUFFIX to -arm and use the ARM Postgres image named in that guide. Stop there. Extra listener variables for PROXY protocol are not part of the published script.

  6. From /data/safeline, run docker compose up -d. Startup can take several minutes. Browse to https://<safeline-ip>:9443/. Initialize the administrator with docker exec safeline-mgt resetadmin. The command prints an initial username of admin and a generated password. Store both outside the host chat log or ticket where other people can read them.

  7. Add the application only after that login works. In the console, open Applications and choose Add Application. Enter the domain, hostname, or IP of the original app, the port SafeLine should listen on, and the upstream address that should receive cleaned traffic. For an HTTPS app, check the SSL option. Then resolve that domain to the IP of the SafeLine server, as the application guide requires. Until DNS points at SafeLine, you are still talking to the old path, so any client-IP comparison is invalid.

  8. Confirm inspection with the published probes, not with a protocol experiment. The application guide lists sample SQL injection, XSS, path traversal, code injection, and XXE URLs. Replace the example host with your domain. A blocking page means SafeLine handled the request. Open the attack list in the console and click detail. Write down every client or address field that page actually shows. If a field is absent, do not invent it. Repeat the comparison with one direct request and one request that crossed your outer load balancer while PROXY protocol toward SafeLine remains off. A difference means the outer hop already changed the address the WAF can see.

Checklist before you call the client IP preserved

  • Pick a source of truth for WAF policy. IP-based rate limiting and the web access control list, both named in the overview, should be judged against the address recorded in step 8. If that address is your load balancer, every visitor shares one identity and rate limits will not mean what you think.
  • Leave PROXY protocol disabled on the connection into SafeLine. The three cited pages do not document acceptance, forwarding, or a toggle. This setup guide will not invent one.
  • Do not tell application owners that the origin now sees the browser IP. Forwarding safe traffic is documented. Preserving the original address through PROXY protocol is not.
  • If the origin must store the browser address for its own audit trail, test an allowed request in a lab and compare the origin log with the SafeLine detail view. If they differ, change the design or the expectation. Do not drop an undocumented flag into .env to force a match.
  • Keep the SSL checkbox in its documented role. It marks an HTTPS application listener. It says nothing about a proxy-protocol listener on the same port.
  • If a client-IP experiment breaks traffic, roll back with the documented uninstall: enter the SafeLine directory, run docker compose down, and remove the directory only when you truly want the data gone. Test protocol ideas on a spare host, not on the only path to production.
  • File a short note with the build you installed, the address shown in the attack detail, the address shown by the origin, and the statement that PROXY protocol was not enabled because these official pages do not describe it.

That note is the outcome of the setup. You will have a working reverse proxy, a verified block, and an honest gap list. You will not have a fictional PROXY protocol integration.

Does any cited SafeLine page document PROXY protocol?

No. The deploy guide documents Docker, Compose, .env, secrets, the console port, and MGT_PROXY for console proxy layers. The application guide documents domain, port, SSL, and upstream. PROXY protocol is absent.

Will this install make my origin log the real browser address?

No. The steps place SafeLine on the reverse-proxy path described in the application guide. They do not configure a client-IP integration that those pages never mention.

Why is client identity part of WAF setup at all?

The overview includes IP-based rate limiting and a web access control list, and the application guide points you to the attack list and its detail view. Those features depend on the client the WAF observes. An outer proxy can hide that client even when attack blocking still works.

Can I point an existing PROXY protocol sender at SafeLine?

Not based on these sources. Keep that sender off toward SafeLine until documentation for your exact version says the product accepts the preamble. A checklist is not a listener configuration.

What should I compare after the site is added?

After DNS points at SafeLine, send one documented test probe, confirm the blocking page, and open attack detail. Then compare a direct request with a request through the outer proxy, with PROXY protocol still disabled toward SafeLine, and record only fields you can see.

SafeLine has surpassed 700,000 installations worldwide as of September 30, 2026. SafeLine Pro annual promotional pricing is $650-$880, compared with the regular $1,000 per year.

Top comments (0)