In this article you will find all of the information on setting up and operating both the virtual and the physical appliances. Two major topics are covered in separate articles: backups and clusters. In another article, we cover the hardware-specific aspects regarding the racks.
We start here with the initial start of the appliance — so the virtual appliance must already have been installed, or the rack connected, respectively. If you simply want to get to the point where you can log in to Checkmk in the browser as quickly as possible, it is best to refer to our quick start instructions for the rack and virt1 respectively.
2. The basic configuration
2.1. Initialization on first startup
During the initial start-up, a first message appears requesting a selection of the desired language:
This language is saved for the entire appliance. Afterwards, a message appears prompting you to initialize the data medium (for the racks in the RAID):
Confirm this dialog and wait for the process to complete. The status view will then be displayed on the local console:
This view shows you general status information and the most important configuration options for your device.
2.2. Network and access configuration via the console
From the status view, you can open the configuration menu by pressing the
To put the appliance into operation, you must now set the network configuration and define this unit’s password.
First set up the network via the Network Configuration item. To do this, the IP address, netmask and the optional standard gateway are requested one after the other.
In most cases, the appliance should also be able to access network devices outside of its own network segment. For this, the standard gateway must also be configured.
After entering these values, the configuration will be activated.
The appliance will then be immediately accessible via the network under the specified IP address.
You can test this connection, for example, with a
ping from another device in the network.
Activating the web interface
Most of the configuration of the unit is done via the web interface. Access to it is protected by the device password, which you must first specify. No such password is preset when the unit is delivered, which means that access to the web interface is not possible.
In the configuration menu, select Device Password, for the menu to enter the device password. The password must be at least 8 characters long and contain at least one lower case letter, one upper case letter and one digit.
Next, select Web Configuration from the configuration menu to activate the web interface.
When you have completed these steps, you will see the changed status view of the console:
In the Device Infos box is the configured IP address and in the Access box is Web Configuration: on. If you have already connected the appliance correctly to your network, in the Status box you should also see that the network connection is active: LAN: UP.
Securing access to the console
When you first started the appliance, you may have noticed that there was no password prompt. Anyone with physical access to the rack or the virtualization solution’s management interface could change its basic settings via the console.
You should therefore activate password protection in the configuration menu via the Console Login menu item. If protection is activated, the device password will be requested before the status view is displayed and any settings can be changed.
Afterwards, in the status view you will see the Console Login: on entry in the Access box.
2.3. Basic settings in the web interface
After you have enabled access to the web interface through the previous configuration, you can now call it up via any computer in the network.
To do this, enter the appliance URL in the browser’s address line, in this case
You will then see the login dialog for the web interface:
When you have logged in with the previously set device password, the main menu opens from which you can access all of the functions of the web interface.
Select Device Settings, to view the most important settings for the appliance and to change these if required:
Clicking on the parameter name will take you to the respective page for editing this setting.
If available in your environment, you should now first configure one or more DNS servers so that the resolution of host names can be used. If one or more NTP servers are available for time synchronization in your environment, enter these via their IP addresses or host names under NTP Servers.
If emails are to be sent from your appliance, e.g. notifications in the event of problems, you must configure the Outgoing Emails option. To do this, enter the SMTP relay server responsible for this device and any access data required for it. All emails generated on the device will be sent to this server. In this setting, you can also configure that all emails generated by the unit’s operating system, e.g. in the event of critical errors, are sent to a separate email address.
3. Device settings
All of the following settings can be found in the Device settings section.
3.1. Changing the language setting
The language you want to use for your appliance was first selected during the basic configuration. You can change the language setting at any time via the console configuration as well as via the appliance settings in the web interface. As with all other settings in this dialog, changes become effective immediately when saved.
3.2. Changing the default web page
If you call up the appliance’s URL in the browser without specifying a path, you will be taken to the appliance’s start page by default.
Via HTTP access without URL brings you to you can alternatively specify an installed monitoring site to which you want to be redirected.
You can then reach the appliance start page via the URL by including its path, for example
3.3. Configuring host and domain names
Host and domain names are used to identify a computer in the network. These names are used, for example, to create the sender’s address when sending emails. In addition, all log entries sent to a syslog server are supplemented with the configured host names as the source host to make it easier to identify the entries.
3.4. Configuring name resolution
Host names or FQDNs (Fully Qualified Domain Names) are often used instead of IP addresses in the monitoring process. In most environments, DNS servers are used to translate IP addresses to host names and vice versa.
To be able to use name resolution on your appliance, you must configure the IP address of at least one DNS server in your environment. We recommend that you enter at least two DNS servers.
Only if you have configured this option, you can use host and domain names when configuring the NTP or mail servers, for example.
3.5. Configuring time synchronization
The appliance’s system time is used in many places, e.g. for recording metrics or writing log files. A stable system time is therefore very important, and this is best ensured by using a time synchronization service (NTP).
To activate synchronization, enter the host address of at least one (preferably non-virtual) time server under NTP-Server.
3.6. Forwarding syslog entries
Log messages are generated on the appliance by its operating system and some permanently running processes, and these are first written to a local log via syslog. You can also have these entries sent to a syslog server in order to evaluate, filter or archive them there.
To configure the forwarding, select Syslog..
In the following dialog, you can now specify which protocol you want to use for forwarding. Syslog via UDP is more common, but not as reliable as via TCP. If your syslog server supports both protocols, we recommend TCP.
Furthermore, you must configure the host address of the syslog server that is to accept the log messages.
3.7. Configuring outgoing emails
In order to be able to send emails from the unit, e.g. in case of events during monitoring, the forwarding of the mails to one of your mail servers must be configured via Outgoing Emails.
To do this, as the minimum, the host address of your mail server must be defined as SMTP Relay Host. This server accepts the emails from your machine and forwards them.
However, configuring the SMTP relay server is only sufficient when your mail server accepts emails via anonymous SMTP. If your mail server requires authentication, then you must activate the appropriate login method under Authentication and enter the appropriate access data.
If you do not receive any emails even after this has been configured, it is worth taking a look at the appliance’s system log. All attempts to send mails are logged here.
The appliance itself can send system mails in the event of a critical problem occurring, e.g. if a job cannot be executed or a hardware problem has been detected. To receive these emails, you must configure an email address via Send local system mails to to which these mails are to be sent.
Finally, you can activate transport encryption via TLS and manually specify a default sender address.
3.8. Customizing access to Checkmk agents
A Checkmk agent is installed on the appliance which, by default, can only be queried by the appliance itself. This allows you to include the appliance in a monitoring site running on it.
It is also possible to make the Checkmk agent accessible from a remote appliance, so that the local appliance can also be monitored by another Checkmk system, e.g. from a central server in a distributed environment. For this purpose, you can configure a list of IP addresses that are allowed to contact the Checkmk agent.
3.9. Altering the network configuration
The basic network configuration for the standard network interface was done via the console during the startup. You can change these settings later via Device Settings > Network Settings. You can also add an IPv6 address at this point.
These settings are in the Simple Mode, as you can see from the title of the dialog: Edit Simple Network Settings. The Advanced Mode button activates the Advanced Mode, which gives you access to all of the available network interfaces and bonding functions.
The advanced configuration can help you to increase the availability of monitoring via redundancies. It is also the starting point for configuring a cluster and is therefore described in detail in the cluster article.
4. Managing Checkmk versions
4.1. Basic information
From appliance version 1.4.14, the Checkmk software is not pre-installed in the appliance. The reason for this is simple: Checkmk is updated much more frequently than the appliance and of course you should not have to start with an outdated Checkmk version.
The installation of Checkmk in the appliance does not run via the command line as on normal computers, but conveniently via its own web interface — as you will see in the following. To be able to use this web interface, you must activate it in the appliance management.
The Checkmk software for installation in the appliance is provided to you as a CMA (Checkmk appliance) file. This is simply an archive format containing the Checkmk folder structure plus an info file.
4.2. The Checkmk installation
Download the CMA file from the Checkmk download page. You will get the appropriate CMA file after selecting the appropriate Checkmk edition and version, and the appliance platform.
After downloading the CMA file, select Check_MK versions from the main menu. On the following page, use the file selection dialog to find the CMA file on your hard drive and confirm your selection by clicking on Upload & Install.
The Checkmk software will now be uploaded to the appliance. This may take a few minutes depending on the network connection between it and your computer. Once the upload has completed successfully, you will see the new version in the table of installed software versions:
It is possible to install multiple Checkmk versions to run in parallel on a single appliance. This allows the operation of several sites in differing versions, and the individual sites can be updated to newer versions independently of each other. For example, you can install a new version and first try it out in a test site and then, after a successful test, update your production site.
You load and install additional Checkmk software versions in the same way as the first one. The result will look like this:
If a particular software version is not being used by a site, you can delete that version by clicking on the recycle bin icon.
Following a major update of the firmware from version 1.4 to 1.5, you may see a note here about incompatibilities between installed Checkmk versions. In this event, you must install a Checkmk version compatible with firmware version 1.5 — which may well have the exact same version number, but which is intended for the newer firmware. The explanation for this is that the 1.5 firmware is based on a new operating system (Debian Buster instead of Debian Stretch).
5. Managing monitoring sites
5.1. Creating a site
Select Site Management from the web interface’s main menu. On this page you have access to all of this appliance’s monitoring sites, and can configure, update, delete — and create new sites.
This page will be empty when you access it for the first time. To create your first site, click the Create New Site button. On the page that follows you can define an initial configuration for the site:
First enter an ID (Unique site ID) here, which is used to uniquely identify the site.
The ID may only contain letters, numbers, hyphens (
-) and underscores (
_), must begin with a letter or underscore and may be a maximum of 16 characters long.
Next select the Checkmk version with which the site is to be created. You will be offered all installed versions as listed in the Checkmk versions management.
Finally, you define the user name and password for the Checkmk administrator. You can leave all other settings unchanged for the time being and adjust these later if required.
Click Create Site to create the site. This may take a few seconds. Once the site has been created and started, a list of all sites will appear on the page:
At this point, the list is short and only shows the newly created site with the ID mysite and its status, here running. You can stop or start the site with the button on the far right in the Control column. On the far left in the Actions column, symbols are shown for the possible actions you can apply to the site, from left to right: Edit, Update, Rename, Clone, Delete and Login.
You can now log in to the started site, either by clicking on the site’s ID or by calling up the site’s URL in your web browser’s address bar, in our example:
In the site’s login dialog, enter the access data you specified when creating the site.
Once logged in, you can set up Checkmk as usual — the first steps are described in the article on Setting up monitoring.
In all appliance sites, the Checkmk Appliance snap-in is available to all administrators in the sidebar:
With the entries in this snap-in, you can always switch from a site to the appliance’s web interface.
5.2. Updating a site
When a site is updated, it will also automatically be updated to a new Checkmk software version. First install the desired new version as described in the chapter on managing Checkmk versions.
Caution: When updating to new Checkmk major versions, you should refer to the related article. It is important here that you only ever update to the next major version and do not skip over any intermediate versions.
Then have the appliance’s web interface list the sites (Main Menu > Site Management):
Make sure that the site is not running, i.e. if its Status is shown as running, stop the site (Control > Stop). Then click on the update icon under Actions.
The following page lists the possible target versions for the update:
Select the target version listed at Target Check_MK version, and click on Update now. After a short time, the update messages will be displayed:
The Back button returns you to the list of sites, with the updated version information. You can now restart the site.
Note: Updating an site in the appliance follows the same principle as updating on a regular Linux server. In the event of problems, error messages or conflicts, you can obtain detailed information on the update process in the Updates and Upgrades article.
5.3. Migrating a site
It is often the case that a site already running on another Linux system is to be migrated to a Checkmk appliance. The Checkmk appliance includes a function with which you can carry out this migration.
The following requirements must be met:
You need a network connection between the source system and your appliance as the target system.
The Checkmk version of the source site must be installed on your appliance (an architecture change from 32-bit to 64-bit is possible).
The source site must be stopped during the migration process.
In the web interface, under Site Management, you will find the Migrate Site button, which will take you to this page:
On this page, you must first enter the host address (host name, DNS name or IP address) for the source system under Source Host. You also enter the ID of the site to be migrated under Source site ID.
The migration of the site is done via SSH.
To do this, you need the access data for a user who can log on to the source system and is authorized to access all of the site’s files.
For this you can use the source system’s
root user — or the site user, if a password has been defined for that site user.
Optionally, you can now still choose whether you want to use a new site ID for the target site on your device or leave the original ID unchanged.
Furthermore, you can specify that you do not want to transfer the performance data (metrics and graphs) and the historical data from the monitoring events during the migration. This can be useful if you do not need a 1:1 image of the site, but only want to duplicate it, e.g. for testing purposes.
After you have filled in the parameters and confirmed with Start, the progress of the migration will be displayed:
Once the migration has finished, you can exit the migration administration via the Complete button. You will end up back in the site management and will be able to start and manage this newly migrated site:
6. Managing firmware
You can update your appliance’s software, i.e. the appliance’s firmware, to a newer version during normal operation.
You can download the appliance firmware as a CFW file from the download page.
Note: Make sure that you select the firmware that matches the edition installed on your appliance. An update of the Cloud Edition in the license state "Trial" or "Free" to a full version of one of the commercial editions is of course also possible.
After you have downloaded the CFW file, select Firmware Update in the main menu, and on the following page with the file selection dialog select the CFW file from your hard disk:
Confirm with a click on Upload & Install. Now the firmware will be uploaded to your unit, which may take a few minutes depending on your network connection.
Once the file has been recognized as valid firmware, the Confirm Firmware Update dialog will be displayed for you to confirm the firmware update. During this process, depending on any differences between the current version and the version to be installed, various messages will appear to inform you of how your data will be handled during the update:
Change in the first digit (major release) of the version number: You must manually back up your appliance’s data and import it again following the update. An update without data migration is not possible.
Update to a higher number in the second digit (minor release): The update can be carried out without data migration. A prior backup is nevertheless recommended.
Change of the third digit (patch) in the version number: The update can be carried out without data migration. A prior backup is nevertheless recommended.
You can cancel the dialog at this point with No, and first make any necessary data backups.
Important: If you confirm the Confirm Firmware Update dialog with Yes!, the appliance will be restarted immediately!
The selected firmware will be installed during this restart. The restart will take considerably longer than usual, but usually less than 10 minutes. Afterwards, another restart will be automatically carried out, which completes the firmware update. The status view in the console will display the newly installed firmware version.
Note on the Update from 1.4 to 1.5: If you update the firmware from 1.4 to 1.5, you must also optionally update all installed Checkmk versions or reinstall them in the same version (but for a newer platform). The reason for this is that 1.5 is based on a new Debian version. Under Site Management you can check whether there are any incompatible firmware versions. Incompatible versions can no longer be started.
7. Resetting / restarting an appliance
7.1. Restarting / shutting down
You can restart or shut down the appliance via the web interface or via the console.
In the web interface, you will find the menu items Reboot Device and Shutdown Device under the Control Device item in the main menu. The appliance will perform the action immediately when the command is selected.
In the console, you can access the menu for controlling the unit by pressing
Warning: If you shut down the physical appliance, you will need either physical access to disconnect and reconnect its power, or an enabled management interface to be able to reboot it.
7.2. Restoring to the factory settings
You can reset your appliance to its factory settings. This means that all changes you have made to the appliance, such as your appliance settings, monitoring configuration or the collected statistics and logs, will be deleted. When you revert to the factory settings, the currently installed firmware version will be retained. The firmware that was installed on the unit as delivered will not be restored.
You can perform this action on the console.
To do this, press the
F2 key in the status view, select Factory Reset in the following dialog and confirm the following dialog with yes.
Your data will now be deleted from the appliance and a restart will be carried out immediately afterwards.
The appliance will thus restart with a fresh, ex-factory configuration.
Important: The settings for the management interface on the physical appliance are persistent, i.e. they are retained even when the factory configuration is restored. This ensures that you will not require physical access to the rack at a later date.
8. Integration of network file systems
If you want to make a data backup to a network share, you must first configure the desired network file system.
Currently supported are the network file systems NFS in version 3 and Windows network shares (Samba or CIFS) as well as SSHFS (SFTP).
From the web interface’s main menu select Manage mounts and from there create a new file system via New mount. Enter an ID here that will later be used to identify the file system.
Then select whether and how the file system is to be mounted. It is recommended to mount the file system automatically when it is accessed or to unmount it automatically when it is inactive.
Next, configure which type of share you want to include. Depending on the type, the appropriate settings are required, for example network addresses, login data or exported paths for NFS.
Once this has been saved, you will see the file system you have just configured and its current status in the file system management. With a click on the plug icon you can now manually mount the file system to test whether the configuration is correct.
If there are any problems, you can find any error messages in the system log.
9. Remote access via SSH
9.1. Access options
You can activate several types of access via the SSH remote maintenance protocol. Basically, the following are supported:
access to the console and
direct login to the sites
Access to the root system user is possible, but is not recommended or supported, as it is very easy to damage the configuration or the software.
9.2. Activating site logins via SSH
You can enable access to the command line for the individual monitoring sites. This allows you to view and control the entire environment at the site.
This access is controlled via the site management. In the settings dialog for each individual site, you can activate and deactivate access and also specify a password to protect the access.
9.3. Activating the console via SSH
It is possible to activate access to the text-based configuration environment on the device (console) via the network. This allows you to view and customize the basic configuration of the unit even without direct access to the unit.
You can enable access via the configuration menu in the console. To do this, select the Console via SSH menu item.
When you activate the option, you will be prompted to enter a password.
You must enter this password when you connect via SSH with the
setup user name.
Access will be automatically enabled immediately after confirming this dialog.
You can now connect to the unit as
setup user with the help of an SSH client (e.g. PuTTY).
You can see whether access is currently enabled in the console’s status view in the Access box.
9.4. Enabling root access via SSH
It is possible to enable access to the unit as the system user
However, after initializing the device, this access is disabled.
Once activated, you can log in to the appliance as
root user via SSH.
root, however, you do not land in the appliance menu, but instead simply on the command line.
Warning: Commands that you execute as
root on the device can permanently change or damage not only your data but also the factory-supplied system.
We will not be held liable for any changes made by you in this way.
Only activate and use the
root user if you are absolutely certain about what you are doing and only for diagnostic purposes.
Up to firmware version 1.4, when root access is activated you will see the addition tainted with the version information in the console — simply as a small warning.
You can enable access via the console’s configuration menu. To do this, select the menu item Root Access via SSH.
Then set the option to enable.
As soon as you activate the option, you will be asked to enter a password.
You must enter this password when you connect as
root user via SSH.
Access will be automatically enabled immediately after confirming this dialog.
You can now connect to the unit as the
root user with the help of an SSH client.
You can see whether access is currently enabled in the console’s status view in the Access box.
10. Securing the appliance GUI via TLS
10.1. Setting up access via TLS
In the factory default setting, access to your appliance’s web interface is via HTTP in plain text. You can secure this access by using HTTPS (TLS) so that the data between your browser and the unit is transmitted in encrypted form.
You can access the configuration via the Web Access button in the Device Settings.
10.2. Installing a certificate
In order to be able to encrypt the data traffic, the device first needs a certificate and a private key. You now have several options for installing the certificate:
Create a new certificate and have it signed by a certification authority with a certificate registration request.
Upload an existing private key and certificate.
Depending on your requirements and capabilities, you can select one of the above options. Certificates signed by certification authorities generally have the advantage that clients can automatically verify that the remote peer (device) is authentic when accessing it. This is usually ensured for official certification authorities.
If a user accesses the web interface via HTTPS and the certificate is signed by a certification authority they do not trust, this will initially trigger a warning in the web browser.
Generating a new certificate and having it signed
To create a new certificate, select the New Certificate option. In the dialog that follows, you now enter information about the device and its operator. This information is then stored in the certificate and can be used both by the certification authority and later by clients to verify the certificate.
After confirming the dialog with Save, you will be returned to the start page in the Web Access section and can download the certificate registration request (CSR) file. You must provide this file to your certification authority. Following this, you will receive a signed certificate and, if applicable, a certificate chain (often consisting of intermediate and/or root certificates) from your certification authority. You will usually receive these in the form of PEM or CRT files.
You can now transfer the signed certificate to the appliance via the Upload Certificate dialog. If you have received a certificate chain, you can also upload it via the dialog.
After confirming the dialog with Upload, you can continue with the configuration of the access paths.
Uploading an existing certificate
If you have an existing certificate and private key that you want to use to secure HTTPS traffic, you can transfer these files to your device using the Upload Certificate dialog.
Once you have confirmed the dialog with Upload, you can continue with the configuration of the access paths.
10.3. Configuring access paths
When you have installed a certificate, you can then configure the access paths according to your requirements.
If you want to secure access to your device via HTTPS, we recommend the HTTPS enforced (incl. redirect from HTTP to HTTPS) option. The device will only respond via HTTPS, but redirect all incoming HTTP requests to HTTPS. Users who accidentally access the web interface directly or via bookmarks using HTTP will therefore be automatically redirected to HTTPS.
If it is very important to you that not a single request goes over the network in plain text, you can select the HTTPS only option. Users accessing via HTTP will receive an error message when this setting is activated.
You can also activate both protocols at the same time via HTTP and HTTPS. However, this option is only recommended in exceptional cases, for migration purposes or for testing.
If you ever want to deactivate HTTPS, you can do so with the HTTP only option.
10.4. Display the current configuration / certificates
You can view the currently active access paths and information about the current certificate at any time on the access path configuration page.
11. Fault diagnosis
Despite careful testing, it cannot be ruled out that unforeseen errors occur which are difficult to diagnose without looking at the operating system.
One possibility is to have the log entries generated on the system sent to a syslog server via syslog. However, the log entries from the individual monitoring sites are not processed via syslog, so these are not forwarded and can only be viewed at the device itself.
To simplify error diagnosis on the appliance, there is a view for displaying various log files on the appliance. You can access this via the menu item View Log Files in the main menu of the web interface.
Here you can select the logs from the device and view their current content.
Note: The system log is reinitialized every time the unit is started, so if you want to receive the log entries, you must send them to a syslog server.
At the local console there is also the possibility of viewing the system log. The most recent entries for the system log are displayed on the second terminal.
You can reach this terminal with the key combination
The third terminal displays all kernel messages.
Here you will find the respective messages in the event of hardware problems.
This terminal can be reached with the key combination
You can switch back to the status view with the key combination
11.2. Available working memory
The working memory available in the appliance is freely available to your monitoring sites minus the memory required by the Checkmk appliance’s system processes.
To be able to guarantee the stability of the system platform, a fixed amount of the working memory is reserved for the device’s operating system. Depending on your appliance configuration, the amount of reserved memory is as follows:
Single unit (without cluster configuration): 100 MB
Clustered: 300 MB
If you want to know exactly how much working memory is available to your monitoring sites and how much is currently allocated, you can have Checkmk monitor your appliance. A User_Memory service is created on the device, which shows you the current and historical utilization.
If more memory is required by the monitoring sites than is available, one of the processes for the monitoring sites will be automatically terminated.
This is implemented by standard mechanisms in the Linux kernel.
12. Service and support
In the event of problems during commissioning or operation, please consult this User Guide first.
Current support information on the appliance is also available at any time on the internet via our website. There you will find the latest version of the documentation as well as general up-to-date information that may go beyond the information in this manual.
The current versions of the firmware can be found on our website. To access the commercial editions you will require the access data from your current support contract.
In the event of a hardware failure, please contact us by e-mail to email@example.com or by telephone at +49 89 99 82 097 - 20.
In the event of a software error, whether in the firmware or the Checkmk monitoring software, contact us via the Checkmk support portal. Support is provided within the framework of the contracted support agreement.