Web-API: Command reference


This article is just a draft and not yet finished!

This article contains a description of every command available in the Web-API. A general knowledge of the API's syntax and other requirements as described in the main article will be assumed.

1. Activating changes

All changes made to the Check_MK-Server can be activated with the activate_changes command. In the request-part enter a list of the sites and whether the command should also activate the changes for other users (0 for ‘no’ and 1 for ‘yes’).

{"sites": [ "master", "slave_1", "slave_2" ],
 "allow_foreign_changes": "0"}

Such a command can look like this, for example:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?_secret=myautomationsecret&_username=automation&action=activate_changes" -d 'request={"sites":["mysite"],"allow_foreign_changes":"0"}'
{"result": {"sites": {"mysite": {"_time_updated": 1507118620.897177, "_status_details": "Started at: 14:03:33. Finished at: 14:03:40.", "_phase": "done", "_status_text": "Success", "_pid": 10633, "_state": "success", "_time_ended": 1507118620.897177, "_expected_duration": 10.0, "_time_started": 1507118613.630956, "_site_id": "mysite", "_warnings": []}}}, "result_code": 0}

2. Host commands

For hosts, the following commands can be executed in the API:

  • get_host
  • add_host
  • edit_host
  • delete_host
  • delete_hosts
  • get_all_hosts
  • discover_services

2.1. get_host

This command can be used to call up an individual host's configuration. For this only the name of the host to be called up is needed. In the example below the output is in a format conveniently readable for humans. In practice the output will always be in a single line:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_host&_username=automation&_secret=myautomationsecret&output_format=python&request_format=python" -d 'request={"hostname":"myserver123"}'
{'result': {'attributes': {'alias': u'someAlias', 'tag_agent': 'cmk-agent', 'tag_criticality': 'prod', 'management_address': '192.168.1.42', 'contactgroups': {'use_for_services': False, 'recurse_perms': False, 'recurse_use': False, 'use': True, 'groups': ['ad_admins']}, 'management_protocol': 'snmp', 'ipaddress': '192.168.0.42', 'site': 'prod', 'tag_address_family': 'ip-v4-only', 'management_snmp_community': 'public'}, 'hostname': 'myserver123', 'path': ''}, 'result_code': 0}

As in the example the response will be in Python format if further processing should likewise be performed in Python. The input format is in JSON, identical to Python and for this reason does not need reformatting.

Structured readably, the output can look like this:

{'result':
    {'attributes': {
        'alias': u'My Server Alias',
                    'contactgroups': {'groups': ['ad_admins'],
                                      'recurse_perms': False,
                                      'recurse_use': False,
                                      'use': True,
                                      'use_for_services': False},
                    'ipaddress': '192.168.0.42',
                    'management_address': '192.168.1.42',
                    'management_protocol': 'snmp',
                    'management_snmp_community': 'public',
                    'site': 'prod',
                    'tag_address_family': 'ip-v4-only',
                    'tag_agent': 'cmk-agent',
                    'tag_criticality': 'prod'},
     'hostname': 'myserver123',
     'path': ''}
 'result_code': 0}

Note that in the response only the fields explicitly defined for the host in WATO will be output. Values which include the defaults, or values inherited from a directory will not be output here. A response containing only the essential fields will therefore look like this:

{'result':
    {'attributes': {},
     'hostname': 'myserver123',
     'path': ''},
 'result_code': 0}

This behaviour can be altered by passing the effective_attributes parameter and setting it to ‘1’. The output will then include all attributes – these are not listed again in the example:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_host&_username=automation&_secret=myautomationsecret&effective_attributes=1" -d 'request={"hostname":"myserver123"}'

2.2. add_host

To add a host, the command must specify at least the host name and the directory. Should the host be located in the home directory simply set two empty quotes (‘’). Optionally the attributes – if available – can be set, nodes specified if a cluster host is to be created, or the automatic creation of directories can be suppressed. For the attributes you can use the output from the get_host as a reference, so that the configuration can look like below, for example:

{'hostname': 'myserver123',
 'folder': 'munich/network',
 'attributes': {'ipaddress': '192.168.0.42',
                'site': 'prod',
                'tag_agent': 'cmk-agent'},
 'create_folders': '0'}

The command will then be processed as usual. In the example, with the create_folders option, the creation of new directories will be suppressed. If nothing is specified it will be assumed that the creation of currently non-existant directories is allowed. The attributes will be listed in braces ({}) (as Dictionary). Host tag s can also be set here. To access these take the tag-group's ID and specify a tag_ as a prefix.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_host&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123","folder":"munich/network","attributes":{"ipaddress":"192.168.0.42","site":"prod","tag_agent":"cmk-agent"},"create_folders":"0"}'
{"result": null, "result_code": 0}

2.3. edit_host

With this command a host's attributes can be customised, or reset to its standard values with unset_attributes.

{'hostname': 'myserver123',
 'unset_attributes': [ 'site', 'alias' ],
 'attributes': {'parents': [ 'myRouter1', 'myRouter2' ],
                'tag_agent': 'cmk-agent'}
}

Only the host name is obligatory here. Note that the attribute to be reset should be specified in a list.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_host&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123","unset_attributes":["site","alias"],"attributes":{"parents":["myRouter1","myRouter2"],"tag_agent":"cmk-agent"}'
{"result": null, "result_code": 0}

2.4. delete_host

To delete a host only the host's name is required in the request-part since it must always be explicit in Check_MK:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=delete_host&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123"}'
{"result": null, "result_code": 0}

2.5. delete_hosts

From Version 1.5.0 you can use this command to delete more than one host at a time. You should take care of the correct spelling of the command. The hosts will be delivered as a list:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=delete_hosts&_username=automation&_secret=myautomationsecret" -d 'request={"hostnames":["myserver123","myserver234"]}'
{"result": null, "result_code": 0}

2.6. get_all_hosts

This command is the only one for the hosts which requires no additional data to be entered. It simply outputs the info for all of the hosts in Check_MK. Likewise as with get_host, in this command it can also be specified whether only the explicitly-coded or all attributes should be output. Note that under some circumstances a very comprehensive response can be produced. For this reason the response's output will be omitted from the example here.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_all_hosts&_username=automation&_secret=myautomationsecret"

2.7. discover_services

With this command all of a host's services can be discovered and added. The syntax of the request command is the samer as for get_host since a summary of the results will be output with the response:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=discover_services&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123"}'
{'result': 'Service discovery successful. Added 7, Removed 0, Kept 52, New Count 59', 'result_code': 0}

Additionally – as in WATO – using mode it can be specified how to handle the newly-discovered and the already configured services. The possible options are:

  • new: Only add new services. This is the default setting when no options are entered.
  • remove: Removes only services that are no longer available.
  • fixall: Removes services that are no longer available, and adds new ones.
  • refresh: Removes all services, and then adds all services as new.

The parameter will then be additionally passed with the host names:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=discover_services&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123","mode":"refresh"}'
{"result": "Service discovery successful. Added 6, Removed 5, Kept 48, New Count 54", "result_code": 0}

3. Directory commands

From Version 1.5.0 Check_MK provides the following commands for managing the directories in WATO:

  • get_folder
  • add_folder
  • edit_folder
  • delete_folder
  • get_all_folders

3.1. get_folder

Querying the configuration of a directory is not much different from that for a host. Enter the name of the directory, and all attributes where applicable will be output. In the example the output_format will be converted to Python, and all of the directory's attributes will be output. Note that in the response all tuples will be converted to lists if the output is formatted in JSON.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_folder&_username=automation&_secret=myautomationsecret&output_format=python&effective_attributes=1" -d 'request={"folder":"munich/network"}'
{'result': {'attributes': {'network_scan': {'scan_interval': 86400, 'exclude_ranges': [], 'run_as': u'automation', 'ip_ranges': [], 'time_allowed': ((0, 0), (24, 0))}, 'tag_agent': 'cmk-agent', 'snmp_community': None, 'ipv6address': '', 'alias': '', 'management_protocol': None, 'site': 'heute', 'tag_room': 'weisses_haus', 'tag_criticality': 'prod', 'contactgroups': (True, []), 'network_scan_result': {'start': None, 'state': None, 'end': None, 'output': ''}, 'parents': ['heute'], 'tag_address_family': 'ip-v4-only', 'management_address': '', 'tag_networking': 'lan', 'ipaddress': '', 'management_snmp_community': None}, 'configuration_hash': '7001db7f20eee1cae51f9c696cddff42'}, 'result_code': 0}

As can be seen in the example, a directory must always be specified relative to the home directory since the path is always unique, but not the name.

The (readable) response will then appear like this (since some of the information delivered is not relevant here, the example shown has been abreviated for clarity):

{'result': {'attributes': {'alias': '',
                           'contactgroups': (True, []),
                           'network_scan': {'exclude_ranges': [],
                                            'ip_ranges': [],
                                            'run_as': u'automation',
                                            'scan_interval': 86400,
                                            'time_allowed': ((0, 0),
                                                             (24, 0))},
                           'network_scan_result': {'end': None,
                                                   'output': '',
                                                   'start': None,
                                                   'state': None},
                           'parents': [],
                           'site': 'prod',
                           'snmp_community': None,
                           'tag_address_family': 'ip-v4-only',
                           'tag_agent': 'cmk-agent',
                           'tag_criticality': 'prod',
                           'tag_networking': 'lan'},
            'configuration_hash': '7001db7f20eee1cae51f9c696cddff42'}
 'result_code': 0}

The ‘alias’ attribute will always be empty in the output – since directories are only created once and never internally renamed, via this attribute the display name in WATO can subsequently be customised. Note then that the name in WATO must not necessarily match the real name!

The configuration_hash can be used if the directory must be modified.

3.2. add_folder

The insertion of directories also works in a similar way to that for hosts. As a minimum the name and the attribute will be required. The latter can also be blank as in the example below:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_folder&_username=automation&_secret=myautomationsecret" -d 'request={"folder":"munich/network/router","attributes":{}}'
{"result": null, "result_code": 0}

As can be seen the path here is likewise always specified relative to the home directory. If a parent directory is not present one will be created. This action can be suppressed if – in a similar way to add_host – the create_parent_folders option is added and set to ‘0’.

3.3. edit_folder

To be able to edit a directory, as a minimum its name will be required. Additionally, the attributes described in get_folder can be customised. With the optional configuration_hash it can be ensured that the directory's configuration will in the interim not be altered. If the hash is not identical Check_MK will not alter the directory. In the example the result from get_folder can be used in order to customise the configuration. Make sure to use Python as the request_format, since tuples can be present in the settings for the network scan:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_folder&_username=automation&_secret=myautomationsecret&request_format=python" -d 'request={"folder":"munich/network","attributes":{"network_scan":{"time_allowed":"((18,0),(24,0))"}},"configuration_hash":"7001db7f20eee1cae51f9c696cddff42"}'
{"result": null, "result_code": 0}

3.4. delete_folder

Deleting a directory is very easy. Simply enter its name. As always for directories that will be its relative path:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=delete_folder&_username=automation&_secret=myautomationsecret -d 'request={"folder":"munich/network"}'
{"result": null, "result_code": 0}

3.5. get_all_folders

Equally easy is the output of all directories. This is done in a similar way to get_all_hosts. Note that the output format should be Python as with get_folder:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_all_folders&_username=automation&_secret=myautomationsecret&output_format=python"
{'result': {'': {}, 'munich/windows': {}, 'munich/network': {'network_scan': {'run_as': 'automation', 'exclude_ranges': [], 'ip_ranges': [('ip_network', ('192.168.20.0', 24))], 'scan_interval': 86400, 'time_allowed': ((20, 0), (24, 0))}, 'tag_agent': 'snmp-only'}, 'munich': {}, 'berlin': {'tag_networking': 'dmz'}, 'berlin/databases': {'tag_criticality': 'critical'}, 'essen': {'tag_networking': 'wan'}, 'essen/linux': {}}, 'result_code': 0}

The output looks (in a readable form) like below. If differs from the query of an individual directory only in detail. The top line with the empty name field is the main directory.

{'result': {'': {},
            'berlin': {'tag_networking': 'dmz'},
            'berlin/databases': {'tag_criticality': 'critical'},
            'essen': {'tag_networking': 'wan'},
            'essen/linux': {},
            'munich': {},
            'munich/network': {'network_scan': {'exclude_ranges': [],
                                                'ip_ranges': [('ip_network',
                                                               ('192.168.20.0',
                                                                24))],
                                                'run_as': 'automation',
                                                'scan_interval': 86400,
                                                'time_allowed': ((20, 0),
                                                                 (24, 0))},
                               'tag_agent': 'snmp-only'},
            'munich/windows': {}},
 'result_code': 0}

4. Group commands

With the Web-API contact, host and service groups in Check_MK can be created, edited, deleted and of course also queried. The following commands are available for these tasks:

  • add_contactgroup
  • edit_contactgroup
  • delete_contactgroup
  • get_all_contactgroups
  • add_servicegroup
  • edit_servicegroup
  • delete_servicegroup
  • get_all_servicegroups
  • add_hostgroup
  • edit_hostgroup
  • delete_hostgroup
  • get_all_hostgroups

The command syntax is the same for the different types of groups. Only the command will be matched as appropriate to each group. For this reason each command type will only be explained once. The examples can then be carried-over for both of the other types of group. To make this clearer, different groups will be used in each of the examples.

Important: All commands must always include the group type. If the subject is add_group and a host group is to be added, the required command is add_hostgroup.

4.1. get_all_groups

This command – like other similar commands – will be invoked without extra parameters. The response will contain all groups with their names and aliases:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_all_contactgroups&_username=automation&_secret=myautomationsecret"
{"result": {"oracle": {"alias": "ORACLE Administrators"}, "windows": {"alias": "Windows Administrators"}, "all": {"alias": "Everything"}, "linux": {"alias": "Linux Administrators"}}, "result_code": 0}

In an easy to read format the response will look like this. As can be seen the syntax is very simple:

{'result': {'all': {'alias': 'Everything'},
            'linux': {'alias': 'Linux Administrators'},
            'oracle': {'alias': 'ORACLE Administrators'},
            'windows': {'alias': 'Windows Administrators'}},
 'result_code': 0}

4.2. add_group

In order to add a group the syntax get_all_groups can be used. Only the group's ID and its alias need to be given. Note that when adding a new group, its ID with its groupname key will be given:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_hostgroup&_username=automation&_secret=myautomationsecret" -d 'request={"groupname":"linux", "alias":"All Linux Servers"}'
{"result": null, "result_code": 0}

4.3. edit_group

Due to the low complexity of the invocation, editing a group functions in a similar way to its creation. The group name (groupname) must obviously already exist in order to be able to edit its alias. In the example the service group ‘cpu_util’ does not exist yet and the response contains an error. In a successful action with the curl-invocation the same response will be produced as with add_group:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_servicegroup&_username=automation&_secret=myautomationsecret" -d 'request={"groupname":"cpu_util", "alias":"CPU utilization of all servers"}'
{"result": "Check_MK exception: Unknown group: linux", "result_code": 1}

4.4. delete_group

Deleting a group is also very easy. Only the group's name needs to be entered.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=delete_hostgroup&_username=automation&_secret=myautomationsecret" -d 'request={"groupname":"linux"}'
{"result": null, "result_code": 0}

5. User commands

The following commands can be used for managing the users. Note however that users synchronised over LDAP or Active Directory can be queried but not edited.

  • add_users
  • edit_users
  • delete_users
  • get_all_users

5.1. add_users

To create a user, the minimum requirement is a user name (ID) and an alias. So that the user can subsequently log in, a password will also need to be defined. This password will be stored encrypted so that during a query the password will not be transmitted as plain text. Only the password for the automated user automation_secret will not be encrypted. All further attributes for a user are optional. To get an overview of a few possible attributes, you can view the response example from get_all_users.

The request-part will begin with users, so that multiple users can be created with a single action. Each entry begins with the new user's ID:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_users&_username=automation&_secret=myautomationsecret" -d 'request={"users":{"hhirsch":{"alias":"Harry Hirsch","password":"myStrongPassword","pager":"+49176555999222"},"customAutomation":{"alias":"Custom Automation User","automation_secret":"mySuperStrongSecret"}}}'
{"result": null, "result_code": 0}

5.2. edit_users

Editing a user functions in almost the same way as creating the user. The user's ID will be required, and the changes are specified with set_attributes. With unset_attributes the attributes can be reset to their default values. With these commands it is also possible to edit multiple users in a single action.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=edit_users&_username=automation&_secret=myautomationsecret" -d 'request={"users":{"hhirsch":{"set_attributes":{"email":"hhirsch@myCompany.org","contactgroups":["windows"]},"unset_attributes":["pager"]}}}'
{"result": null, "result_code": 0}

To recap, here is the request-part in a readable form:

{'users': {'hhirsch': {'set_attributes': {'contactgroups': ['windows'],
                                          'email': 'hhirsch@myCompany.org'},
                       'unset_attributes': ['pager']}}}

5.3. delete_users

To delete one or more users, simply enter the user's ID(s) in users.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=edit_users&_username=automation&_secret=myautomationsecret" -d 'request={"users":["customAutomation"]}'
{"result": null, "result_code": 0}

5.4. get_all_users

No additional parameters are needed in the request-part to retrieve the configurations of all users. The response will then contain all user-IDs and their associated attributes. Note that some attributes will only be output if they are explicitly specified.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_all_users&_username=automation&_secret=myautomationsecret

The output can be very comprehensive. For that reason only two examples of outputs listing a user's attributes, amongst other things, are presented here:

{'automation': {'alias': u'Check_MK Automation - used for calling web services',
                'automation_secret': 'myautomationsecret',
                'contactgroups': [],
                'disable_notifications': {},
                'email': u'',
                'enforce_pw_change': False,
                'fallback_contact': False,
                'force_authuser': False,
                'force_authuser_webservice': False,
                'last_pw_change': 1504517726,
                'locked': False,
                'notifications_enabled': False,
                'num_failed_logins': 0,
                'pager': '',
                'password': '$1$508982$cA48GmuUHxRZn3w2GJUnK0',
                'roles': ['admin'],
                'serial': 2,
                'start_url': 'dashboard.py'},
 'hhirsch': {'alias': u'Harry Hirsch',
             'connector': 'htpasswd',
             'contactgroups': ['windows'],
             'disable_notifications': {'disable': True},
             'email': u'hhirsch@myCompany.org',
             'enforce_pw_change': True,
             'fallback_contact': True,
             'force_authuser': False,
             'force_authuser_webservice': False,
             'idle_timeout': 600,
             'language': None,
             'last_pw_change': 1504713006,
             'locked': False,
             'num_failed_logins': 1,
             'pager': '+49176555999222',
             'password': '$1$238168$dGIr7ja6DVn3E8rMlp1aD.',
             'roles': ['admin', 'user'],
             'serial': 1,
             'start_url': 'dashboard.py'}}

6. Rule Set commands

From Version 1.5.0 Check_MK also provides the facility for defining and retrieving rule sets via the Web-API. An in-depth knowledge of the rule's syntax is a requirement for working with the following commands, meaning that they are really only recommended for advanced Check_MK users.

  • get_ruleset
  • set_ruleset
  • get_ruleset_info

6.1. get_ruleset

Rules must already have been defined in a rule set in order for a rule set to be retrievable. As input the rule set's ID is required, and Python must be defined as the output_format since many rule sets work with tuples.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_ruleset&_username=automation&_secret=myautomationsecret&output_format=python" -d 'request={"ruleset_name":"checkgroup_paramters:filesystem"}'
{'result': {'ruleset': {'': [{'conditions': {'host_specs': ['myserver123'], 'service_specs': [u'/media/customers$'], 'host_tags': []}, 'options': {}, 'value': {'levels': (90.0, 95.0)}}, {'conditions': {'host_specs': ['myserver123'], 'service_specs': [u'/media/meetings$'], 'host_tags': []}, 'options': {}, 'value': {'show_levels': 'onproblem', 'levels': (90.0, 95.0), 'trend_range': 24, 'trend_perfdata': True}}]}, 'configuration_hash': 'e069408225932bbfe2a485f22b9fc40e'}, 'result_code': 0}

As can be seen in the following readably-formatted response, only the elements used in the rule will be listed. In addition the rules will be assigned as a list to a directory:

{'result': {'ruleset': {'munich': [{'conditions': {'host_specs': ['myserver123'],
                                                   'host_tags': [],
                                                   'service_specs': [u'/media/customer$']},
                                    'options': {},
                                    'value': {'levels': (90.0, 95.0)}},
                                   {'conditions': {'host_specs': ['myserver123'],
                                                   'host_tags': [],
                                                   'service_specs': [u'/media/meeting$']},
                                    'options': {},
                                    'value': {'levels': (90.0, 95.0),
                                              'show_levels': 'onproblem',
                                              'trend_perfdata': True,
                                              'trend_range': 24}}]},
            'configuration_hash': 'e069408225932bbfe2a485f22b9fc40e'}
 'result_code': 0}

A query always requires the respective rule's internal name. The internal names (ID) for all rules can be listed with the get_rulesets_info command, for example. For each entry – among other info – the rule's title as can be found in WATO will also be listed. Use such functions if a rule set's ID is unknown.

6.2. set_ruleset

Rule sets can also only be set as complete packets with which one or more rules are defined for a specified directory. These rules will be summarised in a list. It is advisable to first call up the current content of a rule set, and to then use it as the basis for customising a new version. The configuration_hash parameter is also available here to be able to understand interim changes. In the following example we will use the response from above and delete only one of the two rules, by which we rewrite only one rule to this directory. Note that the request_format Is coded in Python – i.e. that the request element is enclosed in double-quotes (“ ”):

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=set_ruleset&_username=automation&_secret=myautomationsecret&request_format=python" -d "request={'ruleset_name':'checkgroup_parameters:filesystem','ruleset': {'': [{'conditions': {'host_specs': ['myserver123'], 'service_specs': [u'/media/customers$'], 'host_tags': []}, 'options': {}, 'value': {'levels': (90.0, 95.0)}}],'configuration_hash': 'e069408225932bbfe2a485f22b9fc40e'}}"
{'result': None, 'result_code': 0}

The more readable request part looks like the following:

request={
    'ruleset_name':'checkgroup_parameters:filesystem',
    'ruleset': {
        '': [{
            'conditions': {
                'host_specs': ['myserver123'],
                'service_specs': [u'/media/customers$'],
                'host_tags': []},
                'options': {},
                'value': {'levels': (90.0, 95.0)}
            }],
        'configuration_hash': 'e069408225932bbfe2a485f22b9fc40e'
    }
}

6.3. get_rulesets_info

If an overview of which rule sets are in Check_MK is desired, they can be called up with this command. As can be seen Python is also recommended as the output format here:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_rulesets_info&_username=automation&_secret=myautomationsecret&output_format=python"

Since all available rule sets can be called up with this command, its output will be omitted here. It is coded like the other commands. Here are examples of two typical rule sets in an easily-readable format:

{'result': {'cmc_service_rrd_config': {'help': 'This configures how many datapoints will be stored of the performance values of services. Please note, that these settings only apply for <i>new</i> services. Existing RRDs cannot be changed.',
                                       'number_of_rules': 1,
                                       'title': 'Configuration of RRD databases of services'},
            'static_checks:ipmi':     {'help': None,
                                       'number_of_rules': 0,
                                       'title': 'IPMI sensors'}},
 'result_code': 0}

This information is especially useful if the title is known but not the ID, and it will help when coding scripts for automation by being able to use the normal titles, thus increasing the readability for maintenance or alterations.

7. Host tag commands

From Version 1.5.0 host tags can be set as well as read with the following two commands:

  • get_hosttags
  • set_hosttags

7.1. get_hosttags

All tags can be called up with this command. The Host tag groups as well as the Auxiliary tags will be output.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_hosttags&_username=automation&_secret=myautomationsecret"
{"result": {"aux_tags": [{"id": "snmp", "title": "monitor via SNMP"}, {"id": "tcp", "title": "monitor via Check_MK Agent"}], "tag_groups": [{"tags": [{"aux_tags": [], "id": "prod", "title": "Productive system"}, {"aux_tags": [], "id": "critical", "title": "Business critical"}, {"aux_tags": [], "id": "test", "title": "Test system"}, {"aux_tags": [], "id": "offline", "title": "Do not monitor this host"}], "id": "criticality", "title": "Criticality"}, {"tags": [{"aux_tags": [], "id": "lan", "title": "Local network (low latency)"}, {"aux_tags": [], "id": "wan", "title": "WAN (high latency)"}, {"aux_tags": [], "id": "dmz", "title": "DMZ (low latency, secure access)"}], "id": "networking", "title": "Networking Segment"}], "configuration_hash": "4c2a236ffeabb0c52d4770ea03eff48e"}, "result_code": 0}

Formatted for readability the response is structured as below:

{'result': {'aux_tags': [{'id': 'snmp', 'title': 'monitor via SNMP'},
                         {'id': 'tcp', 'title': 'monitor via Check_MK Agent'}],
            'tag_groups': [{'id': 'agent',
                            'tags': [{'aux_tags': ['tcp'],
                                      'id': 'cmk-agent',
                                      'title': 'Check_MK Agent (Server)'},
                                     {'aux_tags': ['snmp'],
                                      'id': 'snmp-only',
                                      'title': 'SNMP (Networking device, Appliance)'},
                                     {'aux_tags': ['snmp'],
                                      'id': 'snmp-v1',
                                      'title': 'Legacy SNMP device (using V1)'},
                                     {'aux_tags': ['snmp', 'tcp'],
                                      'id': 'snmp-tcp',
                                      'title': 'Dual: Check_MK Agent + SNMP'},
                                     {'aux_tags': [],
                                      'id': 'ping',
                                      'title': 'No Agent'}],
                            'title': 'Agent type'},
                           {'id': 'criticality',
                            'tags': [{'aux_tags': [],
                                      'id': 'prod',
                                      'title': 'Productive system'},
                                     {'aux_tags': [],
                                      'id': 'critical',
                                      'title': 'Business critical'},
                                     {'aux_tags': [],
                                      'id': 'test',
                                      'title': 'Test system'},
                                     {'aux_tags': [],
                                      'id': 'offline',
                                      'title': 'Do not monitor this host'}],
                            'title': 'Criticality'},
                           {'id': 'networking',
                            'tags': [{'aux_tags': [],
                                      'id': 'lan',
                                      'title': 'Local network (low latency)'},
                                     {'aux_tags': [],
                                      'id': 'wan',
                                      'title': 'WAN (high latency)'},
                                     {'aux_tags': [],
                                      'id': 'dmz',
                                      'title': 'DMZ (low latency, secure access)'}],
                            'title': 'Networking Segment'}],
            'configuration_hash': '32deebf233cade1d42387c6a0639ceb1'},
 'result_code': 0}

7.2. set_hosttags

A configuration in the host tags will, for technical reasons, always be written as a completely new version, even if only a single entry has been added or altered. For this reason, here it is advisable to call up the configuration with the aid of get_hosttags and then insert the alterations. The altered configuration is then written back to Check_MK.

At this point the configuration_hash is useful. If when storing the configuration the hash on the Check_MK server does not match the one being provided, the data will be rejected and an error produced. In this way it can be ensured that the configuration has not been altered in the interim, and that a change is not inadvertently overwritten or deleted.

In the following example the configuration which we called up with the command above will be extended with the host tag ‘location’ and its selection options ‘munich’, ‘essen’ and ‘berlin’, so that the new version of the configuration will look like this:

{'aux_tags': [{'id': 'snmp', 'title': 'monitor via SNMP'},
              {'id': 'tcp', 'title': 'monitor via Check_MK Agent'}],
 'tag_groups': [{'id': 'agent',
                 'tags': [{'aux_tags': ['tcp'],
                           'id': 'cmk-agent',
                           'title': 'Check_MK Agent (Server)'},
                          {'aux_tags': ['snmp'],
                           'id': 'snmp-only',
                           'title': 'SNMP (Networking device, Appliance)'},
                          {'aux_tags': ['snmp'],
                           'id': 'snmp-v1',
                           'title': 'Legacy SNMP device (using V1)'},
                          {'aux_tags': ['snmp', 'tcp'],
                           'id': 'snmp-tcp',
                           'title': 'Dual: Check_MK Agent + SNMP'},
                          {'aux_tags': [],
                           'id': 'ping',
                           'title': 'No Agent'}],
                 'title': 'Agent type'},
                {'id': 'criticality',
                 'tags': [{'aux_tags': [],
                           'id': 'prod',
                           'title': 'Productive system'},
                          {'aux_tags': [],
                           'id': 'critical',
                           'title': 'Business critical'},
                          {'aux_tags': [],
                           'id': 'test',
                           'title': 'Test system'},
                          {'aux_tags': [],
                           'id': 'offline',
                           'title': 'Do not monitor this host'}],
                 'title': 'Criticality'},
                {'id': 'networking',
                 'tags': [{'aux_tags': [],
                           'id': 'lan',
                           'title': 'Local network (low latency)'},
                          {'aux_tags': [],
                           'id': 'wan',
                           'title': 'WAN (high latency)'},
                          {'aux_tags': [],
                           'id': 'dmz',
                           'title': 'DMZ (low latency, secure access)'}],
                 'title': 'Networking Segment'},
                {'id': 'location',
                 'tags': [{'aux_tags': [],
                           'id': 'munich',
                           'title': 'Munich'},
                          {'aux_tags': [],
                           'id': 'essen',
                           'title': 'Essen'},
                          {'aux_tags': [],
                           'id': 'berlin',
                           'title': 'Berlin'}],
                 'title': 'Location'}],
 'configuration_hash': '32deebf233cade1d42387c6a0639ceb1'},

This configuration can be included in the curl invocation and sent sent to the Check_MK server:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=set_hosttags&_username=automation&_secret=myautomationsecret" -d 'request={"aux_tags":[{"id":"snmp","title":"monitor via SNMP"},{"id":"tcp","title":"monitor via Check_MK Agent"}],"tag_groups":[{"title":"Agent type","id":"agent","tags":[{"aux_tags":["tcp"],"id":"cmk-agent","title":"Check_MK Agent (Server)"},{"aux_tags":["snmp"],"id":"snmp-only","title":"SNMP (Networking device, Appliance)"},{"aux_tags":["snmp"],"id":"snmp-v1","title":"Legacy SNMP device (usingV1)"},{"aux_tags":["snmp","tcp"],"id":"snmp-tcp","title":"Dual: Check_MK Agent + SNMP"},{"aux_tags":[],"id":"ping","title":"No Agent"}]},{"title":"Criticality","id":"criticality","tags":[{"aux_tags":[],"id":"prod","title":"Productive system"},{"aux_tags":[],"id":"critical","title":"Business critical"},{"aux_tags":[],"id":"test","title":"Test system"},{"aux_tags":[],"id":"offline","title":"Do not monitor this host"}]},{"title":"Networking Segment","id":"networking","tags":[{"aux_tags":[],"id":"lan","title":"Local network (low latency)"},{"aux_tags":[],"id":"wan","title":"WAN (high latency)"},{"aux_tags":[],"id":"dmz","title":"DMZ (low latency, secure access)"}]},{"tags":[{"aux_tags":[],"id":"munich","title":"Munich"},{"aux_tags":[],"id":"essen","title":"Essen"},{"aux_tags":[],"id":"berlin","title":"Berlin"}],"id":"location","title":"Location"}],"configuration_hash":"32deebf233cade1d42387c6a0639ceb1"}'
{"result": null, "result_code": 0}

8. Sites

From Version 1.5.0 the Distributed Monitoring can be used to establish or delete links to other sites. In this way completely new locations can be automatically integrated in Check_MK. The following commands are available:

  • get_site
  • set_site
  • delete_site
  • login_site
  • logout_site

8.1. get_site

Calling up a site works almost identically to other queries over the Web-API. Enter the ID of the site to be called up in the request-part. Note that this command requires Python for its >output_format:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_site&_username=automation&_secret=myautomationsecret&output_format=python" -d 'request={"site_id":"mySlave"}'
{'result': {'site_id': 'mySlave', 'site_config': {'url_prefix': 'http://mySlaveServer/mySlave/', 'user_sync': None, 'user_login': True, 'insecure': False, 'disabled': False, 'replication': 'slave', 'multisiteurl': 'http://mySlaveServer/mySlave/check_mk/', 'replicate_mkps': True, 'status_host': ('heute', 'mySlave'), 'socket': ('proxy', {'params': None, 'socket': ('mySlaveServer', 6557)}), 'disable_wato': True, 'alias': u'My Slave Check_MK', 'timeout': 10, 'persist': True, 'replicate_ec': True}, 'configuration_hash': '136bd84ff62dfa4e0a4325c6431e294b'}, 'result_code': 0}

In a readable form the response will look like this:

{'result': {'site_id': 'mySlave',
            'site_config': {'alias': u'My Slave Check_MK',
                            'disable_wato': True,
                            'disabled': False,
                            'insecure': False,
                            'multisiteurl': 'http://mySlaveServer/mySlave/check_mk/',
                            'persist': True,
                            'replicate_ec': True,
                            'replicate_mkps': True,
                            'replication': 'slave',
                            'socket': ('proxy',
                                       {'params': None,
                                        'socket': ('mySlaveServer', 6557)}),
                            'status_host': ('mysite', 'mySlave'),
                            'timeout': 10,
                            'url_prefix': 'http://mySlaveServer/mySlave/',
                            'user_login': True,
                            'user_sync': None},
            'configuration_hash': '136bd84ff62dfa4e0a4325c6431e294b',},
 'result_code': 0}

8.2. set_site

Connections to sites can only be altered in their entirety – thus if a customisation is to be performed over the Web-API any existing connections must be recreated as completely new versions. Here again, if performing a customisation it is advisable to first call up the current version with get_site, to make the alterations in the response, and then store this new version in Check_MK. Here also, as in get_folder, the configuration_hash can be used to ensure that in the interim no other alterations can be made to the configuration.

In the following example we take the configuration shown above, and alter only the Alias (alias) and the Persistent Connection (persist). The request format in this situation must be in Python and the request-part in double-quotes (“”):

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_site&_username=automation&_secret=myautomationsecret&output_format=python" -d "request={'site_id': 'mySlave', 'site_config': {'url_prefix': 'http://mySlaveServer/mySlave/', 'user_sync': None, 'user_login': True, 'insecure': False, 'disabled': False, 'replication': 'slave', 'multisiteurl': 'http://mySlaveServer/mySlave/check_mk/', 'replicate_mkps': True, 'status_host': ('heute', 'mySlave'), 'socket': ('proxy', {'params': None, 'socket': ('mySlaveServer', 6557)}), 'disable_wato': True, 'alias': u'My Slave', 'timeout': 10, 'persist': False, 'replicate_ec': True}, 'configuration_hash': '136bd84ff62dfa4e0a4325c6431e294b'}"
{"result": null, "result_code": 0}

8.3. delete_site

Only the site's ID is required to delete the connection to a site. In this case the configuration_hash function can also be used.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=delete_site&_username=automation&_secret=myautomationsecret" -d 'request={"site_id":"mySlave"}'{"result": null, "result_code": 0}

8.4. login_site & logout_site

To be able to directly use a site connection established via Web-API, a login to and a logout from the site can be done. For the login, in addition to the site's ID enter the user name and password.

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=login_site&_username=automation&_secret=myautomationsecret" -d 'request={"site_id":"mySlave","username":"cmkadmin","password":"cmk"}'
{"result": null, "result_code": 0}

Entering the site's ID is sufficient for logging out

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=logout_site&_username=automation&_secret=myautomationsecret" -d 'request={"site_id":"mySlave"}'{"result": null, "result_code": 0}

9. Agent Bakery commands

Automated agents can also be baked via the API. In this way the automatically-created configurations can be fed directly into the agents. Only the signing of the agents still needs to be performed manually, so that the freshly-baked agent's configuration can be verified one final time, and that you retain full control over which agents will actually be delivered to the hosts.

Calling up is very easy and it uses the bake_agents command:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=bake_agents&_username=automation&_secret=myautomationsecret"
{"result": "Successfully baked agents", "result_code": 0}

10. Commands for status data

10.1. Metrics

Check_MK in fact provides the facility for integrating external metrics data bases. In principle however, with the get_graph command Check_MK's metrics data can be accessed by any third-party software. In this way the user is not bound to our standard-issue graphs and can utilise their own self-created custom graphs. The data will then always be produced for a complete graph even when the graph includes multiple metrics.

If you wish to call up one of our standard graphs, the syntax for the request-part is as follows:

{'specification': ['template',
                   {'graph_index': 0,
                    'host_name': 'myserver123',
                    'service_description': 'Memory',
                    'site': 'mysite'}],
 'data_range': {'time_range': [1504623158, 1504626758]}}

Be sure to enter the time range in Unix Time. The >graph_index command specifies the graph to be retrieved. In the example we have retrieved the first Services Memory graph, which is located in the Service Memory RAM + Swap overview under Linux. If instead of this you want to retrieve the RAM used graph, count through the graphs, beginning with 0. A complete retrieval for a time range of 10 minutes (600 Seconds) will look like this, for example:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_graph&_username=automation&_secret=myautomationsecret" -d 'request={"specification":["template",{"service_description":"Memory","site":"heute","graph_index":4,"host_name":"heute"}],"data_range":{"time_range":[1504626158, 1504626758]}}'
{"result": {"step": 60, "start_time": 1504626180, "end_time": 1504626780, "curves": [{"color": "#80ff40", "rrddata": [3752390000.0, 3746380000.0, 3770930000.0, 3773230000.0, 3796020000.0, 3787010000.0, 3777880000.0, 3781040000.0, 3798920000.0, 3805910000.0], "line_type": "area", "title": "RAM used"}]}, "result_code": 0}

Querying a self-created graph is somewhat simpler since this is not bound to a particular host or service or to a particular site. Neverless, remember that an automated user, e.g. automation, can only retrieve such a graph if it has been enabled for all users:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_graph&_username=automation&_secret=myautomationsecret" -d 'request={"specification":["custom","all_disk_utilization"],"data_range":{"time_range":[1504709932, 1504710532]}}'
{"result": {"step": 60, "start_time": 1504709940, "end_time": 1504710540, "curves": [{"color": "#ea905d", "rrddata": [6.2217, 0.728733, 0.7748, 0.158085, 1.90726, 15.2222, 22.6851, 7.31163, 1.96834, 0.413633], "line_type": "stack", "title": "Disk utilization sdb"}, {"color": "#a05830", "rrddata": [1.45488, 0.101608, 0.0832167, 0.0342933, 0.235585, 0.166253, 14.9513, 25.112, 11.2032, 0.400437], "line_type": "stack", "title": "Disk utilization sda"}]}, "result_code": 0}

11. Retrieval options and command overview

11.1. Befehle

Command request_format output_format Required Optional
--- --- --- --- ---
Host command
get_host - - host name effective_attributes
add_host - - host name, folder attributes, nodes, create_folders
edit_host - - host name unset_attributes, attributes, nodes
delete_host - - host name -
delete_hosts - - hostnames -
get_all_hosts - - - effective_attributes
discover_services - - host name mode
Directory commands
get_folder - - folder effective_attributes
add_folder - - folder, attributes create_parent_folders
edit_folder - - folder attributes, configuration_hash
delete_folder - - folder configuration_hash
get_all_folder - - - effective_attributes
Group commands
add_contactgroup, add_hostgroup, add_servicegroup - - groupname, alias, customer* nagvis_maps**
edit_contactgroup, edit_hostgroup, edit_servicegroup - - groupname, alias, customer* nagvis_maps**
delete_contactgroup, delete_hostgroup, delete_servicegroup - - Group name
get_all_contactgroups, get_all_hostgroups, get_all_servicegroups - - - -
User commands
add_users - - users -
edit_users - - users -
delete_users - - users -
get_all_users - - - -
Rule set commands
get_ruleset - Python ruleset_name -
set_ruleset Python - ruleset_name, ruleset configuration_hash
get_ruleset_info - - - -
Host tag commands
get_hosttags - - - -
set_hosttags - - tag_groups, aux_tags configuration_hash
Site commands
get_site - Python site_id -
set_site Python - site_config, site_id configuration_hash
delete_site - - site_id configuration_hash
login_site - - site_id, username, password -
logout_site - - site_id -
Other commands
activate_changes - - - mode, sites, allow_foreign_changes, comment
bake_agents - - - -
get_graph - - specification, data_range -

* Only used with the ‘Managed Services Edition’  Check_MK Managed Services Edition

** Only for contact group commands