Migrating a queue manager to become an HA RDQM queue manager

You can migrate an existing queue manager to become a high availability (HA) replicated data queue manager (RDQM) by backing up its persistent data, then restoring the data to a newly created RDQM queue manager that has the same name.

1. Back up the existing queue manager:
   1. Stop the existing queue manager by issuing a wait shutdown command endmqm -w, or an immediate shutdown command endmqm -i. This step is important to ensure the data in the backup is consistent.
   2. Determine the location of the queue manager data directory by viewing the IBM MQ configuration file, mqs.ini. On Linux, this file is located in the /var/mqm directory. For more information about mqs.ini, see IBM MQ configuration file, mqs.ini.

      Locate the QueueManager stanza for the queue manager in the file. If the stanza contains a key named DataPath then its value is the queue manager data directory. If the key does not exist, then the queue manager data directory can be determined using the values of the Prefix and Directory keys. The queue manager data directory is a concatenation of these values, of the form prefix/qmgrs/directory. For more information about the QueueManager stanza, see QueueManager stanza of the mqs.ini file.

   3. Create a backup of the queue manager data directory. On Linux, you can do this by using the tar command. For example, to back up the data directory for a queue manager you can use the following command. Note the last parameter of the command, which is a single period (dot):

      tar -cvzf qm-data.tar.gz -C queue_manager_data_dir .

   4. Determine the location of the queue manager log directory by viewing the IBM MQ queue manager configuration file qm.ini. This file is located in the queue manager data directory. For more information about the file, see Queue manager configuration files, qm.ini.

      The queue manager log directory is defined as the value of the LogPath key in the Log stanza. For information about the stanza, see Log stanza of the qm.ini file.

   5. Create a backup of the queue manager log directory. On Linux, you can do this by using the tar command. For example, to back up the log directory for a queue manager you can use the following command. Note the last parameter of the command, which is a single period (dot):

      tar -cvzf qm-log.tar.gz -C queue_manager_log_dir .

   6. Create a backup of any certificate repositories used by the queue manager if they are not located in the queue manager data directory. Ensure that both the key database file and the password stash file are backed up. For information about the queue manager key repository, see The SSL/TLS key repository and Locating the key repository for a queue manager. For information about locating the AMS key store if the queue manager is configured to use AMS Message Channel Agent (MCA) interception, see Message Channel Agent (MCA) interception.
   7. The existing queue manager is no longer required, so it can be deleted. However, where possible, you should only delete the existing queue manager after it has been successfully restored on the target system. Deferring deletion ensures that the queue manager can be restarted if the migration process does not complete successfully.
      Note: If you defer deletion of the existing queue manager, do not restart it. It is important the queue manager remains ended because further changes to its configuration or state are lost during the migration.
2. Prepare the primary RDQM node:
   1. Create a new RDQM queue manager with the same name as the queue manager that you backed up. Ensure the filesystem allocated for the RDQM queue manager by crtmqm is big enough to contain the data, primary logs and secondary logs for the existing queue manager, plus some additional space for future expansion. For information about how to create an RDQM queue manager, see Creating an HA RDQM.
   2. Determine the primary RDQM node for the queue manager. For information about how to determine the primary node, see rdqmstatus (display RDQM status).
   3. On the primary RDQM node, if the RDQM queue manager is started, stop it by using the endmqm -w or endmqm -i command.
   4. On the primary RDQM node, determine the location of the data and log directories for the RDQM queue manager (use the methods described in steps 1b and 1d).
   5. On the primary RDQM node, delete the contents of the RDQM queue manager data and log directories, but not the directories themselves.
3. Restore the queue manager on the primary RDQM node:
   1. Copy the backups of the queue manager data and log directories to the primary RDQM node, plus any separate backups of certificate repositories used by the queue manager.
   2. Restore the backup of the queue manager data directory to the empty data directory for the new RDQM queue manager, ensuring that file ownership and permissions are preserved. If the backup was created using the example tar command in step 1c then the following command can be used by the root user to restore it:

      tar -xvzpf qm-data.tar.gz -C queue_manager_data_dir

   3. Restore the backup of the queue manager log directory to the empty log directory for the new RDQM queue manager, ensuring that file ownership and permissions are preserved. If the backup was created using the example tar command in step 1e then the following command can be used by the root user to restore it:

      tar -xvzpf qm-log.tar.gz -C queue_manager_log_dir

   4. Edit the restored queue manager configuration file, qm.ini, in the data directory for the RDQM queue manager. Update the value of the LogPath key in the Log stanza to specify the log directory for the RDQM queue manager.
      Review other file paths that are defined in the configuration file and update them if necessary. For example, you might need to update the following paths:

      • The path for error log files that are generated by diagnostic message services.
      • The path for exits that are required by the queue manager.
      • The path for switch load files if the queue manager is an XA transaction coordinator.
   5. If the queue manager is configured to use AMS Message Channel Agent (MCA) interception, copy the AMS key store to the new RDQM installation, then review and update the configuration. The key store must be available on each RDQM node, so if it is not located in the replicated filesystem for the queue manager it must be copied to each node instead. For more information, see Message Channel Agent (MCA) interception.
   6. Verify that the queue manager is displayed by the dspmq command and its status is reported as ended. The following example shows sample output for an RDQM HA queue manager:

      $ dspmq -o status -o ha 
      
      QMNAME(QM1) STATUS(Ended normally) HA(Replicated) 

   7. Verify that the restored queue manager data has been replicated to the secondary RDQM nodes by using the rdqmstatus command to display the status for the queue manager. The HA status should be reported as Normal on each node. The following example shows sample output for an RDQM HA queue manager:

      $ rdqmstatus -m QM1 
      Node:                           mqhavm10-adm 
      Queue manager status:           Ended normally 
      Queue manager file system:      50MB used, 0.2GB allocated [42%] 
      HA role:                        Primary 
      HA status:                      Normal 
      HA control:                     Disabled 
      HA current location:            This node 
      HA preferred location:          This node 
      HA floating IP interface:       None 
      HA floating IP address:         None 
      
      Node:                           mqhavm11-adm 
      HA status:                      Normal 
      
      Node:                           mqhavm12-adm 
      HA status:                      Normal

   8. Start the queue manager on the primary RDQM node.
   9. Connect to the queue manager and update the value of the SSLKEYR queue manager attribute to specify the new location of the queue manager certificate repository. By default, the value of this attribute is set to queue_manager_data_directory/ssl/key. The certificate repository must be located in the same location on each RDQM node. If the repository is not located in the replicated filesystem for the queue manager, then it must be copied to each node instead.
   10. Review the IBM MQ object definitions for the queue manager and update the value of object attributes that reference changed network settings, the IBM MQ installation directory, or the queue manager data directory, including the following objects:
       • Local IP addresses used by listeners (IPADDR attribute).
       • Local IP addresses used by channels (LOCLADDR attribute).
       • Local IP addresses defined for cluster-receiver channels (CONNAME attribute).
       • Local IP addresses defined for communication information objects (GRPADDR attribute).
       • System paths defined for process and service object definitions.
   11. Stop and restart the queue manager to ensure the changes become effective.
   12. Repeat step 3j for remote queue managers, plus equivalent settings for applications, that connect to the migrated queue manager, including:
       • Channel connection names (CONNAME attribute).
       • Channel authentication rules that restrict inbound connections from the queue manager based on its IP address or hostname.
       • Client channel definition tables (CCDTs), domain name settings (DNS), network routing, or equivalent connection information.
   13. Perform a managed failover of the queue manager to each RDQM node to ensure the required configuration has been established successfully, see Setting the Preferred Location for an RDQM.