geoip - a tool to show geological data based on hostname or IP address(es)
geoip --help geoip --fetch [--no-update] geoip [options] host|IP ...
This tool uses a database to use the (pre-fetched) GeoIP2 data from MaxMind to show related geographical information for IP addresses. This information can optionally be extended with information from online WHOIS services and or derived data, like distance to the location of the server this tool runs on or a configured local location.
The output is plain text or JSON. JSON may be short or formatted.
The tool allows the use of configuration files. It tests for existence of the files listed here. All existing files is read (in this order) if it is only writable by the author
$home/geoip.rc $home/.geoiprc $home/.config/geoip
The format of the file is
# Comment ; Comment option : value option = value
where the : and = are equal and whitespace around them is optional and ignored. The values False and No (case insensitive) are the same as 0 and the values True and Yes are equal to 1. For readability you can prefix use_ to most options (it is ignored). The use of - in option names is allowed and will be translated to _.
:
=
False
No
0
True
Yes
1
use_
-
_
The recognized options and the command line equivalences are
command line option : -f or --fetch
-f
--fetch
default value : False
Fetch new databases from the MaxMind site.
command line option : -u or --update
-u
--update
default value : True
Only in effect when used with --fetch: when new data files from MaxMind have successfully been fetched and any of these is newer that what the database contains, update the database with the new data.
command line option : -d or --distance
-d
--distance
If both the location of the tool and the location of the requested IP are known, calculate the distance between them. The default is to show the distance in kilometers. Choosing a configuration of miles instead of True, Yes, or 1 will show the distance in miles. There is no command line option for miles.
miles
The location of the tool is either locally stored in your configuration (see --local-location) or fetched using the result of the urls iplocation.com or geoiptool. This will - of course - not work if there is no network connection or outside traffic is not allowed.
--local-location
iplocation.com
geoiptool
command line option : -w or --whois
-w
--whois
If Net::Whois::IP is installed, and this option is true, this module will be used to retrieve the whois information. This will not work if there is no network connection or outside traffic is not allowed.
whois
command line option : -s or --short
-s
--short
This option will disable the output of less-informative information like location, EU-membership, satellite and proxy. This option, if True, will also implicitly disable the distance and whois information.
distance
command line option : -Ddsn or --DB=dsn
-Ddsn
--DB=dsn
default value : $ENV{EOIP_DBI_DSN} or dbi:Pg:geoip
$ENV{EOIP_DBI_DSN}
dbi:Pg:geoip
See "DATABASE" for the (documented) list of supported database types.
If the connection works, the tables used by this tool will be created if not yet present.
The order of usage is:
1. Command line argument (C<--DB=dsn>) 2. The C<GEOIP_DBI_DSN> environment variable 3. The value for C<dsn> in the configuration file(s) 4. C<dbi:Pg:dbname=geoip>
command line option : -j or --json
-j
--json
The default output for the information is plain text. With this option, the output will be in JSON format. The default is not prettified.
command line option : -J or --json-pretty
-J
--json-pretty
If set from the command-line, this implies the --json option.
With this option, JSON output is done pretty (indented).
command line option : -l lat/lon or --local=lat/lon
-l lat/lon
--local=lat/lon
default value : Undefined
Sets the local location coordinates for use with distances.
When running the tool from a different location than where the IP access is to be analyzed for or when the network connection will not report a location that would make sense (like working from a cloud or running over one or more VPN connections), one can set the location of the base in decimal notation. (degree-minute-second-notation is not yet supported).
This is also useful when there is no outbound connection possible or when you do not move location and you want to restrict network requests.
The notation is decimal (with a ., no localization support) where latitude and longitude are separated by a / or a ,, like -l 12.345678/-9.876543 or --local=12,3456,45,6789.
.
/
,
-l 12.345678/-9.876543
--local=12,3456,45,6789
command line option : none
Currently not (yet) used. Documentation only.
As downloads are only allowed/possible using a valid MaxMind account, you need to provide a valid license key in your configuration file. If you do not have an account, you can sign up here.
Currently PostgreSQL and SQLite have been tested, but others may (or may not) work just as well. YMMV. Note that the database need to know the CIDR field type and is able to put a primary key on it.
CIDR
MariaDB and MySQL are not supported, as they do not support the concept of CIDR type fields.
The advantage of PostgreSQL over SQLite is that you can use it with multiple users at the same time, and that you can share the database with other hosts on the same network behind a firewall.
The advantage of SQLite over PostgreSQL is that it is a single file that you can copy or move to your liking. This file will be somewhere around 500 Mb.
$ cat ~/.config/geoip use_distance : True json-pretty : yes
$ geoip --short 1.2.3.4
$ geoip --json --no-json-pretty 1.2.3.4
$ geoip --dist --whois 1.2.3.4
The ZIP files also contain IPv6 information, but it is not (yet) converted to the database, nor supported in analysis.
Split up the different parts of the script to modules: fetch, extract, check, database, external tools, reporting.
Turn this into something like App::geoip, complete with Makefile.PL
DBI, Net::CIDR, Math::Trig, LWP::Simple, Archive::ZIP, Text::CSV_XS, JSON::PP, GIS::Distance, Net::Whois::IP, HTML::TreeBuilder, Data::Dumper, Data::Peek, Socket
Geo::Coder::HostIP, Geo::IP, Geo::IP2Location, Geo::IP2Proxy, Geo::IP6, Geo::IPfree, Geo::IP::RU::IpGeoBase, IP::Country, IP::Country::DB_File, IP::Country::DNSBL, IP::Info, IP::Location, IP::QQWry, IP::World, Metabrik::Lookup::Iplocation, Pcore::GeoIP
Check CPAN for more.
Thanks to cavac for the inspiration
H.Merijn Brand <h.m.brand@xs4all.nl>, aka Tux.
The GeoLite2 end-user license agreement, which incorporates components of the Creative Commons Attribution-ShareAlike 4.0 International License 1) can be found here 2). The attribution requirement may be met by including the following in all advertising and documentation mentioning features of or use of this database.
This tool uses, but does not include, the GeoLite2 data created by MaxMind, available from [http://www.maxmind.com](http://www.maxmind.com).
Copyright (C) 2018-2020 H.Merijn Brand. All rights reserved.
This library is free software; you can redistribute and/or modify it under the same terms as Perl itself. See https://opensource.org/licenses/Artistic-2.0|here 3).
1) https://creativecommons.org/licenses/by-sa/4.0/ 2) https://www.maxmind.com/en/geolite2/eula 3) https://opensource.org/licenses/Artistic-2.0
To install App::geoip, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::geoip
CPAN shell
perl -MCPAN -e shell install App::geoip
For more information on module installation, please visit the detailed CPAN module installation guide.