Upgrading from IBM Watson IoT Platform Message Gateway to Eclipse Amlen

If you are a IBM® Watson IoT Platform Message Gateway customer who is upgrading to Eclipse Amlen version 1.0, you will find that normal product operation is almost entirely unchanged by the renaming of the product. Migration requires some simple steps outlined here.

Overview of key changes

The main changes from IBM Watson IoT Platform Message Gateway to be aware of during migration are:

  1. Packages have been renamed and made more granular
  2. Directories have different locations
  3. An important marker file has changed location
  4. TLS keys used for validating peers in HA pairs and clusters have changed

In the following sections we'll look at each change then the actions required during migration

New Packages

Previously the main server package (the rpm that contains the files to be installed) contained code that was not needed by all users, in particular the bridge to IBM MQ and code used with plugins for custom protocols has been split out into separate packages

Table 1. Comparing old and new package names
Old Package Name New Package Name(s)

IBMWIoTPMessageGatewayServer

EclipseAmlenServer

EclipseAmlen

EclipseAmlenProtocolPlugin

Directories have been moved

Due to the renaming of the product the following directories have been moved

Table 2. Comparing old and new directory paths
Old Location New Location Description
/opt/ibm/imaserver /usr/share/amlen-server Server install path
/var/messagesight /var/lib/amlen-server Data/config/diagnostics for the server
/opt/ibm/imawebui /usr/share/amlen-webui WebUI install path
/var/messagesight/webui /var/lib/amlen-webui Data/config/diagnostics path for the WebUI
/opt/ibm/imabridge /usr/share/amlen-bridge Bridge install path
/var/imabridge /var/lib/amlen-bridge Data/config/diagnostics path for the Bridge

Change of location of marker file

There is a file (with path: /var/lib/amlen-server/data/config/store.init) that indicates to Amlen that the persistent data store has been correctly initialised and is valid.

Message Gateway used to use a different path under its install directory which will be removed as part of the uninstall of Message Gateway. Therefore /var/lib/amlen-server/data/config/store.init needs to be manually created as part of the migration process if persistent data (e.g. subscriptions and buffered messages) are to be migrated. An empty file is all that is needed in order to cause the Message Gateway persistent data to be preserved e.g.:

touch /var/lib/amlen-server/data/config/store.init

TLS keys for peers in HA Pairs and Clusters

Both Eclipse Amlen and IBM Watson IoT Platform Message Gateway contain default TLS keys used as a check on connections to peers in Highly Available Pairs and in Clusters. The default keys have changed in Eclipse Amlen. If the servers being migrated are part of an HA pair or a cluster then the simplest migration method is to temporarily disable the checking of certificates during the upgrade then switch to using the default Amlen certificates and then finally move to custom certificates for significantly improved security. For more details about TLS certificates in Eclipse Amlen and IBM Watson IoT Platform Message Gateway see TLS in IBM Watson IoT Platform Message Gateway and Eclipse Amlen

Suggested Procedure for Server Migration

A suggested procedure to migrate from IBM Watson IoT Platform Message Gateway to Eclipse Amlen is:

  1. Update server to be migrated (and any servers in the same HA pair or cluster) to the latest ifix for Message Gateway available at https://ibm.biz/messagegatewayfixes
  2. If using HA or Clustering - stop the links requiring TLS certificates (see TLS in IBM Watson IoT Platform Message Gateway and Eclipse Amlen)
  3. On each server in turn (starting with standbys):
    1. Stop the server: 
      sudo systemctl stop imaserver
    2. Uninstall IBM Watson IoT Platform Message Gateway
    3. Move the data directory (but have a link from the old location to the new as default Message Gateway configs reference paths under the old directory): 
      mv /var/messagesight /var/lib/amlen-server
ln -s /var/lib/amlen-server /var/messagesight
    4. Create the marker file that indicates Message Gateway persistent data should be used with Amlen: 
      touch /var/lib/amlen-server/data/config/store.init
    5. Install Eclipse Amlen
    6. Start the server: 
      sudo systemctl start imaserver
  4. After each server has been migrated, require certificates on all HA and Cluster links; either by initially using the default Amlen keys and certificates or moving straight to custom keys/certs (see TLS in IBM Watson IoT Platform Message Gateway and Eclipse Amlen)