Country geolocation

Clearplane uses GeoIP data to enforce country entries in access control policies (the clearplane.proxy.access-control.allowed-countries and blocked-countries labels, or Country entries in the UI) and to show the country of banned and blocked addresses in the Blocked IPs report.

Choose the provider under System โ†’ Settings โ†’ Country geolocation, or with the clearplane.core.geo-ip.* labels on the Core container:

Provider Key Updates Licence
DB-IP Lite (default) None Monthly CC BY 4.0, attribution required: IP Geolocation by DB-IP
IPLocate None Daily CC BY-SA 4.0, attribution with a link required: IP address data powered by IPLocate.io
MaxMind GeoLite2 A MaxMind license key (CLEARPLANE_CORE_GEO_IP_LICENSE_KEY) Set by MaxMind See maxmind.com

Clearplane shows the DB-IP or IPLocate attribution next to the country picker. Core uses the data only for its own lookups and does not redistribute it.

How the data moves. Core downloads the provider's country archive, reads the CSV straight from it in memory and keeps only the resulting address ranges, in the IP-data database (database/ip-data.db in the clearplane-core-data volume). Edge pulls the ranges from Core and keeps a copy in the clearplane-cache volume, so it restarts with country data while Core is down. Without that copy, Edge has no country data until its first sync.

When it refreshes. Core refreshes the data at startup, when you change the provider or the key, and weekly through the GeoIP database update background job (Sundays at 04:00 UTC by default). A DB-IP edition is monthly; if this month's file is not published yet, Core uses last month's. If the download fails at startup, Core keeps the earlier data from the same provider and logs a warning. With no earlier data from that provider, Core stops with an error until the download works or you turn geolocation off. A failed scheduled refresh keeps the current data.

When the data is missing. Until Edge has country data, every access control policy that has a country entry, directly or through an alias, is skipped entirely, including its address entries. Edge logs a warning and the Edge service panel shows how many policies are unenforced. Policies without country entries still apply.

Country on bans and blocks. A ban or IP filter block records its country when it is first recorded. The country stays empty if the data was not loaded then, and is not filled in later.