Changing a CA SSL certificate for the Agent Bakery

Owned by Anastasios Thomaidis
Last updated: Dec 18, 2024 by Matthew Hierholzer
If your Checkmk Server is using HTTPS, and you're using the Agent Bakery, you need to be careful when exchanging the HTTPS certificate of your Checkmk server.
If the root CA for the new certificate stays the same, this should be no problem for the Agent Bakery. However, if the CA changes, or if you change a standalone self-signed certificate, you must follow some extra steps.

APPLICABLE TO ALL CHECKMK VERSIONS

Table of Contents


Getting Started

Background information regarding this subject is available on our:

Step-by-step guide

  1. Get new certificate

  2. Check if the certificate chain has changed. This means either your root certificate or an intermediate certificate have changed.

    • Yes: Jump to step 3
    • No: Jump to step 4


  3. The chain or the standalone self-signed certificate has changed:
     
    1. Add the new chain to the Agent Updater (do NOT replace the old chain!). 

    2. Bake and sign agents.

    3. Wait until all agents have updated. Make sure to verify this!

    4. Proceed to step 4.


  4. The chain did not change, or step 3 was competed:

    1. Restrict agent updates to only 2 or 3 hosts, to double-check, if everything works as expected.

    2. Deploy the new certificate to the Apache server.

      For Checkmk Appliances: Click on Device Settings → Web Access → Upload Certificate

      screenshot showing the location of device settings

      screenshot showing the location of web access

      screenshot showing the location of upload certifcate

      For more information about Appliances and SSL certificates, please refer to our Official Documentation.

    3. Check for the correct cert and chain by using a browser.

    4. Make sure agent update works for the test hosts.

    5. If the chain changed (see step 3), remove the old chain from the updater rule, bake & sign agents, and see if everything works with the test hosts.

    6. Remove the restriction to the test hosts and update all agents.

Verification

The following can help determine if the certificates of an agent match the certs of the Checkmk server.


Show the Certificate Authority, Issuers, and Subjects of the certificates that were installed with the agent package.

root@mylinuxhost:~# echo "Agent updater certificate store:"
openssl crl2pkcs7 -nocrl -certfile <(cat /etc/check_mk/cmk-update-agent.cfg | egrep "\\n'" | cut -f2 -d":" | cut -f2 -d"'" | sed "s/\\\\n//g") | openssl pkcs7 -print_certs -text -noout | grep -e Subject: -e Issuer -e CA


Show Issuer, Subject and Subject Alternative Names of the certificate of the server where the agent updater is registered to:

root@mylinuxhost:~# s=$(cat /etc/check_mk/cmk-update-agent.cfg | grep "'server'" | cut -f4 -d"'")
echo "CMK Server HTTṔS Certificate for $s"
openssl s_client -connect $s:443 </dev/null 2>/dev/null | openssl x509 -noout -text | grep -e Issuer: -e Subject: -e DNS: