Use > JMX Reference > Administration Methods > How to Set Master Keys

How to Set Master Keys

You can use the JMX console to change the master key that is used to encrypt all UCMDB keys.

Change the master key for a cluster

This method assumes that your UCMDB environment is deployed in a high-availability setup.

Caution  

  • This method involves a restart of the entire cluster, so plan accordingly. It is recommended to change the master key of the cluster when there is little or no load on the servers. For example, you should avoid using this method during data-in operations.

  • Do not change any settings in the time period between changing the master key and restarting the server. Not following this instruction may result in a failure to start the server.
  • Machines that are not up or that will be added later to the cluster will need to be configured manually. Until they are configured, at most they can run as reader machines; trying to run them as writer machines will fail.

  1. Back up the C:\UCMDB\UCMDBServer\conf\cmdb.conf file and the values for the following settings:

    • ha.cluster.authentication.keystore.password
    • ha.cluster.authentication.shared.secret
    • ha.cluster.message.encryption.keystore.password
    • ssl.server.keystore.password
    • ssl.server.truststore.password
  2. Make sure all the servers in the cluster are up and running.

  3. On the writer machine, launch the Web browser and enter the following address to log in to the JMX console: https://localhost:8443/jmx-console.

    Note If a load balancer is present, you must bypass it and not log on to the writer machine through a load balancer.

  4. Do one of the following:

    • Search for changeMasterKeyForCluster.
    • Click UCMDB:service=Security Services > changeMasterKeyForCluster.

  5. Enter and confirm the master key, and click Invoke. The master key will be changed first on the writer machine and then on all reader machines.

    Note  

    The master key must contain exactly 32 characters and include at least one of each of the following four types of characters:

    • Uppercase alphabetic characters
    • Lowercase alphabetic characters
    • Numeric characters
    • Special characters: :/._+-[]

  6. Restart all the machines in the cluster. You can use the JMX method High Availability Services > restartCluster to do this.

    Note Restart the cluster immediately after changing the master key. If you do not, future database connections may fail.

Change the master key for a new machine in a cluster

If at least one of the following settings was changed, use Method A; otherwise, use Method B:

  • ha.cluster.authentication.keystore.password
  • ha.cluster.authentication.shared.secret
  • ha.cluster.message.encryption.keystore.password
  • ssl.server.keystore.password
  • ssl.server.truststore.password

Method A

This method assumes that you already have properly configured a master key for the writer machine that is up and running in the cluster. If not, follow the instructions in Change the master key for a cluster.

  1. Copy the C:\UCMDB\UCMDBServer\bin\wrapper.conf file from the writer machine to the same location on the new (reader) machine.
  2. Restart the server.

Method B

  1. Back up the C:\UCMDB\UCMDBServer\conf\cmdb.conf file.

  2. On the writer machine, launch the Web browser and enter the following address to log in to the JMX console: https://localhost:8443/jmx-console.

  3. Do one of the following:

    • Search for changeMasterKey.
    • Click UCMDB:service=Security Services > changeMasterKey.

  4. Enter and confirm the master key, and click Invoke.

    Note The master key must contain exactly 32 characters and include at least one of each of the following four types of characters:

    • Uppercase alphabetic characters
    • Lowercase alphabetic characters
    • Numeric characters
    • Special characters: :/._+-[]

  5. Restart the machine.

    Note Restart the cluster immediately after changing the master key. If you do not, future database connections may fail.

Revert the master key for a cluster to its default value

This procedure resets the master key for an entire cluster.

  1. Make sure all the servers in the cluster are up and running.

  2. On the writer machine, launch the Web browser and enter the following address to log in to the JMX console: https://localhost:8443/jmx-console.

    Note If a load balancer is present, you must bypass it and not log on to the writer machine through a load balancer.

  3. Do one of the following:

    • Search for restoreMasterKeyForCluster.
    • Click UCMDB:service=Security Services > restoreMasterKeyForCluster.
  4. Click Invoke. The master key will be changed first on the writer machine and then on all reader machines.

  5. Restart all the machines in the cluster. You can use the JMX method High Availability Services > restartCluster to do this.

    Note Restart the cluster immediately after changing the master key. If you do not, future database connections may fail.

Revert the master key for a machine that was down when master key was reverted for whole cluster

  1. Back up the C:\UCMDB\UCMDBServer\conf\cmdb.conf file.

  2. On the writer machine, launch the Web browser and enter the following address to log in to the JMX console: https://localhost:8443/jmx-console.

  3. Do one of the following:

    • Search for restoreMasterKey.
    • Click UCMDB:service=Security Services > restoreMasterKey.
  4. Click Invoke.

  5. Restart the machine.

    Note Restart the cluster immediately after changing the master key. If you do not, future database connections may fail.

Send Help Center feedback