AppDynamics Application Intelligence Platform

3.8.x Documentation



Release Notes

Skip to end of metadata
Go to start of metadata


A common data center design involves putting backend services such as the AppDynamics Controller in a network behind a DMZ. For the Controller, a network proxy residing in the DMZ acts as an end-point for the Controller by presenting a virtual IP address for the Controller, since App Agents and UI browser clients connect to the Controller through the virtual IP.

In addition to providing a security layer, a reverse proxy allows you to move a Controller to another machine or switch between high availability pairs without having to reconfigure and restart monitored applications. 

In the sample scenario shown by the diagram, the reverse proxy listens for incoming requests on a given path, /controller in this case, on port 80. It forwards matching requests to the HTTP listening port of the primary Controller at appdhost1:8090. In terms of network impact in this scenario, switching active Controllers from the primary to the secondary in this scenario only requires the administrator to update the routing policy at the proxy so that traffic directed to the secondary instead of the primary. 

If clients use SSL, the reverse proxy can terminate SSL connections or maintain SSL through to the Controller. Terminating SSL at the proxy removes the processing burden from the Controller machine. It can also simplify administration for the data center as a whole by centralizing SSL key management to a single point and it allows you to use alternative PKI infrastructures like OpenSSL.

About these Instructions

There are various types of devices and software that can act as a reverse proxy. For example, NginxHAProxyApache Web Server, or an application-level load balancer such as F5's BIG-IP can all act as a reverse proxy for the Controller. 

This page provides general considerations for setting up the Controller with a reverse proxy. It also provides sample configurations for a few specific types of proxies. 

It is important to note that this information is intended for illustration purposes only. The configuration requirements for your own deployment is likely to vary greatly, depending on the existing environment, the applications being monitored, and the practices and policies of your organization. 

While AppDynamics supports Controllers that are deployed with a reverse proxy, AppDynamics Support cannot guarantee help with specific set up questions and issues particular for your environment or the type of proxy you are using. For this type of information, please consult the documentation provided with your proxy technology. Alternatively, try posting the question to the AppDynamics community.    

General Guidelines

The following describe general requirements, considerations, and features for deploying the AppDynamics Controller and App Agents with a reverse proxy. 

  • In the Controller configuration, add a JVM option named -Dappdynamics.controller.ui.deeplink.url to the domain configuration file, domain.xml, or using the modifyJvmOptions utility. As the value of the option, provide the hostname or virtual IP address for the Controller as exposed at the proxy. For example:

    <java-config ...>

    The Controller uses this value to compose the deep link URLs it exposes in the UI.

  • If the proxy sits between monitored tiers in the application, make sure that the proxy passes through the custom header that AppDynamics adds for traffic correlation, singularityheader. Most proxies pass through custom headers by default.
  • For App Agents, the Controller Host and Controller Port connection settings should point to the VIP or hostname and port exposed for the Controller at the reverse proxy. For details see Connect the Controller and Agents.
  • If using SSL from the agent to the proxy, ensure that the security protocols used between the App Agent and proxy are compatible. See the compatibility table for the SSL protocol used by each version of the agent.
  • If the proxy (or other network device) needs to check for the availability of the Controller, it can use Controller REST resource at: http://<host>:<port>/controller/rest/serverstatus. If the Controller is active and if in high availability mode, is the primary, it returns an XML response similar to this one:

    <serverstatus vendorid="" version="1">
           <productname>AppDynamics Application Performance Management</productname>

    If the Controller is in standby Controller this resource returns an error response.

The following sections provide notes and sample configurations for a few specific types of proxies, including Nginx and Apache Web Server. 

Using Nginx as a Simple HTTP Reverse Proxy

Nginx is a commonly used web server and reverse proxy available at

To use Nginx as a reverse proxy for the Controller, simply include the Controller as the upstream server in the Nginx configuration. If deploying two Controllers in a high availability pair arrangement, include the addresses of both the primary and secondary Controllers in the upstream server definition. 

The following steps walk you through the set up at a high level. It assumes you have already installed the Controller and have an Nginx instance, and you only need to modify the existing configuration to have Nginx route traffic to the Controller.

The sample network layout represented in the configuration in these steps is:  

To route Controller traffic through an Nginx reverse proxy: 

  1. If the Controller is running, shut down the Controller.

  2. Add a JVM option named -Dappdynamics.controller.ui.deeplink.url to the domain configuration file, domain.xml, or using the modifyJvmOptions utility. 
  3. In the Nginx home directory on the reverse proxy machine, open the conf/nginx.conf file for editing.
  4. In the configuration file, add a cluster definition the specifies each Controller as an upstream server. For example:

     upstream appdcontroller {
      server fail_timeout=0;
    server {
        listen 80;
        expires 0;
        add_header Cache-Control private;
        location / {
            proxy_set_header    Host $host;
            proxy_set_header    X-Real-IP $remote_addr;
            proxy_set_header    X-Forwarded-Proto https;
            proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass          http://appdcontroller;

    In the sample, the Controller resides on and has the fully qualified domain name 

  5. Restart the Nginx server to have the change take effect.
  6. Restart the Controller. 

After the Controller starts, it should be able to receive traffic through Nginx. As an initial test of the connection, try opening the Controller UI via the proxy, that is, in a browser, go to http://<virtualip>:80/controller. For the App Agents, you'll need to configure their proxy host and port settings as described in the general guidelines above

Using Apache as a Reverse Proxy

To use Apache as a reverse proxy, you need to make sure the appropriate Apache module is installed and enabled in your Apache instance. For HTTP proxying, this is typically mod_proxy_http. The mod_proxy_http module support proxied connections that use HTTP or HTTPS. 

To configure Apache with mod_proxy_http

  1. If the Controller is running, shut it down. 

  2. Add a JVM option named -Dappdynamics.controller.ui.deeplink.url to the domain configuration file, domain.xml, or using the modifyJvmOptions utility. 
  3. On the machine that runs Apache, check whether the required modules are already loaded by your Apache instance by running this command:

    apache2ctl -M

    In the output, look for proxy modules as follows:

    proxy_module (shared)
    proxy_http_module (shared)

    The proxy_module is a dependency for proxy_module_http. 

  4. If they are not loaded, enable the Apache module as appropriate for your distribution of Apache. For example, on Debian/Ubuntu: 
    1. Type the following: 

      sudo a2enmod proxy_http
    2. Restart Apache:

      sudo service apache2 restart
  5. Add the proxy configuration to Apache. For example, a configuration that directs clients requests to the standard web port 80 at the proxy host to the Controller could look similar to this:  

    <Proxy *>
        Order deny,allow
        Allow from all
    ProxyRequests       Off
    ProxyPreserveHost   On
    ProxyPass /controller
    ProxyPassReverse /controller
  6. Apply your configuration changes by reloading Apache modules. For example, enter: 

    sudo service apache2 reload
  7. Start the Controller. 

After the Controller starts, test the connection by opening a browser to the Controller UI as exposed by the proxy. To enable AppDynamics App Agents to connect through the proxy, be sure to set the proxy host and port settings in the proxy, as described in the general guidelines above. Also be sure to apply any of the other general guidelines described in the general guidelines above.  

Configure SSL Termination at the Reverse Proxy

This section describes how to set up security when the client-side connection to the proxy uses SSL that's terminated at the proxy. This assumes that the proxy and Controller are in a secured data center and the App Agents or UI browser client connections are from a potentially insecure network. 

Terminating SSL at a proxy offloads the burden of SSL processing from the Controller to the proxy. This configuration is strongly recommended when deploying the Controller to large scale, high workload environments. Terminating SSL at a proxy also provides the benefit of having a central point in the data center for security certificate and key management.

This section provides an sample configuration for Nginx, but the concepts translate to other types of reverse proxies as well.

Configure the Proxy for SSL Termination

To enable SSL termination at the reverse proxy, you need to:

  • Ensure that the App Agents can establish a secure connection with the proxy. See Agent - Controller Compatibility Matrix for SSL settings for various versions of the agent. Ensure that the proxy includes a server certificate signed by an authority that is trusted by the agent. Otherwise, you will need to install the proxy machine's server key on the Agent.
  • If using .NET App Agents in your environment, verify that the reverse proxy server uses a server certificate signed by a certificate authority (CA). The .NET App Agent does not permit SSL connections based on a self-signed server certificate. 
  • Configure the proxy to forward traffic between it and the Controller to a secure port between it and the client.  
  • Configure a mixed-use (SSL and non-SSL) channel on the listening port on the Controller, as described below. Use caution when configuring the Controller in this manner. In this mode, the Controller assumes 
  • The client App Agents and browser clients under this configuration must use the secure port to communicate with the Controller (i.e., the proxy). Configuring a mixed channel on the Controller as described here, in effect, causes the agents to perform as if they were using a secure port. Therefore, you need to ensure that clients use a secure port only. 

A complete example configuration with Nginx performing SSL termination for the Controller would look something like this:  

 upstream appdcontroller {
  server fail_timeout=0;

server {
    listen 80;
    return 301 https://$host$request_uri;
server {
    listen 443;

    ssl on;
    ssl_certificate /etc/nginx/server.crt;
    ssl_certificate_key /etc/nginx/server.key);

    ssl_session_timeout  5m;
    ssl_protocols  SSLv2 SSLv3 TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
    ssl_prefer_server_ciphers   on;

    expires 0;
    add_header Cache-Control private;

    location / {
        proxy_set_header    Host $host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-Proto https;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_redirect      http:// https://;
        proxy_pass          http://appdcontroller;

This example builds on the configuration shown in the simple passthrough example. In this one, any request received on the non-SSL port 80 is routed to port 443. The server for port 443 contains the settings for SSL termination. The ssl_certificate_key and ssl_certificate directives should identify the location of the server security certificate and key for the proxy.

The configuration also indicates the SSL protocols and ciphers accepted for connections. The security settings need to be compatible with the AppDynamics App Agent security capabilities, as described on the Agent - Controller Compatibility Matrix page.   

To work with the Controller, you must configure the Controller with a mixed-channel HTTP listener, as described in the following section, Configure the Controller for SSL Termination at the Proxy.

Configure the Controller for SSL Termination at the Proxy

Be sure to set up the proxy to redirect server side traffic to the secure channel on the client side if you are performing this configuration. If you enable a mixed use channel, as described here, you need to be sure that the clients are configured to use the secure channel. 

To configure a mixed protocol channel for an SSL proxy:

  1. Stop the Controller application server:

    ./ stop-appserver
  2. Open the services-config.xml file for editing. You can find it in the following directory:

  3. Find the channel-definition element with an id value of my-secure-amf.
  4. Replace the default value of the class attribute of the endpoint URL element, flex.messaging.endpoints.SecureAMFEndpoint, with a new value of flex.messaging.endpoints.AMFEndpoint. The resulting element should look like this:

    <channel-definition id="my-secure-amf" class="mx.messaging.channels.SecureAMFChannel">
        <endpoint url="https://{}:{server.port}/{context.root}/messagebroker/amfsecure" class="flex.messaging.endpoints.AMFEndpoint"/>
  5. Start the application server:

    ./ start-appserver

Using SSL from the Reverse Proxy to the Controller

Have the proxy connect to the Controller with SSL requires a minor modification to the proxy configuration. Simply specify the use of HTTPS as the protocol to connect to the backend or upstream server. In other words, for the Nginx configuration, this simply requires you to modify the proxy_pass value as follows: 

proxy_pass          https://appdcontroller;

To complete the configuration, make sure you have configured SSL on the Controller as described in Controller SSL and Certificates


  • No labels