Upgrading the server on the same system

While logged in as the root user on the system where your V8.1.3 Cloud APM server is installed, complete these steps to upgrade your server to V8.1.4 on the same system:

Download and extract the V8.1.4 Cloud APM server installation image

1. Download the V8.1.4 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, the Hybrid Gateway image, or both during the server upgrade, download the images.
   For more information, see Download instructions.
3. Extract the server installation files for your offering.
   In V8.1.4, two offerings are supported instead of four offerings that were supported in the V8.1.3 release. These offerings are:

   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

   The IBM Cloud Application Performance Management, Base Private offering now includes the V8.1.3 IBM Monitoring offering capability and the IBM Cloud Application Performance Management, Advanced Private offering now includes the capability of the other three V8.1.3 offerings. You must use the V8.1.4 offering file that matches the offering that was installed on the V8.1.3 Cloud APM server for the upgrade.
   For example, if IBM Monitoring was installed in the V8.1.3 Cloud APM server, you must use the V8.1.4 IBM Cloud Application Performance Management, Base Private offering file to complete the upgrade.

Download and install the V8.1.3 patch on your V8.1.3 Cloud APM server

4. Install the V8.1.3 patch on your V8.1.3 Cloud APM server:
   1. Download the V8.1.3 interim fix 16 (8.1.3.0-IBM-IPM-SERVER-IF0016) or later patch from IBM Fix Central on the IBM support site.
   2. Copy the 8.1.3.0-IBM-IPM-SERVER-IF0016.tar file to your V8.1.3 Cloud APM server and complete these steps on the V8.1.3 Cloud APM server.
      1. Extract the patch package:

         tar xvf 8.1.3.0-IBM-IPM-SERVER-IF0016.tar

      2. Run the following script to apply the patch:

         apmpatch.sh

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

Back up your V8.1.3 Cloud APM server and then uninstall the server

6. Run the following command as user root to back up your V8.1.3 interim fix 16 or later Cloud APM server installation.

   install_dir/ccm/backup.sh [-f ~/backup813.tar]

   where install_dir is the directory where you installed the V8.1.3 interim fix 16 Cloud APM server. Include the -f option when you want to specify the path and file name for the server backup. For example, ~/backup813.tar saves to /root/backup813.tar. The default path is /opt/ibm/backups/backup_yyyymmdd_hhmmss.tar, such as /opt/ibm/backups/backup_20160826_155605.tar.

   Important:

   • If your MongoDB was installed on a remote system, use the backup file that you created when you upgraded MongoDB instead. For more information, see Installing MongoDB V3.2.12 on your remote system.
   If your existing V8.1.3 server is configured with a non-default user name for the Cloud APM user interface administrator account, you must run the following backup.sh script as user root:

   install_dir/ccm/backup.sh [-f ~/backup813.tar] 
   -u uiadmin_username -p uiadmin_password

   For example, if the Cloud APM UI administrator user name is uiadmin and the non-default password for this user is uiadminpwd, enter the following command:

   install_dir/ccm/backup.sh -u uiadmin -p uiadminpwd

   Note:

   • If you do not want the password to be visible by other users, you can use environment variables to provide the password and the user name by entering the following commands:

     export APMADMIN_USERNAME=uiadmin

     export APMADMIN_PASSWORD=uiadminpwd

     Then, run the backup.sh script as user root by entering the following command:

     install_dir/ccm/backup.sh [-f ~/backup813.tar]

     The Cloud APM UI administrator's user name and password is read from the backup during the restore phase.
   • If your Cloud APM server is connected to a remote Db2 server, you can ignore the warning to run the backup script on the remote Db2 server server.

   Output messages inform you of the backup progress, backup path, and file name upon completion.

7. Uninstall your V8.1.3 Cloud APM server:
   1. Run the following command in the /opt/ibm/ccm directory (or /custom_path/ccm if you installed the server in a different path):

      ./uninstall.sh

   2. Review the list of installed Cloud APM offerings and enter the number that uninstalls all the offerings (the whole product) or enter q (quit) to cancel the uninstall operation.

If your Cloud APM server connects to a remote Db2 server, back up databases and update the SCR database

8. If your Cloud APM server is connected to a remote Db2 server, complete these steps as root user:
   1. As Db2 instance user db2apm on the system where Db2 is installed, back up the DATAMART, WAREHOUS, and SCR32 databases.

      If the database administrator who is managing the remote Db2 server does not have procedures for backing up the database, run the Cloud APM server backup script:

      1. Copy /tools/backup.sh from the V8.1.4 Cloud APM server installation image to the remote Db2 server.
      2. As user root and Db2 instance user db2apm, enter the following commands on the remote Db2 server:

         
         chmod 755 backup.sh

         
         ./backup.sh [-f ~/backup814.tar]
         

         If your Db2 server is running on AIX, you must run the backup.sh script in the bash shell. If the bash shell is not installed on your Db2 server, download the rpm for bash from the AIX Toolbox for Linux Applications.

   2. Copy the setup-dbconfig-platform_64.bin script from the packages/SCR directory of the V8.1.4 Cloud APM server installation image to the remote Db2 server system.
   3. If you are not already logged in as db2apm, enter:

      su - db2apm

   4. Run the setup_dbconfig-platform_64.bin script to set up the SCR32 database where platform is either AIX or Linux.
      Run the script as the same Db2 instance user db2apm who ran the script during the creation of the V8.1.3. SCR database. Do not run the script as user root.

      /path/setup-dbconfig-linux_64.bin -i console

      Follow the console prompts:

      1. When you are prompted to choose a locale, enter 2 to select English.
      2. Enter 1 to accept the license agreement.
      3. Enter the absolute path to the installation folder or press Enter to accept the default path. The default path is the setup-dbconfig installation path for V8.1.3. Do not change this path, unless the path is incorrect. In this procedure, this path is referred to as /opt/ibm/db2/tbsmdb.

         The Cloud APM SCR database configuration tools installed by the setup_dbconfig-platform_64.bin script should not be installed into the same directory as the Tivoli Business Service Manager database configuration tools if the databases for both products reside on the same remote Db2 server.

      4. Enter 1 to select IBM Cloud Application Performance Management(APM) as the product that uses the database.
      5. Enter 1 to select Simple as the type of installation to run.
      6. Enter 2 to instruct the installer not to create the database schema, including the tables, table spaces, and views.
      7. Enter the following database configuration details when you are prompted:
         • Database Name (maximum 8 characters) (DEFAULT: SCR32): SCR32
         • Database host name or IP address (DEFAULT): hostname_or_IP_address
         • Database Port (DEFAULT: 50000): port
         • Database Path (Default: <default>): default_path
      8. Create an encrypted database (only applicable on Db2 for Cloud V10.5 fix pack 3 or later). Press Enter and accept the default selection that is displayed.
   5. Upgrade the database schema and Java UDF routines in the Db2 SCR database.
      Enter:

      
      cd install_path/tbsmdb/tools/XMLtoolkit/bin
      ./scr_restore.sh -U db2apm -P passw0rd -n
      

      where install_path is the path that you entered when you set up setup-dbconfig.

      If you do not want the password visible on the command line, you can omit the -P flag and the script prompts for the password. For example:

      ./scr_restore.sh -n
      Enter the database password:

   6. Enter the following command as the db2apm user for each database to adjust the buffer pool after you determine the size of your environment.

      db2 connect to WAREHOUS
      db2 alter bufferpool IBMDEFAULTBP IMMEDIATE size WAREHOUS_PAGE_COUNT
      db2 disconnect WAREHOUS
      db2 connect to DATAMART
      db2 alter bufferpool IBMDEFAULTBP IMMEDIATE size DATAMART_PAGE_COUNT
      db2 disconnect DATAMART
      db2 connect to SCR32
      db2 alter bufferpool IBMDEFAULTBP IMMEDIATE size 5000
      db2 alter bufferpool TBSMCFG16KBP IMMEDIATE size 1000
      db2 alter bufferpool TBSM4KBP IMMEDIATE size 1000
      db2 alter bufferpool TBSM32KBP IMMEDIATE size 1000
      db2 alter bufferpool TBSMSCR16KBP IMMEDIATE size SCR32_PAGE_COUNT
      db2 disconnect SCR32

      where:

      • WAREHOUS_PAGE_COUNT is the page count (8 K page size) for the WAREHOUS database IBMDEFAULTBP bufferpool: 50000 for small; 100000 for medium; or 200000 for large
      • DATAMART_PAGE_COUNT is the page count (8 K page size) for the DATAMART database IBMDEFAULTBP bufferpool: 100000 for small; 200000 for medium; or 300000 for large
      • SCR32_PAGE_COUNT is the page count (16 K page size) for the SCR32 database TBSMSCR16KBP bufferpool: 30000 for small; 50000 for large; or 100000 for large

      Estimate the size of your environment (small, medium, or large) from the server requirements table in Cloud APM server hardware requirements.

Install the V8.1.4 Cloud APM server

9. Install the new version of the Cloud APM server and restore the data and configuration from the backup. Complete these sub-steps as the root user.
   1. If the computer system or virtual machine where you are installing the Cloud APM server with a local Db2 server is using LDAP to authenticate the root user or Db2 users for your Cloud APM server, you must create local Db2 users before installing the V8.1.4. Cloud APM server. Complete steps 1 to 7 in Installing on a system using an external directory service.
   2. If your V8.1.3 Cloud APM server has a local Db2 server with custom passwords set for Db2 users itmuser and db2apm, you must change the values of the database passwords in Cloud APM 8.1.4.0 install.properties before running install.sh:

      db2apm.password=my_custom_password
      itmuser.password=my_custom_password

   3. When you are upgrading your Cloud APM server from V8.1.3 to V8.1.4, you must install V8.1.4 in the same directory where the V8.1.3 server was previously installed. This installation path was either the default /opt/ibm directory or a directory that you chose. Run the ./install.sh command to start the installation script.
   4. When you are asked if you want to upgrade from an existing installation of the Cloud APM server, enter 1 (Yes).
   5. When you are asked if you want to migrate the server data and configuration automatically or manually, enter 2 for manual migration.
   6. When you are asked for the backup file location, enter the path and file name that you created in Step 6 (such as /opt/ibm/backups/backup_20160826_155605.tar).
   7. When you are asked whether you accept the license agreement, enter 1 to accept the agreement and continue, or enter 2 to decline.
   8. After 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.
      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.
      • Enter the path to the directory for the configured agent installation images or accept the default install_dir/ccm/depot directory.
      • 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 host name and IP address of the server that will be used in a web browser to log into the Cloud APM console, accept the default values or enter your own values.
      This is the address that users enter to start the Cloud APM console from their web browsers, for example: https://myserver:9443 or http://myserver:8080. You can change the IP address and host name later. See Changing the server IP address and host name.
   10. If your Cloud APM server is connected to a remote Db2 server, respond to the prompts to connect to the remote Db2 database:

       
       Enter configuration parameters to establish connection to the  existing DB2 database.
       Enter the hostname/IP address to the DB2 host or accept the default  [10.46.40.100]:
       Enter the port number of the DB2 instance 
       or accept the default [50000]:
       Enter the password for the user "itmuser":
       Enter the remote DB2 instance name or accept the default [db2apm]:
       Enter the password for the instance user "db2apm":

       If you get a message that the Db2 database names must match, accept the default values to use the V8.1.3 names:

       Enter the name of Metric Cache database or accept the default [WAREHOUS]:
       Enter the name of Topology database or accept the default [SCR32]:
       Enter the name of Datamart database or accept the default [DATAMART]:

   Note: After this step is completed, do not restore the remote Db2 server.

   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, such as insufficient disk space. 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.

If the Hybrid Gateway is installed, migrate your configuration

10. Migrate your Hybrid Gateway configuration:
    • To migrate the Hybrid Gateway immediately after a restore, run these commands on the Cloud APM server as the root user:
      1. Copy the restored config.properties file to the ccm directory:

         cp install_dir/ccm/properties/config.properties.restored install_dir/ccm/properties/config.properties

      2. Update the date and time of the config.properties file so that any Hybrid Gateways already running will reload their configuration:

         touch config.properties

      3. Copy the updated config.properties file to the Central Configuration Services component:

         cp install_dir/ccm/properties/config.properties install_dir/wlp/usr/servers/min/dropins/CentralConfigurationServer.war/common/config.properties

    • If any configurations were done on the upgraded system after the restore, complete these steps:
      1. Copy these two lines from theinstall_dir/ccm/properties/config.properties.restored file:

         com.ibm.tivoli.ccm.encryption\:key= 
         com.ibm.tivoli.ccm.gaian.connect\:gaianReq=

      2. Replace the same lines in install_dir/ccm/properties/config.properties with the lines that you just copied.
      3. Copy config.properties to the Central Configuration Services component:

         cp install_dir/ccm/properties/config.properties install_dir/wlp/usr/servers/min/dropins/CentralConfigurationServer.war/common/config.properties

    To verify that the config.properties file in install_dir/wlp/usr/servers/min/dropins/CentralConfigurationServer.war/common/ was replaced, check that the modified date and time are current.