Skip to main content

Configuration Guide

Extendy GeoShield is configured from its WHMCS addon admin page.

The admin page currently provides two sections:

  • Login Events — a read-only view of stored login event metadata.
  • Settings — the addon configuration form and GeoIP provider test form.

Core settings​

Addon Enabled​

Controls whether Extendy GeoShield processes client-area login events.

Allowed values:

  • No
  • Yes

Default:

No

When disabled, the addon settings remain stored, but login-event processing does not run.

Alert Mode​

Controls when Extendy GeoShield should require an alert.

Allowed values:

  • Notify on Every Login
  • Outside Trusted Countries
  • Smart Mode

Default:

Outside Trusted Countries

At a high level:

  • Notify on Every Login alerts for detected login activity according to the detection-failure setting and cooldown rules.
  • Outside Trusted Countries alerts when the detected country is outside the configured trusted country model.
  • Smart Mode alerts when the detected country is new for the WHMCS User and Client Account context.

Smart Mode trust links require authenticated WHMCS access and strict token, user, and client-context validation.

Global Trusted Countries​

Stores administrator-defined trusted countries.

Enter comma-separated ISO alpha-2 country codes, for example:

JO, SA, AE

The addon stores these values internally as uppercase country codes.

GeoIP Provider​

Selects the provider used to resolve a public client IP address into country information.

Allowed values:

  • Not Configured
  • IPinfo
  • MaxMind

Default:

Not Configured

If no provider is configured, or if the provider cannot return country data, the login event is still logged. Whether an email is sent for country detection failure depends on Alert When Country Detection Fails.

Provider credentials​

The Settings page includes credential fields for:

  • IPinfo API Token
  • MaxMind Account ID
  • MaxMind License Key

Provider credentials are stored encrypted at rest and are not displayed in plaintext.

When editing settings:

  • leave a credential input empty to keep the existing stored value;
  • use the explicit clear/remove action to remove a stored credential;
  • do not paste provider credentials into support tickets, logs, screenshots, or shared documentation.

Client IP source​

Client IP Source​

Controls how Extendy GeoShield resolves the client IP address.

Allowed values:

  • REMOTE_ADDR
  • CF-Connecting-IP
  • X-Forwarded-For

Default:

REMOTE_ADDR

Use REMOTE_ADDR when WHMCS receives client requests directly or when no trusted proxy header should be used.

Use CF-Connecting-IP only when WHMCS is actually behind Cloudflare. The addon accepts this header only when the immediate request source matches bundled Cloudflare IP ranges. If the source is not verified as Cloudflare, the header is ignored and the addon falls back safely.

Use X-Forwarded-For only when WHMCS is behind a trusted proxy that you explicitly configure.

Trusted Proxy IPs / CIDRs​

Used only for X-Forwarded-For mode.

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

The addon trusts X-Forwarded-For only when the immediate request source matches a configured trusted proxy range. If no trusted proxy range is configured, X-Forwarded-For is ignored.

Private proxy ranges are allowed, but overly broad ranges are unsafe.

warning

Do not enable proxy-header modes unless your WHMCS deployment is protected so clients cannot reach the origin server directly and spoof headers.

The Login Events page records IP resolution metadata. The ip_source_verified field means the selected source or header was verified as acceptable to use. It does not mean the visitor or IP address is inherently safe.

Country detection failure​

Alert When Country Detection Fails​

Controls whether Extendy GeoShield sends a client alert when the login country cannot be determined.

Allowed values:

  • No
  • Yes

Default:

No

When set to No, a country-detection failure is logged, but no client email is sent only because country detection failed.

When set to Yes, the addon uses the normal login alert template with Unknown country values. Smart Mode trust links are not generated for Unknown country alerts.

Alert cooldown​

Alert Cooldown​

Controls how long repeated alerts are suppressed for the same user/client/country decision key.

Allowed range:

0 to 720 hours

Default:

24 hours

A value of 0 disables cooldown suppression.

Retention​

Retention​

Controls automatic cleanup of Extendy GeoShield login event records.

Allowed values:

  • 180 Days
  • Disabled (Automatic Cleanup Off)

Default:

180 Days

When set to 180 Days, WHMCS daily cron removes Extendy GeoShield login event records older than 180 days.

When set to Disabled (Automatic Cleanup Off), automatic cleanup is disabled. Use this only if your organisation manages retention separately.

Retention cleanup affects only Extendy GeoShield login event records. It does not remove known countries, trust tokens, settings, email templates, or unrelated WHMCS data.

Controls how long a Smart Mode trust link token remains valid.

Allowed range:

1 to 168 hours

Default:

48 hours

Trust links are one-time use and require WHMCS authentication before a country can be trusted.

GeoIP Provider Test Connection​

The Settings page includes a GeoIP Provider Test Connection form.

It tests the currently saved provider and saved credentials using a public test IP address. It does not save settings and does not create login events.

The test output displays normalised provider, status, and country result fields or a safe error message. It does not display provider credentials or raw provider responses.

Email alert behaviour​

Extendy GeoShield uses WHMCS email templates and WHMCS SendEmail.

In the current product behaviour:

  • alerts are sent to the primary WHMCS Client Profile email address for the safely resolved Client Account;
  • the WHMCS User email that performed the login is included in the email content as the login actor;
  • no alert email is sent when the Client Account context is missing or ambiguous;
  • the addon does not silently send alerts to unrelated contacts, additional contacts, or other Client Accounts.

Deactivation​

Deactivation preserves Extendy GeoShield data.

It does not delete:

  • settings;
  • login event records;
  • Smart Mode known countries;
  • trust tokens;
  • email templates;
  • addon database tables.

Full removal is a separate manual procedure and should only be performed after a verified database backup.