Geo2IPAD Conversion Tool
------------------------

This is a Windows command line program to create the GEOLOC.DAT file for
use with IPAD-OS 7.0 or newer to block unwanted email sources using country
codes. It combines all IPV4 information into a master list and all adjacent
address blocks assigned to the same country are consolidated both for size
and for higher performance on the IPAD-OS mail server.

The GeoIP information can come from several different public or commercial
sources. See the "Where To Get Data" section at the end of this document.

Note: mail filtering based on country code requires IPAD-OS 7.0 or newer.

Syntax:

 GEO2IPAD [<input_file>] [/C] [/D] [/F] [/R] [/?]

 input_file = This is an optional input file name. The file must be either
        in ARIN format or MaxMind format. If no input file name is given,
        the default is to look for files named "delegated-*-latest" in the
        current directory. See the "Where To Get Data" section below.

   /C = Create a file with just the list of known country codes. The output
        file is named COUNTRY.LST and is the same information shown on the
        first line of the GEOLOC.DAT file. This option exists because it is
        sometimes easier for automated tools to include a whole file than a
        single line from a larger file.

        If the COUNTRY.LST file exists, it is checked even if the /C switch
        is not used. This allows you to notice when the country code list
        changes and update your DNSBL.CTL file.

   /D = Debug mode. This exposes the internal workings of the program to
        help locate problems. It is not suggested to use this optional
        command line switch unless you are gathering data for a bug report.

   /F = Not every IP address is assigned. This command line option creates
        a filler block of addresses for every gap. The country code given
        to every gap is "00" (zero zero) so it is easy to spot.

        WARNING! FILTERING BASED ON THE DOUBLE-ZERO CODE IS BAD!

        Never make a filter based only on unknown IP address assignment.
        This option is designed to help the IPAD-OS log files show when
        your Geo database may be out of date.

   /R = There are several blocks of IP addresses that do not appear in any
        geographic IP address database because they are assigned by RFC,
        not by ARIN. This optional command line switch adds these address
        blocks to the output file with appropriate names like "LOCAL",
        "LOOPBACK" and "PRIVATE".

        WARNING! FILTERING BASED ON THE RFC ADDRESS CODE IS BAD!

        Never make a filter based only on RFC IP address assignment.
        This option allows the IPAD-OS log files show extra information
        that may be useful to you.

   /X = Suppress the country code comment line at top of the output file.
        This creates a GEOLOC.DAT file for use outside the IPAD-OS.

   /? = Display the internal command line help information.


OUTPUT FILE NAME - GEOLOC.DAT

 The output is always written to a file named GEOLOC.DAT and this file must
 be put into the C:\IPAD directory with the IPAD.EXE kernel. The IPAD-OS
 automatically notices whenever a new GEOLOC.DAT file appears and updates
 the database used by the mail server. There is no need to reboot the
 IPAD-OS kernel to update the GEOLOC.DAT file.

 The first line at the top of the default GEOLOC.DAT file is a comment that
 holds a complete list of every country code found in the current database.
 It is a good idea to copy this line to your DNSBL.CTL file for use later.
 You may optionally use the /C command line switch to create this list in a
 file named COUNTRY.LST to make it easier to include into other files.

 The country code list is a good reference for anyone that wants to create
 "negative" blocking where everything is blocked except for a few country
 codes. The negative blocking is accomplished by copying the full list of
 country codes and selectively removing the allowed countries for each user
 that wants this kind of extreme filtering. For example, you can block mail
 to a single user from all countries except for the USA and Canada by
 pasting the full list of country codes and removing "US" and "CA".

 Remember that no spaces are allowed in the list of country codes in the
 DNSBL.CTL file.

 Because it is a very bad idea to filter based on unknown address blocks or
 address blocks assigned by RFC, those codes are never included in the
 comment line. If you feel the need to filter these codes it is a sign you
 should update your database or find a more complete data source.

 The rest of the GEOLOC.DAT file has the following format.

 <starting_IP_address>|<ending_IP_address>|<name>

 The starting and ending IP addresses may be given in dotted notation,
 32-bit decimal notation or in hexadecimal notation. The hexadecimal
 notation requires a "0x" (zero-x) prefix. The name is typically a two
 character country code, but may be any code you need. Shorter codes are
 always more efficient for the mail server. The fields are delimited with a
 vertical bar character which is found on the same key with the back slash
 on English keyboards.

 It is very important the GEOLOC.DAT file never contain overlapping address
 blocks. The GEO2IPAD program does everything it can to remove or resize
 blocks to prevent any potential overlap. This filtering includes removing
 duplicate address blocks and combining contiguous address blocks for the
 same country. There is no way to prevent overlap and still retain 100% of
 the source data when two or more different country blocks overlap. The
 address block with the lower IP address is always given preference.
 This is simply the most direct way to avoid the overlap problem.

WHERE TO GET DATA

 Start with the DOWNLOAD.BAT file described below. It uses the DOWNLOAD.TXT
 script file (also described below) to get the latest ARIN information and
 compile it into IPAD-OS format. This can be used on a weekly or monthly
 schedule to ensure your geographic IP information is always current.

 ARIN

 It is best to start with the American Registry for Internet Numbers (ARIN)
 source files for testing. These files come from public sources that are
 updated on a regular basis. You may download new copies of the files
 repeatedly without penalty.

 Look for files named "delegated-*-latest" in any directory found on the
 "ftp://ftp.arin.net/pub/stats/" site. The following is a list of the
 files as of the writing of this document.

        ftp://ftp.arin.net/pub/stats/afrinic/delegated-afrinic-latest
        ftp://ftp.arin.net/pub/stats/apnic/delegated-apnic-latest
        ftp://ftp.arin.net/pub/stats/arin/delegated-arin-latest
        ftp://ftp.arin.net/pub/stats/lacnic/delegated-lacnic-latest
        ftp://ftp.arin.net/pub/stats/ripencc/delegated-ripencc-latest

 You can use any scriptable FTP client to automate the download of these
 files if needed. An example DOWNLOAD.BAT is described below.

 MAXMIND

 The MaxMind database comes from a combination of public and private
 sources which is why their database has a restricted license. Please note
 the GeoIPCountry.csv or GeoIPCountryWhois.csv source files come in two
 versions, a free "lite" version and a more complete commercial version.
 Both are available from the MaxMind (http://www.maxmind.com/) web site.

 The free "lite" version can be downloaded from the following URL, but be
 aware that you may only be allowed a limited number of downloads.
 Do not abuse this free service!

            http://geolite.maxmind.com/download/geoip/database/

 Only the IPV4 versions (the files without IPV6 in the name) are compatible
 with this program and IPAD-OS country code filtering.

 OTHER SOURCES

 If you find a source for Geographic IP Address information that is not
 published in ARIN or MAXMIND format, please contact the IFX Group through
 our web site so we can update this program to support the new format.

NOTES

 The free databases from either ARIN or MaxMind have enough country
 information for most IPAD-OS mail server filtering and reporting needs.
 Try these first before you consider buying or subscribing to the
 commercial list.

SCRIPTED DOWNLOADS

 The following two files can be used to automatically download updates to
 the geographic IP address source information from the ARIN server. The
 first file is a script for the command line FTP program included with all
 versions of Microsoft Windows. The second is a batch file that calls the
 FTP script followed by the GEO2IPAD program.

--[DOWNLOAD.TXT]---------------------------------------------------------------
anonymous
user@example.com
binary
get /pub/stats/afrinic/delegated-afrinic-latest
get /pub/stats/apnic/delegated-apnic-latest
get /pub/stats/arin/delegated-arin-latest
get /pub/stats/lacnic/delegated-lacnic-latest
get /pub/stats/ripencc/delegated-ripencc-latest
bye
-------------------------------------------------------------------------------


--[DOWNLOAD.BAT]---------------------------------------------------------------
:: Download fresh copies of the source data files
FTP -i -s:download.txt ftp.arin.net
:: Compile the data into IPAD-OS format
GEO2IPAD
-------------------------------------------------------------------------------


 The fully commented PowerBASIC/CC source code for GEO2IPAD is included
 with this program to show exactly how it works.

 The latest version of this program is on the WWW.IFXGROUP.NET web site.

Copyright 2009-2010 Casey Sprangel.
