Installing and upgrading on-premises Agile Service Manager

Learn how to upgrade to the latest version of Agile Service Manager.

About this task

You install a new version or upgrade an existing version of Agile Service Manager (on-premises) using the standard installation procedures for all components. When using the IBM®® Installation Manager to install the Netcool® Hybrid Deployment Option Integration Kit, you must install a new version.

After completing the installation, you may have to migrate the configuration settings. Previous configuration settings are preserved during installation, but you may need to manually transfer settings from your previous to your current configuration files.

The yum upgrade (install) process preserves existing configuration settings in two ways.

Replace previous configuration files: If a previous configuration file can be replaced without disabling the Agile Service Manager system, the install process will do so, and save the old version with the .rpmsave extension.; For example the old version of poll_docker.sh will be replaced with a new version, and backed up as poll_docker.sh.rpmsave
Preserve current configuration file: If a previous configuration file can not be replaced without disabling the Agile Service Manager system, the install process will keep the old configuration file in place, and save the new version with the .rpmnew suffix.; For example the old version of docker-compose.yml will be kept in place, and the new version will be deployed as docker-compose.yml.rpmnew

Procedure

Obtain the Agile Service Manager software

Obtain the Agile Service Manager installation images for the user interface and core services from the Passport Advantage® site, and extract them to a temporary directory.
More detailed information can be found in the download document here: http://www-01.ibm.com/support/docview.wss?uid=swg24043717
Note: You need an IBM ID to access the download document.

Backup custom UI configuration settings

To preserve customized UI configuration settings such as user preferences, topology tools, custom icons, relationship types, and global settings, perform a backup of these settings, as described in the Exporting configuration data (on-premises) topic of the Administration section in the Agile Service Manager documentation:

https://www.ibm.com/docs/en/SS9LQB_1.1.13/Administering/t_asm_exportingconfig.html

Install (upgrade) Agile Service Manager

Stop any Agile Service Manager services that are running:
```
/opt/ibm/netcool/asm/bin/asm_stop.sh
```
Install a new version of Agile Service Manager, or update an existing installation.
Follow the standard installation procedure as described in the following topics:
- Install Agile Service Manager core and observers: https://www.ibm.com/docs/en/SS9LQB_1.1.13/Installing/t_asm_installingcore.html#t_asm_installingcore
  Tip: Using the wildcard installation command (sudo yum install nasm-*.rpm) will initiate an upgrade of changed or new packages only.
- Install the Netcool Hybrid Deployment Option Integration Kit: If this is an upgrade, first uninstall the hybrid kit that is already installed in DASH.https://www.ibm.com/docs/en/SS9LQB_1.1.13/Installing/t_asm_installinghybridintegrationkit.html
After the upgrade, the yum install process lists all changed configuration files.

Transfer your configuration settings

Remember: If you have upgraded an existing installation of Agile Service Manager, you must upgrade your configuration files.

Manually migrate your backed up configuration settings to the new configuration files.
Tip:
- You can search for affected configuration files with the .rpmsave or .rpmnew extensions.
- You can compare configuration file versions using a Diff tool, before migrating the required configuration setting to the new configuration files.
Import any previously backed up UI configuration settings into your new system, as described in the following topic:

https://www.ibm.com/docs/en/SS9LQB_1.1.13/Administering/t_asm_importingconfig.html#t_asm_importingconfig

Additional configuration

Depending on your deployment, you may need to perform some of the following configuration tasks:
Edge types migration
To migrate any existing edge types from Agile Service Manager 1.1.3 to 1.1.5 (or later), use the following curl command:
```
curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/migrateEdgeTypes'
```
Match token migration to lowercase
To convert older resource matchTokens from Agile Service Manager 1.1.3 or 1.1.4 (but not 1.1.4.1) to 1.1.5 (or later) to lowercase, use the following curl command:
```
curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/lowercaseMatchTokens'
```
Composite end time migration

To allow composite vertices to show status within the search results you must migrate any existing composites to the latest version of Agile Service Manager.
To do so, use the following curl command:
```
curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/compositeEndTime'
```
Restrict the Transport Layer Security (TLS) version to 1.2 only
To enforce TLS 1.2 in nginx, change the ssl_protocols setting in the $ASM_HOME/etc/nginx/nginx.conf file:
```
server {
listen 8443 ssl;
server_name localhost;
ssl_certificate /opt/ibm/netcool/asm/security/asm-nginx.crt;
ssl_certificate_key /opt/ibm/netcool/asm/security/asm-nginx.key;
ssl_protocols TLSv1.2;
```
Docker Observer
When updating from Agile Service Manager 1.1.7 (or earlier) with existing Docker Observer job data, run the following migration script to avoid the creation of duplicate observer records before running any new Docker Observer jobs:
$ASM_HOME/bin/execute_crawler.sh -c docker_provider_transfer
Failing to run this script before running any new Docker Observer jobs can result in duplicate resources, as can running an older Docker Observer job after running the crawler.
Kubernetes Observer
When updating from Agile Service Manager 1.1.4.1 (or earlier), ensure that your Weave Scope jobs are running before you update your system.
- The location of the Weave Scope listen job changes from Agile Service Manager 1.1.5 onwards, but existing Weave Scope jobs that are running during an upgrade will have their paths automatically renamed when the observer starts.
- However, Weave Scope jobs that are not running (stopped) will not be recognized, and so will not have their path renamed. As a consequence, the UI will be unable to restart them.
ITNM Observer
When updating from Agile Service Manager 1.1.3 (or earlier) to the latest version, you must run a migration script to avoid the creation of duplicate ITNM Observer records before running any ITNM Observer jobs:
```
cd $ASM_HOME/bin
/execute_crawler.sh -c itnm_provider_transfer
```
- Running this script before making any new observations with the ITNM Observer prevents the creation of duplicate records.
- Running this script after making new observations with the ITNM Observer removes duplicate records, but may not preserve some historical topology data previously gathered by the ITNM Observer.
The script, which may take some time to complete on large topologies, creates a management artifact in the topology. You can monitor its progress by querying the artifact via Swagger.