Author: Jeff Sani
Contributors: Matt Drown, Chuck Cox
Version: 1.0
Last Update: 5/27/2022
Accurate IP location information is important if you are using this as a factor for device posture or for geofencing applications and APIs. This script will automate the refresh of the Citrix ADC (NetScaler) InBuilt MaxMind Location Database files Citrix_Netscaler_InBuilt_GeoIP_DB_IPv4 and Citrix_Netscaler_InBuilt_GeoIP_DB_IPv6 which are used with Static Proximity GSLB and Policy Expressions that reference a Location. See Citrix GSLB Documentation for more information about GSLB Static Proximity. The default InBuilt IP DB files are based on the GeoLite2 free edition which is also the default for this script, but MaxMind also has a Enterprise version (GeoIP2) which is more precise, contains additional information, and is updated more frequently. For more information about the MaxMind GeoLite2 and GeoIP Geolocation databases and their limits, accuracy, etc... visit the GeoLite2 and GeoIP2 product pages. This script supports both versions by setting the "EDITION" variable.
The main benefit of this script is to keep the location files up-to-date as these are not updated via on-box automation or new firmware installs. At the time of writing, the InBuilt files were last updated in 2019. According to the MaxMind support knowledge base, the GeoLite2 IP Databases are updated each Tuesday and the GeoIP2 IP Databases are updated every Tuesday and Friday - Please refer to the Database Update KB article for more details. Based on this, the init script configures a cron job which is scheduled to run every Wednesday morning at 1:00AM to perform the update of the GeoLite2 IP Database and every Wednesday and Saturday morning at 1:00AM for the GeoIP2 IP Database version. The script will download the MaxMind City or Country DB (CSV Format) if it has been refreshed, perform a checksum on the file to verify file integrity, convert it to the required NetScaler location db format, upload the new files to the requisite directory where the InBuilt files are located, create static ip databse entries for IPv4 and IPv6, and save the configuration. The InBuilt files will get automatically synchronized across HA pair or Cluster nodes.
Automated Setup Steps (For CentOS/Fedora or Ubuntu Linux Host)
- Login to your host as the user you want to create the script under
- Install the required Linux packages or follow this prompt in the init script
- Complete steps 3-5 in the requirements below for access to the MaxMind GeoLite2 or GeoIP2 databases
- Clone the repo into the desired directory on your linux host:
- cd to MaxMindGeoIP2ADC
- Run the mmgeoip2adc-init.sh script
Script Requirements
To implement this script you will need the following if you plan to implement manually and not use the init script:
- A Linux host or container to run this on
- Citrix ADC Build Version 12.1, 13.0, or 13.1 (It may work on older builds as well but I did not test those and they are EOL)
- A GeoLite2 account or GeoIP2 Enterprise account
- An API License Key - created post account setup in the MaxMind portal
- Permalinks to the Country and/or City Geo IP Databases in CSV format - obtained on the downloads page within your account
- Required Linux Packages:
- Debian/Ubuntu: curl unzip libwww-perl libmime-lite-perl libnet-ip-perl git sshpass moreutils
- CentOS/Fedora: curl unzip perl-libwww-perl perl-MIME-Lite perl-Net-IP perl-Time-Piece git sshpass more-utils
- The Citrix ADC GSLB GeoIP Conversion Tool
- Environment variables set for the user running the script that contain the MaxMind and Citrix ADC details as per below
- cron job to schedule the script to check for IP DB updates
Required Environment Variables
The following variables and their respective values are required at script runtime so it is suggested they be stored in .bashrc and or .bash_profile or a local configuration file
- LICENSE_KEY=XXXX
- EDITION=[GeoLite2 or GeoIP2]
- CITRIX_ADC_USER=XXX
- CITRIX_ADC_PASSWORD=XXX
- CITRIX_ADC_IP=X.X.X.X
- CITRIX_ADC_PORT=NNN
Script Usage
If you want to override the freshness check for the databases, you can use the -f flag when running the script:
#./mmgeoip2adc.sh -f
ADC Service Account and Command Policy
It is optional but recommended to create a service account on ADC to use for the purposes of running this script in lieu of just using nsroot:
add system cmdPolicy geoip2adc_cmdpol ALLOW "((^(scp).*/var/netscaler/inbuilt_db*)|(^save\s+ns\s+config)|(^save\s+ns\s+config\s+.*)|(^add\s+(locationFile|locationFile6))|(^add\s+(locationFile|locationFile6)\s+.*))"
add system user geoip2adc -timeout 900 -maxsession 2 -allowedManagementInterface CLI
bind system user geoip2adc geoip2adc_cmdpol 100