The geolocation functions allow you to identify the country where
the given IP address or host name is located. These functions are
available only if the libmaxminddb
library is installed and
mailfromd
is compiled with the ‘GeoIP2’ support.
The libmaxminddb
library is distributed by ‘MaxMind’ under
the terms of the Apache License Version 2.0. It is available
from https://dev.maxmind.com/geoip/geoip2/downloadable/#MaxMind_APIs.
Historically, mailfromd
supports also the legacy
‘GeoIP’ library. If you are interested in it, please refer to
Legacy geoip support.
Opens the geolocation database file filename. The database must be in GeoIP2 format.
If the database cannot be opened, geoip2_open
throws the
e_failure
exception.
If this function is not called, geolocation functions described below will try to open the database file ‘/usr/share/GeoIP/GeoLite2-City.mmdb’.
Returns the name of the geolocation database currently in use.
The geolocation database for each IP address, which serves as a look up key, stores a set of items describing this IP. This set is organized as a map of key-value pairs. Each key is a string value. A value can be a scalar, another map or array of values. Using JSON notation, the result of a look up in the database might look as:
{ "country":{ "geoname_id":2921044, "iso_code":"DE", "names":{ "en": "Germany", "de": "Deutschland", "fr":"Allemagne" }, }, "continent":{ "code":"EU", "geoname_id":6255148, "names":{ "en":"Europe", "de":"Europa", "fr":"Europe" } }, "location":{ "accuracy_radius":200, "latitude":49.4478, "longitude":11.0683, "time_zone":"Europe/Berlin" }, "city":{ "geoname_id":2861650, "names":{ "en":"Nuremberg", "de":"Nürnberg", "fr":"Nuremberg" } }, "subdivisions":[{ "geoname_id":2951839, "iso_code":"BY", "names":{ "en":"Bavaria", "de":"Bayern", "fr":"Bavière" } } }
Each particular data item in such structure is identified by its
search path, which is a dot-delimited list of key names leading
to that value. For example, using the above map, the name of the city
in English can be retrieved using the key city.names.en
.
Looks up the IP address ip in the geolocation database. If found, returns data item identified by the search path path.
The function can throw the following exceptions:
The ip was not found in the database.
The path does not exist the returned map.
General error occurred. E.g. the database cannot be opened, ip is not a valid IP address, etc.
Looks up the ip in the database and returns entire data set associated with it, formatted as a JSON object. If the optional parameter indent is supplied and is greater than zero, it gives the indentation for each nesting level in the JSON object.
Applications may test whether the GeoIP2 support is present and
enable the corresponding code blocks conditionally, by testing if
the ‘WITH_GEOIP2’ m4 macro is defined. For example, the
following code adds to the message the ‘X-Originator-Country’
header, containing the 2 letter code of the country where the client
machine is located. If mailfromd
is compiled without
‘GeoIP’ support, it does nothing:
m4_ifdef(`WITH_GEOIP2',` try do header_add("X-Originator-Country", geoip2_get($client_addr, 'country.iso_code')) done catch e_not_found or e_range do pass done ')
For compatibility with older releases, mailfromd
supports
the legacy ‘GeoIP’ library. This support is going to be removed
in the next release, so its use is not recommended. Please use
‘GeoIP2’ instead.
The support for the legacy GeoIP library is available if
mailfromd
is compiled with the ‘GeoIP’ support (the
--with-geoip configure option). The m4
macro
‘WITH_GEOIP’ is defined if it is so.
The legacy GeoIP is distributed by ‘MaxMind’ under the terms of the GNU Lesser General Public License. The library is available from http://www.maxmind.com/app/c.
Look up the ‘ISO 3166-1’ country code corresponding to the IP address ip. If tlc is given and is not zero, return the 3 letter code, otherwise return the 2 letter code.
Look up the ‘ISO 3166-1’ country code corresponding to the host name name. If tlc is given and is not zero, return the 3 letter code, otherwise return the 2 letter code.
If it is impossible to locate the country, both functions raise the
e_not_found
exception. If an error internal to the
‘GeoIP’ library occurs, they raise the e_failure
exception.
Applications may test whether the GeoIP support is present and
enable corresponding code blocks conditionally, by testing if
the ‘WITH_GEOIP’ m4 macro is defined. For example, the
following code adds to the message the ‘X-Originator-Country’
header, containing the 2 letter code of the country where the client
machine is located. If mailfromd
is compiled without
‘GeoIP’ support, it does nothing:
m4_ifdef(`WITH_GEOIP',` header_add("X-Originator-Country", geoip_country_code_by_addr($client_addr)) ')
This document was generated on August 13, 2022 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.