/
How-to exchange a signature key for the automatic agent updater

How-to exchange a signature key for the automatic agent updater

Owned by Matthew Hierholzer
Last updated: Jun 24, 2025

To ensure integrity and authenticity, agent packages must be signed. This article explains how to exchange the signature key.

LAST TESTED ON CHECKMK 2.3.0P1

Table of Contents

Getting Started

Agents download updates via HTTP or HTTPS from the central monitoring server. Since they contain executable code, it's critical to ensure their authenticity. This is achieved using signature keys based on a public and private key pair.

Starting with version 2.2, Werk #15064: Agent updater checks for certificate validity set the lifetime of new signing-keys to 2 years. With Werk #17102: Agent Signature Key Expiry and Notifications, the key mechanism was reworked. The lifetime is extended to 10 years.


Problem

Depending on your patch level and the creation date of the signature key, you will be informed about the expiring signature key (< 90 days) by a WARN state of the service "Check_MK-Agent" :

 

or all users with the permission “Create Signature Keys” receive a User Message referring them to further steps for exchanging the signature keys:


.

.

Step-by-step guide

Replacing keys before they expire

  1. Navigate to “Setup → Agents → Windows, Linux, Solaris, AIX → Agents” and choose the option Signature keys




  2. Click Generate key. This option creates a new signature key.



    You also have the option to use your own CA by selecting Upload key. For more information, refer to the article Certificate Issuance via Your Own CA.


    .

  3. Enter a description or comment, along with a passphrase. Choose a very secure passphrase and store it in a secure place!




  4. Click Create. Do not delete the old key yet.




Select the new Signature key

  1. Navigate to the Agent updater rule and modify the existing Rule : Setup → Agents → Windows, Linux, Solaris, AIX → Agent rules →  Agent updater (Linux, Windows, Solaris) 




  2. Select at least one new Signature key that should be accepted by the Agent updater. You can uncheck the old key.




  3. Click Save and activate changes



Sign the Agents with old Signature key

  1. Navigate to Setup → Agents → Windows, Linux, Solaris, AIX

  2. Click on Sign agents

  3. Select the old signature key from the list of available keys.



  4. Enter the passphrase associated with the selected key.

  5. The agents will be signed using the selected key. You can verify successful signing in the configuration overview; look for a small key icon in the Signed column for each agent package.

  6. Monitor the agent update status in the appropriate view (Monitor → System → Agent update status). Verify that all agents have been updated.

  7. Once all agents have been updated with the new key, you can delete the old key. No further interactions necessary.


Replacing expired keys

If the signature key has expired, the agent will no longer accept any updates signed with that key. If no other, still valid keys are available, you will need to force the update on each host manually:

  1. Create a new signature key

  2. Select that new key under Signature keys the agent will accept in the Agent updater rule (you can uncheck the old key)

  3. Bake and sign agents with the new key

  4. Log into the host and force the update without checking signatures using cmk-update-agent --skip-signatures

  5. Use cmk-update-agent show-config to verify that the update succeeded