View Only

Secure System Backups on the IBM MQ Appliance

By Jamie Squibb posted Thu February 29, 2024 06:01 AM


For those of you who might not be aware, the IBM MQ Appliance is a dedicated hardware appliance that runs IBM MQ. It hosts queue managers to which business applications can connect to send and receive messages. It has support for high availability and disaster recovery built-in, and it can provide total cost of ownership savings over deploying MQ as a software offering through simplified management and easy-to-install firmware updates.

One area that we have wanted to improve for a while with the appliance is that of system backups. For several years we have had the capability to backup and restore queue managers, but backing up system settings and local administrative users has needed some improvement. To date, administrators back up a number of resources separately, so it can be easy to overlook something. Also, it has not been possible to back up all secrets, such as some user passwords, and any private keys that are stored in the cert: folder.

From IBM MQ 9.3.5, the MQ Appliance firmware supports a capability known as Secure Backup, which you might be familiar with from the IBM DataPower Gateway (a related offering in IBM’s integration portfolio). A Secure Backup is a full backup of the system settings and related secrets, which is encrypted by using a user-supplied certificate. A Secure Backup can be restored on the same or a different appliance, so it can be used to recover from a failure or to simplify migration during rolling hardware upgrades. With the introduction of this enhancement, backups are now easy to achieve and automate, with a secure backup for the system settings, and the pre-existing queue manager backups for messaging data and logs.

Some notes about secure backups

  • The certificate used for a Secure Backup can either be generated on the appliance, or a custom certificate can be uploaded that has been obtained from elsewhere.
  • Although queue manager backups remain separate, the local messaging users that are defined for use by MQ are included in a Secure Backup. This means that the messaging users do not need to be backed up separately by using the userbackup command.
  • To restore a Secure Backup the appliance must have firmware installed that has the same version (V.R.M.F) as when the backup was created. For example, a backup created by using the firmware can be restored by the firmware, but not by firmware with a different V.R.M.F, such as or This means that a new Secure Backup should be created each time the appliance firmware is upgraded.
  • The appliance must be factory reset before restoring a Secure Backup. The recovery process is therefore to perform a factory reset, restore the Secure Backup, then restore any queue manager backups and setup HA or DR.
  • IPMI passwords are not restored by a Secure Backup because they are stored in the Baseboard Management Controller (BMC). These passwords must be set manually after restoring a Secure Backup.
  • Upon restoring a Secure Backup, the password for the built-in admin user is reset to its factory default value to ensure you can login without you needing to remember a password from when the backup was created. It is recommended that you change this password as soon as possible.

Secure Backup walkthrough


Create a private key and certificate, then download and save these files (or generate your own certificate elsewhere and upload it to the appliance).

mqa(config-crypto)# keygen CN "My Backup Cert" gen-sscert file-name mybackupcert export-key export-sscert

keygen: Generating a 2048 bit RSA private key
keygen: This could take some time, please be patient
keygen: Saved private key in 'cert:///mybackupcert-privkey.pem'
keygen: Saved private key in 'temporary:///mybackupcert-privkey.pem' [INSECURE DIRECTORY]
keygen: Saved certificate signing request in 'temporary:///mybackupcert.csr'
keygen: Saved self-signed certificate in 'cert:///mybackupcert-sscert.pem'
keygen: Saved self-signed certificate in 'temporary:///mybackupcert-sscert.pem'

Note: Files cannot be downloaded from the cert: folder. The export-key and export-sscert options are required to have the private key and the certificate files copied to the temporary: folder, so you can download them to use with a Secure Restore. Remember to delete these files from the temporary: folder after you have downloaded them.

Create a Secure Backup

1. Define a crypto certificate object that references the required certificate file in the cert: folder.

mqa(config-crypto)# certificate mybackupcert cert:///mybackupcert-sscert.pem
Creating certificate 'mybackupcert'

mqa(config-crypto)# show certificate mybackupcert

certificate: mybackupcert [up]
 admin-state enabled 
 file-name cert:///mybackupcert-sscert.pem 
 Password alias toggle (deprecated) off 
 ignore-expiration off 

If you prefer, you can alternatively specify “gen-object object-name mybackupcert” as extra parameters to the keygen command to have this certificate object be created when generating the certificate file.

2. Create a Secure Backup, then download and save the generated files.

mqa(config)# secure-backup mybackupcert temporary:///myBackup

Secure backup to 'temporary:///myBackup' scheduled (may take a few minutes to complete).
Secure backup is complete.

mqa(config)# dir temporary:///myBackup

   File Name                    Last Modified                    Size
   ---------                    -------------                    ----
   backupmanifest.xml           Oct 2, 2023 7:13:04 PM           5240
   root.tgz                     Oct 2, 2023 7:13:04 PM           6808
   config.tgz                   Oct 2, 2023 7:13:03 PM           4152
   cert.tgz                     Oct 2, 2023 7:13:03 PM           5688
   local.tgz                    Oct 2, 2023 7:13:03 PM           2592
   password-map.tgz             Oct 2, 2023 7:13:03 PM           304
   mq-users.tgz                 Oct 2, 2023 7:13:03 PM           432

   5115.3 MB available to temporary:///myBackup

A secure backup contains a digitally signed manifest (backupmanifest.xml), plus one or more encrypted backup files. The files that are created will depend on the resources and definitions on the appliance. For example, the backup might contain a sharedcert.tgz file if the sharedcert: folder contains certificate files.

Restore a secure backup

1. Define crypto certificate, key, and identification credentials objects

To restore a secure backup, perform a factory reset of the appliance and complete the initial steps to reconnect the appliance to the network. Upload the certificate used to create the Secure Backup and its private key to the cert: folder. Define crypto certificate, key and identification credentials objects for these files.

mqa(config-crypto)# certificate mybackupcert cert:///mybackupcert-sscert.pem
Creating certificate 'mybackupcert'

mqa(config-crypto)# key mybackupkey cert:///mybackupcert-privkey.pem
Creating key 'mybackupkey'

mqa(config-crypto)# idcred mybackupcred mybackupkey mybackupcert
Creating Identification Credentials 'mybackupcred’

mqa(config-crypto)# show idcred mybackupcred

idcred: mybackupcred [up]
 admin-state enabled
 key mybackupkey [up]
 certificate mybackupcert [up]

2. Upload the backup files, then optionally validate the backup

Upload the backup manifest and the encrypted backup files to the appliance, such as to a directory in the temporary: folder. Use the secure-restore command to verify the backup is complete and all its files are present. Validating a backup does not modify the system state.

mqa(config)# secure-restore mybackupcred temporary:///myBackup on

Secure restore from 'temporary:///myBackup' scheduled (may take a few minutes to complete).
The secure-restore validation is complete

3. Restore the secure backup

Repeat the secure-restore command, but omit the final parameter that indicates to just verify the backup. The backed up configuration will be restored, then the appliance will automatically restart.

mqa(config)# secure-restore mybackupcred temporary:///myBackup

Secure restore from 'temporary:///myBackup' scheduled (may take a few minutes to complete).
Secure restore is complete. The system will be restarted.

Important Note: As per the comments above, the password for the built-in admin user is reset to its factory default value to ensure you can login after the appliance restarts. It is recommended that you change this password as soon as possible.

For more information about the Secure Backup enhancement on the MQ Appliance see the product documentation at