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
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.
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:
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
How to filter by group membership, without this attribute, can be learned below.
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
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.
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:
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.
member as standard.
Under OpenLDAP this can also be
Alter the option as appropriate.
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.
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.
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:
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.
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
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.
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.
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.
Normally the user’s first and last name.
When a user will be logged out or locked out.
The user’s email address.
Mega menu icons
Display green icons by topic (
Navigation bar icons
Display only icons (
A nominated telephone/pager contact number.
Show more / Show less
Display less (
Display the sidebar on the right (
Start URL to display in main frame
URL of the start page.
Unit of temperature in Celsius or Fahrenheit for display in graphs and Perf-O-Meters.
User interface theme
The theme of the user interface: Dark (
Visibility of hosts/services
Display all hosts and services (
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:
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).
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.
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
These messages can likewise point to the source of an error:
2020-09-19 16:03:17,155  [cmk.web 31797] /ldaptest/check_mk/wato.py Internal error: Traceback (most recent call last): File "/omd/sites/ldaptest/share/check_mk/web/htdocs/wato.py", line 6563, in mode_edit_ldap_connection state, msg = test_func(connection, address) File "/omd/sites/ldaptest/share/check_mk/web/htdocs/wato.py", line 6506, in test_group_count connection.connect(enforce_new = True, enforce_server = address) File "/omd/sites/ldaptest/share/check_mk/web/plugins/userdb/ldap.py", line 274, in connect ('\n'.join(errors))) MKLDAPException: LDAP connection failed: ldap://myldap.mycompany.org: Can't contact LDAP server
7. Files and directories
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.