Showing results for 
Search instead for 
Did you mean: 

TechTip: Extending the Pulse vTM GeoIP database

Pulse Virtual Traffic Manager contains a GeoIP database that maps IP addresses to location - longitude and latitude, city, county and country.  The GeoIP database is used by the Global Load Balancing capability to estimate distances between remote users and local datacenters, and it is accessible using the geo.* TrafficScript and Java functions.


For example, to discover the 2-letter country code that a site visitor is accessing from, use the following:


$ip = request.getRemoteIP();
$countryCode = geo.getCountryCode( $ip );


The database that is included in Pulse vTM is derived from MaxMind's GeoLite City database and is updated with each release. It is also possible to update to a later version using an upgrade package, or to switch to the MaxMind GeoIP City database, see Updating the Pulse vTM GeoIP database for details.


What if the IP address I'm using is not recognized?

The database does not include locations for private IP address ranges (as per RFC1918), and other IP ranges may be missing or inaccurate if they were recently allocated or moved.  This tech tip explains how you can extend the internal GeoIP database to add or override IP address ranges.


Extending the Pulse vTM GeoIP database

Extensions to the database are stored in the file ZEUSHOME/zxtm/conf/locations.cfg, where ZEUSHOME refers to the installation directory of your Traffic Manager, typically /opt/zeus or /usr/local/zeus.


The format of each extension is a single line as follows:



firstIP    lastIP    lat    lon    CC    RR    city


The following rules and definitions apply to each mapping:


  • The elements in the line are white-space separated
  • The IP range is inclusive, and the latitude (lat) and longitude (lon) are either "-" or decimal degrees.
  • CC and RR are either "-" or two-letter country and region codes, e.g. US TX for Texas. The special files ZEUSHOME/zxtm/etc/geo/country_codes.txt and ZEUSHOME/zxtm/etc/geo/region_codes.txt provide a full list of the relevant codes.
  • The city name can include spaces, e.g. San Francisco, but does not specifically have to refer to a city (any descriptive text is acceptable).
  • Only the first two fields are required.


Some example mappings are provided below:  52.1234  -0.5678  US  TX  Shiny new datacentre -        -        -   -   Test VPN



Testing the IP Address mappings


You can test any changes with the following simple request rule:


$text = "";

$text .= whereis( "" ); $text .= "\n";
$text .= whereis( "" ); $text .= "\n";
$text .= whereis( "" ); $text .= "\n";

http.sendResponse( "200", "text/plain", $text, "" );

sub whereis( $ip ) {
return $ip . " is in:\n" .
" Country: " . geo.getCountry( $ip ) . "\n" .
" CountryCode: " . geo.getCountryCode( $ip ) . "\n" .
" Region: " . geo.getRegion( $ip ) . "\n" .
" City: " . geo.getCity( $ip ) . "\n" .
" Long/Lat: " . geo.getLongitude( $ip ) .'/'. geo.getLatitude( $ip ) . "\n";


Editing Pulse vTM Configuration Files


You can edit the ZEUSHOME/zxtm/conf/locations.cfg file directly.  The configuration system will notice the fact that this file has changed and automatically accept the location mappings defined within it.


Configuration is normally replicated automatically across a cluster, but not if you edit a configuration file directly in the file system.  You'll need to replicate the updated configuration in one of three ways:


  • If you make a configuration change using the UI, REST or SOAP APIs, the configuration on the target vTM  is then replicated across the cluster
  • You can manually initiate a configuration replication operation from the Diagnose -> Cluster Diagnosis page in the Admin Interface of the machine you have updated
  • You can call the ZEUSHOME/zxtm/bin/replicate-config script on the local machine to replicate its configuration across the cluster.
Version history
Revision #:
3 of 3
Last update:
‎01-14-2021 06:19:AM
Updated by:
Labels (1)