.. _Geolocation: Geolocation =========== Introduction ------------ ntopng includes Geolocation support provided by the following companies - `MaxMind `_ - `DB-IP `_ 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. #. Install package ``ntopng-data`` which pulls in MaxMind downloader ``geoipupdate`` as dependency. #. Register for a MaxMind account at https://www.maxmind.com/en/geolite2/signup. #. Create a license key at https://www.maxmind.com/en/accounts/current/license-key. #. Select "Generate New License Key". #. Add a license key description and answer "Yes" to the question "Will this key be used for GeoIP Update?". #. 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``. #. Once the license is created, you will be prompted 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``. #. 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). #. Run ``sudo geoipupdate`` to download the database files. #. 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 directly 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): .. code-block:: shell 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: #. 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 #. Then place the downloaded files under a specific 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. .. code-block:: text # 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 the package ``geoipupdate`` from MaxMind must be installed to perform the upgrade. If this is the case, to resolve it suffices to run .. code-block:: shell sudo apt-get --with-new-pkgs upgrade