This document covers updating the built-in GeoIP database. See TechTip: Extending the Pulse vTM GeoIP database for instructions on adding custom entries to the database.
Pulse Secure vTM GeoIP Update package
Pulse Secure now provides a GeoIP Update package, available in the Related Software section of the http://my.pulsesecure.net portal. This package is updated whenever a new release of the traffic manager is made, and its version number can be compared with the GeoIP database version in $ZEUSHOME/zxtm/etc/geo/version. To use this update package:
- Download the GeoIP Update by logging in to http://my.pulsesecure.net and searching for "Pulse Secure Virtual Traffic Manager GeoIP Update". This will find a file with a description such as "Pulse Secure Virtual Traffic Manager GeoIP Update 20180905" and filename
geoip_update_20180905.tgz
- Upload the package to the target vTM instance (System > Traffic Managers > Upgrade).
- Select "Upgrade specified traffic managers".
- Select the traffic manager you are logged in to.
- Click 'Upgrade'. vTM applies the update to the traffic manager and restarts.
- Check the error log for any problems with the upgrade.
- Repeat 2-5 for other cluster members.
Updates dated 2020-05-19 or later include the GeoIP data for IPv6 geo-location. These update packages are compatible with all versions of the Traffic Manager, but only versions 20.2 or better can carry out IPv6 geo-location.
If you upgrade to a new version of the Traffic Manager it will switch to the GeoIP database version included in that version of the Traffic Manager. If you had previously updated to a later version of the database you will need to reapply the GeoIP update.
Using the MaxMind GeoIP2 City database
The GeoIP database shipped with Pulse Secure vTM is based on the MaxMind GeoLite2 City database. MaxMind also produce a commercially licensed database of IPv4 locations, GeoIP2 City, which is more detailed. You can switch to this database If you are using version 18.3 or later, or one of the LTS releases 17.2r3 or later, or 18.2r1 or later.
The following process for this can also be used to switch to a newer version of the GeoLite2 City database, if you require a more recent version than is available on the https://my.pulsesecure.net portal.
First take a copy of the folder $ZEUSHOME/zxtm/etc/geo and the file $ZEUSHOME/zxtmadmin/lib/perl/Zeus/ZXTM/CountryData.pm.
You can switch back to to original GeoIP database by restoring these and restarting the traffic manager.
- Download the "GeoIP2-City-CSV" version of the GeoIP2 City database.
- Unzip the resulting archive. This will create a folder such as GeoIP2-City-CSV_20181204 containing CSV files with names like GeoIP2-City-Blocks-IPv4.csv and GeoIP2-City-Locations-en.csv. The location data is supplied in several languages and you can use whichever of the locale-specific location files you choose.
- Run the conversion script, specifying paths to the 2 CSV files in the order: locations file, blocks file e.g:
$ZEUSHOME/zxtm/bin/process_geoip.pl \
GeoIP2-City-CSV_20181204/GeoIP2-City-Locations-en.csv \
GeoIP2-City-CSV_20181204/GeoIP2-City-Blocks-IPv4.csv \
GeoIP2-City-CSV_20181204/GeoLite2-City-Blocks-IPv6.csv
- This can take several minutes to complete and will create a folder called output_en containing:
- CountryData.pm
- base_locations.txt
- country_codes.txt
- ip-to-location.bin
- ipv6-to-location.bin
- region_codes.txt
If you select the locations file for a different locale, the output directory will be named appropriately.
- Overwrite $ZEUSHOME/zxtmadmin/lib/perl/Zeus/ZXTM/CountryData.pm
with a copy of CountryData.pm if they differ.
- Replace the contents of $ZEUSHOME/zxtm/etc/geo with copies of the other files in the output folder
- Restart the traffic manager
- Repeat steps 7-9 for other cluster members
If you upgrade to a new version of the Traffic Manager, you will need to reapply these changes.
Using the MaxMind GeoIP City database
Versions prior to vTM 18.3 used a GeoIP database based on the MaxMind GeoLite City database. MaxMind also produced corresponding commercially licensed database of IPv4 locations, GeoIP City, which is more detailed. If you are using version 9.6 or later you can switch to using this database.
First take a copy of the folder $ZEUSHOME/zxtm/etc/geo and the file $ZEUSHOME/zxtmadmin/lib/perl/Zeus/ZXTM/CountryData.pm.
You can switch back to to original GeoIP database by restoring these and restarting the traffic manager.
- Download the "CSV with IP addresses in numeric format and separate table for locations" version of the GeoIP City database.
- Unzip the resulting archive. This will create a folder such as GeoIP-134_20140218 containing two CSV files with names like GeoIPCity-134-Blocks.csv and GeoIPCity-134-Location.csv.
- Download the country codes file from http://dev.maxmind.com/static/csv/codes/iso3166.csv
- Download the region codes file from http://dev.maxmind.com/static/csv/codes/maxmind/region.csv
- Run the conversion script, specifying paths to the 4 CSV files in the order: locations file, blocks file, country codes, region codes. e.g:
$ZEUSHOME/zxtm/bin/process_geoip.pl \
GeoIP-134_20140218/GeoIPCity-134-Location.csv \
GeoIP-134_20140218/GeoIPCity-134-Blocks.csv \
iso3166.csv \
region.csv
- This will create a folder called output containing:
- CountryData.pm
- base_locations.txt
- country_codes.txt
- ip-to-location.bin
- region_codes.txt
It will also report on IP ranges whose Region Code is not found in the regions file.
These will return a region code, but will return an empty string when asked for the region name.
- Overwrite $ZEUSHOME/zxtmadmin/lib/perl/Zeus/ZXTM/CountryData.pm
with a copy of CountryData.pm if they differ.
- Replace the contents of $ZEUSHOME/zxtm/etc/geo with copies of the other files in the output folder
- Restart the traffic manager
- Repeat steps 7-9 for other cluster members
If you upgrade to a new version of the Traffic Manager, you will need to reapply these changes.
