AppDynamics: Installing a Machine Agent on Ubuntu 14.04

The AppDynamics Machine Agent is used not only to report back on basic hardware metrics (cpu/memory/disk/network), but also as the hook for custom plugins that can report back on any number of applications including: .NET, Apache, AWS, MongoDB, Cassandra, and many others.

In this article, I’ll go over the details to install the Machine Agent unto an Ubuntu 14.04 system.


The first step is to grab the latest Machine Agent from the AppDynamics download site.  This requires an account, but even trial accounts have access to the download.

For Ubuntu, I always pick the bundled 64 bit zip package which includes a Java1.8 JRE along with the installation.  The JRE is located in a subdirectory of the Machine Agent home directory which keeps it isolated and independent.

Install Binaries

Copy the archive, which will be named something like “”, into the /tmp directory and then deploy like:

# mkdir -p /opt/appdynamics/machine-agent/logs
# chmod ugo+r+w /opt/appdynamics/machine-agent/logs -R
# cd /opt/AppDynamics/machine-agent
# mv /tmp/ .
# apt-get install unzip -y
# unzip

Edit Configuration

Then edit the configuration at conf/controller-info.xml:

<controller-host> should be set to the FQDN of the controller and needs to match the CN of the controller certificate if using SSL

<controller-port> typically 8090 or 8181

<controller-ssl-enabled> true if hitting SSL enabled port of controller

<force-default-cerficate-validation> if SSL enabled, then “true” is supposed to prevent strict checking of the server cert.  But even with this set, I still see errors when the <controller-host> does not match the exact name of the cert CN.  This setting does work however for the AppServer and Database agents.

<unique-host-id> hostname

<account-access-key> API key for Controller (Gear > License > Show key)

<sim-enabled> true

<force-agent-registration> true if node definition should be created automatically, usually false because done via web GUI.  If however, it is set to true, then you also need to set <application-name>, <tier-name>, and <node-name>

Startup Script

First copy the prepackaged startup script into the /etc/init.d directory:

# cp /opt/appdynamics/machine-agent/etc/init.d/appdynamics-machine-agent /etc/init.d/appdynamics-machine-agent

Then create the lock directory used in the startup script:

# mkdir -p /var/lock/subsys
# chmod 755 /var/lock/subsys

Then create the proper init.d startup links:

# cd /etc/init.d
# update-rc.d -f appdynamics-machine-agent start 99 2 3 4 5 .
# service appdynamics-machine-agent start

Log levels can be changed in conf/logging/log4j.xml.  Logs can be tailed from /opt/appdynamics/machine-agent/logs/machine-agent.log

Known Issues

There are a couple of issues I ran into during installation.

The very first time you want to create a server definition in the Web GUI it makes you go through a wizard.  As one of the steps in the wizard, your browser tries to download the machine agent binary package.  This download is attempted from, which may not be accessible from your intranet or datacenter and hence you cannot create a server definition.  In order to get around this, you have to set the <force-agent-registration> equal to true in controller-info.xml.  Subsequent server additions do not force you to use the wizard, and therefore the issue is not seen again.

The second issue is an error in the parsing of process utilization.  The machine agent calls the ‘ps’ utility, but if you are ssh’d into the box, it chokes on the virtualMemSizeKB parsing and no data will be collected while you have an ssh connection into the box.  You can fix this by modifying scripts/ at line #571.

virtualMemSizeKb = tokens[17]
# without this fix, no collection happens when ssh console open
if ( $virtualMemSizeKb == "domain" ); then