Client IP Source Modes

Extendy GeoShield resolves a client IP address during WHMCS client-area login processing.

The resolved IP address is used for GeoIP country lookup, login event records, and later alert decisions. Choosing the correct source mode is important because proxy headers can be spoofed if the WHMCS origin server accepts direct traffic from untrusted clients.

Available modes

Extendy GeoShield currently supports three client IP source modes.

Mode	Intended use	Header trust behaviour
REMOTE_ADDR	Direct WHMCS access or deployments where no proxy header should be trusted	Uses the immediate peer address seen by PHP and ignores forwarded headers
CF-Connecting-IP	WHMCS behind Cloudflare	Uses CF-Connecting-IP only when the immediate peer matches bundled Cloudflare IP ranges
X-Forwarded-For	WHMCS behind a known reverse proxy or load balancer	Uses X-Forwarded-For only when the immediate peer matches configured Trusted Proxy IPs / CIDRs

The default mode is:

REMOTE_ADDR

REMOTE_ADDR mode

REMOTE_ADDR mode is the safest default.

In this mode, Extendy GeoShield:

• reads the direct peer IP address from REMOTE_ADDR;
• does not trust CF-Connecting-IP;
• does not trust X-Forwarded-For;
• rejects private, loopback, local, documentation, reserved, malformed, and otherwise non-public addresses as client IPs for GeoIP lookup.

If REMOTE_ADDR is not a valid public client IP address, the login event is still recorded, but the event may have an empty IP address and GeoIP country detection may fail.

This can be normal in local development, private networks, containers, or internal reverse-proxy topologies.

CF-Connecting-IP mode

CF-Connecting-IP mode is for WHMCS installations that are actually proxied through Cloudflare.

In this mode, Extendy GeoShield accepts the CF-Connecting-IP header only when REMOTE_ADDR belongs to the addon’s bundled Cloudflare IP ranges.

If REMOTE_ADDR is not Cloudflare:

• the CF-Connecting-IP header is ignored;
• Extendy GeoShield falls back safely to REMOTE_ADDR;
• if the fallback address is not a valid public client IP, the stored event IP address may remain empty.

This protects against a direct request to the origin server that includes a spoofed CF-Connecting-IP header.

For Cloudflare-specific guidance, see Cloudflare Setup.

X-Forwarded-For mode

X-Forwarded-For mode is for WHMCS installations behind a trusted proxy or load balancer that forwards the original client IP address.

This mode requires explicit Trusted Proxy IPs / CIDRs configuration.

Extendy GeoShield trusts X-Forwarded-For only when the immediate REMOTE_ADDR matches one of the configured trusted proxy ranges.

If no trusted proxy range is configured, or if the immediate peer does not match, the header is ignored and the resolver falls back safely to REMOTE_ADDR.

For proxy configuration guidance, see Proxy Setup.

What “IP Source Verified” means

The Login Events Log displays IP Source Verified.

This value means the selected IP source or header was verified as acceptable to use according to the configured mode.

It does not mean:

• the visitor is trusted;
• the IP address is safe;
• the login was legitimate;
• the country result is guaranteed to be accurate.

For example, in Cloudflare mode, IP Source Verified means the request came through a bundled Cloudflare range before CF-Connecting-IP was accepted.

In X-Forwarded-For mode, it means the immediate peer matched a configured trusted proxy and the header chain resolved to a valid public client IP.

Relationship to GeoIP lookup

GeoIP lookup runs only when Extendy GeoShield has a valid public client IP address.

If the resolver cannot produce a valid public client IP, the login event remains logged, but country detection may fail. The addon then follows the Alert When Country Detection Fails setting.

For provider behaviour, see GeoIP Providers Overview.

For event visibility, see Login Events Log.

Security guidance

Use the most restrictive mode that matches your topology.

• Use REMOTE_ADDR unless you have a real proxy or Cloudflare deployment requirement.
• Use CF-Connecting-IP only when WHMCS is actually behind Cloudflare.
• Use X-Forwarded-For only with explicitly configured trusted proxy ranges.
• Do not trust headers from the open Internet.
• Restrict direct origin access where possible when relying on proxy headers.

Extendy GeoShield is notification-only. These IP source modes affect logging, GeoIP lookup, and alert decisions; they do not block logins.