Product Documentation

Add a location file to create a static proximity database

A static proximity database is a UNIX-based ASCII file. Entries added to this database from a location file are called static entries. Only one location file can be loaded on a Citrix ADC appliance. Adding a new location file overrides the existing file. The number of entries in the static proximity database is limited by the configured memory in the Citrix ADC appliance.

The static proximity database can be created in the default format or in a format derived from commercially configured third party databases (such as www.maxmind.com and www.ip2location.com).

The Citrix ADC appliance includes the following two IP geolocation database files. These are GeoLite2 files, published by MaxMind.

  • Citrix_Netscaler_InBuilt_GeoIP_DB_IPv4
  • Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6

These database files are available in a format supported by the Citrix ADC appliance in the directory /var/netscaler/inbuilt_db.

You can use these IP geolocation databases as the location file for the static proximity based GSLB method, or in location based policies.

These databases vary in the details they provide. There is no strict enforcement of the database file format, except that the default file has format tags. The database files are ASCII files that use a comma as the field delimiter. There are differences in the structure of fields and the representation of IP addresses in the locations.

The format parameter describes the structure of the file to the Citrix ADC appliance. Specifying an incorrect value for the format option can corrupt the internal data.

Note

  • After an upgrade, if the /var/netscaler/inbuilt_db/ directory contains the da tabase file (Citrix_Netscaler_InBuilt_GeoIP_DB.csv) from the earlier Citrix ADC software versions, the file is retained.
  • The default location of the database file is /var/netscaler/locdb, and on a high availability (HA) setup, an identical copy of the file must be present in the same location on both Citrix ADC appliances.

The following abbreviations are used in this section:

CSHN. Short name of a country based on the country code standard of ISO-3166.

LCN. Long name of the country.

RC. Region code based on ISO-3166-2 (for US and Canada). The region code “FIPS-10-4” is used for the other regions.

  • Some databases provide short country names according to ISO-3166 and long country names as well. The Citrix ADC uses short names when storing and matching qualifiers.

  • To create a static proximity database, log on to the UNIX shell of the Citrix ADC appliance and use an editor to create a file with the location details in one of the Citrix ADC supported formats.

To add a static location file by using the CLI

At the command prompt, type:

add locationFile <locationFile> [-format <format>]
-  show locationFile

Example:

add locationFile /var/nsmap/locdb/nsgeo1.0 -format netscaler
Done

show locationFile
Location File: /var/nsmap/locdb/nsgeo1.0
Format: netscaler
 Done
>

To add a static location file by using the GUI:

  1. Navigate to AppExpert > Location, click the Static Database tab.
  2. Click Add to add a static location file.

You can view an imported location file database by using the View Database dialog box in the configuration utility. There is no CLI equivalent.

To view a static location file by using the GUI:

  1. Navigate to AppExpert > Location, click the Static Database tab.
  2. Select a static location file, and from the Action list, click View Database.

To convert a location file into the Citrix ADC format:

By default, when you add a location file, it is saved in the Citrix ADC format. You can convert a location file of other formats into the Citrix ADC format.

Note: The nsmap option can be accessed only from the command line interface. The conversion is possible only into the Citrix ADC format.

To convert the static database format, at the CLI prompt, type the following command:

nsmap -f <inputFileFormat> -o <outputFileName> <inputFileName>

Example:

 nsmap -f ip-country-region-city -o nsfile.ns ip-country-region-city.csv

Script to convert Maxmind GeoLite2 database format to Citrix ADC database format

MaxMind GeoIP database cannot be used directly in Citrix ADC. The MaxMind GeoIP database must be converted into Citrix ADC format and then loaded for IP location detection in GSLB static proximity method and other features like policies. You can use a script to convert the GeoLite2 database format to Citrix ADC database format. This script can be used to convert both IPv4 and IPv6 files. The script is available in the location: https://github.com/citrix/MaxMind-GeoIP-Database-Conversion-Citrix-ADC-Format

Steps to convert GeoIP2 database to Citrix ADC format

1. Download the GeoLite2 City or GeoLite2 Country database in .csv format from https://dev.maxmind.com/geoip/geoip2/geolite2/.

2. Copy the file in a Citrix ADC directory (say /var). Unzip the file using the following shell command, which would create a directory with the same name.

tar -xf <filename>

3. Download the script Convert_GeoIPDB_To_Netscaler_Format.pl from https://github.com/citrix/MaxMind-GeoIP-Database-Conversion-Citrix-ADC-Format and copy it to the directory created in step #2.

4. To check the acceptable options for the script execution, run the following command:

perl Convert_GeoIPDB_To_Netscaler_Format.pl –help

Various options available are;

  • <filename> IPv4 output file. Default output file name: Netscaler_Maxmind_GeoIP_DB_IPv4.csv

  • -p <filename> IPv6 output file. Default output file name: Netscaler_Maxmind_GeoIP_DB_IPv6.csv

  • -logfile <filename> File containing list of events/messages

  • -debug Prints all the messages to STDOUT

4. Execute the following command to convert the GeoLite2 database format to Citrix ADC database format.

perl Convert_GeoIPDB_To_Netscaler_Format.pl

Note: The operation can take up to 5 minutes.

The default file names used in the script are that of the Maxmind GeoLite2 City based database. If you have downloaded GeoLite2 Country database, you must provide the input file names accordingly as listed.

  • -b <filename> name of IPv4 block file to be converted. Default file name: GeoLite2-City-Blocks-IPv4.csv
  • -i <filename> name of IPv6 block file to be converted. Default file name: GeoLite2-City-Blocks-IPv6.csv
  • -l <filename> name of location file to be converted. Default file name: GeoLite2-City-Locations-en.csv

Example:

perl Convert_GeoIPDB_To_Netscaler_Format -b GeoLite2-Country-Blocks-IPv4.csv -i GeoLite2-Country-Blocks-IPv6.csv -l  GeoLite2-Country-Locations-en.cs

The following are the output files generated after running the script.

  • Netscaler_Maxmind_GeoIP_DB_IPv4.csv
  • Netscaler_Maxmind_GeoIP_DB_IPv6.csv

5. Once the conversion of the database into Citrix ADC format is complete, use the following command to start using it.

add locationFile <locationFile>
Version

Add a location file to create a static proximity database