IBM Performance Management

Downloading and installing the server

The installation procedure involves downloading the Performance Management server installation media, extracting the installation files on the system, and running the installation script. Before installing the monitoring agents and, optionally, the IBM® Performance Management Hybrid Gateway, install the Performance Management server on a virtual machine or computer in your network that is running Red Hat Enterprise Linux.

Before you begin

If you are using a virus scan program (such as McAfee Virus Scan for Linux or Sophos), you must configure the virus scan program to exclude all DB2® database files; including storage groups, table spaces, and buffer pools. Configure the virus scan program before you install the Performance Management. The DB2 database files are installed in the <apm-server-home>/db2 directory by default, for example, /opt/ibm/db2.

About this task

Complete the following steps to download, decompress, and install the server and supporting components on a Red Hat Enterprise Linux system. If the agent and Hybrid Gateway installation images are downloaded to the same directory as the server installation image, the images can be configured during server installation.

Procedure

While logged on as the root user (root permissions are required to install and run the Performance Management server), complete the following steps:

Download the Performance Management server installation image from the download site to a staging location of your choosing. See Downloading from Passport Advantage.
If you plan to configure the agent images or Hybrid Gateway image (or both) during installation of the server, download the images to the same system where the server will be installed. For details, see Download instructions.
Extract the server installation files for your offering:
IBM Application Performance Management Advanced
```
tar -xf ipm_apm_advanced_8.1.3.tar
```
IBM Application Performance Management
```
tar -xf ipm_apm_8.1.3.tar
```
IBM Application Diagnostics
```
tar -xf ipm_app_diagnostics_8.1.3.tar
```
IBM Monitoring
```
tar -xf ipm_monitoring_8.1.3.tar
```
Go to the directory where you extracted the server installation files.
Verify that the default permissions are set correctly on the directory. Open a command prompt and enter umask.
A value of 0022 is returned if the permissions are set correctly. If any other value is returned, set the permissions by entering the following command:
```
umask 0022
```
If you want to change the protocol from the default HTTP to HTTPS (secure) communications, enter the following command:
```
export APM_SECURE_COMMUNICATION=y
```
(See Setting HTTP or HTTPS communications.)
Install the Performance Management server on the VM or your computer system:
1. Enter one of the following commands to run the installation script:
  - Install the server in the default /opt/ibm directory:
```
./install.sh
```
  - Install the server in a directory of your choosing:
```
./install.sh -d /custom/path/
```
    where /custom/path/ is the path to the directory where you want the server installed.
  - Install the server and view the output on the console:
```
./install.sh -v 
```
    The output is saved to the installation log file whether you choose the verbose (-v) option or not. You can enter both the directory (-d) and verbose (-v) options in the command: ./install.sh -d -h.
2. When asked whether you want to upgrade from an existing installation, enter 2 (no). The installer checks for any existing installed offerings and the offering you are installing now, and asks you to confirm that you want to continue.
3. Review the offering or offerings that are displayed and enter 1 (yes) to continue with the installation or 2 (no) to stop the installation.
4. If you are asked whether you want to change the default installation directory, enter 1 to specify a different directory or 2 to accept the default /opt/ibm.
5. When you are asked whether you accept the license agreement, enter 1 to accept the agreement and continue, or enter 2 to decline.
6. When you are prompted to change the default password for the administrator account, enter either 1 (yes) and create a new encrypted password, or 2 (no) to keep the default apmpass unencrypted password. If you change the password, keep a copy in a safe place; you cannot recover the password if you forget it. When you answer the prompt to change the administrator password, the installation continues.
7. When you are asked whether you want to configure your agent installation images and Hybrid Gateway installation image (if used) to connect to the server, enter either 1 (yes) to configure the images now or 2 (no) to defer configuration of the agent and Hybrid Gateway images.
8. If you entered 1 (yes), you are prompted to confirm the following information:
  - The path to the directory on the server where the agent images and Hybrid Gateway (if used) are stored.
    The agent images and Hybrid Gateway images can be mounted on an NFS partition but must be accessible using the file system.
  - Whether to change the directory for the configured agent installation images (1 - yes) or to accept the default install_dir/ccm/depot (2 - no). If you selected 1 (yes), enter the directory for the configured agent installation images to be stored.
  - If you accepted the default directory for storing the configured agent and Hybrid Gateway images, the installer creates the directory install_dir/ccm/depot for storing the configured agent and Hybrid Gateway images. However, if you chose to change the directory or if the installer fails to create the directory or the directory is not writable, you are prompted to specify the output directory.
  If you entered 2 (no), this step is skipped.
9. When you are prompted to enter the IP address and host name that will be used by agents to communicate with the server, enter the server IP address or host name for the agents and Hybrid Gateway to use. The format of the IP address can be IPv4 or the fully qualified domain name. You can change the IP address and host name later. See Changing the server IP address and host name.
10. When you are prompted for the following values, enter the values for the server that is used in a web browser to log in to the Performance Management console. This corresponds to the address that users enter to start the Performance Management console from their web browsers.
  - Fully qualified domain name, for example: myserver.example.com.
  - Short host name
  - IP address
  Tip: The fully qualified domain name and short host name are resolved by using DNS. If your system does not have good DNS resolution, enter the IP for all three values.
  You can change the IP address and host name later. See Changing the server IP address and host name.
11. When you are prompted to install the database or connect to an existing DB2 database, enter either 1 to install the default database or 2 to connect to an existing DB2 database.
  If you entered 2 (connect to existing database), you are prompted to provide or accept the default values for the following DB2 parameters to establish the connection.
  - hostname/IP address
  - port number
  - password for the itmuser user
  - password for the db2apm instance user
If the installer detects any agent configuration packages in install_dir/ccm/depot from a previous installation of the Performance Management server, it warns you that it renamed the old packages and created new agent packages. The old packages are named install_dir/ccm/depot.old.

If the installer detects a keyfiles directory in install_dir from a previous installation of the Performance Management server, it warns you that it renamed the old keyfiles directory and created a new directory. The old keyfiles directory is named install_dir/keyfiles.old.
A prerequisite scan of your environment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. A prerequisite such as a missing library or insufficient disk space stops the installation. You must address the failure and start the installation again. A soft prerequisite such as low available memory does not stop the installation, but you must enter 1 to continue installing or 2 to stop. For more information, including the yum provides feature_name and yum install feature_name commands, see Dependencies, and Prerequisite scanner properties.

Results

The installer installs the server components and support files; no further user input is required. After server installation, the installer configures the components, which can take 30 minutes or more to complete. The portion of the installation that involves creating and configuring the databases can take as little as 2 minutes or as much as 2 hours, depending on your hard drive I/O speed and drive caching.

Two server agents, the Monitoring Agent for Transactions Event and the Monitoring Agent for Synthetic Events, are installed and started automatically, regardless of which offerings you installed. The Tranactions Event agent provides services for transaction tracking and the Synthetic Events agent provides services for synthetic transactions.

After the Performance Management server is installed, you cannot change the permissions of the Performance Management files and directories. In addition, you cannot change the user or group owners of these files and directories.

What to do next

Ensure that the KQZ_JDBC_JAR_PATHS variable is set to the path where the DB2 client JDBC driver is located. This path depends on where you installed the DB2 IBM Data Server Client in step 3 in the Connecting to a remote DB2 server topic. If the KQZ_JDBC_JAR_PATHS variable is not set to the path where the DB2 client JDBC driver is located, then set the variable to this path now and restart the Transaction Event agent by completing the following steps:
- Go to the install_dir/serveragents/config directory. install_dir is the directory where the Performance Management server is installed.
- Back up the hostname_te.cfg file. hostname is the Performance Management server hostname.
- Open the hostname_te.cfg file and find the following line:
```
KQZ_JDBC_JAR_PATHS=/opt/ibm/db2/10.5/java
```
- Edit the path to point to where your JDBC driver jars are located. For example, if your IBM Data Server Client is installed in the default /opt/ibm directory, the path looks like the following line:
```
KQZ_JDBC_JAR_PATHS=/opt/ibm/db2/V10.5/java
```
- Save the hostname_te.cfg file.
- Restart the Transaction Event agent by issuing the following command:
```
apm restart txagent
```
  The Transaction Event agent connects to the remote DB2 database and the thresholds are working.
If you did not configure the agent installation images during installation of the server, follow the instructions in Configuring the installation images.
If you want to use the old agent configuration packages from a previous installation for the agent installation, complete these steps:
1. Go to the install_dir/ccm directory.
2. Delete the depot file.
3. Change the name of the depot.old file to depot.
If you want to use the old keystore from a previous installation for the Performance Management server, complete these steps:
1. Go to the install_dir directory.
2. Delete the keyfiles directory.
3. Change the name of the keyfiles.old directory to keyfiles.
4. Update the certificates that are used by the monitoring agents to connect to the Performance Management server to use the new keystore. For instructions, see Configuring certificates between the server and agents.
5. Update the certificates that are used by the server agents to connect to the Performance Management server to use the new keystore. For instructions, see Configuring certificates between the server and agents.
Install the agents on the systems where the applications that you want to monitor are installed, as described in Installing your agents.
If you forgot to set the correct password for itmuser before installation, run the script to provide the correct password. See Changing a password.
If you are having trouble reinstalling the server after uninstallation, check that the uninstallation was completed successfully. For more information about uninstalling the server, see Uninstalling the server.
If the server installation does not progress or complete after 30 minutes (or longer if your hard drive I/O speed is slow), review the most recent install_dir/ccm/logs/apm-server-yyyymmdd_hhmmss.log file where install_dir is the server installation directory, yyyymmdd is the year, month, and day, and hhmmss is the hour, minute, and second.
- If the last log entry is MongoDB Upstart script installed, the Upstart initialization process might be unable to restart a stopped service and you might need to restart the computer or VM. For more information, visit IBM Performance Management Forum on IBM developerWorks®and search for Upstart.
- If the last log entry is Creating and configuring databases, check the log again after two hours before restarting the computer or VM.
- If you see that the Creating and configuring databases process has completed or has not started yet, you might need to restart the computer or VM.
If you have another Performance Management server installed with agents that connect to it, you can change the agents on each managed system to connect to your newly installed server. For more information, see Connecting agents to a different server.