Upgrading to Eclipse Amlen version 1.0: server configuration and store

System administrators can upgrade their IBM® IoT MessageSight version 1.2 systems to an Eclipse Amlen version 1.0 environment by migrating the configuration and store from an IBM IoT MessageSight version 1.2 physical or virtual appliance to a running Eclipse Amlen version 1.0 environment. The upgrade process requires the use of high availability (HA) servers.

Contact IBM Support to review and verify your upgrade plan.
It is best practice to take a backup of the IBM IoT MessageSight version 1.2 production system store to test the upgrade process before you perform the upgrade process. For instructions for taking a backup of the IBM IoT MessageSight production system store, see Upgrading to Eclipse Amlen version 1.0: taking a backup of the IBM IoT MessageSight version 1.2 configuration and store.
The IBM IoT MessageSight version 1.2 server must be at the latest interim fix level. A list of interim fixes is available here: Fixes released for IBM MessageSight.
The Eclipse Amlen version 1.0 server to which you are migrating the configuration and store must be installed and configured and have no configured objects.
Communication over TCP/IP must be possible between the IBM IoT MessageSight version 1.2 server and the Eclipse Amlen version 1.0 server.
HA is enabled and configured on the IBM IoT MessageSight server as part of the upgrade process. The primary server is used for the upgrade process. If you need to configure HA, or change the current HA configuration, you must be prepared for a server outage and restart.

The server configuration and the contents of the server store are migrated from an IBM IoT MessageSight version 1.2 physical or virtual appliance to a running Eclipse Amlen version 1.0 environment. The store contains buffered messages, retained messages, subscriptions, and topics. It contains all persistent messages and objects that have been dynamically created by clients. Use this method if you need to preserve the contents of the server store when you upgrade from IBM IoT MessageSight version 1.2 to Eclipse Amlen version 1.0.

Configure the IBM IoT MessageSight version 1.2 server to replicate by using TCP.
- If the server is a physical appliance, issue the following command:
```
advanced-pd-options _setconfig imaserver 
ReplicationProtocol 1'
```
  and restart the server by issuing the following commands:
```
imaserver stop
imaserver start
```
- If the server is a virtual appliance, it is already configured to replicate by using TCP.
If HA is not already configured and enabled on the IBM IoT MessageSight version 1.2 server, configure and enable HA.
For more information about configuring HA on the IBM IoT MessageSight version 1.2 server, see Configuring your system for high availability. An example command follows:
```
imaserver create HighAvailability "EnableHA"= "True"  "StartupMode"="StandAlone"
"Group"="TestGroup1"  "RemoteDiscoveryNIC"=10.78.54.140"
"LocalReplicationNIC"="10.77.207.15"  "LocalDiscoveryNIC"="10.78.54.137"
```
1. Ensure that the value of the LocalDiscoveryNIC field on the IBM IoT MessageSight version 1.2 server is the same as the value of the RemoteDiscoveryNIC field on the Eclipse Amlen version 1.0 server.
2. Ensure that the value of the StartupMode is Standalone so that the primary server can become available even though the standby server is not available.
3. Restart the server by issuing the following commands:
```
imaserver stop 
imaserver start
```
4. After the server restart, check that the HA status of the server by issuing the following command:
```
imaserver harole
```
If HA is already configured and enabled on the IBM IoT MessageSight server, check that the value of the LocalDiscoveryNIC field on the IBM IoT MessageSight version 1.2 server is the same as the value of the RemoteDiscoveryNIC field on the Eclipse Amlen version 1.0 server.
- If you changed the HA configuration, restart the server by issuing the following commands:
```
imaserver stop 
imaserver start
```
  and then check the status of the server by issuing the following command:
```
imaserver harole 
 
```
- If you have not changed HA configuration, you do not need to restart the server.
Configure the Eclipse Amlen version 1.0 server for HA.
For more information about configuring HA on the Eclipse Amlen version 1.0 server, see Configuring your system for high availability.
If HA was already configured on the IBM IoT MessageSight version 1.2 server and the Eclipse Amlen version 1.0 server is reusing the IP addresses of the previous standby server, the values of the Group field must be the same. The following example shows that the Eclipse Amlen version 1.0 server is reusing the IP address of the previous standby and is using the same value of the Group field as the IBM IoT MessageSight version 1.2 server as configured in the example command in step 2:
```
curl -X POST http://10.78.54.140:9089/ima/v1/configuration -d '{ "HighAvailability": {    
"EnableHA": true, "StartupMode":  "AutoDetect", "LocalDiscoveryNIC":"10.78.54.140",
"RemoteDiscoveryNIC":"10.78.54.137",  "LocalReplicationNIC":"10.77.207.15",
"Group":"TestGroup1" }}' 
```
Check HA configuration on the Eclipse Amlen version 1.0 server by using the REST API GET method.
For example:
```
curl -X GET http:// 10.78.54.140:9089/ima/v1/configuration/HighAvailability
```

Check the response from the REST API GET method to ensure that the EnableHA field is set to true, the StartupMode field is set to AutoDetect, and the values in the RemoteDiscoveryNIC, LocalReplicationNIC, and LocalDiscoveryNIC fields are correct.

For example:


{
  "Version": "v1",
  "HighAvailability": {
    "EnableHA": true,
    "Group": "TestGroup1",
    "StartupMode": "AutoDetect",
    "PreferredPrimary": false,
    "DiscoveryTimeout": 600,
    "HeartbeatTimeout": 10,
    "RemoteDiscoveryNIC": "10.10.11.11",
    "LocalReplicationNIC": "10.10.11.12",
    "LocalDiscoveryNIC": "10.10.11.13",
    "ExternalReplicationNIC": "",
    "ExternalReplicationPort": 0,
    "ReplicationPort": 0,
    "RemoteDiscoveryPort": 0,
    "UseSecuredConnections": false,
    "RequireCertificates": true
  }
}

Restart the Eclipse Amlen version 1.0 server with the CleanStore field set to true by using the REST API POST method.
For example:
```
curl -X POST http://10.78.54.140:9089/ima/v1/service/restart -d
'{"Service":"Server","CleanStore":true}'
```
The server starts as the standby server.

Check the HA status of the Eclipse Amlen version 1.0 server by using the REST API GET method in 2 calls.

For example:

curl -X GET http://10.78.54.140:9089/ima/v1/configuration/HighAvailability

curl -X GET http://10.78.54.140:9089/ima/v1/service/status

Check the response from the REST API GET method to ensure that the HA Status field is set to Active, and the NewRole field is set to AutoDetect

For example:


{
  "Version":"v1",
  "Server": {
    "Name": "ima-server:9089",
    "UID": "o7AVNFjE",
    "Status": "Running",
    "State": 10,
    "StateDescription": "Standby",
    "ServerTime": "2018-08-22T19:32:57.168Z",
    "UpTimeSeconds": 340,
    "UpTimeDescription": "0 days 0 hours 5 minutes 40 seconds",
    "Version": "5.0 20180820-0334",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Container": {
    "UUID":""
  },
  "HighAvailability": {
    "Status": "Active",
    "Enabled": false,
    "Group": "TestGroup1",
    "NewRole": "STANDBY",
    "OldRole": "UNSYNC",
    "ActiveNodes": 2,
    "SyncNodes": 2,
    "PrimaryLastTime": "",
    "PctSyncCompletion": -1,
    "ReasonCode": 0,
    "RemoteServerName":"https://10.10.10.10:9087"
  },
  "Cluster": {
    "Status": "Inactive",
    "Enabled": false
  },
  "Plugin": {
    "Status": "Inactive",
    "Enabled": false
  },
  "MQConnectivity": {
    "Status": "Inactive",
    "Enabled": false
  },
  "SNMP": {
    "Status": "Inactive",
    "Enabled": false
  }
}

Disable HA on the Eclipse Amlen version 1.0 server to force the server to start in maintenance mode so that the configuration can be checked.

Use the REST API POST method to disable HA. For example:

curl -X POST http://10.78.54.140:9089/ima/v1/configuration -d '{ "HighAvailability": {
"EnableHA": false, "StartupMode":  "AutoDetect", "LocalDiscoveryNIC":"10.78.54.140",
"RemoteDiscoveryNIC":"10.78.54.137",  "LocalReplicationNIC":"10.77.207.15",
"Group":"TestGroup1" }}'

The server restarts automatically in maintenance mode.

Review and update the migrated configuration.
In particular, review and fix:
- Endpoint configuration, particularly if your endpoints were listening on specific interfaces. If such explicit interfaces are different, the upgrade process cannot update the configuration to the new values.
- Existing LDAP configuration which might need to be changed.
- Other configuration items that might need to be amended for the new environment.
Restart the Eclipse Amlen version 1.0 server so that it starts in production mode.
For example:
```
curl -X POST http://10.78.54.140:9089/ima/v1/service/restart -d '{ "Service":"Server" }'
```
Check the status of the server to verify the success of the upgrade process by using the REST API GET method.
For example:
```
curl -X GET http://10.78.54.140:9089/ima/v1/service/status
```

Check the response from the REST API GET method to ensure that the server Status field is set to Running, the StateDescription field is Running (production), the HA Status field is set to Inactive, and the HA Enabled field is set to false.

For example:


{
  "Version":"v1",
  "Server": {
    "Name": "mar078:9089",
    "UID": "AKOkJc1Z",
    "Status": "Running",
    "State": 1,
    "StateDescription": "Running (production)",
    "ServerTime": "2018-08-22T21:05:59.667Z",
    "UpTimeSeconds": 5569,
    "UpTimeDescription": "0 days 1 hours 32 minutes 49 seconds",
    "Version": "5.0 20180820-0334",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Container": {
    "UUID":""
  },
  "HighAvailability": {
    "Status": "Inactive",
    "Enabled": false
  },
  "Cluster": {
    "Status": "Inactive",
    "Enabled": false
  },
  "Plugin": {
    "Status": "Inactive",
    "Enabled": false
  },
  "MQConnectivity": {
    "Status": "Inactive",
    "Enabled": false
  },
  "SNMP": {
    "Status": "Inactive",
    "Enabled": false
  }
}

The Eclipse Amlen version 1.0 server is ready for messaging traffic. You can now switch messaging traffic from IBM IoT MessageSight version 1.2 to the Eclipse Amlen version 1.0 environment.