Written documentation about MaxMind GeoIP service upgrade.

(Redmine issue: #6157)

doc/sphinx/_doclib/upgrading.rst

@@ -294,6 +294,83 @@ After these steps it is necessary to update following configuration files:
     ``"db_path": "/var/lib/postgresql/12/main",``
 
 
+.. _section-upgrading-geoip:
+
+Upgrading to authenticated version of GeoIP service
+--------------------------------------------------------------------------------
+
+Since 30.12.2019 the `MaxMind <https://www.maxmind.com/en/home>`__ IP geolocation
+service  `changed significantly <https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/>`__
+its access policies for downloading free versions of IP geolocation databases.
+These
+
+Following actions are necessary to make event enrichment with IP geolocation data
+working again:
+
+#. `Create free MaxMind account and generate access key <https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/>`__. Make sure to generate the key usable with GeoIP Update protocol, you will be asked for this during key creation process.
+#. Install and configure the `geoipupdate <https://github.com/maxmind/geoipupdate/releases>`__ program. Keep the default database directory pointed at ``/usr/share/GeoIP/``. This path will be preconfigured as default in Mentat system.
+#. Execute the `geoipupdate <https://github.com/maxmind/geoipupdate>`__ to fetch latest database.
+#. Upgrade to Mentat system version ``2.6.x`` and review all default configuration file changes. The changes occured in ``/etc/mentat/mentat-controller.py.conf`` and ``/etc/mentat/core/services.json.conf`` configuration files.
+#. Restart Mentat system:
+
+.. code-block:: shell
+
+    $ mentat-controller.py --command stop
+    $ mentat-controller.py --command start
+    $ mentat-controller.py --command enable
+    $ systemctl restart apache2
+
+#. Finally make sure all obsolete files are gone:
+
+.. code-block:: shell
+
+    rm /etc/cron.d/fetch-geoipdb-sh
+    rm /etc/mentat/cron/fetch-geoipdb-sh.cron
+    rm /etc/mentat/scripts/fetch-geoipdb.sh
+
+If you are reading this before Mentat version ``2.6.x`` is released follow steps 
+described above and in step 4 please make following patches:
+
+.. code-block:: shell
+
+    diff --git a/conf/mentat-controller.py.conf b/conf/mentat-controller.py.conf
+    index 493903e2..4e454073 100644
+    --- a/conf/mentat-controller.py.conf
+    +++ b/conf/mentat-controller.py.conf
+    @@ -134,7 +134,7 @@
+             { "name": "mentat-cleanup-py" },
+     
+             # Utility for fetching current versions of IP geolocation databases.
+    -        { "name": "fetch-geoipdb-sh" },
+    +        { "name": "geoipupdate" },
+     
+             # Provide periodical informational report emails about overall performance of Mentat system.
+             { "name": "mentat-informant-py" },
+
+    diff --git a/conf/core/services.json.conf b/conf/core/services.json.conf
+    index 81988e55..ca38cdba 100644
+    --- a/conf/core/services.json.conf
+    +++ b/conf/core/services.json.conf
+    @@ -25,9 +25,9 @@
+             # GeoIP service settings.
+             #
+             "geoip": {
+    -            "asndb": "/var/opt/opensourcedbs/GeoLite2-ASN.mmdb",
+    -            "citydb": "/var/opt/opensourcedbs/GeoLite2-City.mmdb"
+    -            #"countrydb": "/var/opt/opensourcedbs/GeoLite2-Country.mmdb"
+    +            "asndb": "/usr/share/GeoIP/GeoLite2-ASN.mmdb",
+    +            "citydb": "/usr/share/GeoIP/GeoLite2-City.mmdb"
+    +            #"countrydb": "/usr/share/GeoIP/GeoLite2-Country.mmdb"
+             },
+
+Then create new crontab file called ``/etc/mentat/cron/geoipupdate.cron`` with contents
+similar to these:
+
+.. code-block:: shell
+
+    0 6 * * 3   root /usr/bin/geoipupdate
+
+
 .. _section-upgrading-debian:
 
 Upgrading underlying Debian system