This is open source software for running a simple UDP server that provides geolocations for IP addresses. A request packet incoming to the server will contain an IP address, and the response packet outgoing from the server will contain a country code, country name, region, city, latitude, and longitude for the IP address.
This software is distributed under a BSD-style license.
Here are some selling points of this software:
Drawbacks of using this software:
Please refer to the protocol for an explanation of the functionality that this server has to offer.
To get the source code and documentation for the ip2loc server:
rambetter@porky# svn checkout svn://svn.clanwtf.net/repos/ip2loc ./ip2loc
The most recent version of this HTML document that you are now reading is available as
./ip2loc/README.html .
Once you have the source code downloaded, the next step is to compile:
rambetter@porky# cd ./ip2loc/ rambetter@porky# make
This will generate two executables, ip2loc-server and ip2loc-csv-parser . You
will need both of these programs.
To run the ip2loc server, you need to get your hands on some proprietary data that is provided by the company IP2Location(TM). The exact product that you need from them is DB5 (link here).
DB5 is downloaded as a ZIP archive named IP-COUNTRY-REGION-CITY-LATITUDE-LONGITUDE-FULL.ZIP .
Inside this archive is a file named IP-COUNTRY-REGION-CITY-LATITUDE-LONGITUDE.CSV . This
CSV file is the only file that we need. Uncompressed, the CSV file is approximately 250 megabytes in size.
Fortunately, it is a file consisting of plain text, and it compresses pretty well (the ZIP file distributable
is just under 40 megabytes in size).
The IP2Location(TM) proprietary IP-to-location data is updated once a month, at the beginning of each month. Usually, you buy a one-year subscription to DB5 for about $350, then download the updated data at the beginning of each month from IP2Location(TM).
Note that it is possible to find this IP2Location(TM) DB5 product using torrents. However, acquiring the proprietary data in this fashion is not lawful and such activity is not endorsed by the author.
We now need to "compile" the IP-COUNTRY-REGION-CITY-LATITUDE-LONGITUDE.CSV file to a much more
compact custom format that is needed to run the ip2loc server. To do this, we use the
ip2loc-csv-parser command. This command is very simple: it takes no command-line arguments,
reads the CSV file from standard input, and writes a compiled version of the database to standard output.
Any parsing errors are displayed on standard error. Usually, you'll want to save the compiled
IP-to-location database to a file named ip2loc.bin . To sum up, we run a command such as this:
rambetter@porky# cat IP-COUNTRY-REGION-CITY-LATITUDE-LONGITUDE.CSV | ./ip2loc-csv-parser > ip2loc.bin
The generated ip2loc.bin file will be about 20 megabytes in size. You will need this file to
run the ip2loc server, so keep it handy. The ip2loc.bin file compresses to about 10 megabytes using
standard compression tools such as gzip . You may consider storing it compressed if disk usage is
an issue, in which case you'll want to gunzip the file on-the-fly when you need to use it later on.
The executable to launch the server process is ip2loc-server . You can run
this binary with no arguments to get a better idea of how to use it:
rambetter@porky# ./ip2loc-server Usage: ./ip2loc-server <listen-port> <listen-IP> The second argument, the IP address to listen on, can be omitted, in which case the server will listen on all available interfaces. This program reads standard input, which should be the contents of an "ip2loc.bin" file. A file in the current directory named ".password" will be read, which should consist of a single line of text specifying the password that the server will be protected by.
So, to run the server, we'll do something like this:
rambetter@porky# echo "pa55w0rd" > .password rambetter@porky# cat ip2loc.bin | ./ip2loc-server 10020 127.0.0.1
Note that the server process runs in the foreground. If you want to launch the server in your shell and
then leave the server running after logging out of your shell,
you'll need to either use a tool such as screen
or use a utility such as /usr/sbin/daemon on FreeBSD to launch the server process. Also, you
probably want to pipe standard error to a log file. Nothing on standard out will be generated by the server
program.
This section describes the communication over network UDP that happens with the ip2loc server.
The country code, country, region, and city strings will always consist of ASCII text (punctuation characters such as commas may be present). These strings will never contain the double quote character '"' or the newline character '\n'. Also, no lowercase letters ('a' through 'z') will be present in the strings.
A request to the ip2loc server looks like this (over UDP):
ip2locRequest pa55w0rd getLocationForIP 64.156.193.115
The lines of text in the request are separated by a single newline character. There must be a trailing newline
after the IP address. The second line must match the contents of the .password file exactly, and the last
line is the IP address to be queried.
A response looks like this:
ip2locResponse getLocationForIP 64.156.193.115 US UNITED STATES CALIFORNIA SAN DIEGO 32.7473 -117.148
Here, "US" is the country code, "UNITED STATES" is the country, "CALIFORNIA" is the region, and "SAN DIEGO" is the city. The second to last line is the latitude and the last line is the longitude. It may happen that some of the values for country code, country, region, and city will not be present. If that is the case, they will appear as blank lines. The lines of the response packet are separated by a single newline character. The last line is terminated by a newline character.
If the password is incorrect or if the request packet is malformed in some other way, the server will silently drop the packet without sending a response of any kind.
A request to the ip2loc server looks like this (over UDP):
@@@@ip2locRequest pa55w0rd getLocationForIP 64.156.193.115
@@@@
If the request is well-formed and if the password is correct, the server will respond with a UDP packet that looks like this:
@@@@ip2LocResponse "getLocationForIP" "64.156.193.115" "US" "UNITED STATES" "CALIFORNIA" "SAN DIEGO" "32.7473" "-117.148"
The response does not have a trailing newline.
You can shut down the ip2loc server process by sending a "quit" request. However, this request must be sent on the loopback (127.0.0.1) interface. If the ip2loc server is not listening on the loopback interface, the packet must be sent from an IP address that is local.
ip2locRequest pa55w0rd quit
No response is returned for this type of packet.