I wanted to automate certificate management on Checkmk Appliances without having to manually upload renewed certificates through the Webconf every few months.
After spending some time looking into the appliance internals (and with quite a bit of help from ChatGPT while reverse-engineering the Webconf Python code ), I ended up writing a small wrapper around acme.sh together with a custom deploy hook that uses the appliance’s own Python APIs for certificate installation.
The goal was to integrate with the appliance instead of simply replacing certificate files on disk.
Features
Supports standalone and HA appliances
Automatically skips certificate operations on standby nodes
Uses the internal Webconf certificate handling
Triggers the normal ssl_certs activation hook
Synchronizes certificates to the cluster partner using the appliance’s built-in synchronization
No manual Webconf interaction required
No changes on the appliance OS files
The wrapper currently provides three simple commands:
./cma-acme.sh issue
./cma-acme.sh renew
./cma-acme.sh status
Configuration is handled through a single configuration file, while the deploy hook takes care of installing, activating and synchronizing the certificate.
Tested environment
Currently tested with:
Checkmk Appliance 1.7.21
acme.sh
dns_custom
Other DNS providers should work as well, but I have only tested dns_custom so far.
Hopefully it’s useful for anyone running Checkmk Appliances and wanting fully automated certificate management.
Feedback, bug reports, feature requests and pull requests are always welcome. If you test it with other appliance versions or DNS providers, I’d love to hear how it works for you.
As the person having written the current iteration of Securing the web interface with HTTPS , I totally understand the motivation and will propagate this to our internal appliance working groups ( Hi, @robin.gierse !).
I genuinely hate to be the bearer of bad news here, but:
This is obviously unsupported and voids support
We have no capacity to look into integrating this or building this ourselves
The APIs used are not official APIs and can break with any release
On a personal note: This is pretty cool, and I hope it provides value to some. Just be advised, that using it will void support. Maybe you want to add a disclaimer at the top of your repo @mathse. And while I would love to see this as official functionality in the Checkmk Appliance, I am afraid currently it is not up for discussion. You can and should of course file the idea over at https://ideas.checkmk.com (if it is not already filed), so we gain visibility.
Thanks for your feedback and the clarification. I completely understand that this cannot be officially supported since it relies on internal appliance APIs.
The goal of this project is not to replace an official solution, but to provide a community-maintained option for those of us who prefer automated certificate management over manual uploads.
I added a clear disclaimer to the repository that this is unsupported and may require adjustments after appliance updates.
The upcoming CA/Browser Forum changes towards shorter certificate lifetimes were the main motivation for this project. If certificate renewals become necessary every few weeks instead of every few months, manually uploading certificates through the appliance Webconf is no longer a practical long-term solution. That was my main driver.
as Mathias already pointed to the CA/Browser forum changes:
March 2027 maximum certificate lifetime will be reduced from 200 to 100 days
March 2029 maximum certificate lifetime will be reduced from 100 to 47 days
A manual process to change certificates will no longer be acceptable for a professional product. If a vendor does not have any automation yet (or at least an API that customers can use to take care themselves) this should absolutly be on this years roadmap.
I’m irritated that such an important security aspect is delegated to the ideas portal.
As of my understanding, these lifetime reductions only apply to publicly trusted certificates. I believe most checkmk installations use certificates from the enterprises’ internal CA, where you can still issue certificates with e.g. 1y lifetime. At least thats what we do. Of course this also depends on your security policies, but I personally do not see a benefit in renewing my checkmk certificate every month.
I totally agree ACME is a nice feature, but probably not high prio for 99.9% of the customers.
While this currently might only apply to public CAs reality has shown us that not all implementations care: we run into that issue when certificate lifetime was reduced from 2 years to 1 year. In theory nothing should have happened. In reality browsers and Apple devices did not accept these certificates anymore.
And I guess there are some service providers which might want to use public certificates to secure Checkmk instances they provide for their customers. I don’t know what Checkmk is doing themselves for their Cloud offering.
Next will be an upcoming compliance issue. With public certificates having short lifetimes due to security reasons this will be considered best practice or “Stand der Technik” to use are famous BSI wording. Good luck arguing about that in your upcoming security audits.
So in my opinion at least an API to change the certificate should be on the roadmap for Checkmk 3.0. Having an ACME implementation or at least ACME challenge support in Checkmk would save a lot of work. Especially with the HTTP-01 challenge.
), I ended up writing a small wrapper around acme.sh together with a custom deploy hook that uses the appliance’s own Python APIs for certificate installation.
Hi, 