Custom Geo Server for AppDynamics: Step-by-Step Installation and Configuration

AppDynamics, by default, utilizes a Geo Server to determine the geographical location of users based on their IP addresses. This is crucial for features like Browser RUM (Real User Monitoring), allowing you to visualize user locations and analyze performance geographically. However, in certain scenarios, relying solely on the default public Geo Server might not be optimal. Hosting your own custom Geo Server offers significant advantages, particularly for intranet and hybrid applications.

Why Host a Custom Geo Server?

There are primarily two key reasons why you might choose to host your own Geo Server:

• Intranet Applications: For applications accessed within a corporate intranet, public IP addresses often point to the company’s central gateway, not the user’s actual location within the network. A custom Geo Server allows you to map private IP ranges to specific internal locations, providing much more granular and meaningful geographic data for your intranet application users.

• Hybrid Applications: In hybrid environments where users access your application from both private (intranet) and public networks, a custom Geo Server offers a flexible solution. You can configure it to resolve locations for known private IP ranges and, if an IP address falls outside these ranges, default to the public Geo Server for broader coverage. This ensures accurate location data for all users, regardless of their access point.

AppDynamics custom Geo Server is designed to be flexible, supporting the AD-X-Forwarded-For HTTP header, which allows you to explicitly declare an IP address for geo-resolution. It also supports the X-Real-IP header for similar purposes.

Setting Up Your Custom Geo Server: A Practical Guide

Here’s a step-by-step guide to hosting your own Geo Server for AppDynamics:

Prerequisites for Geo Server Hosting

Before you begin the installation process, ensure your server meets these minimum requirements:

• Memory: 2 GB RAM
• Java Runtime Environment: Java 8.x

Downloading and Installing the Geo Server Software

1. Download the Geo Server Package: Obtain the GeoServer.zip file directly from the AppDynamics download center: https://download.appdynamics.com/download.

2. Extract the Package: Unzip the downloaded GeoServer.zip file to create a GeoServer directory. This directory contains the necessary files and configurations, structured as follows:

   GeoServer
   ├── schema.xsd         <-- Schema for geo-ip-mapping.xml configuration
   └── geo
       ├── WEB-INF
       │   ├── classes
       │   │   └── logback.xml  <-- Logging configuration
       │   └── web.xml      <-- Web application configurations
       ├── geo-ip-mappings.xml <-- IP mapping configuration file
       └── ...

   This structure is essential for the Geo Server to function correctly.

3. Deploy to Tomcat: Copy the geo folder from the extracted GeoServer directory into the TOMCAT_HOME/webapps directory of your Tomcat application server. Important: Do not deploy the Geo Server within the same Tomcat container as your AppDynamics Controller. Using a separate Tomcat instance is crucial for performance and stability.

Configuring the Geo Server URL in AppDynamics Controller

1. Access Browser RUM Settings: Log in to your AppDynamics Controller UI and navigate to the Browser RUM configuration section.

2. Specify Geo Server URL: Locate the Geo Server URL field within the Browser RUM settings. Enter the complete URL to your newly hosted Geo Server, including the context root (typically /geo if you deployed the geo folder as is). For example: http://your-geo-server-host:8080/geo.

   Important Note: If you are using manual injection for your AppDynamics JavaScript agent, it is imperative to download a fresh copy of the agent script after configuring the Geo Server URL in the Controller. This ensures that the agent is correctly configured to communicate with your custom Geo Server.

Creating and Customizing the IP Mapping File (geo-ip-mappings.xml)

The geo-ip-mappings.xml file is the heart of your custom Geo Server. It defines the mappings between IP addresses (or ranges) and geographic locations.

1. Locate the Template: Navigate to the TOMCAT_HOME/webapps/geo/geo-ip-mappings.xml file. This file serves as a template and contains example mappings.

2. Edit the Mapping File: Open geo-ip-mappings.xml with a text editor. You will see the <mappings> root element, which contains <mapping> elements for each location you want to define.

3. Define IP Mappings: You can define mappings using either subnet-based or IP-range-based configurations:

   • Subnet-Based Mapping:

     <mappings>
       <mapping>
         <subnet from="192.168.1.1" mask="255.255.255.0"/>
         <location country="United States" region="California" city="San Francisco"/>
       </mapping>
       </mappings>

     This example maps the entire 192.168.1.0/24 subnet to San Francisco, California, USA.

   • IP-Range-Based Mapping:

     <mapping>
       <ip-range from="10.240.1.1" to="10.240.1.254" />
       <location country="France" region="Nord-Pas-de-Calais" city="ENGLOS" />
     </mapping>

     This example maps the IP address range from 10.240.1.1 to 10.240.1.254 to Englos, Nord-Pas-de-Calais, France.

4. Location Details: Within each <mapping>, the <location> element requires <country>, <region>, and <city> sub-elements. These are essential for displaying location data in Browser RUM. Ensure that the <country> and <region> values correspond to valid geographic names recognized by the AppDynamics geo dashboard. You can find the correct names by hovering over regions in the Geo Dashboard view within the Controller UI.
   Note: If the country and region names are not recognized, location data might not be displayed on maps, but Browser RUM metrics will still be available in grid views and reports.

5. Default Location (Optional): The <default> element within <mappings> allows you to specify a default location for IP addresses that are not explicitly mapped.

   <default country="United States" region="California" city="San Francisco"/>

   If you intend to use the public AppDynamics Geo Server for unmapped IP addresses, remove the <default> element from the geo-ip-mappings.xml file.

Hybrid Custom-Public Geo Server Configuration

For a hybrid setup where you want to leverage both your custom Geo Server and the public AppDynamics Geo Server:

1. Remove <default> Element: As mentioned above, ensure that the <default> element is removed from your geo-ip-mappings.xml file.

2. AppDynamics Behavior: With the <default> element removed, AppDynamics will first consult your custom Geo Server for IP resolution. If no mapping is found in your geo-ip-mappings.xml, it will then automatically fall back to the public AppDynamics Geo Server to resolve the location.

Advanced Customization: Log and Mapping File Locations

You can further customize the Geo Server by changing the default locations for log files and the IP mapping file.

Modifying Log File Location

1. Edit logback.xml: Open the TOMCAT_HOME/webapps/geo/WEB-INF/classes/logback.xml file.

2. Change LOG_HOME Property: Locate the <property name="LOG_HOME" value="{path-to-file}/logs"/> line. Modify the value attribute to specify your desired log file directory.

   <property name="LOG_HOME" value="/opt/appdynamics/geo-server/logs"/>

Modifying Mapping File Location

1. Edit web.xml: Open the TOMCAT_HOME/webapps/geo/WEB-INF/web.xml file.

2. Change AD_GEO_CONFIG_FILE Parameter: Find the <context-param> section and the <param-name>AD_GEO_CONFIG_FILE</param-name> parameter. Change the <param-value> to the new path for your geo-ip-mappings.xml file.

   <web-app ...>
     ...
     <servlet>
       <servlet-name>FrontControllerServlet</servlet-name>
       <servlet-class>com.appdynamics.eum.geo.web.FrontControllerServlet</servlet-class>
       <context-param>
         <param-name>AD_GEO_CONFIG_FILE</param-name>
         <param-value>/opt/appdynamics/geo-server/conf/geo-ip-mappings.xml</param-value>
       </context-param>
       ...
     </servlet>
     ...
   </web-app>

   Note: In older versions of the Geo Server, the enclosing tag for AD_GEO_CONFIG_FILE was <context-param>. This has been updated to <init-param> in more recent versions. Ensure you are modifying the correct parameter tag in your web.xml file.

By following these steps, you can successfully deploy and configure a custom Geo Server for AppDynamics, gaining enhanced location accuracy and control, especially within intranet and hybrid application environments. This will provide richer geographic insights into your application’s user behavior and performance.