This topic describes how to install the AppDynamics Controller on Microsoft Windows and Linux operating systems for an on-premise deployment of the AppDynamics Application Intelligence Platform. You do not need to install the Controller if you are using a SaaS Controller.
About the Controller Installer
The AppDynamics Controller installer is an executable binary file that you can run in the following modes:
- GUI: The installer presents a graphical interface for performing the installation. By default, the installer run in GUI mode. If the operating system is not set up to display the GUI, it will start in console mode. In order to launch the installer in GUI mode on Linux, it must have X Terminal support.
- Console: The installer runs interactively in the console window.
- Silent: The installer runs non-interactively, taking installation options from a response file.
All software components required for Controller installation are bundled with the installer, so you do not normally need to install additional software to install the Controller.
During installation you configure several accounts for the Controller, including the database account, a root user in the Controller, and an administrator in the Controller.
Usernames and passwords should not include the @, !, or & characters. If a user account needs to access the Controller REST API, additional limitations on the use of special characters in usernames apply. See Users and Groups for more information.
- AppDynamics strongly recommends that you run the Controller on a dedicated machine. See Supported Environments and Versions for supported operating systems.
- The target machine must meet the requirements described in Controller System Requirements based on the number of agents you plan to deploy. In particular, make sure that Disk I/O capacity for the profile is sufficient. Run the Disk I/O measurement tests described at To measure available Disk I/O.
- Run the installer as a user that has write permissions to the destination directory. If installing other components of the platform, such as the EUM Server or Analytics Processor, you should install all components as the same user or as a user with equivalent permissions.
- During installation and setup, the installer tries to start the Controller. This procedure can take some time. If startup exceeds the 30 minute default timeout, the installer exits but leaves changes on disk, allowing you to troubleshoot the issue. When finished troubleshooting, you will need to replace the installation directory with the backup directory, apply the troubleshooting remediation, and restart the installation. Optionally, you can extend the timeout by passing the ad-timeout-in-min command line parameter with the new value in minutes to the installer.
- The installer writes temporary files to the system temporary directory, typically /tmp on Linux or c:\tmp on Windows. The installer requires 1024 MB of free temp space. It checks for available space before proceeding, and quits with an "out of space" error if not. On Windows, in case of this error, you can set the temporary directory environment variable to a directory with sufficient space for the duration of the installation process. You can restore the setting to the original temp directory when installation is complete. On Linux, you can pass an alternate directory for the installer to use as a temporary directory as an argument to the installer. Use the format
- A time synchronization service, such as the Network Time Protocol daemon (ntpd), should be enabled on the Controller target machine.
- Ensure that no MySQL processes are running when you install the Controller.
Also note the following platform-specific requirements.
- Install the Controller on a 64-bit Linux system if you plan to use a Medium, Large, or Extra Large Performance Profile. For details see Controller Performance Profiles.
- For the Extra Large profile, AppDynamics recommends either the XFS, ZFS, or EXT4 file systems with RAID. Additionally, you should tune your operating system as described in Tuning for Large Scale Deployments.
- The Controller requires the libaio library to be present on Linux machines. See information on installing libaio on Linux in Configure Linux for the Controller.
- Make sure the file descriptor limit is set to at least 65535. See information on limiting file descriptors on Linux in Configure Linux for the Controller.
- Be sure to perform the installation as a user that has read/write/execute permissions on the directory where you install the Controller.
- If you are installing other AppDynamics Application Intelligence Platform server components, such as the EUM Server or Application Analytics Processor, on the same machine, it is recommended that you perform the installation as the same user or a user with the same permissions on the target machine.
- The target machine will need to be accessible by network to the machines on which agents and browsers accessing the AppDynamics UI are run.
- Verify that you have administrative privileges on the Windows machine to launch the Controller installer.
Components of the .NET Framework 3.5 are required to allow the Controller to be installed as a Windows service on the target machine. The installer checks your system and indicates if .NET 3.5 is not found on your system. Follow the instructions on the installer to get the required components.
The Controller is automatically installed as a Windows service. Windows 7 or Server 2008 R2 operating systems must have the hotfix described in http://support.microsoft.com/kb/2549760. This hotfix ensures that the Windows registry modifications made by the installer to extend the default service timeouts work as expected. The installer checks for the presence of the hotfix and warns you if it is not found.
After installation, you will need to configure virus scanning, Windows defender, and the Windows indexing service to ignore the AppDynamics database directory, as described in Configure Windows for the Controller.
- Never stop the Controller or its individual services (the AppDynamics Application service or AppDynamics Database services) from the task manager. To stop and restart the AppDynamics processes, open an elevated command prompt (run as administrator) and run the scripts for starting and stopping the service, as documented in Start or Stop the Controller.
Installing with the GUI Installer
- At a command line, navigate to the directory to which you downloaded the installer
Assign execute permissions to the downloaded installer script. For example:
Run the installer script. For example:
Open an elevated command prompt (run as administrator).
Run the downloaded installer binary you downloaded. For example:
Follow the instructions in the wizard to complete the installation. See installation options for additional information on the various screens and fields in the installer.
Installing in Console Mode
In console mode, the installer presents the installation configuration options in its command line interface. Functionally, this installation mode is equivalent to using the GUI installer or the silent mode installer.
To start the installer in console, use the -c switch when starting the installer. For example, on Linux, enter:
Follow the on-screen prompts to complete the installation. See installation options for more information on the various screens and fields in the installer.
Installing in Silent Mode (Response File)
To start the installer silent mode, use the -q option and pass a response file as the value of the varfile argument. The response file should contain the installation options for your instance.
Before starting, create and configure the response file. The following provide example response files for each operating system.
Linux response file:Click here to expand...
Be sure to set the values for the properties in the file, such as the controllerConfig, hostname, passwords, for your environment.
Windows response file:Click here to expand...
Be sure to set the values for the properties in the file, such as the controllerConfig, hostname, passwords, for your environment.
When ready, start the installer with the -q switch and passing the response file as the -varfile argument.
On Linux, for example, the command would be similar to:
On Windows, similarly pass the path to the varfile. Run the command from an elevated command prompt. For example:
See the following section, for more information on the options you can configure in the response file.
Installation Configuration Settings
Whether running the installer in GUI mode, console mode, or by passing a response file, the options you have while performing the installation are the same.
The installer does some basic system checking of your environment as it performs the installation. It notifies you if it encounters conditions that need to be addressed.
The installer configures listening ports for Controller. In GUI and Console mode, the installer checks to make sure that each port it suggests is available on the system before suggesting it. If a default port number is already in use, it chooses the next highest available number for the port. For example, if the usual default port of 8090 for the Controller application server is taken, the installer suggests 8091. You only need to edit a default port number if you know it will cause a future conflict or if you have some other specific reason for choosing another port.
Due to browser incompatibilities, AppDynamics recommends using only ASCII characters for usernames, passwords, and account names.
Configure your installation using these response file settings:
|GUI Mode Screen or Option Label||Response File variable||Description|
Scroll to the end of the license agreement and accept the agreement to continue the installation or do not accept to discontinue. Set to
|Consent to collect usage information|
True to permit data statistics collection from your Controller. The data collected helps AppDynamics improve its products and services.
Directory in which to install the Controller. If not specified, it is installed into the default directory of the target environment, such as AppDynamics/Controller under the user's home on Linux systems.
|Database Root User's Password|
The password of the user account that the Controller uses to access its MySQL database. Do not use the "!", "|", or "$" characters in this password.
|Application Server Host Name|
Server host name or IP address that AppDynamics agents and the AppDynamics UI use to connect to the Controller. Note that "localhost" and "127.0.0.1" are not valid settings.
This will be the host name (or IP address) that AppDynamics app agents and Controller UI browser clients use to connect to the Controller.
|Application Server Primary Port|
The primary HTTP port for the application server. If not specified, the installer uses the default, 8090, if it is available on the current machine. If is not available, the installer suggests the next available port number.
This will be the port that AppDynamics app agents and Controller UI browser clients use to connect to the Controller.
|Database Server Port|
The port for the Controller database. If not specified, the installer uses the default, 3388.
|Application Server Admin Port|
The application server's administration port. If not specified, the installer uses the default, 4848.
|Application Server JMS Port|
The application server's JMS port. This port is used for internal system communication. If not specified, the installer uses the default, 7676.
|Application Server IIOP Port|
The application server's IIOP port. This port is used for internal system communication. If not specified, the installer uses the default, 3700.
|Application Server SSL Port|
The secure HTTP port for the application server. If not specified, the installer uses the default, 8181. This is the secure alternative to the application server primary port. By default, it uses a built-in, self-signed certificate. For a production deployment, you should install a CA-signed certificate.
|Events Server REST API Port||restAPIPort||The Events Server REST API port. This port is used for internal system communication. 9080 by default.|
|Events Service REST API Admin Port||restAPIAdminPort||The Events Server REST API admin port. This port is used for internal system communication. 9081 by default.|
|Events Service Elastic Search Port||elasticSearchPort||The port on which the Elastic Search process listens. This port is used for internal system communication. 9200 by default.|
|Reporting Service HTTP Port||reportingServiceHTTPPort||The reporting service HTTP port. This port is used for internal system communication. 8020 by default.|
|Reporting Service HTTPS Port||reportingServiceHTTPSPort||The reporting service HTTPS port. This port is used for internal system communication. 8021 by default.|
|AppDynamics Controller Tenancy Mode Configuration|
The tenancy mode: single or multi. Single tenancy is recommended for most installations. See Controller Tenant Mode and Accounts for more information.
Multi-tenancy allows you to partition the AppDynamics environment into separate accounts in the UI.
|Controller root User's Password|
The Controller root user password. The root user is a Controller user account with privileges for accessing the system Administration Console.
This password is used for the admin user of the built-in Glassfish application server as well. The Glassfish admin user lets you access the Glassfish console and the asadmin utility. See Access the Administration Console for more information about the console.
|Verify Controller root User's Password|
The root user password repeated for validation purposes.
|User Name (Admin User Setup)|
The username of the administrator account in the Controller UI. This is the administrator for the built-in account if single-tenant systems, or for the initial account for multi-tenant. See AppDynamics Administrator.
Usernames and password cannot include the @ or ! character.
Also note that if this account will be used to access the REST API, additional limitations on the use of special characters in usernames apply. See Users and Groups for more information.
|Password (Admin User Setup)||password|
The admin user password.
|Verify Password (Admin User Setup)|
The admin user password repeated.
For multi-tenancy mode, the name for the initial account in the system.
In the response file, ignored if controllerTenancyMode=single.
|Account Access Key|
Your AppDynamics account access key.
|AppDynamics Controller Performance Profile|
The performance profile type for the instance. See Controller Hardware Requirements for information about how the types correspond to sizes.
The installer limits the choice of profiles to Demo and Small profile on 32-bit systems. When you submit your choice in GUI or console mode, the installer checks your system for minimum requirements and warns you if any are not met.
In the response file, use demo, small, medium, large, or extra-large for the profile types.
|MySQL data directory|
The path to the Controller's data directory.
|Elastic Search data directory||elasticSearchDataDir|
The path to the Elastic Search file store. Elastic Search is used by Database Monitoring features. By default, the directory is located in the Controller home. However, if you are putting the MySQL data directory in an alternate location, such as on a separate partition, the Elastic Search data directory would likely need to be put there as well.
If you are not sure whether you will use database monitoring, you can keep the default location for now and change the data directory location later, if needed, in the events_service/analytics-processor/conf/analytics-all.properties file.
|AppDynamics Controller High Availability Configuration|
The high availability mode for this instance. For more information see Controller High Availability.
In the response file, use primary, secondary, or notapplicable. If not specified, defaults to notapplicable, which means that HA is not enabled.
(Response file only). The language identifier for the system. en by default.
Verifying the Controller Installation
When the installation is finished, a status screen in the installer indicates that the installation is complete and the Controller is started.
Verify by navigating in a browser to the URL of the Controller UI:
Log in using the credentials of the initial Controller administrator.
To access the Controller UI, you need to have a valid license. For a trial installation, the license file (license.lic) is bundled in your download. Otherwise, you may have acquired the license file from AppDynamics.
To apply a license file manually, copy the license file to the Controller home directory. After moving the license file, allow up to 5 minutes for the license change to take effect.
Complete the set up by ensuring or configuring these requirements:
- For Linux, see Configure Linux for the Controller.
- For Windows, see Configure Windows for the Controller.