Running apcertmgmt to update certificates

By default, IBM provides the certificates required for platform manager, but you can also choose to provide your custom certificates instead. If your custom certificates expire, you can use the apcertmgmt command to apply new certificates for platform manager.

There are two types of certificates that must be provided:
  • cluster certificates, which are used for internal platform management communication, no endpoint accessible externally is using them
  • REST certificates, which are used for externally accessible REST API (for example, ap commands use this API)
Note: If you are using IBM provided certificates and you want to update them, follow the instructions in Platform Manager certificate patch release notes.

About this task

To upgrade the certificates, application downtime is required.

The system must be in state Active, that is, with the platform manager running and system application stopped. Depending on the state your system is in, you can run apstop -a to stop the system application, or apstart -p to start the platform manager only.

All nodes must be reported as monitored in ap node output, as in the following example:
[apuser@node0101 ~]$ ap node
+-----------------+---------+-----------+-----------+
| Node            |   State | Monitored | Is Master |
+-----------------+---------+-----------+-----------+
| hadomain1.node1 | ENABLED |       YES |       YES |
| hadomain1.node2 | ENABLED |       YES |        NO |
| hadomain1.node3 | ENABLED |       YES |        NO |
| hadomain1.node4 | ENABLED |       YES |        NO |
| hadomain1.node5 | ENABLED |       YES |        NO |
| hadomain1.node6 | ENABLED |       YES |        NO |
| hadomain1.node7 | ENABLED |       YES |        NO |
+-----------------+---------+-----------+-----------+

The apcertmgmt command allows you to manage the certificates. Cluster certificates can be both generated and propagated to the other nodes using this tool. The REST certificate can only be propagated (it has to be generated manually). Following are the steps needed to update both types of certificates:

Procedure

  1. Ensure that the system is in Active state, that is with the platform manager running and system application stopped.
    If the application is running, run:
    apstop -a
  2. To update cluster certificates:
    1. Run apcertmgmt without any parameters. The command is interactive: 
      [apuser@node0101 ~]$ apcertmgmt
Do you want to replace current cluster certificate? [y/N]: y
Create cluster certificate automatically? [y/N]: y
Certificate for cluster created
Continue cluster certificate propagation? [y/N]: y
Certificate for cluster copied to nodes. Do you want to proceed (Appliance will be stopped)? [y/N]: y
Successfully deactivated system
Appliance stopped. Apply new certificate? [y/N]: y
Cert for cluster applied successfully, issued apstart -p
Successfully activated platform
      Alternatively, a quiet version of the command can be used: apcertmgmt -q. All inputs are assumed to be y:
      [apuser@node0101 ~]$ apcertmgmt -q
Certificate for cluster created
Successfully deactivated system
Cert for cluster applied successfully, issued apstart -p
Successfully activated platform
    2. Verify that certificates were properly updated by running the following command and checking the Not After field: 
      [apuser@node0101 ~]$ openssl s_client -connect node0101-fab:5003 2>/dev/null | openssl x509 -text -noout
Certificate:
    Data:
        Version: 4 (0x3)
        Serial Number: 2 (0x2)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, CN=Sailfish, ST=NY, L=New York, O=IBM, OU=IBM Analytics
        Validity
            Not Before: Jan  1 00:00:00 1970 GMT
            Not After : Jul 18 09:37:34 2026 GMT
        Subject: C=US, CN=Sailfish, ST=NY, L=New York, O=IBM, OU=IBM Analytics
        Subject Public Key Info:
            ...
  3. To update the REST certificate:
    1. Generate the certificate. It can be done using the openssl command as in the following example: 
      openssl req -x509 -newkey rsa:4096 -keyout pm_server.key -out pm_server.cert -days 36500 -nodes -subj "/C=US/ST=New York/L=Armonk/O=International Business Machines Corporation/OU=Analytics/CN=Magneto"
      Two files should be generated: pm_server.cert, and pm_server.key. Certificate subject can be adjusted as needed, externally generated certificate can also be provided.
    2. Use the apcertmgmt command to propagate the certificate: 
      [apuser@node0101 ~]$ apcertmgmt --cert pm_server.cert --key pm_server.key
Validating REST certificate on node node0101-fab ...
Validating REST certificate on node node0102-fab ...
Validating REST certificate on node node0103-fab ...
Validation is successful on all node
Certificate for HTTP REST copied to nodes. Do you want to proceed (Appliance will be stopped)? [y/N]: y
Successfully deactivated system
Appliance stopped. Apply new certificate? [y/N]: y
Cert for HTTP REST applied successfully, issued apstart -p
Successfully activated platform
      Alternatively, a quiet version of the command can be used, where all inputs are assumed to be y:
      [apuser@node0101 ~]$ apcertmgmt --cert pm_server.cert --key pm_server.key -q
Validating REST certificate on node node0101-fab ...
Validating REST certificate on node node0102-fab ...
Validating REST certificate on node node0103-fab ...
Validation is successful on all node
Successfully deactivated system
Cert for HTTP REST applied successfully, issued apstart -p
Successfully activated platform
    3. Verify that certificates were properly updated by running the following command and checking the Not After field: 
      [apuser@node0101 ~]$ openssl s_client -connect node0101-fab:5001 2>/dev/null | openssl x509 -text -noout
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            c4:59:99:52:a8:56:24:53
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, ST=New York, L=Armonk, O=International Business Machines Corporation, OU=Analytics, CN=Magneto
        Validity
            Not Before: Jul 19 10:39:03 2021 GMT
            Not After : Jun 25 10:39:03 2121 GMT
        Subject: C=US, ST=New York, L=Armonk, O=International Business Machines Corporation, OU=Analytics, CN=Magneto
        Subject Public Key Info:
            ...
      Ctrl-C might be needed out of this command.
    4. If certificates were properly applied and they were generated using the openssl command, they can now be safely removed from the current working directory: 
      rm -f pm_server.cert pm_server.key

What to do next

In the process, the system is stopped and then platform manager is started (apstart -p). Note that the application is not started automatically. Start the system application with the following command:
apstart -a