1. Checkmk in a Docker container
In our installation guide for Checkmk in Docker we’ve already shown you how to set up Checkmk in a Docker container. This article takes a closer look at more of the details.
2. Optional parameters during the setup
All of the following parameters are specified additionally when setting up a Checkmk site as a container and are therefore not available separately.
2.1. Using HTTPS
If Checkmk is the only web server on your dockernode, you can also bind the
port to the standard (
80) HTTP port. As soon as you you have multiple
web servers on a dockernode however, you will probably use a reverse-proxy
like NGINX – this directs the inquiries to the correct container. With this
technology you can also use (possibly preexisting) HTTPS. The reverse proxy
will then be addressed via HTTPS, while communicating with the container
continues via HTTP.
2.2. Setting an initial password
In Checkmk, when setting up an instance a
random password for the default user
cmkadmin is created. When creating a Checkmk container you can also
assign a password manually. Simply add the
-e CMK_PASSWORD ='mypassword' option during the creation process.
2.3. Setting your own instance ID
With the default command to create a Checkmk container, the ID of the instance
created in the container will be
cmk. This is important to be able to
access the instance via HTTP(S) and it must therefore be explicit. If you have
multiple containers of Checkmk on the same dockernode, you will have to set the ID
manually to ensure this uniqueness. You can do that by including the
2.4. Sending notifications
An important feature of Checkmk is the sending of notifications per email. Checkmk uses Postfix as its MTA (Mail Transfer Agent) for outgoing mails. This postfix instance is configured not to deliver mails directly to the recipient, but basically tries to forward to an additional mail server (SMTP Relay Server, Smarthost) which you need to provide outside of the container. Such a relay server is available in almost every organization.
When implementing, specify the relay mail server that will forward the notifications.
MAIL_RELAY_HOST variable — e.g.,
-e MAIL_RELAY_HOST='mailrelay.mydomain.com'. If the mail server expects a specific host name, add the following
Checkmk containers currently do not support the configuration of access data for a smart host. You can bind a postfix configuration or configuration folder from the docker node if you need them.
If you use one of the Checkmk Enterprise Editions, you are able to bypass postfix completely so that Checkmk forwards notifications directly to a smarthost. This is done by the synchronous SMTP, which is described in detail in the article about notifications. Here an authentification over SMTP is also possible.
2.5. Access to Livestatus via TCP
As soon you connect multiple Checkmk containers/instances together
in a distributed environment you will need a special TCP port for the
Livestatus interface. This interface allows communication between the
instances. Bind this port – likewise the port for HTTP – to one of the
Docker nodes, and enable this TCP port in the Livestatus instance:
2.6. Access via the command line
In some cases you will want to execute commands on the command line.
Because commands for an instance are always executed via a special user,
you must specify this when logging in. In Checkmk the user always has the
same name as the instance it manages. Specify the user
cmk with the
-u cmk option:
root@linux# docker container exec -it -u cmk monitoring bash
You can then pass your commands to the instance.
2.7. Using the Event Console
Checkmk is able to receive SNMP traps and syslog messages. To be able
to use this feature in a Checkmk container, the standardized ports must
be provided to the Checkmk container with the following options:
162:162/udp -p 514:514/udp -p 514:514/tcp `. In order that the instance
itself also respects these ports, next activate the the appropriate add-ons
in the instance with `omd config. You can
find these in the
root@linux# docker container exec -it -u cmk monitoring bashomd config
3. Updating a Checkmk container
3.1. Simple update for current Checkmk images
The updating of a Checkmk instance differs depending on the version of the image. As of 1.5.0p13 the update process is very simple, and the following are the only requirements:
The container is not deleted when the container is stopped — i.e., the
--rmoption was not used at startup.
You know the ID of the data storage (volume) for the container. Normally you should have given its storage a unique ID when you started the container. If you are unsure of your volume’s ID, you can find help below.
If you followed the Introduction to Checkmk in container you should automatically meet the first two requirements. If your container uses an image that is older than 1.5.0p13, please follow the instructions below. Otherwise the update process is performed in 3 steps:
Stop the container. If the Checkmk container is called
myContainer, the command will be, for example:
docker stop myContainer.
Remove the container. The command is:
docker rm myContainer.
Start a new container with the desired version, and mount the known volume. If your volume is called
myVolume, the corresponding option is
Checkmk will then automatically do the rest — updating and starting your Checkmk instance. Afterwards you will be able to log in as usual.
3.2. Detailed update for older Checkmk images
Updating a Checkmk instance older than 1.5.0p13 is more complex. The reason is mainly due to the architecture of Checkmk, since in the course of a version change the configuration of an instance and other data need to be updated as well. An update is therefore performed — differently to as described above or directly on a server — in the following steps:
Backup the Checkmk container
If you have created the container as recommended, all data will be stored in a persistent file system which is independent of the container itself. It is therefore not sufficient to take a snapshot of the container to save the data. Therefore stop the container and backup the container’s data to a suitable external location:
root@linux# docker stop monitoring monitoring root@linux# docker cp monitoring:/omd/sites - > /my/path/to/backup.tar
Update the Checkmk container
Now create a second container with the new version, so that for the update both the old version and the desired one are available. A command is given to prevent them from both from starting. Keep this shell open so that the update can be carried out later:
root@linux# sudo docker container run -it --rm --volumes-from monitoring --name monitoring_update checkmk/check-mk-enterprise:1.5.0p6 bash root@801beb91d3b6:/#
Checkmk always sets a standard specifying which Checkmk version should be used. Change this entry on the second container with the following command:
root@linux# docker cp -L monitoring:/omd/versions/default - | docker cp - monitoring_update:/omd/versions/
Now you can perform the update on the second container. If applicable, close the open shell after the update is complete:
root@linux# docker exec -it -u cmk monitoring_update omd update 2018-10-12 14:32:29 - Updating site 'mytest' from version 1.5.0p4.cee to 1.5.0p5.cee... [green]#* Updated *etc/apache/conf.d/omd.conf Finished update.
Exchange the Checkmk container
After you have updated the (configuration) data, you can replace the old container with the new one. First rename the old container:
root@linux# docker rename monitoring monitoring_old root@linux#
You can now start a container with the new Checkmk version, and assign the updated file system from the old container to it:
root@linux# docker container run -dit -p 8080:5000 --tmpfs/omd/sites/cmk/tmp --volumes-from monitoring_old --name monitoring checkmk/check-mk-enterprise:1.5.0p6
You can also check in the logs to see whether the container has started without problems:
root@linux# docker container logs monitoring // STARTING SITE Preparing tmp directory /omd/sites/cmk/tmp...OK Starting mkeventd...OK Starting liveproxyd...OK Starting mknotifyd...OK Starting rrdcached...OK Starting cmc...OK Starting apache...OK Initializing Crontab...OK // STARTING CRON // CONTAINER STARTED
Finally, delete the old container:
root@linux# docker rm monitoring_old
4. Creating your own container-images
With the help of our our repository you can also
create your own images with a Checkmk Enterprise Editions. Clone the current
Checkmk-Git, and navigate to the
docker directory. With the help of your customer data you can now
create your own image:
UP(myuser@myhost:~/git/check_mk/docker#):docker build \ --build-arg CMK_VERSION=1.5.0p5 \ --build-arg CMK_EDITION=enterprise \ --build-arg CMK_DL_CREDENTIALS='myusername:mypassword' \ -t mycompany/check-mk-enterprise:1.5.0p5
During the build process you will need two external files which — using your customer login data — will be automatically downloaded from our download server. To prevent this you can also
first load the necessary files manually and place them in the
The Checkmk installation package for Debian Stretch
The public GPG-Key for the installation packet
5. Useful commands
docker inspect myContainer
With this command you can get all sorts of information about a running container with the name