Skip to content
Hyperion

Install the GeoIP database

Country blocking on a site’s Protection card needs a GeoIP database. Hyperion uses MaxMind’s free GeoLite2 Country database, and you need a MaxMind account for the download. Until it is installed, every visitor resolves to ZZ and no country rule matches anybody, so a rule cannot cut a site off before the data exists.

The database lives on the master. Sites on worker nodes have no copy, so only sites on the master can block countries.

Before you start

Section titled “Before you start”
  • You are an Owner. Other users can see the card, and the forms are disabled.
  • You have a MaxMind account with a licence key. In MaxMind, open My account, then Manage licence keys.
  • The master can reach MaxMind’s download servers.
  • If you already run MaxMind’s own geoipupdate, its /etc/GeoIP.conf is read as is, and there is nothing to enter here.

Steps

Section titled “Steps”
  1. Open Settings in the sidebar, then Brute-force & GeoIP under Security.
  2. Find the GeoIP database card. The pill reads installed or not installed.
  3. Enter your MaxMind account ID.
  4. Paste the key into Licence key.
  5. Click Save and download.

Hyperion writes the credentials to /etc/GeoIP.conf, readable by root only, and downloads the database immediately, so a wrong key fails straight away. The page never shows the key again. When one is stored, the field reads “stored — type a new one to replace it”.

To refresh later, click Refresh now (or Download now when nothing is installed yet). Hyperion does not refresh the database on a schedule. MaxMind publishes twice a week, so refresh it now and then.

Check that it worked

Section titled “Check that it worked”
  • The page shows “GeoIP database installed — N ranges.” or “Credentials saved and the GeoIP database installed — N ranges.”
  • The pill reads installed and the card says “Last refreshed” with a UTC time.
  • On a site on the master, enter a code under Countries, Blocked countries on the Protection card. Visitors from that country now receive a 403.

If it fails

Section titled “If it fails”
  • “Only an Owner can change the GeoIP credentials.” or “Only an Owner can refresh the GeoIP database.”: sign in as an Owner.
  • “The agent did not answer: …”: the master’s agent is not reachable. Check Service health.
  • The download is refused: the message comes from MaxMind through the agent. Check the account ID and licence key, then save again.
  • Country blocking does nothing on a worker node’s site: worker nodes have no copy of the database.