How to set up PHP-GeoIP with automatic database updates

Here is how to configure and setup automatic database updates for IPv4 and IPv6 to geographical location data with the free GeoLite2, GeoIP, service from MaxMind in Debian, Fedora Linux, and Ubuntu.

The GeoLite2 service provides free data for mapping IPv4 and IPv6 addresses to geographical locations. This service and an auto-update service is included in the package repository of all major Linux distributions, but the setup instructions vary a little for each distribution. Here are the complete steps for the most popular Linux distributions.

You can skip installing the php-geoip package, and the step adjusting php.ini file if you intend to use another GeoIP compatible implementation and just want to know how to configure geoipupdate.

Jump to instructions for Fedora Linux and derivatives or for Ubuntu, Debian, and derivatives.

Fedora Linux

Tested with Fedora Linux 24, 23, and 22.

Fedora Linux has already done almost all the work for you, and you just need to install a few extra configuration packages to get going.

  1. Install all the packages with the following command:
    dnf install geoipupdate geoipupdate-cron* php-pecl-geoip
  2. Run the geoipupdate program once to initiate the database. It will be kept updated by the cron jobs that were installed along with the package.
  3. Open /etc/php.ini for editing, and append the following at the bottom:
    geoip.custom_directory="/usr/share/GeoIP/"
  4. Restart the php-fpm, httpd, nginx, etc. services as necessary.

Ubuntu

Tested with Ubuntu 16.04 “Xenial Xerus” and Debian 8.5, but the below instructions may not work with older versions without making some adaptations because of packaging changes.

  1. Install all the packages with the following command:
    apt install geoipupdate geoip-database php-geoip
  2. Copy the sample GeoIP configuration file to your configuration directory:
    cp /usr/share/doc/geoipupdate/templates/GeoIP.conf.default /etc/GeoIP.conf
  3. Open /etc/GeoIP.conf for editing, and locate and adjust these three parameters:
    UserID 999999
    LicenseKey 000000000000
    ProductIds GeoLite2-City GeoLite2-Country GeoLite-Legacy-IPv6-City GeoLite-Legacy-IPv6-Country 506 517 533
    Pay attention to the quotation marks used, they’re significant for escape sequences.
  4. Run the geoipupdate program once to initiate the database.
  5. Install a weekly maintenance job for updating the databases in cron:
    echo -e '#!/bin/sh' "ngeoipupdate > /dev/null" > /etc/cron.weekly/geoipupdate
  6. Make the maintenance task executable:
    chmod +x  /etc/cron.weekly/geoipupdate
  7. Open /etc/php.ini for editing, and append the following at the bottom:
    geoip.custom_directory="/usr/share/GeoIP/"
  8. Restart the php-fpm, apache2, nginx, etc. services as necessary.

Make sure you meet the license and attribution requirements for using the GeoLite2 database. MaxMind uses a permissive Creative Commons Attribution-ShareAlike 4.0 International License for this data. You can consider upgrading to their paid GeoIP2 database if you need increased precision.

IP based location services may not be very accurate for IPv6 yet, but you should make sure to test that you’ve configured support for both IPv4 and IPv6 in your program. The above instructions should ensure that you’ve access to both IPv4 and IPv6 location databases, but supporting both my require additional implementation steps.