Skip to content

Trusted Proxies PR Review

Ed Mozley edited this page Nov 20, 2026 · 1 revision

Behind a reverse proxy: recording the real address - review

#410 by @cloudcogsio Β· Verdict: merge, with additions Β· 5.8.0 (#3033)

In plain words

When something sits in front of FreeITSM - nginx, a load balancer, a Cloudflare Tunnel - every visitor reaches FreeITSM through it. So FreeITSM sees one address for everybody: the proxy's. The sign-in log, the audit trails and API key address checks all show that one address.

The proxy does pass the real address along, in a header such as X-Forwarded-For. But anyone can write that header, so FreeITSM must only believe it when it comes from the proxy itself. TRUSTED_PROXIES is how you tell it which machine that is. User page: Installation - Behind a reverse proxy.

What the branch does

Two optional settings in docker-compose.yml, off unless set:

      - TRUSTED_PROXIES=192.0.2.10          # the proxy's address (or a container name)
      - TRUSTED_PROXY_HEADER=CF-Connecting-IP   # only for a Cloudflare Tunnel

On start, docker/entrypoint.sh turns on Apache's mod_remoteip with them, checks the result with apache2ctl -t, and never stops Apache over a bad value - it turns the feature off and says why in docker logs. Apache then puts the real address in REMOTE_ADDR before PHP runs, so no PHP changes were needed. It also closes /server-status while this is on (a forged 127.0.0.1 must not open it), warns in the log about ranges wider than /24 (IPv4) or /64 (IPv6), and logs the client in Apache's access log.

How it was checked

On the branch's own test stack - FreeITSM behind a real nginx, in throwaway containers - with its check-ip.sh, which signs in and reads back the address system_logs recorded:

Case Recorded
Normal sign-in through the proxy The caller, not the proxy
A forged X-Forwarded-For through the proxy Ignored - still the caller
A forged 127.0.0.1 Ignored
A forged header sent straight to the app, round the proxy Ignored
/server-status with a forged 127.0.0.1 403
TRUSTED_PROXIES empty (EXPECT=proxy) The proxy, for everyone - as expected when it is off

What was added: a screen that explains it, and a Test button

The branch had no screen: the setting lives only in docker-compose.yml. A setting that can quietly let anyone fake their address needs more than a help page, so System β†’ Docker gained a Behind a reverse proxy section (Docker installs only):

  • Status, from what Apache actually loaded - On, Off, or Set, but not in force. It reads conf-enabled/freeitsm-remoteip.conf, not just the environment variable, so it cannot say "on" when the value was refused. Amber, not green, when the range is too wide.
  • "What a wrong setting does - read this before you change it", always shown, in red: too wide (anyone in the range can fake any address - in the sign-in log, the audit trails, and past an API key's address restriction), not set (everyone is the proxy; an API allow-list can only name the proxy, which lets in anyone behind it), the wrong address (ignored - back to everyone being the proxy).
  • A live warning when the setting in force is wider than one proxy.
  • Test - read-only. It shows the address FreeITSM recorded for you just now and what it means:
Verdict When Says
Working On, and you are not one of the proxies Check it really is your computer's address
Off behind a proxy Off, and a proxy header arrived Everyone is recorded as the proxy - and prints the exact line to add, with the proxy's address
Too wide On, and your own address is inside a range that is too wide Not safe: FreeITSM cannot tell you from the proxy
Still the proxy On, but you are recorded as the proxy The proxy is not sending the header
Direct Off, no proxy header Nothing to set
Not in force Set, but refused Fix the setting first

The verdict the real stack found

The first version of Test had no Too wide verdict. On the test stack with TRUSTED_PROXIES=172.16.0.0/12, it told the tester "the proxy is not sending the header" - wrong. The tester's own address (the Docker gateway, 172.27.0.1) was inside the range, so FreeITSM rightly treated them as a proxy; the range was the fault, not the header. That is the very case the warning exists for, so it now has its own verdict, checked first. A unit test alone would not have found it: it needed a real address inside a real range.

All four settings were then checked in the container - the proxy by name, empty, 172.16.0.0/12 and an invalid value - each giving the verdict in the table.

Also fixed

The branch's Docker help said the sign-in log is in System β†’ Logs; it is in Reporting β†’ Logs.

πŸ“ Files

File Change
🐳 docker/entrypoint.sh The branch: mod_remoteip from the two settings, checked, never fatal
πŸ§ͺ docker/proxy-test/* The branch: nginx test stack and check-ip.sh
🟣 includes/docker_proxy.php New: dockerProxyState() (what Apache loaded) and dockerProxyCheck() (the verdict), sharing the API allow-list's range matching
🟣 api/system/docker_proxy_check.php New: the Test button; administrators only, read-only
🟣 system/docker/index.php The section, the warnings, Test
πŸ§ͺ tests/docker-proxy-check.php New: 20 checks of the verdicts and range warnings, no Docker needed; a version that always says "working" fails 7
🌐 lang/*/system.php 32 strings, 9 languages
πŸ“„ system/help/docker.php, system/help/api.php The branch's help, with Reporting β†’ Logs

Worth knowing

  • List the proxy's own address, nothing wider. A container name also works, but it is looked up once when FreeITSM starts: restart FreeITSM if the proxy gets a new address.
  • An API key's allowed addresses must name the real addresses once this is on, not the proxy.
  • On other installs, set this up in the web server itself (mod_remoteip on Apache, or the equivalent on IIS or nginx); the System β†’ Docker section only appears in the Docker image.

Related: Installation Β· Docker volumes - review

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally