Skip to content

Trusted Proxies Developer Guide

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

Trusted proxies: the real client address in Docker - Developer Guide

(5.8.0, #410, contributed by @cloudcogsio)

Behind a reverse proxy - nginx, a load balancer, a Cloudflare Tunnel - every request reaches FreeITSM from the proxy, so the sign-in log, the audit trails and API key address checks all record the proxy's address. The Docker image's TRUSTED_PROXIES setting makes Apache take the real address from the proxy's header, but only on connections from the proxy. How to set it is in Installation - Behind a reverse proxy; the merge review and the tests on a real nginx stack are in Behind a reverse proxy - review. This page is how it works.

Not to be confused with TRUST_PROXY_HTTPS (Running behind a reverse proxy), which is about the scheme (https://), not the address.


Files

File What it holds
docker-compose.yml The two optional settings, commented out: TRUSTED_PROXIES, TRUSTED_PROXY_HEADER
docker/entrypoint.sh On every start: writes conf-available/freeitsm-remoteip.conf, enables mod_remoteip, checks with apache2ctl -t, warns on wide ranges and host names; never stops Apache
includes/docker_proxy.php dockerProxyState() (what Apache really loaded), dockerProxyListFacts() (wide ranges, names), dockerProxyCheck() (the Test verdict)
api/system/docker_proxy_check.php The Test button: administrators only, Docker only, read-only
system/docker/index.php System → Docker → Behind a reverse proxy: status, the "what a wrong setting does" warning, Test
includes/api_security.php apiIpAllowed() - the range matching the Test shares with API key allow-lists
docker/proxy-test/* A throwaway nginx stack and check-ip.sh that signs in and reads back what system_logs recorded
tests/docker-proxy-check.php 20 checks of the verdicts and range warnings, no Docker needed

1. No PHP changes: Apache fixes REMOTE_ADDR

FreeITSM reads the client address from REMOTE_ADDR everywhere, and must: a header such as X-Forwarded-For is written by the caller and proves nothing.

// includes/api_security.php
 * 🔴 The address is REMOTE_ADDR, the connection's own - never a header such as
 * X-Forwarded-For, which the caller writes. Behind a reverse proxy every request
 * comes from the proxy, so an allow-list there must name the proxy - the help says so.
 * Unless the Docker image's TRUSTED_PROXIES is set: Apache (mod_remoteip) then puts
 * the client's address in REMOTE_ADDR itself, before PHP runs, and the allow-list
 * names the clients (docker/entrypoint.sh).

So the whole feature is Apache configuration. mod_remoteip believes the header only on a connection from a listed proxy, reads X-Forwarded-For from the right, skips every listed address, and puts the first one left into REMOTE_ADDR.

2. The entrypoint

Decided on every start, starting from off - so a host name that no longer resolves, or a value removed from docker-compose.yml, never leaves an old configuration behind:

# docker/entrypoint.sh
REMOTEIP_CONF=/etc/apache2/conf-available/freeitsm-remoteip.conf
remoteip_off() {
    a2disconf -q freeitsm-remoteip >/dev/null 2>&1
    a2dismod -q remoteip >/dev/null 2>&1
    rm -f "$REMOTEIP_CONF"
}
remoteip_off
PROXY_LIST=$(printf '%s' "$TRUSTED_PROXIES" | tr ',\t\r\n' '    ' | tr -s ' ' | sed 's/^ //; s/ $//')
PROXY_HEADER="${TRUSTED_PROXY_HEADER:-X-Forwarded-For}"
if [ -z "$PROXY_LIST" ]; then
    :
elif printf '%s' "$PROXY_LIST" | grep -q '[^A-Za-z0-9.:/ -]' \
    || printf '%s' "$PROXY_HEADER" | grep -q '[^A-Za-z0-9-]'; then
    echo "TRUSTED_PROXIES or TRUSTED_PROXY_HEADER is not valid, so client addresses are not taken from the proxy." >&2
else
    {
        echo "# Written by entrypoint.sh from TRUSTED_PROXIES - do not edit."
        echo "RemoteIPHeader $PROXY_HEADER"
        echo "RemoteIPInternalProxy $PROXY_LIST"
        echo 'LogFormat "%a %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" combined'
        echo '<Location /server-status>'
        echo '    Require all denied'
        echo '</Location>'
    } > "$REMOTEIP_CONF"
    a2enmod -q remoteip >/dev/null 2>&1
    a2enconf -q freeitsm-remoteip >/dev/null 2>&1
    if APACHE_ERR=$(apache2ctl -t 2>&1); then
        echo "TRUSTED_PROXIES is set: ..."
        # ...warn on an IPv4 range wider than /24, an IPv6 range wider than /64, and on host names
    else
        remoteip_off
        echo "TRUSTED_PROXIES was refused by Apache, so client addresses are not taken from the proxy: ..." >&2
    fi
fi
  • Values are whitelisted before they reach a config file (letters, digits, .:/ - for the list; letters, digits and - for the header name), so nothing can inject an Apache directive.
  • apache2ctl -t is the judge. A value Apache refuses turns the feature off and says why in docker logs; Apache always starts.
  • %a in the access log is the address after mod_remoteip; the stock %h would keep logging the proxy.
  • /server-status is closed while it is on. mod_status allows it with Require local; with 127.0.0.1 forgeable through a wide range, "local" would no longer mean local.
  • Host names (a container name) are looked up once, when Apache starts - restart the container if the proxy's address changes. The log says so.
  • It runs before the HTTPS check that follows it, and both start from off, so each tests this start's settings.

3. The screen: what Apache actually loaded

dockerProxyState() reads the enabled config file, not the environment variable, so the screen can never say "on" when the value was refused:

// includes/docker_proxy.php
const DOCKER_PROXY_CONF_ENABLED = '/etc/apache2/conf-enabled/freeitsm-remoteip.conf';

function dockerProxyState(): array
{
    $env    = trim((string)getenv('TRUSTED_PROXIES'));
    $header = trim((string)getenv('TRUSTED_PROXY_HEADER')) ?: 'X-Forwarded-For';
    $list   = [];
    $state  = 'off';

    $conf = @file_get_contents(DOCKER_PROXY_CONF_ENABLED);
    if (is_string($conf) && preg_match('/^RemoteIPInternalProxy\s+(.+)$/m', $conf, $m)) {
        $state = 'on';
        $list  = preg_split('/\s+/', trim($m[1]), -1, PREG_SPLIT_NO_EMPTY);
        if (preg_match('/^RemoteIPHeader\s+(\S+)/m', $conf, $h)) $header = $h[1];
    } elseif ($env !== '') {
        $state = 'refused';
        $list  = preg_split('/[\s,]+/', $env, -1, PREG_SPLIT_NO_EMPTY);
    }
    return ['state' => $state, 'header' => $header] + dockerProxyListFacts($list);
}

dockerProxyListFacts() applies the entrypoint's own thresholds (wider than /24 or /64 is wide) and resolves host names, so the page warns about exactly what the log warned about. The section always shows, in red, what a wrong setting does: 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), the wrong address (ignored).

4. The Test verdict

api/system/docker_proxy_check.php (System admins via admin_api_guard.php; 400 outside the Docker image) returns dockerProxyCheck(dockerProxyState(), $_SERVER):

if ($state['state'] === 'refused') {
    $verdict = 'refused';
} elseif ($state['state'] === 'off') {
    $verdict = $headers ? 'off_proxy' : 'direct';
    if ($headers) $suggest = $recorded;
} else {
    // Found on the real proxy stack: with a range like 172.16.0.0/12 the person's own address
    // is inside it too, so "still the proxy" would blame the header when the range is the fault.
    $inWide  = $recorded !== '' && $state['wide'] && apiIpAllowed(implode("\n", $state['wide']), $recorded);
    $isProxy = $recorded !== '' && $state['resolved'] && apiIpAllowed(implode("\n", $state['resolved']), $recorded);
    $verdict = $inWide ? 'too_wide' : ($isProxy ? 'still_proxy' : 'working');
}
Verdict When
direct Off, and no forwarding header arrived: nothing to set
off_proxy Off, and a forwarding header arrived: everyone is recorded as the proxy; suggest is the recorded address - the line to add
working On, and the recorded address is not a listed proxy - the person confirms it is their own computer's
too_wide On, and the recorded address is inside a range wider than one proxy: FreeITSM cannot tell this person from a proxy
still_proxy On, but the recorded address is a listed proxy: the proxy sends no usable header
refused Set, but not in force (see docker logs)

Behind mod_remoteip the proxy's own address is gone from PHP's view, so the verdict says what it can prove and asks the person to confirm the rest. It reuses apiIpAllowed(), the API allow-list's range matching, so "inside a range" means the same thing in both places. The forwarding headers it echoes back are trimmed to 300 characters.

TRAP: check too_wide before still_proxy. The first version did not, and on the test stack with TRUSTED_PROXIES=172.16.0.0/12 it told the tester the proxy was not sending the header - when their own address (the Docker gateway) was inside the range and the range was the fault. A unit test alone would not have found it: it needed a real address inside a real range.


Traps

  • Never read the client address from a header in PHP. Use REMOTE_ADDR; on Docker, TRUSTED_PROXIES is what makes it right behind a proxy. Outside Docker, the same is done in the web server (mod_remoteip on Apache, real_ip on nginx, the equivalent on IIS).
  • List the proxy's own address, nothing wider. Every host in a listed range can claim any client address, 127.0.0.1 included.
  • API key allow-lists name the real clients once this is on, not the proxy.
  • Make sure nobody can reach the container round the proxy - a direct connection is not from a listed address, so its header is ignored, but its own address is recorded as-is.

Testing

php tests/docker-proxy-check.php       # the verdicts and range warnings, no Docker
docker/proxy-test/check-ip.sh          # the real stack: nginx in front, sign in, read back system_logs

The real-stack cases - normal, forged X-Forwarded-For, forged 127.0.0.1, a header sent straight to the app, /server-status, and the setting empty - are tabled in the review.

Related: Installation · Running behind a reverse proxy · 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