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 NetScaler 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 NetScaler 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 NetScaler 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 NetScaler 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 NetScaler 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 database file (Citrix_Netscaler_InBuilt_GeoIP_DB.csv) from the earlierNetScaler 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 NetScaler appliances.
  • If the location file is stored in a location other than the default location, then specify the path of the location file.
  • For admin partitions, the default path is: /var/partitions/<partitionName>/netscaler/locdb.
  • Some databases provide short country names according to ISO-3166 and long country names as well. The NetScaler uses short names when storing and matching qualifiers.
  • To create a static proximity database, log on to the UNIX shell of the NetScaler appliance and use an editor to create a file with the location details in one of the NetScaler-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
>

Example:

add locationFile /var/netscaler/inbuilt_db/Citrix_Netscaler_InBuilt_GeoIP_DB_IPv4 -format netscaler

add locationFile6 /var/netscaler/inbuilt_db/Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6 -format netscaler

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 NetScaler format

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

Note: The nsmap option can be accessed only from the command line interface. The conversion is possible only into the NetScaler 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

Add a third-party static database file on a NetScaler appliance

Perform the following steps to add a third-party static database file on a NetScaler appliance.

  1. Obtain the location database file from a third-party vendor, such as www.maxmind.com or www.ip2location.com.
  2. Copy the location database file to the NetScaler appliance using the WinSCP utility.

    Note

    The default location of the database file on the appliance is /var/netscaler/locdb.

  3. Execute the following command to add a static location file:

    add location file <locationfile Name> -format LocationFormat
    
  4. Execute the following command to ensure that the location database is loaded:

    show location parameter
    

    This command displays the parameters, such as number of static entries. If the database is not loaded correctly, this command also displays an error message. A maximum of 3M-1 (3 million minus one) entries can be loaded.

  5. Execute the following command to view the location of the GSLB site:

    show gslb service
    

    Note

    • If the database is loaded correctly, the location of the GSLB sites is automatically populated in the database.
    • You can specify only one location file in the configuration on the appliance.
    • If the appliances are in a high availability setup, then one appliance must copy the database from the other appliance.
    • If no match is found for an incoming IP address, the request is processed using the Round Robin method.
  6. Execute the following command to configure the GSLB method on the appliance:

    set gslb vserver GSLBVserverName -lbMethod MethodType