ADC

Add a location file to create a static proximity database

December 17, 2024

Contributed by:

C C S

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 that 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.

NetScaler can continue using the existing location database file until the new location file is fully implemented. This enhancement ensures uninterrupted services and significantly reduces the risk of disruptions. To monitor the status of the location database file, use the Show locationfile command, which provides real-time information about the location database file state.

Notes:

After an upgrade, if the /var/netscaler/inbuilt_db/ directory contains the database file (Citrix_Netscaler_InBuilt_GeoIP_DB.csv) from the earlier NetScaler 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 location database file including directory name.

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.

NetScaler appliance is shipped with the GeoLite2 database (IPv4 and IPv6) but NetScaler does not maintain or update the MaxMind GeoLite2 database regularly. If necessary, you can get the GeoLite2 database from https://www.maxmind.com and convert it to NetScaler database format. For more information, see Script to convert MaxMind GeoLite2 database format to NetScaler database format.

To add a static location file by using the CLI

At the command prompt, type:

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

Example:

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

show locationFile
Location File: /var/netscaler/locdb/nsgeo1.0
Format: netscaler
 Done
>
<!--NeedCopy-->

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
<!--NeedCopy-->

When replacing the existing location database file with the new one, the show location file command displays the status of the new location database file along with the status of the existing location database file. In the preceding example, the new Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6_1 location database file replaces the existing Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6 location database file.

Example:

add locationFile6 /var/netscaler/inbuilt_db/Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6_1 -format netscaler
Done

show locationfile

Location File IPv6: Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6
Location File Format: netscaler
Status: In Progress

Previous Location File IPv4: Citrix_Netscaler_InBuilt_GeoIP_DB_IPv4
Previous File Format: netscaler
Status: Active
Done
<!--NeedCopy-->

To add a static location file by using the GUI:

Navigate to AppExpert > Location, click the Static Database tab.
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:

Navigate to AppExpert > Location, click the Static Database tab.
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>
<!--NeedCopy-->

Example:

 nsmap -f ip-country-region-city -o nsfile.ns ip-country-region-city.csv
<!--NeedCopy-->

Script to convert MaxMind GeoLite2 database format to NetScaler database format

MaxMind GeoIP database cannot be used directly in NetScaler. The MaxMind GeoIP database must be converted into NetScaler format and then loaded for IP location detection in the GSLB static proximity method and other features like policies. You can use a script to convert the GeoLite2 database format to NetScaler 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 NetScaler format

Download the GeoLite2 City or GeoLite2 Country database in .csv format from https://dev.maxmind.com/geoip/geoip2/geolite2/.
Copy the file in a NetScaler directory (say /var). Unzip the file using the following shell command, which would create a directory with the same name.

tar -xf <filename>
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.
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
Run the following command to convert the GeoLite2 database format to NetScaler 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 the 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.pl -b GeoLite2-City-Blocks-IPv4.csv -i GeoLite2-City-Blocks-IPv6.csv -l  GeoLite2-City-Locations-en.csv

```
The following are the output files generated after running the script.
- Netscaler_Maxmind_GeoIP_DB_IPv4.csv
- Netscaler_Maxmind_GeoIP_DB_IPv6.csv
Once the conversion of the database into NetScaler format is complete, use the following command to start using it.

add locationFile <locationFile>

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.

Obtain the location database file from a third-party vendor, such as www.maxmind.com.

Note:

If you download the location database file from www.maxmind.com, you can use the readily available script to convert it into NetScaler database format. For information on using the script, see Script to convert MaxMind GeoLite2 database format to NetScaler database format.

For location databases downloaded from other third-party vendors, you must convert them to NetScaler database format before adding them to a NetScaler appliance.
Run the following command to add a static location file:
```
add location file <locationfile Name>

```
Note:
- If the location database file is not placed in the default /var/netscaler/locdb location, then the <locationfile Name> must contain the location of the file along with the file name.
- Before you run the add location file <locationfile Name> command:
  - Make sure that the location database file is present in one of the directories of the NetScaler appliance.
  - Run the sync HA files command on the high availability setup and the sync cluster files command in a cluster setup. These commands ensure that the location database file is copied to the secondary appliance of the high availability pair and peer nodes of the cluster.
Run the following command to ensure that the location database is loaded:
```
show locationParameter

```
This command displays location parameters related to static proximity-based load balancing. A maximum of 3M-1 (3 million minus one) entries can be loaded. When the database loading is in progress, the command displays Loading: In progress. After the loading is completed, the command displays Loading: Idle.
Run 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 no match is found for an incoming IP address, the request is processed using the Round Robin method.
Run the following command to configure the GSLB method on the appliance:
```
set gslb vserver GSLBVserverName -lbMethod MethodType

```

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Add a location file to create a static proximity database

December 17, 2024

Contributed by:

C C S

December 17, 2024

Contributed by:

C C S

Add a location file to create a static proximity database

To add a static location file by using the CLI

Script to convert MaxMind GeoLite2 database format to NetScaler database format

Steps to convert GeoIP2 database to NetScaler format

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

In this article