Retrieve location details from user IP address using geolocation database

Last published : Sep 30, 2026
Note This feature is available from NetScaler release 12.1 build 50.x and later.
The NetScaler appliance can get user location details like continent, county, and city. For any public IP address from a geo location database. It is performed using the advanced policy infrastructure. The retrieved location details are then used in a rewrite action or a responder action for performing the following use cases.
  • Insert an HTTP header with user location details (such as country, city information) when sending the client request to the back-end server.
  • Add country name in the HTML page response for an invalid user.
The appliance can also log the location details using the audit logging mechanism.
Related information
Advanced load balancing settings

Getting user location details using geolocation functions

The components interact as per the following:
  1. User sends a client request from a particular geographic location.
  2. The NetScaler appliance looks for the user IP address from the client request and retrieves the geo location details. The details include continent, country, region, city, ISP, organization, or custom details from a geolocation database.
  3. Once the location details are retrieved, the appliance uses either a responder policy or a rewrite policy to evaluate the request.
  4. In a rewrite policy, the appliance adds a header with the geo location details and sends it to the back-end server. For example, insert a custom HTTP header with country information.
  5. In a responder policy, the appliance evaluates the HTTP request and based on policy evaluation, allows access to the users or redirects the user to an error page. It states the region from where they are accessing the application does not have access.

Setting up geolocation database

As a pre-requisite, you must have a geolocation database to run on the NetScaler appliance. The geolocation database files are available with NetScaler firmware. To download the database files from a vendor, convert it into NetScaler format and import it into your appliance. For more information about the geolocation database, see Add a location file to create static proximity database topic.

Geolocation functions

The following table gives a list of geolocation functions that retrieves location details of any public IP address. These functions can be used in rewrite or responder policies.
Geolocation function Example
CLIENT.IP.SRC.LOCATION Asia.In.Karnataka.Bangalore
CLIENT.IP.SRC.LOCATION.GET (1).LOCATION_LONG India
CLIENT.IP.SRC.LOCATION(3) Asia.In.Karnataka
CLIENT.IP.SRC.LAT_LONG 12,77
CLIENT.IPV6.SRC.LOCATION North America.US.California.Santa Clara.Verizon.Citrix
CLIENT.IPV6.SRC.LOCATION(3) North America.US.California
CLIENT.IPV6.SRC.LOCATION.GET(1).LOCATION_LONG United States
CLIENT.IPV6.SRC.LOCATION.GET(3) California
CLIENT.IPV6.SRC.LAT_LONG 36, -119

Configuring geolocation functions

To configure geolocation functions using advanced policy infrastructure, you must enable the load balancing, rewrite, and responder features and then complete the following use cases.

Enable load balancing, responder, rewrite features

If you want the NetScaler appliance to authorize user access from a particular geo location, you must enable the load balancing, rewrite, and responder features.
enable ns feature loadbalancing rewrite responder

Use case 1: Configuring geolocation function for redirecting invalid users outside geo location

When a user from India is requesting access to a webpage, block the request and respond with an HTML page with country name.
The following steps help you to complete the configuration of this use case.
  • Add responder action
  • Add responder policy
  • Bind responder policy to load balancing server
For more information about the GUI procedures for rewrite action and rewrite policy configuration, see Responder topic

Add responder action

Add a responder action to respond with HTML page with country name. At the command prompt, type:
add responder action <name> <type> (<target> | <htmlpage>) [-comment <string>] [-responseStatusCode <positive_integer>][-reasonPhrase <string>]
Example:
add responder action responder_act respondwith "HTTP.REQ.VERSION + \" 304 Requested Page not allowed in your country - \" + CLIENT.IP.SRC.LOCATION.GET (1).LOCATION_LONG + \"\r\n\""

Add audit log message action

You can configure audit message actions to log messages at various log levels, either in syslog format only or in both syslog and newnslog formats. Audit-message actions use expressions to specify the format of the audit messages. To create an audit message action by using the command line interface
At the command prompt, type: add audit messageaction <name> <logLevel> <stringBuilderExpr> [-logtoNewnslog (YES|NO)]
Example:
add audit messageaction msg1 DEBUG "\"Request Location: \"+CLIENT.IP.SRC.LOCATION"

Add responder policy

Add a responder policy to identify requests coming from India and associate the responder action to this policy. At the command prompt, type:
add responder policy <name> <rule> <action> [<undefAction>] [-comment <string>] [-logAction <string>] [-appflowAction <string>]
Example:
add responder policy responder_pol CLIENT.IP.SRC.MATCHES_LOCATION("Asia.India.*.*.*.*") responder_act -logaction msg1

Bind responder policy to load balancing server

Bind the responder policy to a load balancing virtual server of type HTTP/SSL. At the command prompt, type:
bind lb vserver <vserver name> -policyName < policy_name >  -priority <> -type <L7InlineREQUEST | L4Inline-REQUEST>
Example:
bind lb vserver http_vserver -policyName responder_pol -priority 100 -type REQUEST

Use case 2: Configuring geolocation function for inserting new HTTP header with location details for back-end to respond

Consider a scenario, where a NetScaler appliance must insert the user location in the HTTP header of a request sent to the application server so that the server can use the information for some business logic. The following steps help you to complete the configuration of this use case.
  • Add rewrite action
  • Add rewrite policy
  • Bind rewrite policy to load balancing
For more information about the GUI procedures for rewrite action and rewrite policy configuration, see Responder topic.

Add rewrite action

Add a rewrite action to insert a custom HTTP header with user geolocation details in the request and send it back-end servers. At the command prompt, type:
add rewrite action <name> <type> <target> [<stringBuilderExpr>] [-search <expression>] [-refineSearch <string>][-comment <string>]
Example:
add rewrite action rewrite_act insert_http_header "User_location" CLIENT.IP.SRC.LOCATION

Add rewrite policy

Add a rewrite policy to evaluate if the rewrite action must be run. In this case, all requests going to the application server must have a custom HTTP header, so the rule can be “true.” At the command prompt, type:
add rewrite policy <name> <rule> <action> [<undefAction>] [-comment <string>] [-logAction <string>]
Example:
add rewrite policy rewrite_pol true rewrite_act -logaction log_act

Bind rewrite policy to load balancing

Bind the rewrite policy to the required load balancing virtual server of type HTTP/SSL. At the command prompt, type:
bind lb vserver <vserver name> -policyName < policy_name >  -priority <> -type <L7InlineREQUEST | L4Inline-REQUEST>
Example:
bind lb vserver http_vserver -policyName rewrite_pol -priority 100 -type REQUEST

Syslog support for logging geolocation details (optional)

If you prefer to log the user’s geolocation details, you must specify the SYSLOG action to be performed when a request matches the policy. The appliance stores the details as a log message in the ns.log file. For more information about SYSLOG and NSLOG auditing, see Audit logging topic.

Output for user geolocation details

The following output is logged in the appliance using the SYSLOG or newnslog action if you try to access an application from the Bangalore location and if the appliance uses the geolocation function, "CLIENT.IP.SRC.LOCATION'.
Asia.India.Karnataka.Banglore
Sample output log:
07/23/2018:19:03:54 GMT  Debug 0-PPE-0 : default REWRITE Message 22 0 :  "Request Location: asia.in.karnataka.bangalore.*.*"
07/23/2018:19:23:55 GMT  Debug 0-PPE-0 : default RESPONDER Message 32 0
Done