The side-by-side upgrade task is completed by using two separate systems;
one system runs version 8.1.3 of the Cloud
APM server and the other system will run version 8.1.4 of the server after this
upgrade procedure is completed. With this method, minimal downtime occurs because V8.1.3 of the
Cloud
APM server is running
continuously while the new V8.1.4 server is being installed.
The V8.1.3 server is shut down only during the switch to the new V8.1.4 server; hence, the user
experiences minimal disruption. Another advantage of this method is that if upgrade issues or
failure occur, you can continue to use the previous Cloud
APM server version before the
upgrade, which is V8.1.3. Customers with large monitoring environments usually choose this
method.
Before you begin
-
Before you can complete this upgrade procedure, ensure that two systems are available, a system
that is running V8.1.3 of the Cloud
APM server and a separate system to upgrade to V8.1.4 of the server.
-
When you perform the
Cloud
APM server upgrade, the
Db2® server for the
Cloud
APM server V8.1.4.0 must be at the same version as the
Db2 server used by the
Cloud
APM server V8.1.3. Check the
Db2 version that is in use by the
Cloud
APM server V8.1.3:
-
If LDAP is enabled on
your V8.1.3
Cloud
APM server to authenticate Cloud APM
console users, complete the following steps on your V8.1.3
Cloud
APM server before you back up your V8.1.3 data:
- Retrieve the value of the realm attribute from the
install_dir/wlp/usr/shared/config/ldapRegistry.xml file.
- Check the value of the oauthRealm attribute in the
install_dir/wlp/usr/shared/config/oauthVariables-onprem.xml file. If the value
of oauthRealm attribute does not match the value of the realm
attribute in the ldapRegistry.xml file, update the value of the
oauthRealm attribute to match the value of the realm
attribute.
- Complete the following steps to update the
install_dir/wlp/usr/servers/apmui/server-oauth2-tai.xml file to add the user
from the install_dir/wlp/usr/servers/server1/cscs/conf/cscsRoleAdmin.conf file:
- Find the properties line <properties, and identify the
systemUser parameter, if it does not exist you will need to add it in the next
step. Identify the closing tag /> for the properties line.
- Add a new line or edit the existing line before the /> closing tag as
follows:
systemUser="testuser LDAP distinguished name"
where testuser
matches the user string from the
cscsRoleAdmin.conf file, for example:
systemUser="CN=testuser,CN=users,dc=adtest,dc=mycity,dc=mycompany,dc=com"
Note: Do
not include the user:prefix or realm name that was specified in
cscsRoleAdmin.conf.
- Confirm that the /> closing tag was not deleted, then save and close the
file.
-
If your V8.1.3 Cloud
APM server is connected to a remote
MongoDB, install MongoDB V3.2.12. For instructions, see Installing MongoDB V3.2.12 on your remote system.
- If
you modified the trust store password for your Cloud
APM server V8.1.3, change the password back to the default
password before performing the server upgrade. After the upgrade completes, you can change the
password back to your custom trust store password. For details, Changing the password for the shared truststore.
- If
a custom password is configured for MongoDB on your V8.1.3 Cloud
APM server, you must set the MongoDB password back to the
default value before running
backup.sh
. After the upgrade to version 8.1.4.0 is
complete, you can set the MongoDB password back to a custom password. For more information, see
Default users and passwords.
About this task
These steps assume that the system that is running V8.1.3 of the Cloud
APM server is using the local
Db2 server that is installed by default with the
Cloud
APM server. If the V8.1.3
Cloud
APM server system that you
are using is connected to a remote Db2 server, you
must complete the steps in the Upgrading your server when connected to a remote Db2 server topic and complete the steps
in this topic. Start with the steps in Upgrading your server when connected to a remote Db2 server. You are referred to the
steps in this topic.
The
procedure for upgrading the
Cloud
APM server from V8.1.3
to V8.1.4 on the two systems involves these general steps:
- Install the Cloud
APM
V8.1.3 interim fix 16 (8.1.3.0-IBM-IPM-SERVER-IF0016) or
later on your V8.1.3 Cloud
APM server.
- Back up your V8.1.3 interim fix 16 or
later server data and configuration files with the backup script that is part of the V8.1.3 interim fix 16 server installation.
- Install your V8.1.4 Cloud
APM server and either
restore the V8.1.3 Cloud
APM server data from step 2 or
complete an automatic backup and restore of your V.8.1.3 server data.
- Shut down your V8.1.3 Cloud
APM server.
- Reassign the V8.1.3 Cloud
APM server IP address or
both the IP address and host name to the V8.1.4 Cloud
APM server.
If you are using a remote
Db2 server, the
procedure involves these general steps:
- Install the Cloud
APM
V8.1.3 interim fix 16 (8.1.3.0-IBM-IPM-SERVER-IF0016) or
later on your V8.1.3 Cloud
APM server.
- Back up your V8.1.3 Db2 databases.
- Set up the new V8.1.4 SCR database.
- Restore the V8.1.3 Db2 database data to the
new V8.1.4 databases.
- Back up your V8.1.3 Cloud
APM server data and
configuration files with the backup script that is part of the V8.1.3 server installation if you are completing a manual backup.
- Install your V8.1.4 Cloud
APM server and either
restore the V8.1.3 Cloud
APM server data from step 5 or
complete an automatic backup and restore of your V.8.1.3 server data.
- Stop your V8.1.3 Cloud
APM server.
- Optionally, rename your new V8.1.4 databases to use the same database names that were used for
V8.1.3.
- Reassign the V8.1.3 Cloud
APM server IP address or
both the IP address and host name to the V8.1.4 server.
Procedure
Complete the following steps as a root user:
-
Download the V8.1.4 Cloud
APM server installation image from the download site to a staging location of your choosing.
-
If you plan to configure the agent images, the Hybrid Gateway image, or both during the server upgrade, download the images.
-
Extract the server installation files for your offering.
-
Install the V8.1.3 patch on your V8.1.3 Cloud
APM server:
-
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.
-
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.
- Extract the patch
package:
tar xvf 8.1.3.0-IBM-IPM-SERVER-IF0016.tar
- Run the following script to apply the patch:
apmpatch.sh
-
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.
-
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
-
From the directory where you extracted the installation files, install V8.1.4 of the Cloud
APM server on the virtual machine or computer system that you are using for the upgrade.
-
Take note of the installation location of the V8.1.3 server on the existing system because you must install V8.1.4 in the same directory on the upgrade system.
The installation path was either the default /opt/ibm directory or a directory that you chose.
- 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
-
Start the installation script:
-
After you start the installation, when you are asked if you are upgrading from an existing installation of the Cloud
APM server, enter 1 (yes) to continue with the upgrade.
-
When you are asked if you want to move the data and configuration automatically or manually
from the existing system, enter 1 (yes) to accept the default and
automatically move the data or 2 (no) to complete a manual migration.
-
If you entered 2 [manually] to move your data from the existing V8.1.3
server, you must run the backup as user root on this existing server. The
backup.sh script is in the ccm directory of the V8.1.3 Cloud
APM server installation
directory.
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.
-
If you entered 1 [automatically] to move your data from the existing
V8.1.3 server, you are prompted to provide or accept default values to set up the SSH connection to
the existing V8.1.3 server.
- name for the Performance Management UI administrator account or accept the default
[apmadmin]
- password for the Performance Management UI administrator account
- hostname/IP address of the remote server
After you respond to the prompts, a connection is established and a backup of the existing
server data and configuration is created. The time that it takes to create the backup depends on the
size of the backup.
-
After the backup is finished, you must enter the root password of the V8.1.4 Cloud
APM server so you can copy the backup
file to this server.
-
If you are manually migrating your data, copy the backup tar image from step 9 to the server where you
are installing the Cloud
APM server and enter the path and file name that you created (such as
/opt/ibm/backups/backup_20160826_155605.tar) when you are prompted.
-
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.
-
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.
Important: These steps assume that the
Cloud
APM server system that you are
upgrading from is using the local
Db2 server that
is installed by default when the server was installed. If this version of the server is connected to
a remote
Db2 server, during the V8.1.4
installation, you are prompted to complete the steps in
Upgrading your server when connected to a remote Db2 server to back up the databases
separately to avoid any issues between the V8.1.3 server and the new V8.1.4 server.
The V8.1.4
Cloud
APM server installation is
started.
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.
-
When the installation is complete, you can verify that the V8.1.4 upgrade is a success by completing the following steps:
-
Issue the apm status command from the /usr/bin/ directory on the upgraded V8.1.4 server to view the list of running components. If all the components are running, the upgrade is a success.
-
If you log in to the Application Performance Dashboard using the same credentials that you used for V8.1.3 and check your applications, groups, and instances for V8.1.4, they are the same as they were for V8.1.3.
-
Shut down the V8.1.3 Cloud
APM server system if it is running by entering the following command from any directory:
-
Reassign the V8.1.3 Cloud
APM server IP address or both the IP address and host name to the V8.1.4 server. Whether you reassign the IP address only or both the IP address and host name depends on your configuration.
-
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:
- Copy the restored config.properties file to the ccm
directory:
cp install_dir/ccm/properties/config.properties.restored install_dir/ccm/properties/config.properties
- Update the date and time of the config.properties file so that any Hybrid
Gateways already running will reload their
configuration:
touch config.properties
- 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:
- 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=
- Replace the same lines in install_dir/ccm/properties/config.properties with the lines that you just copied.
- 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.
Results
The Cloud
APM server upgrade to V8.1.4 is complete. You can now access the latest functions for your agents and other components.