ContextQMD
Back to Ntopng

README.Geolocation

doc/README.geolocation.md

6.65.2 KB
Original Source

Introduction

ntopng includes Geolocation support provided by the following companies

ntopng geolocation is based on a database file stored locally with no cloud access whatsoever.

You can choose to install the free (albeit not very accurate) GeoIP databases or the commercial ones. By default the ntopng-data includes the DB-IP databases that are released under the Creative Commons Attribution License.

Please install the ntopng-data package to enable geolocation in ntopng, this unless you already have geolocation databases installed.

Using MaxMind geolocation in ntopng

New privacy regulations, such as GDPR and CCPA, place restrictions that impact our ability to continue distributing MaxMind GeoLite2 databases in the public ntopng-data package. Reasons are explained in detail at the following page https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/.

Starting December 30, 2019, to continue using geolocation in ntop software, you are required to register for a MaxMind account and obtain a license key in order to download GeoLite2 geolocation databases.

The following section lists all the steps which are necessary to use geolocation in ntopng.

  1. Install package ntopng-data which pulls in MaxMind downloader geoipupdate as dependency.
  2. Register for a MaxMind account at https://www.maxmind.com/en/geolite2/signup.
  3. Create a license key at https://www.maxmind.com/en/accounts/current/license-key.
    1. Select "Generate New License Key".
    2. Add a license key description and answer "Yes" to the question "Will this key be used for GeoIP Update?".
    3. Then choose one of the two available options "Generate a license key and config file". Choice depends on the installed geoipupdate version. Most likely, installed version is older than 3.1.1 so the correct option to select is "Generate a license key and config file for use with geoipupdate versions older than 3.1.1". If you don't know the version type geoipupdate -V.
  4. Once the license is created, you will be promted to download file GeoIP.conf which contains account id and license key necessary to download the databases. Download and place this file in /etc/GeoIP.conf.
  5. Make sure that the EditionIDs section (or ProductIds according to the geoipupdate version) in /etc/GeoIP.conf contains GeoLite2-Country GeoLite2-City GeoLite2-ASN (GeoLite2-ASN could be missing by default).
  6. Run sudo geoipupdate to download the database files.
  7. Restart any running ntop software. Upon restart, software will automatically locate and load the downloaded databases.

Subsequent updates of the ntopng-data package will check for the availability of newer geolocation databases and will possibly update them automatically.

If you prefer to handle updates manually, you may skip ntopng-data installation and direcly use geoipupdate. Instructions to use geoipupdate are available at https://dev.maxmind.com/geoip/geoipupdate/

Using geolocation on Raspberry Pi OS (Raspbian)

Since the geoipupdate package is not available on Raspberry Pi, the MaxMind database should be downloaded and installed manually on this platform. Please check the next section for further instructions.

How to use MaxMind instead of DB-IP ?

The simplest solution is to install ntopng-data. However if this is not possible please do (as root):

  • sudo su
  • cd /usr/share/ntopng/httpdocs/geoip/
  • mkdir backup
  • mv *mmdb backup
  • ln -s /var/lib/GeoIP/GeoLite2-City.mmdb .
  • ln -s /var/lib/GeoIP/GeoLite2-ASN.mmdb .
  • service ntopng restart

Using geolocation when ntopng-data is not available

In case package ntopng-data or geoipupdate is not available on your platform:

  1. Manually download database files

    • DB-IP: dbip-city-lite, dbip-asn-lite, and dbip-country-lite (https://db-ip.com/db/) databases in MMDB format
    • MaxMind: GeoLite2-ASN.mmdb and GeoLite2-City.mmdb from the "GeoIP2 / GeoLite2" > "Download Files" section of your MaxMind account page

  2. Then place the downloaded files under a specifiy folder which depends on the platform:

    • Linux (including Raspberry Pi OS): place downloaded files under /var/lib/GeoIP/ (/usr/share/GeoIP/ is also a valid path)
    • Windows: place downloaded files under Program Files/ntopng/httpdocs/geoip/
    • OS X package: place downloaded files under /usr/local/share/ntopng/httpdocs/geoip (in case the geoip folder is missing, it is necessary to create it with mkdir -p /usr/local/share/ntopng/httpdocs/geoip before copying the files)

Upgrading from a previous version of ntopng-data

In case an old ntopng-data package was already installed in the system, you may receive the message The following packages have been kept back with reference to it.

# sudo apt-get update
[...]
Calculating upgrade... Done
The following packages have been kept back:
  ntopng-data

This occurs usually on debian because the dependencies have changed on the ntopng-data you have installed so that a the package geoipupdate from MaxMind must be installed to perform the upgrade. If this case, to resolve it suffices to run

sudo apt-get --with-new-pkgs upgrade