1. Welcome to Checkmk as AMI
Whether you are a long-time user of Checkmk or have only recently found us with the availability of ready-made images in the Amazon Web Services (AWS) Marketplace, in this article you will find all of the resources required to configure the prepared Amazon Machine Image (AMI) into a monitoring suitable for your needs.
If you are new to Checkmk, we recommend reading our Beginner’s Guide in preparation. Preconfigured VM images may shortcut many tasks during an installation, but some knowledge of fundamental concepts, such as sites, will help during the setup process.
1.1. The basics
If you are an AWS user, you have always had the option of adding Checkmk to an existing Ubuntu image available in the Marketplace, in order to set up a 'monitoring in the cloud'. Checkmk 2.2.0 takes this a step further and provides a pre-installed image based on Ubuntu 22.04 (Jammy Jellyfish) with all of the required dependencies already included. Only the Checkmk Cloud is used here. This will be in a 30-day 'Trial' license state with no restrictions when the first site is set up. After the trial period expires, Checkmk can continue to be used as a single site with up to 750 monitored services without requiring a subscription. If more services need to be monitored, or more sites are required, you will need a license key.
In general, the setup is a bit more involved than, for example, Docker image, after all, the image provided must cover various deployment scenarios:
A single site setup on a server at various scales
Central site in a distributed monitoring
Remote site in a distributed monitoring
Mixed operations consisting of a production site and site(s) for running tests on a host
For this reason, the AM image does not include a ready-to-run site, an email or a firewall configuration.
In this article we will guide you through the complete setup. Where additional background information would be useful, we link to detailed articles in our User Guide.
2. Preparation
As well as the dimensioning of RAM, processor and virtual hard drives, you should also think about the location for the storage of backups.
Checkmk natively supports Amazon’s object stores, but backups can also be stored in file system paths, which allows backups to SMB or WebDAV mounts or regular transfers via rsync.
2.1. Creating SSH keys
AWS currently supports keys in the ED25519 and RSA formats. You can create an ED25519 key pair for the first login to the virtual machine, whose public key you upload when you create the VM. Alternatively, you can let AWS create the key pair. In this case, do not forget to save the private key immediately after creation, because it will next be automatically deleted for security reasons.
2.2. Determining the required ports
In a Checkmk configuration with a single site setup, in which hosts also send data to the Checkmk site in the push mode, the following Checkmk server ports must be accessible:
From the hosts in monitoring: Port 80/443 (HTTP/HTTPS, during agent registration) and Port 8000 (the Agent Receiver, permanently).
For management via the browser and the REST API: Port 80/443 (HTTP/HTTPS)
The sharing of these ports is predefined in our Standard Security Groups. For best possible security, you should further restrict access to the IP address ranges you actually need.
Consult our overview of all ports used if you want to set up a distributed monitoring or, for example, make status queries via the Livestatus interface.
2.3. Booking an image in the Marketplace
The following VM instances represent a recommendation for the dimensioning of the number of services to be monitored.
| Type | CPU cores | RAM (GB) | Checkmk services |
|---|---|---|---|
|
4 |
8 |
12 000 |
|
8 |
16 |
30 000 |
|
16 |
32 |
60 000 |
The basis for such calculations of dimensioning is approximately 15 % of services by special agents and active checks, as well as 25 or more services per regular host delivered via an agent in push mode. Under certain circumstances, significantly more services are possible in a purely synthetic monitoring (in which data is primarily delivered by special agents). When using agents in pull mode, the specified number of services may only be achievable through consistent optimization.
The dimensioning of the hard disk space is based on experience of typical Windows and Linux server environments. If there are many services producing a large volume of metrics, a larger amount of storage space may be required.
2.4. Booking backup storage
Because of the favorable traffic costs, we advise the use of an AWS S3 Bucket. For the calculation of the required storage space, read the notes on the RRD data format. As a rule of thumb for calculating a full backup, Round Robin Databases will have reached just over a third of their maximum capacity after 10 days. This means that after this time it makes sense to again review the size of the backup storage that has been booked.
3. Setup
3.1. Login to the virtual machine
The root login is disabled on the AWS/Azure images.
Instead, the user ubuntu is employed, which has permission to run sudo with arbitrary commands without a password prompt.
If you have created a separate key pair for login to the virtual machine, you must specify the path to its private component with the -i parameter.
Of course, the IP address must be customized to the one under which the VM can be accessed from a remote location:
user@host:~$ ssh -i /path/to/id_file.priv ubuntu@192.0.2.123You will now find yourself at the ubuntu user prompt.
The actual prompt can contain the host name specified when the VM was created or an IP address as the host name.
We will use the host name cloud throughout the rest of this article:
ubuntu@cloud:~$3.2. Setting up a site
A Checkmk site must have a unique name and should also be easily identifiable.
Here, as in most other places in this manual, we use mysite as the site name.
Creating a site is performed with the Checkmk administration tool omd.
The latest version of Checkmk is always pre-installed:
ubuntu@cloud:~$ sudo omd create mysite
Adding /opt/omd/sites/mysite/tmp to /etc/fstab.
Creating temporary filesystem /omd/sites/mysite/tmp...OK
Updating core configuration...
Generating configuration for core (type cmc)...
Starting full compilation for all hosts Creating global helper config...OK
Creating cmc protobuf configuration...OK
Executing post-create script "01_create-sample-config.py"...OK
Restarting Apache...OK
Created new site mysite with version 2.2.0p1.cce.
The site can be started with omd start mysite.
The default web UI is available at http://cloud/mysite/
The admin user for the web applications is cmkadmin with password: UbWeec9QuazIf
For command line administration of the site, log in with 'omd su mysite'.
After logging in, you can change the password for cmkadmin with 'cmk-passwd cmkadmin'.Now start the newly created site with
ubuntu@cloud:~$ sudo omd start mysiteThe URL in the command output shown above (http://cloud/mysite) contains the host name used internally by your AWS or Azure VM.
Since it is usually not resolved externally, this URL is of limited use.
Typically, you will initially access it using the IP address or a host name stored in your own DNS server.
3.3. Storing certificates
For the system Apache to be able to actually listen on HTTPS port 443, it will require valid certificates. The self-signed Snakeoil Inc. certificates are generated for this purpose when the virtual machine is first started. We strongly advise replacing these as soon as possible with your own certificates that allow the complete certificate chain to be easily verified.
In doing so, the Apache configuration closely follows the Ubuntu standards, and modified certificate paths must be entered in the /etc/apache2/sites-enabled/000-default.conf file.
3.4. Setting up an email system
Since the paths for notifications in Checkmk are many and can vary, a default email system is not predefined.
Checkmk without an email system
It is also possible to completely dispense with a local email system if you only want to enable trackable delivery of HTML emails via SMTP or rely on notification plug-ins for platforms such as Microsoft Teams or Slack.
Note, however, that bulk notifications is not possible in this configuration.
Relay-only or full Mail Transport Agent (MTA)
As a rule, you will want to set up an email system because of its greater flexibility. For smaller environments, the relay-only MTA Nullmailer has been proven to work well.
For larger installations, where unforeseen events can result in several hundred emails, we recommend installing a full-featured MTA such as Postfix.
3.5. Adding hosts to a monitoring
Localhost in pull mode
In the vast majority of cases, the Checkmk server itself should be the first host you add to the monitoring.
To do this, you must first install the Linux agent on the Checkmk server.
This agent communicates with the server in the pull mode.
If you find downloading the agent package via the web interface followed by a transfer via scp too cumbersome, you can install the agent in its default configuration ('Vanilla') directly from the file system:
ubuntu@cloud:~$ sudo apt install $(sudo find /opt/omd/versions/ -name 'check-mk-agent_*.deb' | tail -n1)Immediately following an installation, the Checkmk agent listens in the unencrypted legacy pull mode on port 6556. Therefore, promptly perform a registration to prevent unauthorized third parties from accessing the agent output:
ubuntu@cloud:~$ sudo cmk-agent-ctl register --hostname localhost --server localhost --site mysite --user cmkadminHosts in push mode
If hosts to be monitored are behind a firewall and thus cannot be accessed directly by the Checkmk server, the push mode is often the preferred communication path. You can select the push mode with the Checkmk agent connection mode option in the host’s properties in the Monitoring agents section. Alternatively, you can combine the push mode with pre-configured agent packages for the auto-registration to further increase convenience.
3.6. Updating Checkmk
Check the download page regularly for updates and download the updated package with the wget command shown there.
The installation of an update is done in two steps, which is due to the fact that omd can run multiple sites, each with different versions of Checkmk, on the same server.
Installing a new Checkmk version and updating the site
The first step is to install the package, in the following example the 2.2.0p2 version:
ubuntu@cloud:~$ sudo apt install ./check-mk-cloud-2.2.0p2_0.jammy_amd64.debThe next step is to update your site(s):
ubuntu@cloud:~$ sudo omd stop mysite
ubuntu@cloud:~$ sudo omd update mysite
ubuntu@cloud:~$ sudo omd start mysiteRemoving packages that are no longer required
If you run multiple sites on the server (for example, one for production use and one for the testing of extensions), make sure that all of these are updated:
ubuntu@cloud:~$ omd sites
SITE VERSION COMMENTS
mysite 2.2.0p2.cce default version
mytestsite 2.2.0p2.cce default versionVia the Ubuntu package management you can then uninstall Checkmk versions that are no longer being used:
ubuntu@cloud:~$ sudo apt purge check-mk-cloud-2.2.0p14. Post-processing
4.1. Configuring the backups
Checkmk provides a convenient backup function, which is configured under Setup > Maintenance > Backups > Backup targets. With Add backup target you add a storage location. Here it is advisable to select a AWS S3 bucket as the Destination because of its fast and cheap data transfer.
In addition to the credentials, you must also specify a folder path where the archive is temporarily stored before it is copied to the object store.
This can be under /tmp.
If your AWS instance provides a volatile (ephemeral) drive, you can mount this and use it as a cache.
Procedure for a restore
The restore of a backup must always be done on exactly the same version of Checkmk as was used to create it. If a backup is to be used to move to another type of virtual machine, to another cloud provider or from an on premise installation to the cloud (or vice versa), always first upgrade to the highest available patch level of Checkmk before the final backup and migration.
The following points apply to the restore of a backup:
On the target system, install exactly the version of Checkmk that was used to create the backup.
Create a monitoring site with
omd createthat uses the same site name as the source system.Specify the backup destination and upload the backup key.
Perform the actual restore.
5. Monitoring AWS
Checkmk not only provides availability as an AMI, but also a comprehensive monitoring of your AWS infrastructure. Even if Checkmk should be your first or only AWS project, it is already worth monitoring the performance of the site, the state of the backup buckets and the level of costs incurred.