PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
71 rates

This topic describes how to install the AppDynamics Controller on Microsoft Windows and Linux operating systems for an on-premises deployment of the AppDynamics Application Intelligence Platform. If using a SaaS Controller, the Controller is installed and administered for you. 

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 runs 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. 

Before Starting

  • Run the installer as a user that has write permissions to the destination directory. Note that 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 -Djava.io.tmpdir=<alternate_dir_path>
  • 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 for Linux and Windows. 

Linux notes

  • 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
  • The user account that performs the installation requires read/write/execute permissions on the directory where you install the Controller and write permission on the /etc/.java/.systemprefs directory
  • If you are installing other AppDynamics 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. 
  • On Linux systems, port numbers below 1024 may be considered privileged ports that require root access to open. The default Controller listen ports are not configured for numbers under 1024, but if you intend to set them to a number below 1024 (such as 80 for the primary HTTP port), you need to run the installer as the root user.   

For more information about the Linux notes, see Configure Linux for the Controller

Windows notes

  • 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. 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

Amazon AWS and Microsoft Azure notes

  • When you install the controller, use the fully qualified host name for the application server that users and agents will use to access the controller.  
  • Verify that the fully qualified host name is in the /etc/hosts file. The following example shows an entry in /etc/hosts with the IP 21.43.65.987, the fully qualified host name application1.mycompany.com, and the alias app1: 

    21.43.65.987 application1.mycompany.com app1

Installing with the GUI Installer  

On Linux:
  1. At a command line, navigate to the directory to which you downloaded the installer
  2. Assign execute permissions to the downloaded installer script. For example:

    chmod 775 controller_64bit_linux.sh

     

  3. Run the installer script. For example:

    ./controller_64bit_linux.sh

     

On Windows: 
  1. Open an elevated command prompt (run as administrator).

  2. Run the downloaded installer binary you downloaded. For example:

    controller_32bit_windows.exe

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: 

./controller_64bit_linux.sh -c

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...
    controllerConfig=demo
    iiopPort=3700
    serverPort=8090
    serverHostName=demoserver #Specify the controller hostname instead of demoserver
    haControllerType=notapplicable
    controllerTenancyMode=single
    adminPort=4848
    sys.languageId=en
    jmsPort=7676
    sys.installationDir=/home/appduser/AppDynamics/Controller
    mysqlRootUserPassword=DRvYYv9eq6
    databasePort=3388
    userName=admin
    password=pa55word
    rePassword=pa55word
    sslPort=8181
    realDataDir=/home/appduser/AppDynamics/Controller/db/data
    elasticSearchDataDir=/home/appduser/AppDynamics/Controller/events_service/analytics-processor
    disableEULA=true
    rootUserPassword=pa55word2
    rootUserRePassword=pa55word2
    reportingServiceHTTPPort=8020
    reportingServiceHTTPSPort=8021
    elasticSearchPort=9200

    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...
    controllerConfig=demo
    iiopPort=3700
    serverPort=8090
    serverHostName=demoserver #Specify the controller hostname instead of demoserver
    haControllerType=notapplicable
    controllerTenancyMode=single
    adminPort=4848
    sys.languageId=en
    jmsPort=7676
    sys.installationDir=C\:\\AppDynamics\\Controller
    mysqlRootUserPassword=DRvYYv9eq6
    databasePort=3388
    userName=admin
    password=pa55word
    rePassword=pa55word
    sslPort=8181
    realDataDir=C\:\\AppDynamics\\Controller\\db\\data
    elasticSearchDataDir=C\:\\AppDynamics\\Controller\\events_service\\analytics-processor
    disableEULA=true
    rootUserPassword=pa55word2
    rootUserRePassword=pa55word2
    reportingServiceHTTPPort=8020
    reportingServiceHTTPSPort=8021
    elasticSearchPort=9200

     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:  

    ./controller_64bit_linux.sh -q -varfile /home/user/response.varfile
  • On Windows, similarly pass the path to the varfile. Run the command from an elevated command prompt. For example:

    controller_64bit_windows.exe -q -varfile C:\temp\response.varfile

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 LabelResponse File variableDescription
License Agreement

disableEULA

Scroll to the end of the license agreement and accept the agreement to continue the installation or do not accept to discontinue. Set to true in the response file to enable installation.

Consent to collect usage information

enableUDC

True to permit data statistics collection from your Controller. The data collected helps AppDynamics improve its products and services.

Destination directory

sys.installationDir

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

mysqlRootUserPassword

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

serverHostName

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

serverPort

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

databasePort

The port for the Controller database. If not specified, the installer uses the default, 3388.

Application Server Admin Port

adminPort

The application server's administration port. If not specified, the installer uses the default, 4848.

Application Server JMS Port

jmsPort

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

iiopPort

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

sslPort

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 PortrestAPIPortThe Events Server REST API port. This port is used for internal system communication. 9080 by default.
Events Service REST API Admin PortrestAPIAdminPortThe Events Server REST API admin port. This port is used for internal system communication. 9081 by default.
Events Service Elastic Search PortelasticSearchPortThe port on which the Elastic Search process listens. This port is used for internal system communication. 9200 by default.
Reporting Service HTTP PortreportingServiceHTTPPortThe reporting service HTTP port. This port is used for internal system communication. 8020 by default.
Reporting Service HTTPS PortreportingServiceHTTPSPortThe reporting service HTTPS port. This port is used for internal system communication. 8021 by default.
AppDynamics Controller Tenancy Mode Configuration

controllerTenancyMode

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

rootUserPassword

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.

Allowed characters in the password are: a-z, A-Z, 0-9, ., +, =, @, _, -, $, |, :, #, ,, %, (, ), !, {, }

Verify Controller root User's Password

rootUserRePassword

The root user password repeated for validation purposes.

User Name (Admin User Setup)

userName

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)

rePassword

The admin user password repeated.

Account Name

accountName

For multi-tenancy mode, the name for the initial account in the system.

In the response file, ignored if controllerTenancyMode=single.

Account Access Key

accountAccessKey

Your AppDynamics account access key.

AppDynamics Controller Performance Profile

controllerConfig

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

realDataDir

The path to the Controller's data directory.

Elastic Search data directoryelasticSearchDataDir

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

haControllerType

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.

n/a

sys.languageId

(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:

http://<application_server_host_name>:<http-listener-port>/controller

Log in using the credentials of the initial Controller administrator. 

Next Steps

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.

Verify that you have completed the following requirements based on your operating system: 

You may have completed some of the required configurations before you installed the Controller.  For example, you cannot install the Controller on Linux without libaio.

In addition to the required configuration, you can also configure the Controller to use Java 1.8.  By default, the Controller uses Java 1.7.  For more information about how to change the Java version, see Platform Version Information.

Watch the Video

For full-screen viewing, click Installing the Controller on Linux.

 


  • No labels