Downloading and installing the server

While logged on as the root user (root permissions are required to install and run the Cloud APM server), complete the following steps to download, decompress, and install the server and supporting components on a Red Hat Enterprise Linux system:

1. Download the Cloud APM server installation image from the download site to a staging location of your choosing.
   See Downloading from Passport Advantage.
2. If you plan to configure the agent images or Hybrid Gateway image (or both) during the server installation, download the images to the same system where the server will be installed.
   For details, see Download instructions.
3. Extract the server installation files for your offering:

   IBM Cloud Application Performance Management, Advanced Private

   advanced_8.1.4.0.tar

   IBM Cloud Application Performance Management, Base Private

   base_8.1.4.0.tar

4. Go to the directory where you extracted the server installation files.
5. Verify that the default permissions are set correctly. 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

6. 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.)
7. If you chose to use a remote Db2® database rather than install a Db2 server locally with the Cloud APM server (Connecting to a remote Db2 server) and you created the Cloud APM databases with Db2 authentication set to server_encrypt rather than the default server, take the following steps:
   1. Change to the directory where you decompressed the Cloud APM server installation tar file.
   2. Edit the install.properties file to set db2.authentication=server_encrypt.
8. If you chose to use a remote Db2 database rather than install a Db2 server locally with the Cloud APM server and you created databases with custom names on the remote Db2 server, complete the following steps:
   1. Login as the db2apm user on the Cloud APM server.
   2. If you are not using the default database names, you must create alias catalog entries for the default names to reference your database names. Catalog the node and databases, for example:

      db2 CATALOG TCPIP NODE APM5 REMOTE 9.42.13.5 SERVER 50005

      where:

      • APM5 is the node name. Use any name (up to 8 characters) except APM_NODE because Cloud APM uses the APM_NODE name.
      • 9.42.13.5 is the IP address or hostname of the remote Db2 server.
      • 50005 is the port number configured for the Db2 instance on the remote Db2 server.
   3. If the default entries are already cataloged from a previous install, uncatalog the default databases as follows:

      db2 uncatalog db warehous
      db2 uncatalog db datamart
      db2 uncatalog db scr32
      

   4. Catalog your database names as the new default database names:

      db2 CATALOG DB WHOUS5 as WAREHOUS at NODE APM5 
      db2 CATALOG DB DMART5 as DATAMART at NODE APM5
      db2 CATALOG DB SCR5 as SCR32 at NODE APM5
      

      where WHOUS5 is your name for the WAREHOUS database. DMART5 is your name for the DATAMART database. SCR5 is your name for the SCR32 database. APM5 is the node that you created in step 8.b.

      Note: If you added db2.authentication=server_encrypt to the install.properties file in step 7.b, then append authentication server_encrypt to each db2 CATALOG command.
   5. Test the connection to the remote database, for example:

      db2 connect to  warehous user itmuser
      db2 terminate 
      

      Output similar to the following is displayed:

      [db2apm@APM814c ~]$ db2 connect to warehous user itmuser
      Enter current password for itmuser:
      
         Database Connection Information
      
       Database server        = DB2/LINUXX8664 10.5.6
       SQL authorization ID   = ITMUSER
       Local database alias   = WAREHOUS
      
      [db2apm@APM814c ~]$ db2 terminate
      DB20000I  The TERMINATE command completed successfully. 
      

   6. Login as the root user on the Cloud APM server.
   7. Locate the install.properties file in the installation media package. It is in the same directory as the install.sh script. Save a backup copy of the file and then edit it. In the file there are three lines that contain the names of the Cloud APM databases:

      datamartdb.name=DATAMART
       metriccachedb.name=WAREHOUS
       topologydb.name=SCR32 
      

      Change the names to match your database names and save the file:

      datamartdb.name=DMART5
       metriccachedb.name=WHOUS5
       topologydb.name=SCR5 
      

9. Install the Cloud APM server on the virtual machine or your computer system:
   1. The TMOUT environment variable should not be set when the Cloud APM server install.sh script is executed because it may cause the install process to exit before the install has completed. To confirm that the variable is not set, perform these steps:

      Enter the following command and confirm that the TMOUT environment variable is not set:

      env | grep TMOUT

      If the variable is set then enter this command to unset it:

      unset TMOUT

      If the unset command fails then your OS administrator may have defined the TMOUT variable as read-only so work with your administrator to unset it before you install the Cloud APM server. You can set the TMOUT environment variable back to its original value after the Cloud APM server install completes.

   2. 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 to be 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 -v.
   3. When asked whether you want to upgrade from an existing installation, enter 2 (no).
      The installer checks for an existing installed offering and the offering you are installing now, and requests confirmation that you want to continue.
   4. Review the offering that is displayed and enter 1 (yes) to continue with the installation or 2 (no) to stop the installation.
   5. 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.
   6. When you are asked whether you accept the license agreement, enter 1 to accept the agreement and continue, or enter 2 to decline.
   7. 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.
   8. When you are asked whether you want to configure your agent installation images, data collector 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, data collector, and Hybrid Gateway images.
   9. 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, data collector images, and Hybrid Gateway (if used) are stored.
        The agent images, data collector 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 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 images to be stored.
      • If you accepted the default directory for storing the configured agent, data collector, and Hybrid Gateway images, the installer creates the directory install_dir/ccm/depot for storing the configured agent, data collector, 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.

   10. When you are prompted to enter the IP address and host name that the agents will use 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.
   11. 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 Cloud APM console. This value corresponds to the address that users enter to start the Cloud APM 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.
   12. 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), complete the following steps:

       • You are prompted to provide or accept the default values for the hostname/IP address and port number Db2 parameters to establish the connection.
       • Enter the password for the itmuser that you created when you set up the remote Db2 system.
       • Enter the remote external_db2_instance user name or accept the default db2apm name.

         where external_db2_instance is the remote Db2 server instance user name that you created when you set up the remote Db2 server.

       • Enter the password for this external_db2_instance user.

       If you entered 1 and transparent LDAP is configured for this system, the server installation fails. For more information, see Installing the Cloud APM server on a computer system where LDAP authentication is used.

   If the installer detects any agent configuration packages in install_dir/ccm/depot from a previous installation of the Cloud APM 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 Cloud APM 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 about the yum provides feature_name and yum install feature_name commands, see Dependencies. If the prerequisite scan detects that the RPM database is corrupted, the rpm.dbStatusCorrect property returns a FAIL status. For a possible solution, search the IBM Support Forums for Cloud Application Performance Management .
10. If the Cloud APM server installation fails, review the log messages displayed by the install.sh script and correct any problems identified by the prerequisite scanner.
    • If you need help from IBM support, run the install_dir/ccm/collectLogs.sh script and provide the output file.
    • If you want to re-install the Cloud APM server, perform these steps:
      1. Run the install_dir/ccm/uninstall.sh script on the Cloud APM server.
      2. If the Cloud APM server install failed after the prerequisite scanner ran and you configured the server to use a remote Db2 server, you must drop the three Cloud APM server databases and recreate them before re-installing the Cloud APM server. Perform steps 2.k through 2.q in Connecting to a remote Db2 server to drop the databases and recreate them.
      3. Re-install the Cloud APM server, starting with step 4.