GeoIP and Access Location
Audience: System Admin, Deployment Administrator, Support, Developer
Related documentation: Configuration, Audit and logging, Data retention and purge, Security and scoping, Raspberry Pi deployment, GCP deployment
Why Blackcap records access location
Blackcap records the source IP address and country associated with selected authentication, display, API, and voice-assistant activity so administrators can understand which countries are accessing those resources. This is useful for:
- recognizing expected household, customer, or deployment access;
- spotting unexpected country or source-IP breadth;
- troubleshooting whether a Hosted Web Receiver, Kiosk, Remote Pi Client, API Token, or voice connection is reaching the intended Blackcap instance;
- confirming that a reverse proxy is forwarding the real client address instead of reporting only a loopback or proxy address;
- investigating login failures and security events without requiring full request-content logging.
Country information is diagnostic context, not an authorization decision. GeoIP is approximate, may reflect a VPN, carrier gateway, corporate proxy, or cloud egress location, and must not be treated as proof of a person's physical location.
How lookup works
Blackcap performs an optional, local country lookup against a MaxMind-compatible MMDB database. The built-in reader also supports the DB-IP Lite country MMDB format. No request is sent to a third-party geolocation API during normal lookup.
The lookup is fail-open:
- application access continues when GeoIP is disabled;
- application access continues when the database is absent or unreadable;
- an unknown country remains unknown rather than blocking the request;
- country-display failures do not prevent login, display polling, API work, or voice actions.
The setting value maxmind identifies the compatible local MMDB reader; it does not require that the file itself was purchased from MaxMind. DB-IP Lite may be used through the same reader.
Activity surfaces covered
Authentication
Access activity can record successful and failed internal logins, authentication-provider logins, MFA outcomes, and trusted-browser activity. Account and administrative activity views use these records to show recent source addresses and countries where permitted.
Login page country indicator
When Show Country Flags is enabled, the login page may show the country inferred for the current request. This gives an immediate troubleshooting signal about how Blackcap sees the user's connection. Turning the flag off does not disable access-location tracking.
Displays
Blackcap records access breadth for externally reachable display surfaces, including:
- Hosted Web Receiver page access and state polling;
- Kiosk page access and state polling;
- authenticated or token-based display access;
- Remote Pi Client state, heartbeat, preview, and panel-transport requests.
Display Details can summarize countries and recent access for the selected display. Hosted and Kiosk surfaces may show the current viewer country flag when flag display is enabled. This helps distinguish, for example, a local kitchen display from a remote or cloud-hosted viewer and can reveal an incorrectly shared display URL or token.
API Tokens
Requests authenticated by an API Token can record the endpoint, source IP, and country. This makes it easier to understand where Chrome Extension or other API activity is originating without changing token permissions. API Tokens remain distinct from AI Seeds and from browser sessions.
Voice assistants
Alexa and Google Home access can record source-location context through the voice access-tracking boundary. Provider infrastructure may cause the recorded country or address to represent a provider endpoint rather than the household device, so interpret voice records as connection diagnostics rather than precise device location.
Administrative and support views
Country information can appear in login/activity history, display diagnostics, API-token activity, voice diagnostics, and instance/support diagnostics where the current user's permissions allow it. The Support Request flow can include the server-observed client IP/location as part of its sanitized diagnostic context; it does not include GeoIP database contents or unrelated access-history rows.
The login, Hosted Web Receiver, and Kiosk current-viewer indicator is presentation-only. It uses the same request IP and local lookup path but does not create an extra activity row beyond the normal login/display/API tracking event.
Blackcap must not expose raw activity data to unrelated organizations.
Platform configuration
System Admins manage these settings under Configuration > Platform > GeoIP / Access Location:
| Setting | Purpose |
|---|---|
| Enable GeoIP Lookup | Enables local country lookup. Tracking remains fail-open. |
| GeoIP Provider | Selects none or the MaxMind-compatible local reader. |
| MMDB Database Path | Points to the country MMDB file. |
| GeoIP Update Source | Selects DB-IP Lite download, MaxMind geoipupdate, or manual maintenance. |
| DB-IP Lite URL Template | Advanced download template; {year_month} represents YYYY-MM. |
| Show Country Flags | Shows country indicators on login and display surfaces while leaving tracking independent. |
Country-flag presentation is configured separately under Configuration > Platform > Country Flags, including the enabled state and SVG, emoji, or country-code presentation mode.
Country-flag assets and presentation
The country result is stored as country/location data independently of how it is displayed. Configuration > Platform > Country Flags controls whether the UI uses bundled SVG flags, flag emoji, or compact country codes. Show Country Flags under GeoIP / Access Location controls whether login/display indicators are visible at all.
Bundled SVGs live in inky_admin/static/country_flags/. If a requested SVG is absent, Blackcap falls back to flag emoji and then the country code. Local/private access uses the LAN indicator; unknown locations use an unknown-location indicator.
System Admins can generate missing observed-country assets from the Country Flags configuration panel when the optional OS tools are installed. Flag generation is optional at runtime; tracking and country-code display do not depend on TeX/Inkscape being installed.
Database locations and updates
The intended managed locations are deployment-specific:
- Raspberry Pi: application data under the Blackcap installation, normally
data/geoip/dbip-country-lite.mmdbbeneath/home/pi/Blackcap-Pi; - GCP:
/var/lib/blackcap/geoip/dbip-country-lite.mmdb.
The blackcap_geoip_update.timer systemd timer runs blackcap_geoip_update.service on its configured schedule, normally monthly. The Configuration diagnostics panel also provides Update GeoIP DB Now for an authorized manual refresh. A successful replacement clears the in-process lookup cache so new requests use the new database. A manual deployment may instead place a compatible MMDB at the configured path.
Never commit licensed GeoIP databases, account credentials, or private download tokens to the repository.
Reverse proxies and the real client address
Blackcap trusts X-Forwarded-For or X-Real-IP only when proxy-header trust is enabled and the immediate peer is within the configured trusted proxy CIDRs. This prevents arbitrary internet clients from forging their apparent source country.
On GCP, Nginx should forward the client address to Gunicorn. On Raspberry Pi deployments using stunnel or another proxy, preserve the established proxy protocol or trusted-header design. If most records show only 127.0.0.1, the proxy address, or one internal address, troubleshoot proxy forwarding before interpreting the country results.
Privacy, permissions, and retention
IP addresses and inferred countries are operational/security data. They must be organization-scoped where the resource is organization-scoped, visible only to authorized users, omitted from normal public documentation examples, and excluded from exports that do not require them.
The platform purge policy purge.access_activity.after_days controls how long access-location history is retained; the normal default is 90 days. Purging old activity does not disable future tracking. See Data retention and purge.
Troubleshooting
No country is shown
Check that GeoIP is enabled, the provider is maxmind, the MMDB path exists and is readable by the application service, and the source address is public. Private, loopback, or reserved addresses normally have no country.
The wrong country is shown
Verify the source IP in the same activity record. VPNs, mobile carriers, cloud providers, and corporate networks commonly terminate in another region. Update the MMDB if it is stale, but do not treat a mismatch as proof of malicious activity.
Flags are hidden but country history continues
This is expected. Show Country Flags controls UI presentation. Enable GeoIP Lookup and access-activity policy control lookup and tracking.
Every request appears to come from one proxy
Review Nginx, stunnel, Gunicorn proxy protocol, trusted proxy headers, and trusted proxy CIDRs. Do not broadly trust forwarded headers from untrusted peers merely to make the dashboard look correct.
The update job fails
Review the GeoIP update service/timer logs, the configured update source, network access, target-directory permissions, available disk space, and any MaxMind credentials stored outside the repository. A failed update should leave the prior valid database in place.