Monitoring Windows

You install the Windows agent by installing the MSI package.

Before installation, you need to get the package and bring it to the host on which the agent will run (for example with scp or WinSCP).

The commercial editions have a software module, the Agent Bakery, for automatically packaging customized agents. A detailed description of this can be found in the general article on the agents. Installation of the baked MSI package is done in the same way as described above for the included package.

In Checkmk Ultimate you can additionally use the Agent Bakery to provide agent packages with a configuration for auto-registration, which facilitates the automatic creation of hosts. In this case, the agent registration is done automatically once the agent package has been installed, and manual registration, as described in the following chapter, will no longer be necessary.

If you use the Agent Bakery, you can also set up automatic updates of the agent. These updates are described in their own article.

During an installation the MSI package stores the program-specific files in C:\Program Files (x86)\checkmk\service\ and the host-specific files in C:\ProgramData\checkmk\agent\. You do not need to customize the program-specific files. The host-specific files are used to store plug-ins, log and configuration files and to configure the behavior of the agent.

Note: By default, the entire C:\ProgramData directory is hidden in Windows.

The agent reads three configuration files in succession:

If an option has been set in multiple files, then the last file read in determines the content of this option. For manual work with the agent, therefore, only the last configuration file check_mk.user.yaml is relevant, because it is read in last and thus has the last word. If the Agent Bakery is not used, this is in fact the only file in which customizations to the agent’s configuration may be made.

As you may have already recognized from the file extension of the configuration files, YAML is used as the file format.

After installing the agent including the Agent Controller, the next step is the registration, which sets up TLS encryption so that the encrypted agent output can be decrypted by the Checkmk server and displayed in monitoring.

There is a special feature when the agent has been installed with the Agent Controller for the first time. In such a case the agent will switch to the unencrypted legacy pull mode, so that the Checkmk server is not cut off from the monitoring data and can continue to display it. This applies to both a new installation and an update of a very old agent (older than version 2.1.0).

It will look like this in the monitoring:

The Checkmk site recognizes from the agent output that the Agent Controller is present and thus that TLS encryption is possible—​but not yet enabled. The Check_MK Agent service changes to the WARN state and remains so until you register it. After registration, only the encrypted pull mode will be used for communication. The legacy pull mode is switched off and will remain so. However, it can be switched on again by command if necessary.

The situation will be different when using a legacy agent on a very old Windows system. Without the Agent Controller a registration is not possible. Thus, for legacy agents the only relevant sections in the Registration chapter are adding the host to the Setup and then to the monitoring. In the chapter Testing and troubleshooting you must omit the test for calling the Agent Controller, because this is not available for a legacy agent. Since there is also no TLS encryption without the Agent Controller, you will need to use other methods of encryption if required. In this case we recommend using the built-in (symmetric) encryption using the Symmetric encryption (Linux, Windows) rule.

Note: In the Checkmk Agent installation auditing rule set you will find various settings to check the state of the agent and make it visible in monitoring. Among other things, here you can specify which state the Check_MK Agent service should have if TLS configuration has not yet been performed.

Immediately after installing the agent (including when updating a very old agent, i.e., one older than version 2.1.0), only unencrypted communication is possible in the legacy pull mode. An exclusively encrypted data transmission can only be activated once a trust relationship has been established.

An exception to this are the packages preconfigured for the auto-registration and downloaded via the Agent Bakery. These packages perform the registration automatically after installation.

In all other cases, you perform the manual registration promptly after installing the agent. This chapter shows how to perform the registration.

The registration and thus the establishment of the mutual trust relationship is done under a Checkmk user with access to the REST-API. For this, a good choice is the automation user agent_registration which only has the permission to register agents and is automatically created with every Checkmk installation. You can randomize the corresponding automation password (automation secret) with the icon. You must save the user before you can use the new password.

Note: Since there is no Agent Controller, and thus no registry and TLS encryption, on very old Windows systems you will need to use alternative encryption methods if required. In this case we recommend using the built-in (symmetric) encryption using the Symmetric encryption (Linux, Windows) rule.

First create the new host via Setup > Hosts > Add host. A host must exist in the configuration environment before it can be registered.

In Checkmk Ultimate you will find the Checkmk agent connection mode option in the properties of the host in the section on monitoring agents. Here you can activate the push mode for the Checkmk agent as an alternative to the pull mode, which is available in all editions.

The registration is done using the Agent Controller cmk-agent-ctl, which provides a command interface for configuring the connections. You can display command help with cmk-agent-ctl help, also for specific available subcommands, for example with cmk-agent-ctl help register.

Whether the host is configured for the pull mode or the push mode makes no difference for the command examples. The Agent Receiver tells the Agent Controller in which mode it should operate during registration.

Now go to the host that is to be registered. Here you have to make a request to the Checkmk site with administrator rights:

The host name following the --hostname option must be exactly the same as it was when it was created in the Setup. The --server and --site options specify the name of the Checkmk server and the site. The server name may also be the IP address, the site name (here mysite) corresponds to the one you see in the URL path for the web interface. The options are completed by the name and password used by the automation user. If you omit the --password option, the password will be requested interactively.

Caution, trap for the unwary: If you primarily administer Unix machines, you are used to enclosing paths or parameters with spaces or special characters in single quotes (apostrophes, 0x27). Windows interprets this character as part of the call—​in this case the password—​and the registration will fail. Use double quotes (quotation marks, 0x22) instead.

If the specified values were correct, you will be asked to confirm the identity of the Checkmk site to which you want to connect. For clarity here, we have abbreviated the server certificate to be confirmed:

Confirm with Y to complete the process.

If no error message is displayed, the encrypted connection will have been established. All data will now be transmitted in compressed form via this connection.

If you want to disable the interactive check of the certificate—​for example to fully automate the registration—​you might use the additional parameter --trust-cert. The transferred certificate will be automatically trusted in this case. Keep in mind that you should take other measures to verify the integrity of the certificate. This can be performed (manually or scripted) by inspecting the file C:\ProgramData\checkmk\agent\registered_connections.json.

Checkmk Ultimate offers the facility to create hosts automatically at registration. For such auto-registration, in addition to a user with permission to register hosts, you need at least one folder configured to hold the hosts that are to be created automatically.

If these conditions have been met, you can also carry out the registration, including automatic host creation, via the command line.

Usually you will use the Agent Bakery settings procedure, which includes the C:\ProgramData\checkmk\agent\pre_configured_connections.json configuration file in the agent package and which performs the registration automatically during installation. The command line call presented here is therefore primarily used for testing and debugging, for example trying out your own agent labels with the --agent-labels <KEY=VALUE> option.

The biggest difference here is the modified register-new subcommand, which is used to request the registration and creation of a new host in the Checkmk site. The name of the host is the one stored in the %COMPUTERNAME% environment variable. The subsequent confirmation of the certificate is the same as shown in the last section.

Whether the host is created in pull mode, in push mode or not at all is defined by your settings in the Agent registration rule set. Following a successful registration, it may take several minutes before the host appears in the monitoring.

The cmk-agent-ctl status command now shows exactly one trust relationship with the Checkmk server:

If the information is needed in a machine-readable format, append the additional parameter --json to retrieve the output formatted as a JSON object.

Note: There can only ever be one trust relationship between host and site. For example, if you register an already registered host mynewhost under a different name (mynewhost2) but with the same IP address, then the new connection will replace the existing one. The connection from mynewhost to the site will be disconnected and no more agent data will be supplied to the host for monitoring.

For easier registration of multiple hosts, any host on which the agent is installed can perform a registration on behalf of other hosts. The registration process exports a JSON file, which can then be transferred to the target host and imported there. Again, as before, the host registered in the job must already be set up on the site.

First, on any host in the Setup, the registration is performed by proxy. Here, of course, the Checkmk server comes in handy, as it is usually the first host to be set up. As with the example above, you can pass the password by option or be asked for it interactively if you omit the --password option. We redirect the JSON output to a file in the example:

Next we transfer the /tmp/mynewhost3.json file to the host we registered for and import that file:

Once the registration is complete, perform a connection test and a service discovery in the Checkmk server Setup. Then, as the last step include the discovered services in the monitoring by activating the changes.

If the connection test fails, refer to the following chapter for testing and troubleshooting information.

You can also deregister a host.

On a host connected to the Checkmk server, you can revoke the trust. Here, in the following command, the Universally Unique Identifier (UUID) to specify is the one output by the cmk-agent-ctl status command:

To delete all connections from the host and additionally restore the legacy pull mode, enter the following command:

After that, the agent will behave as it did following the initial installation and before the first registration, and sends its data unencrypted.

Complete the deregistration on the Checkmk server: In the Setup, on the Properties of host page, select the Host > Remove TLS registration menu item and confirm the prompt.

If you prefer using the command line: On the Checkmk server, for each connection of a host that is in monitoring, there is a soft link with the UUID that points to the folder with the agent output:

In Checkmk Ultimate you can switch hosts from push to pull mode and vice versa. This may be necessary in individual cases if changes to the network topology are pending, or a downgrade to Checkmk Pro--in which only the pull mode is possible—​is to be carried out.

First specify the access mode in the Setup, in the properties of the host, with the Checkmk agent connection mode option. Within the next minute, all services will assume the UNKNOWN status since no monitoring data is being received. Then perform a new registration. During this re-registration, the Checkmk server’s Agent Receiver tells the Agent Controller whether it expects data in pull or push mode. A subsequent check using cmk-agent-ctl status will then show a new UUID and a mode consistent with the change made in the Setup.

To check that the configuration has been read in as expected, call the agent program with the showconfig option. With this option you will not only get the configuration as it is currently used by the agent, but additionally, the environment variables as well as the configuration files in use will always be displayed.

If only a certain part of the configuration is of interest, you can limit the output to that specific part. Here, for example, it is checked whether the options in the ps section have been set correctly:

In this way you get a quick overview of how the three different configuration files have been merged and used by the agent program. Errors will be immediately visible.

If registering a host fails even before a certificate is presented, knowledge about the connections used for communication can help in identifying the problem—​and of course in solving it.

To find out why the registration failed, run the registration again with the additional option -vv. This will display not only errors but also additional information and debugging messages. For example, if the Checkmk server is not accessible from the host, the output will look something like this: