Checkmk
to checkmk.com

1. Einleitung

Da eine händische Einrichtung von Benutzern nur bis zu einem gewissen Grad skaliert, bietet Checkmk die Möglichkeit, LDAP-basierte Dienste für die Benutzerverwaltung zu nutzen. Sie sind damit in der Lage, automatisiert Benutzer aus diesen zentralen Verzeichnissen zu synchronisieren und ihnen, ebenfalls automatisiert, Kontaktgruppen, Rollen und andere Attribute in Checkmk zuzuweisen. Checkmk ist dabei nicht auf eine einzelne LDAP-Quelle eingeschränkt und kann die Benutzer bei Bedarf auch an andere verbundene Instanzen weiterverteilen.

2. Konfiguration einer LDAP Verbindung

2.1. Verbindung zum Server

Um zu einem LDAP-fähigen Server eine Verbindung herzustellen, benötigen Sie zunächst einen Benutzer, welcher Leserechte auf dem Server besitzt. Er muss mindestens Lesezugriff auf die Personen und Gruppen haben, welche er synchronisieren soll. In den folgenden Beispielen heißt dieser Benutzer check_mk.

Unter Setup > Users > LDAP & Active Directory > Add connection können Sie nun eine neue Verbindung anlegen. Im Formular vergeben Sie zunächst eine beliebige ID für die Verbindung im Kasten General Properties. Optional können Sie hier unter Description einen leicht lesbaren Titel vergeben. Die ID muss wie immer eindeutig sein und kann später nicht mehr geändert werden. Sie darf nur aus Buchstaben, Ziffern, Gedanken- und Unterstrich bestehen, beginnend mit einem Buchstaben oder Unterstrich.

ldap new connection general properties

Unter LDAP Connection werden nun der LDAP-Server und — falls vorhanden — ein oder mehrere Failover Server definiert. Sie müssen nun noch den Directory type auswählen und die Benutzerdaten für den Lesezugriff unter Bind credentials definieren. Achten Sie darauf, dass der Benutzer mit seinem vollständigen LDAP-Pfad angegeben wird. Groß-/Kleinschreibung muss nicht beachtet werden. Ihre Konfiguration sollte nun etwa so aussehen:

ldap new connection ldap connection

Checkmk unterstützt nicht nur Active Directory. Um das Verzeichnis z.B. auf OpenLDAP zu ändern, wählen Sie es entsprechend in dem Feld Directory type aus. Die weitere Konfiguration ändert sich dabei für Sie nur an wenigen Stellen.

Die Failover Servers werden benutzt, wenn der eigentliche Server nicht erreichbar ist oder eine Zeitbeschränkung überschritten wurde. Das ist sinnvoll, wenn Sie lokal über keinen eigenen Server verfügen, aber die Verbindung redundant aufbauen möchten.

Die Verbindung von Checkmk mit dem LDAP-Server wird immer so lange aufrechterhalten bis der LDAP-Server aufgrund eines Timeouts oder anderer Probleme nicht mehr erreichbar ist. Erst dann wird zum Failover Server gewechselt. Das Gleiche gilt auch nach dem Wechsel: Die Verbindung wird erst dann wieder zurück zum eigentlich konfigurierten Server wechseln, wenn der Failover Server nicht erreicht werden kann.

2.2. Benutzer definieren

Als Nächstes werden die Pfade zu den Benutzern und Gruppen bestimmt und Filter gesetzt. Geben Sie in User base DN zunächst den Pfad an, unter dem die Benutzer zu finden sind. Achten Sie hier darauf, die Operational Unit (OU) so zu setzen, dass möglichst alle gewünschten Benutzer, aber möglichst wenig andere enthalten sind. Je mehr Benutzer abgefragt werden, desto langsamer wird die Synchronisation am Ende sein.

Danach setzen Sie die Option Search scope. Sie können hier rekursiv nach allen Benutzern filtern, die sich in der OU und in den Units darunter befinden oder die Suche auf diejenigen einschränken, die sich nur direkt in dieser OU befinden. Falls Sie in dem Pfad einen Benutzer direkt angegeben haben, sollten Sie Search only the entry at the base DN auswählen. Es wird dann nur dieser Benutzer erfasst.

Sie können nun mithilfe der Option Search filter die Auswahl der zu importierenden Benutzer weiter einschränken. Wollen Sie z.B. nur Benutzer synchronisieren, welche einer bestimmten Gruppe angehören, so setzen Sie hier eine LDAP-Abfrage ein, wie in dem folgenden Screenshot zu sehen. Voraussetzung dabei ist, dass die Benutzer über das Attribut memberof verfügen. Wie Sie ohne dieses Attribut nach einer Gruppenzugehörigkeit filtern, erfahren Sie weiter unten.

ldap new connection users

Sie können den Standardfilter auch mit memberof oder anderen Filtern kombinieren:

(&(objectclass=user)(objectcategory=person)(memberof=cn=cmk-admins,ou=groups,dc=mycompany,dc=example))

Wie Sie im Kasten Users sehen können, gibt es noch weitere Optionen bei der Benutzersuche. So ist es möglich mit der Option User-ID attribute zu bestimmen, welches Attribut der Benutzer als Login ID in Checkmk benutzen wird. Mit diesem Login wird sich der Benutzer später anmelden. In der Regel wird dies bei Active Directory das Attribut sAMAccountName sein, welches auch als Standard in Checkmk genutzt wird. Unter OpenLDAP ist dies oft das Attribut uid.

Mit der Option Lower case User-IDs können Sie die synchronisierten IDs in Kleinbuchstaben umwandeln. Das ist unter Umständen sinnvoll, da, wie bereits erwähnt, Active Directory/LDAP nicht zwischen Groß- und Kleinschreibung unterscheidet, Checkmk allerdings schon. Das kann zu Verwirrung führen, die durch diese Option gelöst wird.

Die Option Umlauts in User-IDs (deprecated) ist nur noch aus Kompatibilitätsgründen vorhanden und sollte nicht mehr verwendet/verändert werden.

Zu guter Letzt bietet Ihnen die Option Create users only on login die Möglichkeit, neue Benutzer nicht bei der Synchronisierung sondern erst bei ihrem ersten Login in Checkmk anzulegen.

ldap new connection users search filter 2

Die Option Filter group sollte nur verwendet werden, wenn der LDAP-Server kein Active Directory ist und in den Benutzerdaten das dynamische Attribut memberof nicht verfügbar ist. Die Filterung der Benutzer erfolgt in diesem Fall in Checkmk selbst. Es werden dabei unter Umständen viele Benutzer abgefragt, welche später wieder verworfen werden. Ein solches Szenario kann das LDAP-Modul in Checkmk stark ausbremsen.

Sind Sie jedoch auf diese Option angewiesen, so wird hier der komplette Pfad zu der Gruppe eingetragen, nach der gefiltert werden soll:

ldap new connection users filter group

2.3. Gruppen definieren

Falls Sie bei den Benutzern nach einer Gruppe filtern, richten Sie noch den Pfad zu der Gruppe ein, damit ein Abgleich stattfinden kann. Sie können hier in gleicher Weise vorgehen, wie bei den Benutzern: Wird eine Gruppe direkt angegeben, so kann unter Search scope die Option Search only the entry at the base DN genommen werden. Ansonsten wird entweder in der OU direkt gesucht, oder die Units darunter werden ebenfalls einbezogen.

Und auch hier ist es mithilfe der Option Search filter möglich, zu bestimmen, wie der Name der Gruppe in Checkmk festgelegt wird. Zusätzlich können Sie angeben, wie das Attribut heißt (Member attribute), in dem die Mitglieder der Gruppe hinterlegt sind. Standardmäßig verwendet Checkmk member. Unter OpenLDAP kann dies aber auch uniqueMember sein. Ändern Sie die Option dann entsprechend ab.

ldap new connection groups

2.4. Testen der Konfiguration

Sie haben nun bereits die erste Einrichtung abgeschlossen und können zur Diagnose die Konfiguration über den Knopf Save & test speichern und testen:

ldap new connection diagnostics

Sie müssen keine Gruppen angeben, um eine funktionierende Konfiguration zu erhalten. Sofern sich aber in der OU nur Benutzer für Checkmk befinden, ist es sinnvoll die Auswahl über eine oder mehrere Gruppen einzuschränken.

2.5. Das Synchronisierungsintervall

Als Letztes können Sie noch definieren, wie oft die Benutzer automatisch synchronisiert werden sollen. In einer Umgebung, in der sich selten etwas ändert, ist der Standardwert vielleicht etwas zu eng gewählt. Das Zeitfenster sollte allerdings auch nicht zu weit gesetzt werden, damit Änderungen auch zeitnah in Checkmk abgebildet werden können.

ldap new connection other

Sie können die Synchronisation auch jederzeit manuell in Setup > Users > Users > Synchronize users anstoßen. Zusätzlich wird ein Benutzer auch bei Bedarf synchronisiert, wenn er versucht sich anzumelden, aber noch nicht synchronisiert ist.

3. Automatische Zuordnung von Attributen

3.1. Kontaktgruppen

Es bringt leider nichts alle Benutzer automatisch anzulegen, wenn man diese danach manuell den Kontaktgruppen zuordnen muss. Checkmk bietet die Möglichkeit, die Gruppen des LDAP-Servers zu nutzen, um diese Kontaktgruppen zuzuordnen. Aktivieren Sie dafür die Option Attribute sync plugins > Contactgroup Membership:

ldap new connection contactgroup membership

Damit eine Zuordnung klappt, muss der Name (cn) der Gruppe auf dem LDAP-Server identisch mit dem in Checkmk sein. Das heißt, die Kontaktgruppe oracle_admins wird nur korrekt einem Benutzer zugeordnet, wenn dieser auch im LDAP in der Gruppe oracle_admins ist. Ist er stattdessen in der Gruppe oracle-admins oder ORACLE_admins, so wird die Zuordnung nicht funktionieren. Achten Sie also auf die korrekte Schreibweise, falls es an dieser Stelle zu Problemen kommt.

Nested Groups

Checkmk bietet — im Moment nur für Active Directory — die Möglichkeit, auch vererbte Gruppen zu nutzen. Aktivieren Sie diese Option, wenn z.B. Ihr Benutzer in der Gruppe oracle_admins ist und diese Gruppe wiederum Mitglied in cmk-user.

Gruppen aus anderen Verbindungen

Wenn in Checkmk mehrere LDAP-Verbindungen eingerichtet wurden, können Sie auch Gruppen aus anderen Quellen benutzen, um eine Zuordnung zu ermöglichen. Das kann sinnvoll sein, wenn Sie eine allgemeine Verbindung konfiguriert haben und in den anderen nur auf bestimmte Gruppen filtern.

3.2. Rollen

Auch die Rollen können in einer ähnlichen Weise automatisch zugeordnet werden und die Funktion Nested Groups kann hier ebenfalls genutzt werden. Für jede Rolle können eine oder mehrere Gruppen definiert werden. Wählen Sie dafür die Rolle aus, zu der Sie eine Verknüpfung einrichten wollen und geben Sie den vollständigen Pfad zu der Gruppe an. Standardmäßig wird in den Gruppen gesucht, welche vom Gruppenfilter gefunden wurden. Sie können aber auch andere Verbindungen und die darüber gefundenen Gruppen nutzen. Wählen Sie dafür in der Liste die entsprechende Verbindung aus.

ldap new connection roles

Mit den Einstellungen im obigen Bild werden alle Benutzer aus der angegebenen Gruppe der Rolle Administrator zugeordnet, sofern sie durch den Benutzerfilter auch synchronisiert werden. Wie Sie im Bild sehen können, können Sie auch selbst konfigurierte Rollen auswählen und mit Gruppen aus dem LDAP verknüpfen.

3.3. Weitere Attribute

Für die Synchronisation von weiteren Benutzerinformationen braucht es in der Regel nur die Aktivierung des jeweiligen Plugins unter Attribute Sync Plugins und eventuell der Angabe des Attributs, welches die Information bereitstellt. Nachfolgend eine Tabelle der Plugins, genutzten Attribute (wenn nicht manuell gesetzt) und Kurzbeschreibungen. Einige der Attribute finden sich auch im User-Menü eines Benutzers.

Plugin Attribut Syntax Mögliche Werte Beschreibung

Alias

cn

String

Normalerweise der Vor- und Nachname des Benutzers.

Authentication Expiration

pwdlastset

Interval

Wann ein Benutzer abgemeldet oder gesperrt wird.

Disable notifications

disable_notifications

Boolean

True, False

True deaktiviert alle Benachrichtigungen an den Benutzer.

Email address

mail

String

Die E-Mail-Adresse des Benutzers.

Mega menu icons

icons_per_item

String

None, entry

In den Mega-Menüs grüne Symbole beim Thema (None) oder farbige Symbole bei jedem Menüeintrag (entry) anzeigen.

Navigation bar icons

nav_hide_icons_title

String

None, hide

In der Navigationsleiste nur Symbole (hide) oder Symbole mit Titel (None) anzeigen.

Pager

mobile

String

Eine hinterlegte Telefon-/Pagernummer.

Show more / Show less

show_mode

String

default_show_less, default_show_more, enforce_show_more

In der Benutzeroberfläche weniger (default_show_less), mehr (default_show_more) oder stets alles (enforce_show_more) anzeigen. Mehr Informationen zum Show-less- und Show-more-Modus finden Sie im Leitfaden für Einsteiger.

Sidebar position

ui_sidebar_position

String

None, left

Die Seitenleiste auf der rechten (None) oder auf der linken (left) Seite anzeigen.

Start URL to display in main frame

start_url

String

Beispiele: view.py?view_name=allhosts oder dashboard.py

URL der Startseite.

Temperature unit

temperature_unit

String

celsius, fahrenheit

Einheit der Temperatur in Celsius oder Fahrenheit für die Anzeige in Graphen und Perf-O-Metern.

User interface theme

ui_theme

String

facelift, modern-dark

Das Thema der Benutzeroberfläche: Dark (modern-dark) oder Light (facelift).

Visibility of hosts/services

force_authuser

Boolean

True, False

Alle Hosts und Services anzeigen (False) oder nur diejenigen, für die der Benutzer als Kontakt zugewiesen ist (True).

4. LDAP in verteilten Umgebungen

Bei der Einrichtung einer verteilten Umgebung mit einer zentralen Konfiguration können Sie bestimmen, ob und welche LDAP-Verbindungen von der Remote-Instanz aus synchronisiert werden sollen. Wenn Sie nichts ändern, wird die Remote-Instanz alle Benutzer aus den konfigurierten Verbindungen selbst synchronisieren. Auf diese Weise werden Änderungen automatisch auf jeder Instanz innerhalb des definierten Intervalls abgebildet und müssen nicht erst von der Zentralinstanz zur Remote-Instanz kopiert werden. Sie können die Synchronisation aber auch auf bestimmte Verbindungen einschränken oder ganz abschalten. In letzterem Fall werden die Benutzer auf der Zentralinstanz aus den LDAP-Verbindungen abgerufen und beim Aktivieren der Änderungen auf die Remote-Instanzen kopiert.

Sie können die Einstellungen in Setup > General > Distributed monitoring in den Properties der Verbindung konfigurieren. Hier ein Beispiel, bei dem die oben eingerichtete Verbindung ausgewählt wird:

ldap distributed monitoring sync ldap

5. LDAP mit SSL absichern

Um die LDAP-Verbindung mit SSL abzusichern, aktivieren Sie lediglich in den Verbindungsdaten das Häkchen Use SSL und passen noch den TCP port an (bei LDAP über SSL üblicherweise 636).

ldap new connection ldap connection ssl

Sofern der oder die LDAP-Server ein Zertifikat nutzen, welches von einer vertrauenswürdigen Zertifizierungsstelle signiert wurde, ist damit bereits alles Nötige getan, um eine verschlüsselte Verbindung aufzubauen.

Wenn Sie ein selbstsigniertes Zertifikat nutzen, wird der Verbindungsaufbau nur dann funktionieren, wenn Sie dieses noch in den Zertifikatsspeicher importieren. Erst dann wird es als vertrauenswürdig eingestuft und die Verbindung aufgebaut.

Öffnen Sie dazu Setup > General > Global settings > Site management > Trusted certificate authorities for SSL. Klicken Sie hier auf Add new CA certificate or chain und kopieren Sie den Inhalt Ihres Zertifikats entweder in das vorgesehene Feld oder wählen Sie Upload CRT/PEM File und laden Sie Ihre PEM- oder CRT-Datei hoch.

ldap add new ca certificate

6. Fehlerdiagnose

Eine Fehlerdiagnose ist in der Konfigurationseinrichtung direkt implementiert. Auch nach der Einrichtung kann hier überprüft werden, woher ein Problem kommen könnte. Zusätzlich werden Fehlermeldungen auch in das web.log geschrieben. Diese Meldungen können ebenfalls auf die Fehlerquelle hinweisen:

~/var/log/web.log
2020-09-19 16:03:17,155 [40] [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. Dateien und Verzeichnisse

Pfad Bedeutung

~/etc/check_mk/multisite.d/wato/user_connections.mk

In dieser Datei werden alle im Setup konfigurierten LDAP Verbindungen festgehalten.

~/etc/check_mk/multisite.d/wato/users.mk

Alle Benutzer werden hier definiert.

~/var/log/web.log

Die Log-Datei, in der Verbindungsfehler aufgezeichnet werden. Es ist damit eine der ersten Quellen bei Problemen.

Auf dieser Seite