Skip to main content

Licensing GeoIP

A license buys one thing: real data​

There are no editions or tiers: a license either covers this service or it does not. The console's License page lists the one capability it buys, Real geolocation data (its feature column reads details).

Every endpoint answers on an unlicensed installation. /lookup, /details and /lookup/batch at any size, with any fields, all return 200. Nothing on the lookup surface is ever refused for want of a license, so an integration written against this service keeps running when a license lapses.

StateWhat the service does
Unlicensed (no license, or one that does not validate)Answers every lookup with a fixed placeholder and says so in every response. Downloads no database, consults none on disk, refuses GET /databases/{edition}, and POST /update reports that it did nothing and why
LicensedDownloads and refreshes the GeoLite2 databases under your MaxMind account, answers from them, and serves the .mmdb files to your mirrors
Lapsed (expired, removed, refused by the license server, or out of its check-in window)The same as unlicensed, from the moment the service sees it. The databases on disk are kept. See When a license lapses

Getting and keeping a license​

Where to buyantelao.io
Bound toOne host. A license is activated for the hardware challenge shown on the License page, which is why the compose file mounts /etc/machine-id: without it every recreated container looks like a different machine. A license bound to another machine is refused
ActivationOn the License page, Activate online with the license key and the e-mail address it was issued to, or Install a license file with the .lic file you were sent. A license file that has never been activated works for 14 days from the moment it is first seen, so the service runs while activation is arranged
Check-inThe service re-reads its license every hour, and checks in with the Antelao license server once a day and straight after a license is installed. It needs outbound internet access for that
When a check-in failsThe service keeps working on its last successful check-in for 14 days, unless the license states another period, and then runs unlicensed until a check-in gets through
Offline useNot available in the container. A license issued for a machine with no route to the license server needs attested TPM hardware, and the container has no TPM, so such a license is refused

Perpetual and offline licenses​

  • A perpetual license applies only once it is activated. The 14 days a license file gets while activation is arranged do not apply to it: activate it on the license portal before you update the service, or the service stops being licensed after the update.
  • An offline license is not supported. It needs a machine whose TPM proves itself to the service, and the service's container has none. Use a license that checks in with the license server.

Moving a license to another host​

A license runs on as many installations as it allows, one unless it says otherwise. The console has no move of its own: Remove on the License page deletes the license file on this host, and the installation keeps its place with the Antelao license server. Activating the license on another host while that place is taken is refused as already in use, so write to support@antelao.io with the license key to move it.

Recreating the container is not a move. With /etc/machine-id mounted, as in the compose file, a recreated container is the same machine and keeps its license.

What an unlicensed lookup returns​

GET /lookup/203.0.113.7:

{
  "address": "203.0.113.7",
  "countryCode": null,
  "continentCode": null,
  "isUnknown": true,
  "synthetic": true,
  "licensed": false,
  "note": "This installation of Antelao GeoIP is not licensed, so this answer is a placeholder and describes no real location. countryCode and continentCode are null, which every caller reads as 'this address could not be placed'. Install a license for real data."
}

GET /details/203.0.113.7:

{
  "address": "203.0.113.7",
  "found": false,
  "countryCode": null,
  "countryName": "Nowhere",
  "continentCode": null,
  "continentName": null,
  "registeredCountryCode": null,
  "network": "203.0.113.0/24",
  "asNumber": 0,
  "asOrganization": "Antelao GeoIP (unlicensed placeholder)",
  "cityName": "Nullhaven",
  "subdivisionName": "Placeholder Province",
  "postalCode": "00000",
  "latitude": 0.0,
  "longitude": 0.0,
  "accuracyRadiusKm": 0,
  "timeZone": "Etc/UTC",
  "synthetic": true,
  "licensed": false,
  "note": "..."
}

The other fields are filled in so that an unlicensed answer is recognisable at a glance in a console, a log or a support ticket. Nullhaven, Placeholder Province at 0,0 is not a place and cannot be mistaken for one.

Every response also carries synthetic, licensed and note, so a program reading the JSON never has to infer any of this from the values. GET /status reports the same thing once, as synthetic and syntheticReason, and the console shows it as a banner.

When a license lapses​

A license that has ended - expired, removed, refused by the license server, or past its check-in window - is not bridged by anything further. From the moment the service sees it, every lookup is answered with the placeholder above, and refreshes stop.

Databases already on disk are kept. A lapse deletes nothing; the files simply stop being consulted, and the first refresh after a license is installed again is a cheap conditional request rather than a full download. A license installed later starts that refresh straight away.

The country and continent codes are null, so a lapse never changes anyone's rules

Callers - the Odoo Host Manager's firewall above all - decide with those two fields, and every one of them already treats "no codes" as "this address cannot be placed, so do not act on it". A lapsed license therefore makes those callers fall back to the behaviour they already have when the databases are missing. It never starts blocking somebody's customers, and it never starts letting a blocked country through.

Inside the Odoo Host Manager​

When GeoIP runs as the ohm-geoip container, it is what the manager's country and continent firewall rules are matched against. Its licensing is sponsored by that product. How the rules use it, and that product's own editions, are in its manual: see Related.

When the manager's license stops carrying IP location data - a lower edition, or a subscription that ended - it withdraws the sponsorship. To this service that is a lapse like any other: every lookup is answered with the placeholder above, the databases on disk are kept and no longer refreshed. The manager offers the sponsorship again by itself when its license carries the data again. While the manager merely cannot reach its own license server, nothing is withdrawn.

Managing the license​

On the console's License page, or through GET/POST/DELETE /license and POST /license/activate.

A license installed or activated on the License page or through the API applies at once. A license that arrives by restoring a backup archive is the exception: the restore writes it to the license directory and tells you to restart the container, and it takes effect then. Everything else in that archive applies at once.

The start-up log says how the service is licensed: by its own license, sponsored by the product that offered it (a sponsorship is kept on the volume and holds across restarts), or running unlicensed with the reason - a sponsorship that no longer holds, or the last offer that was refused.

Last updated on