Proxy Setup

If WHMCS is behind a reverse proxy or load balancer, the direct peer address seen by PHP may be the proxy, not the original visitor.

Extendy GeoShield can use X-Forwarded-For only when the proxy path is explicitly trusted. This prevents clients from spoofing an X-Forwarded-For header and controlling the IP address used for GeoIP lookup.

When to use X-Forwarded-For mode

Use X-Forwarded-For mode only when:

• WHMCS is behind a known reverse proxy, load balancer, or edge layer;
• that proxy reliably sends X-Forwarded-For;
• the immediate peer address seen by PHP can be matched to a configured trusted proxy IP or CIDR range;
• direct client access to the WHMCS origin is restricted where possible.

Do not use this mode just because an X-Forwarded-For header appears in requests. Headers from untrusted clients are not safe.

Configuration steps

In the Extendy GeoShield Settings page:

1. Set Client IP Source to:

   X-Forwarded-For

2. Enter the immediate trusted proxy addresses or CIDR ranges in Trusted Proxy IPs / CIDRs.

   Enter one IPv4 address, IPv6 address, or CIDR range per line.

   Examples:

   192.0.2.10/32
   2001:db8:1234::/48

3. Save the settings.

4. Perform a controlled client login and review the Login Events Log.

The examples above use documentation-reserved address ranges. Replace them with your real proxy addresses.

Trusted proxy ranges

Trusted proxy ranges should describe only the proxy infrastructure that directly or legitimately forwards requests to WHMCS.

Private proxy ranges are allowed for internal networks, but broad ranges are risky.

Avoid trusting:

• 0.0.0.0/0;
• ::/0;
• an entire hosting network when only one load balancer should be trusted;
• client-accessible networks;
• ranges you do not control.

Extendy GeoShield validates the trusted proxy list and rejects entries that are malformed or trust the entire Internet.

How X-Forwarded-For is resolved

When X-Forwarded-For mode is enabled, Extendy GeoShield follows this model:

1. Check REMOTE_ADDR.
2. Continue only if REMOTE_ADDR matches a configured trusted proxy range.
3. Read the X-Forwarded-For header.
4. Split the header into hops.
5. Resolve the chain from right to left.
6. Remove trusted proxy hops from the right side.
7. Select the first valid public IP address that is not a trusted proxy.

If the header is missing, malformed, too long, contains too many hops, contains private or reserved client addresses, or contains only trusted proxy hops, Extendy GeoShield falls back safely to REMOTE_ADDR.

If the fallback address is not a valid public client IP, the event may be logged without an IP address and country detection may fail.

IPv4, IPv6, and CIDR support

Trusted proxy entries support:

• IPv4 addresses;
• IPv6 addresses;
• IPv4 CIDR ranges;
• IPv6 CIDR ranges.

Extendy GeoShield normalises and validates entries before using them.

Login Events visibility

The Login Events Log can help confirm whether the proxy configuration is working.

Relevant fields include:

• IP Address — the resolved public client IP when available.
• IP Source Used — the source/header actually used.
• IP Source Verified — whether the configured source/header was verified as acceptable to use.

The event record also stores additional IP resolution metadata for admin diagnostics.

Common outcomes

Outcome	Likely meaning
IP Source Used is X-Forwarded-For and IP Source Verified is yes	The immediate peer matched a trusted proxy and the header resolved to a valid public client IP
IP Source Used is REMOTE_ADDR and IP Source Verified is no	The configured proxy/header source was not accepted and the resolver used safe fallback
IP Address is empty	No valid public client IP was available, often because the environment uses private/local addresses

Security notes

Only trust proxies that are part of your controlled infrastructure.

If clients can reach WHMCS directly, they may be able to send spoofed forwarding headers. Extendy GeoShield will ignore X-Forwarded-For unless REMOTE_ADDR matches your trusted proxy configuration, but direct origin access can still produce incomplete or misleading IP context.

This feature affects login-event context and alert decisions. It does not block logins.