Configuration via HTTP-API

To use the Web-API from a client, an automation user must be set up on the Checkmk server. Only this user is permitted to execute commands over the Web-API.

For the authentication you need the user name and the corresponding so-called "automation secret for machine accounts", i.e. the password of the automation user. Both information must be transmitted to the Checkmk server in every command.

On a newly-created site the automation user already exists. It can be found, like other users, in Setup > Users > Users. Make sure that the roles and the associated permissions for the automation user are set to allow the execution of your commands

In this article the default automation user will always be used as an example.

The following examples always draw on the curl command line program to clarify the general syntax of the invocations. If you are using another technology adapt the invocations as appropriate.

For the actual URL http://myserver/mysite/check_mk/webapi.py various parameters are required. These parameters contain the access data for the automated users, and the information regarding the tasks to be performed. If the invocation is to draw on a particular element in Checkmk, this data will be transferred as a payload:

With curl the first five parameters can be transferred directly in the URL. They begin with a ? and are linked with a &, and they can be coded in any order:

On the one hand, the answer will contain a result_code – this will show if an error has occurred during the query. If the query was successful a 0 will be returned, if there has been an error a 1 will be returned. On the other hand there is the (result) itself, in which the site’s response is found. This response can be an error message if the query has failed, or it can contain the desired data if the query has been successful. If a command has been directed to the Checkmk server the result field can under some circumstances be empty, or respectively, a 'None' value can be returned.

Some commands require the request parameter. This contains the required data – for example, to query a specific host’s configuration. The switch -d is used to transfer this data:

Important: In the following examples and in the Command reference the input and answer are often spread over several lines to improve readability and the overview in general. In practice both the input and the answer will be coded without line breaks.

The API recognises two parameters for defining the input or answer data format. The input format is defined by request_format, and the answer is defined by output_format. If these parameters are not used API defaults to JSON format.

These days however the support of JSON in Checkmk has become generally experimental/obsolete. Even though many commands use JSON without errors, Python should always be used for inputs and answers. Below is a practical example in which, for example, tuples are used in the answer:

JSON and Python have a few other differences in their data formats. These are:

So that Web-API commands can be tested directly from the Checkmk server, it makes sense to work as an instance user. You can then access local variables and also directly read the automated user’s password. In the following example the variables $OMD_SITE and $OMD_ROOT which refer to the site’s name and home directory are used. The password will be directly output with cat:

As long as the automation user is present this invocation will work on every site. You could could simply copy the above example and test it on your own site, for example. This of course can only work if the command is executed as an instance user on the Checkmk server.

Checkmk uses a number of commands for managing the configurations of hosts, rules and much more. Have a look in the Command reference for a description of all of the commands.

To illustrate working with the API using a simple example, we will create a host with its services via the Web-API using only three commands. In principle you can proceed in exactly the same way as with Checkmk’s Setup:

A host can be created in Checkmk with the add_host command. For this the minimum requirement is a host name and the directory where it is to be stored. Additionally, available attributes such as, for example, a host’s IP-address, can also be explicitly defined. The request-component will look like this, for example:

In the above example the host myserver123 will be stored in the main directory. In the process it will receive an IP-address, and additionally be defined as a host that receives its data from a Checkmk agent, and it will be assigned to the instance mysite. To test on the command line, the host can be created as follows (substitute your own real values for the placeholders):

Once the host has been created, services can be added to it. Here enter the host name, and specify the type of Service Discovery as required. If nothing is entered only the newly-discovered services will be added:

Finally, the changes can be activated as in Checkmk’s Setup:

As explained above, a query returns an error code if it was unsuccessful. This is contained in the result_code. A description of the error is included in the result itself. This is a good place to start an analysis of the problem.

Also check whether the following requirements have been met:

As already mentioned an automated user’s permissions can be a source of errors if, for example, configuration data is to be retrieved. The automation user supplied with Checkmk has the Administrator role and it can thus see and process everything. Because every available role can be assigned to an automated user, the contact groups must be adapted as appropriate to be able to query or process specific hosts. In the case of an error, check that these permissions are correct for the relevant automated user.

When testing with curl it will quickly become confusing in the request-component. Therefore always check whether the syntax is correct (even if you are not using curl).

Coding the request-component in a file can be quite a good method to aid with visualisation:

These lines can also be copied into a Python-Prompt, and then they can be output in one line with the print command:

By the way, the blank characters can remain in the curl command: