About Controller Upgrades

To upgrade the Controller, you run the installer for the version of the Controller to which you want to upgrade on the Controller machine. When a Controller instance is already present, the installer detects the instance and prompts you to upgrade that instance. If there are multiple Controller instances on the machine, the installer detects the last one installed.

The Controller installer supports upgrading from a given version to any later version, so you don't need to apply updates for each intermediate version to update the Controller by several versions. However, be sure to read the release notes for all intermediate versions to learn about the new features and known issues that may apply to you.

During an upgrade, the Controller does not process metrics from the agents because it is not running. You are not required to stop the agents during the Controller upgrade.

Prior to Upgrade

Read the Release Notes and Key Updates and Known Issues for any information that might affect your particular upgrade.
Back up your Controller home directory and data directory as described in Back up the Existing Controller.
Check the most recent Controller System Requirements to determine whether you need to update your systems and/or change your performance profile. See Hardware Requirements Per Performance Profile.
Review the Controller Sizing FAQ.
If you have changed any Glassfish settings that are not JVM options, note your changes. You will have to reset them after upgrade. Controller upgrade does not persist properties manually set in the domain.xml file or with the Glassfish asadmin utility. For related information see Modify GlassFish JVM Options.
The database user password storage mechanism changed in Release 3.8. If upgrading from 3.7.x or earlier, note these considerations related to the database user password:
- If you have not changed the Controller's database user password since the original installation, the upgrade should work with no additional intervention required.
- If you have removed the password from the file where it was stored before 3.8, <Controller_install_dir>/.install4j/response.varfile, and don't provide the password as a command-line argument to the installer or in the response file, you will be prompted to provide the password during the upgrade. In this case, you need to copy the password from the old response.varfile file prior to upgrading, and enter that password during upgrade. Alternatively, you can pass the password to the installer:
  - As a command-line argument to the installer, using -VmysqlRootUserPassword=<newpassword>, or
  - As the mysqlRootUserPassword variable in <Controller_Home>/.install4j/response.varfile.
- If you want to change the password, you must do it either after the upgrade or before. You cannot change the password through the installer during an upgrade.
For more information about how to change and administer the database user password, see Controller Data and Backups.

Back up the Existing Controller

Before applying an upgrade to the Controller, you must back up the existing installation. If the upgrade does not finish successfully for any reason, you will need to use the backup files to restore the installation to its previous state. Do not attempt to upgrade again without restoring the installation. See Troubleshooting the Upgrade for more information.

You need to back up the existing Controller home and the data directory for the Controller. Be default, the data directory resides under the Controller home in the db directory.

To back up the Controller instance

Stop the Controller application server and database.

For Linux, run:

<controller_installation_directory>/bin/controller.sh stop-appserver
<controller_installation_directory>/bin/controller.sh stop-db

For Windows, run the following command in an elevated command prompt (right-click on the Command Prompt icon in the Windows Start menu and choose Run as administrator):
```
<controller_installation_directory>\bin\controller.bat stop-appserver
<controller_installation_directory>\bin\controller.bat stop-db
```

Back up the Controller home by copying the entire Controller home directory to a backup location. Note the following points:
- If the data home for the Controller is not under the Controller directory, be sure to back up the database directory as well.
- If it's not possible to back up the entire data set, you can selectively back up the most important tables. To do so, use the Metadata Backup SQL script described and attached to the Controller Data Backup and Restore page.

Apply the Upgrade

The following steps describe how to upgrade the Controller on Windows and Linux. To upgrade a Controller that is running as a service on Windows, see Install the Controller as a Windows Service.

You use the Controller installer in GUI mode, console mode, or silent mode to perform the upgrade.

If using silent mode to apply the upgrade, pass the response file that the installer generated at first installation to the installer. This response file is at the following location

<Controller_home_directory>/.install4j/response.varfile

If you have made any changes to the settings as originally configured by the installer—such as to the connection port numbers, tenancy mode, or data directory—you must make the same change in the response file before starting the upgrade.

You must also add the existing root user password to˜ the file, rootUserPassword and rootUserRePassword. If you do not, the installer prompts you to add the password.

To upgrade the Controller

Download the latest release from AppDynamics Download Center.
If you prefer to use the Linux shell, see Downloading from the Linux Shell.
If they are running, stop the Controller application server and database. The Controller cannot be running during the upgrade. No data is collected from the time you shut down and start the new version of the Controller.
- For Linux, run:
```
<controller_installation_directory>/bin/controller.sh stop-appserver
<controller_installation_directory>/bin/controller.sh stop-db
```
- For Windows, run the following command in an elevated command prompt (right-click on the Command Prompt icon in the Windows Start menu and choose Run as administrator):
```
<controller_installation_directory>\bin\controller.bat stop-appserver
<controller_installation_directory>\bin\controller.bat stop-db
```
Launch the Controller installer. On Windows, be sure to start the Controller installer in an elevated command prompt by right-clicking on the Command Prompt icon in the Windows Start menu and choosing Run as administrator. (For more information on launching the installer on Windows, see Install the Controller on Windows.)
Confirm that the installation directory is the same as the previous Controller installation directory on this machine. The Controller will automatically migrate the data only when the existing installation directory is specified. Once the installer detects the old version of the Controller in that location, it will perform an upgrade instead of doing a fresh install.
The installer completes the upgrade and restarts the Controller.
(Optional for Windows) If you want to install the Controller as a Windows service, see Install the Controller as a Windows Service.
If you made any manual changes to the configuration files listed, re-apply those changes to the equivalent files in the upgraded instance. The installer does not automatically propagate changes you have made to those files.
Contact Technical Support if you have questions about mapping configuration changes across versions.
Open a browser and access the AppDynamics user interface:
```
http://<Controller_Host>:<Controller_Port>/controller
```
If the UI does not display the new Controller, refresh your browser cache to view the new UI.

To upgrade Controllers configured in HA mode

If you configure the high availability mode for the AppDynamics Controller, you must upgrade both the primary and the secondary Controller.

On the secondary Controller, stop the application server:

<controller_installation_directory>/bin/controller.sh stop-appserver

Upgrade the primary Controller using the instructions provided in the To upgrade the Controller. Be sure to back up the existing files.
When you upgrade the primary Controller, the schema changes are replicated to the secondary Controller. Then, when you launch the Controller installer on the secondary Controller, the installer checks the schema version and, because the schema version is the same as the new version, the installer skips any schema upgrades and only upgrades software for the secondary Controller.
Verify that on the secondary Controller all the data has been replicated correctly.
1. Open a command line utility and go to the <controller_installation_directory>/bin directory.
2. Log into the secondary Controller database:
  - For Linux, run:
    controller.sh login-db
  - For Windows, run the following command in an elevated command prompt (right-click on the Command Prompt icon in the Windows Start menu and choose Run as administrator):
    controller.bat login-db
3. Execute following command:
```
SHOW SLAVE STATUS\G
```
  This step should provide you following result:
```
Seconds_Behind_Master: $Number_Of_Seconds_Behind_Master
```
  If you get a non-zero number for this test, wait until the number becomes zero.
Start the application server for the secondary Controller:
1. Navigate to the <controller_installation_directory>/bin directory.
2. Use following command to start the application server for the Controller:
  - For Linux, run:
    <controller_installation_directory>/bin/controller.sh start-appserver
  - For Windows, in an elevated command prompt, run:
    <controller_installation_directory>\bin\controller.bat start-appserver
Upgrade the secondary Controller using the instructions provided in the To upgrade the Controller.
Stop the application server for the secondary Controller.
1. From the command line, go to the secondary Controller's <controller_installation_directory>/bin directory.
2. Use following command to stop the application server for the secondary Controller:
  - For Linux, run:
    controller.sh stop-appserver
  - For Windows, in an elevated command prompt, run:
    controller.bat stop-appserver

Both the primary and secondary Controllers are now upgraded.

Troubleshooting the Upgrade

The installer attempts to restart the Controller and database after applying an update or installation. For large databases and depending on the system resources, this can take a considerable amount of time. If the Controller installer cannot finish starting up the Controller within a set time-out period (30 minutes by default), it exits the installation or upgrade.

If the upgrade does not succeed for any reason, the installer does not roll back changes on disk. This give you an opportunity to diagnose and troubleshoot the issue before reattempting the installation or upgrade.

To troubleshoot the issue, check the installation log at <Controller_home>/.install4j/installation.log, along with any other Controller log files.

After diagnosing the issue, you need to manually revert the installation back to its state prior to starting the upgrade. To do so, replace the existing Controller directory and data home directories with the backup directories you created before starting the upgrade. Then apply your remediation changes, and restart the update or installation.

If necessary, you can increase the default time out period for system startup in the installer. To do so, set the ad-timeout-in-min property to the new time in minutes in the response.varfile under Controller_home/.install4j directory or from the command line as an argument to the installer.

Learn More

Upgrade the Controller