.\" Copyright (c) 2022, Peter Haag
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\"  * Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"  * Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"  * Neither the name of the author nor the names of its contributors may be
.\"    used to endorse or promote products derived from this software without
.\"    specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate$
.Dt GEOLOOKUP 1
.Os
.Sh NAME
.Nm geolookup
.Nd geo location lookup for IP addresses
.Sh SYNOPSIS
.Nm 
.Op Fl G Ar geofile
.Ar iplist
.Nm
.Fl d Ar directory
.Fl w Ar geofile
.Sh DESCRIPTION
.Nm 
is a tool to lookup AS and geo location information of one or more IP addresses. You need
to create a lookup database first, in order to use
.Nm
.Pp
.Nm
is also used to create the nfdump formatted lookup database file from the maxmind csv files.
You need to have a maxmind account at https://maxmind.com, in order to download the relevant
csv file. See below for building instructions.
.Pp
.Nm
accepts a list of IP addresses either on the command line, separated by spaces
or on
.Ar stdin
line by line. The IP address on each line can be embedded in a string separated be
spaces on the left and right, therefore it can read the piped output from another tool.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d Ar directory
Use the csv files in 
.Ar directory
to build the binary lookup database file. With this argument
.Nm
creates a new binary lookup database file.
.It Fl w Ar geofile
Name of the new lookup database file.
.It Fl G Ar geofile
Use the binary geofile as lookup database for the current AS and location lookups.
.El
.Pp
To specify the geo lookup database 
.Nm
searches at the following places:
.Bl -bullet -compact
.It
If the default
.Ar nfdump(1)
configuration file exists, it reads the tag
.Ar geodb.path
.It
If the environment variable
.Ar NFGEODB
is set, use this setting as lookup database.
.It
The command line argument
.Fl G
.El
If multiple locations are given, the environment variable
.Ar NFGEODB
overwrites the nfdump config file and the command line option
.Fl G
overwrites the environment variable
.Ar NFGEODB .
.Sh RETURN VALUES
.Nm
returns 0 on success and 255 otherwise.
.Sh ENVIRONMENT
.Nm
reads the environment variable
.Ar NFGEODB
.Sh EXAMPLES
To create a lookup database, you need an account at
.Ar https://maxmind.com.
It works with the paid GeoDB as well as with the free GeoLite2 csv files. The easiest way for creating or 
updating the binary lookup database is the use of the script
.Ar updateGeoDB.sh
provided with all other nfdump files. Insert your license key and run the script. This creates a new lookup databse.
.Pp
If you want to do it manually follow these steps:
.Bl -enum -compact
.It
Log into https://maxmind.com and download the corresponding csv files: GeoLite2-ASN-CSV and GeoLite2-City-CSV
.It
Unpack the zip files and put the following csv files into a newly created build directory:
GeoLite2-ASN-Blocks-IPv4.csv, GeoLite2-ASN-Blocks-IPv6.csv, GeoLite2-City-Blocks-IPv4.csv, GeoLite2-City-Blocks-IPv6.csv, GeoLite2-City-Locations-en.csv
Maxmind offeres several languages for the City-Locations file. Choose only one.
.It
.Nm
.Fl d Ar builddir Fl w Ar geofile
.It 
Move the lookup database to the final location.
.El
.Sh SEE ALSO
.Ar nfdump
has already builtin lookup options to decorate the text output with geo location and AS information.
.Pp
.Xr nfdump 1