1. Introduction

Since the manual definition of users is scalable only up to a certain level, Checkmk provides a facility for using LDAP-based services for managing users, for automatically synchronizing users from the home directories, and likewise for assigning contact groups, roles and other attributes to these users in Checkmk automatically. Checkmk is not restricted to a single LDAP source, and it can also distribute the users to other connected sites if required.

2. Configuring an LDAP connection

2.1. Connecting to the server

Creating a connection to an LDAP-compatible server requires a user with read permission for the server. As a minimum it must have read permission for the persons and groups that it is to synchronize. In the following example this user is called check_mk.

Under Setup > Users > LDAP & Active Directory > Add connection a new connection can be created. In the form, first enter any desired ID for the connection in the General Properties box. A simple meaningful title can be optionally entered in the Description field. As always, the ID must be unique and cannot be changed later. It may only consist of letters, digits, dashes and underscores, starting with a letter or underscore.

ldap new connection general properties

Next, under LDAP Connection the LDAP server can be defined, as well as one or more failover servers if they are available. Then only the Directory type needs to be selected, and the user data for the read-access defined under Bind credentials. Note that the user name with its full LDAP path must be entered. Upper and lower case must not does not need to be taken into account. The configuration should then look something like this:

ldap new connection ldap connection

Checkmk supports more than just Active Directory. To alter the directory to, e.g., OpenLDAP, select it in the Directory type field — further configuration alterations resulting from this action occur in only a few locations.

The Failover Servers are used when the actual server is not accessible, or when a time limit has been exceeded. This makes sense if there is no local own server in use, but it is desired to create a redundant connection.

The connection of Checkmk with the LDAP server is always maintained until the LDAP server is no longer accessible due to a timeout or other problems. Only then is the switch to the failover server made. The same applies after the switchover: The connection will only revert to the actually configured server if the failover server becomes unavailable.

2.2. Defining users

Next the paths to the users and groups will be defined, and the filters set. In User base DN, first enter the path via which the users are to be found. Make sure here that the Operational Unit (OU) is set so that all desired users and as few others as possible are included. The more users that are queried, the slower the synchronization will be to process.

Next set the Search scope option. Here you can recursively filter for all users located in the OU and in those units below it, or restrict the search to those located directly in this OU. If you have entered a user directly in the path, you should select Search only the entry at the base DN — only this user will then be included.

With the help of the option Search filter you can narrow down the selection of users to be imported even further. If for example you want to synchronize only the users belonging to a specific group, set an LDAP query as shown in the following screenshot. The prerequisite for this is that the users have the memberof attribute. How to filter by group membership, without this attribute, can be learned below.

ldap new connection users

The standard filter can also be combined with the memberof, or with other filters:


As can be seen in the Users box, there are further options for a user search. With the User-ID attribute option it is possible to specify which attribute the user is to utilize as its login ID in Checkmk. The user will subsequently use this login when signing in. As a rule, in Active Directory it will be the sAMAccountName attribute, which is used as standard in Checkmk. Under OpenLDAP it is often the uid attribute.

With the Lower case User-IDs options you can convert the synchronized IDs to lower-case letters. This is possibly sensible, since as already mentioned, Active Directory/LDAP does not differentiate between upper and lower case letters, but Checkmk does. That can lead to confusion which this option can solve.

The Umlauts in User-IDs (deprecated) option was only provided for compatibility reasons and should no longer be used/altered.

Last but not least the option Create users only on login allows you to create new users only once they login to Checkmk instead of during the synchronization with LDAP.

ldap new connection users search filter 2

The Filter group option should only be used if the LDAP server is not an Active Directory, and the memberof dynamic attribute is not available in the user data. In such cases the user filtering takes place in Checkmk itself. In the process it is possible that many users will be queried which will later be discarded. Such a scenario can be largely stopped by the LDAP module in Checkmk.

Should you be dependent on this option however, the complete path for the group to be filtered must be entered here:

ldap new connection users filter group

2.3. Defining groups

Should you wish to filter the users by group, define the path to the group so that a matching can be performed. This can be done in the same way as with the users — when a group is directly specified, under Search scope the Search only the entry at the base DN option can be used — otherwise the search will be performed either directly in the OU or its subsidiary units will also be included.

Here as well, with the help of the Search filter option it is possible to specify how the group’s name is to be defined in Checkmk. You can additionally specify the name of the attribute (Member attribute) in which the group’s members are lodged. Checkmk uses member as standard. Under OpenLDAP this can also be uniqueMember. Alter the option as appropriate.

ldap new connection groups

2.4. Testing the configuration

The first setup is now complete, and for diagnosis the configuration can now be saved and tested via the Save & test button.

ldap new connection diagnostics

You don’t need to specify groups to produce a functioning configuration. However, if there are only users for Checkmk in the OU, it makes sense to restrict the selection via one or more groups.

2.5. The synchronization interval

Finally, you can also define how often the users are to be automatically synchronized. In an environment in which changes seldom occur the standard is perhaps too tight. The time frame should not not be too long however, so that any changes can be reflected promptly in Checkmk.

ldap new connection other

A synchronization can be manually initiated at any time in Setup > Users > Users > Synchronize users. In addition, a user will be synchronized if required when they attempt to log in and have not yet been synchronized.

3. Automatic allocation of attributes

3.1. Contact groups

It is not much use being able to create all users automatically, if it is then necessary to allocate them to contact groups manually. Checkmk provides the function of using the LDAP server’s groups to enable allocation to contact groups. For this, activate the Attribute sync plugins > Contactgroup Membership option:

ldap new connection contactgroup membership

For an allocation to be successful, the group’s name (cn) on the LDAP server must be identical to that in Checkmk — i.e., the oracle_admins group will only be allocated to a user if it is also in the oracle_admins group in LDAP. If, instead of this, it is in the oracle-admins or the ORACLE_admins groups the allocation will not work. Therefore be careful to use the correct syntax and use of upper and lower case should problems arise in this situation.

Nested groups

Checkmk also offers — currently only for Active Directory — the possibility of using inherited groups. Activate this option if, for example, your user is in the oracle_admins group, and this group is in turn a member of cmk-user.

Groups from other connections

If multiple LDAP connections have been created in Checkmk, groups from other sources can also be utilized to enable an allocation. This can make sense if one general connection has been configured, and others are filtered only for particular groups.

3.2. Roles

Roles can also be automatically allocated in a similar way and the Nested groups function likewise used here. One or more groups can be defined for each role. Select the role for which a connection is to be created and enter the full path to the group. As standard a search will be performed in groups found in group filter. Other connections can however be searched in order to use the groups found there. Select the connections to be searched from the list.

ldap new connection roles

With the settings in the image above, all users in the nominated group will be allocated to the Administrator role, as long as they are also synchronized by the user filter. As can be seen in the screenshot, your own configured roles can also be selected and connected with LDAP groups.

3.3. Other attributes

For the synchronization of other user information, as a rule only the activation of the relevant plug-in under Attribute Sync Plugins is required, and possibly also the entry of the attribute which provides the information. Below is a table of the plug-ins and the attribute used (if not manually set) and a short description. Some of the attributes are also found in the User menu of a user.

Plug-in Attribute Syntax possible values Description




Normally the user’s first and last name.

Authentication Expiration



When a user will be logged out or locked out.

Disable notifications



True, False

True disables all notifications to the user.

Email address



The user’s email address.

Mega menu icons



None, entry

Display green icons by topic (None) or colored icons by each menu item (entry) in the mega menus.

Navigation bar icons



None, hide

Display only icons (hide) or icons with title (None) in the navigation bar.




A nominated telephone/pager contact number.

Show more / Show less



default_show_less, default_show_more, enforce_show_more

Display less (default_show_less), more (default_show_more) or always all (enforce_show_more) in the user interface. For more information on Show less and Show more modes, see the Beginner’s Guide.

Sidebar position



None, left

Display the sidebar on the right (None) or on the left (left) side.

Start URL to display in main frame



Examples: or

URL of the start page.

Temperature unit



celsius, fahrenheit

Unit of temperature in Celsius or Fahrenheit for display in graphs and Perf-O-Meters.

User interface theme



facelift, modern-dark

The theme of the user interface: Dark (modern-dark) or Light (facelift).

Visibility of hosts/services



True, False

Display all hosts and services (False) or only those for which the user is assigned as contact (True).

4. LDAP in distributed environments

When configuring a distributed monitoring with a centralized configuration you can specify whether, and which LDAP connections should be synchronized from the remote site. If not otherwise specified, the remote site itself will synchronize all users of the configured connection. In this way changes will be automatically reflected on every site within the defined time frame and do not first need to be copied from the central to the remote site(s). The synchronization can also be restricted to specific connections or completely disabled. In the second case the users on the central site are retrieved from the LDAP connections and copied to the remote sites with an activate changes.

You can configure the settings in Setup > General > Distributed monitoring in the Properties of the connection. Here is an example where the connection set up above is selected:

ldap distributed monitoring sync ldap

5. Securing LDAP with SSL

In order to secure the LDAP connection with SSL, simply activate the Use SSL checkbox in the connection data and match the TCP port (usually 636 for SSL in LDAP).

ldap new connection ldap connection ssl

If the LDAP server(s) use a certificate signed by a trustworthy certification authority, everything necessary to establish an encrypted connection is already done.

If a self-signed certificate is to be used, the connection can only be established after the certificate has been imported into the certificate store. Only then will it be classified as trustworthy and the connection established.

In order to do so, simply go to Setup > General > Global settings > Site management > Trusted certificate authorities for SSL. Click Add new CA certificate or chain and either paste in the content of your CRT or PEM file or choose Upload CRT/PEM File and do just that.

ldap add new ca certificate

6. Error diagnosis

An error diagnosis is implemented directly in the configuration settings. Even after setup, it is possible to check here for the possible source of an error. Error messages will additionally be written to the web.log. These messages can likewise point to the source of an error:

2020-09-19 16:03:17,155 [40] [cmk.web 31797] /ldaptest/check_mk/ Internal error: Traceback (most recent call last):
  File "/omd/sites/ldaptest/share/check_mk/web/htdocs/", line 6563, in mode_edit_ldap_connection
    state, msg = test_func(connection, address)
  File "/omd/sites/ldaptest/share/check_mk/web/htdocs/", line 6506, in test_group_count
    connection.connect(enforce_new = True, enforce_server = address)
  File "/omd/sites/ldaptest/share/check_mk/web/plugins/userdb/", line 274, in connect
MKLDAPException: LDAP connection failed:
ldap:// Can't contact LDAP server

7. Files and directories

File path Function


All LDAP connections configured in the Setup will be retained in this file.


All users will be defined here.


The log file in which connection errors are be recorded — it is thus one of the first sources of information when problems occur.

On this page