Die Bakery-API

1. Einleitung

In den kommerziellen Editionen können Sie die Bakery-API nutzen, um eigene, sogenannte Bakery Plugins zu schreiben, die Funktionen in die Agentenpakete der Agentenbäckerei (Agent Bakery) einbinden. In den meisten Fällen handelt es sich bei diesen Funktionen um Agentenplugins, d.h. um zusätzliche Skripte, die vom Checkmk-Agenten ausgeführt werden sollen, sowie deren Konfigurationsdateien. Sie können aber auch auf die Funktionen des Paketmanagers Einfluss nehmen, sofern diese abgebildet werden können durch das Einbinden von Dateien, das Ausführen von Paket-Skriptlets (für die Paketformate RPM, DEB und Solaris PKG) oder die Angabe von spezifischen Konfigurationseinträgen für den Windows-Agenten (in YAML). All diese „Artefakte“ können mit der Bakery-API in einer einheitlichen Syntax beschrieben werden.

Ein Anwendungsfall ist zum Beispiel der folgende: Sie haben die Einführung in die Entwicklung von Erweiterungen für Checkmk gelesen und davon inspiriert Ihr eigenes agentenbasiertes Check-Plugin mit zugehörigem Agentenplugin geschrieben. Beide haben Sie dann zu einem Checkmk-Erweiterungspaket (MKP) zusammengefasst.

Nun wollen Sie das Agentenplugin konfigurierbar machen (z.B. nur von bestimmten Benutzern oder auf bestimmten Hosts ausführen lassen) und zusätzlich Aktionen bei der Installation oder Deinstallation des Agentenpakets durchführen. Dazu können Sie die Bakery-API nutzen — als Paketierungs- und Verteilungshilfe, wie wir in diesem Artikel an einem Beispielszenario zeigen werden. Dabei werden zwei neue Dateien erstellt, die dann zusammen mit den vorhandenen Plugin-Dateien zu einem neuen MKP geschnürt werden können. Dafür finden Sie in der Checkmk Exchange ein ausführlich kommentiertes Beispiel: das Hello world! MKP (ausgepackt auf GitHub), welches eng an das in diesem Artikel vorgestellte Beispielszenario angelehnt ist.

Beachten Sie, dass die Bakery-API keine Funktionen zur Verfügung stellt für die Konfiguration des Bakery Plugins, d.h. für die Erstellung des zugehörigen Regelsatzes, und auch nicht für die Inhalte der mit dem Plugin bereitgestellten Dateien, also z.B. die Agentenplugins.

Auch wenn die Agentenbäckerei nur in den kommerziellen Editionen enthalten ist, existiert die Bakery-API seit Checkmk 2.3.0 in allen Editionen. Dies gibt Benutzern von Checkmk Raw die Möglichkeit, Erweiterungspakete zu erstellen, welche auf allen Editionen installiert werden können. Falls mit der Bakery-API erstellte Pakete auf Checkmk Raw installiert werden, wird die zusätzliche Funktionalität schlicht ignoriert.

2. Die API-Dokumentation

Software und Dokumentation der Bakery-API stammen aus der gleichen Quelle. Daher passt die API-Dokumentation stets zur Software und beschreibt genau das, was die API kann — und deshalb ist es auch nicht nötig, den Referenzteil der verfügbaren Funktionen, Klassen, Parameter etc. im Checkmk-Handbuch zu beschreiben. Stattdessen finden Sie die API-Dokumentation außerhalb dieses Handbuchs, direkt in Ihrer Checkmk-Instanz.

2.1. Versionierung

Die API mit ihrer Dokumentation ist versioniert und nutzt dabei eine zweistufige Nummerierung nach dem Semantic Versioning 2.x Standard im Format X.Y, wobei X für eine Major Version steht und Y für eine Minor Version. Eine neue Minor Version enthält neue, rückwärtskompatible Funktionen. Eine neue Major Version kann dagegen Änderungen enthalten, die die API inkompatibel mit der vorherigen Major Version machen.

2.2. Versionsgeschichte und -ausblick

Jedes Plugin deklariert beim Zugriff auf die API explizit die API-Version, auf der es basiert. Version 1 ist die seit Checkmk 2.0.0 aktuelle Version der Bakery-API, die in diesem Artikel beschrieben wird.

Checkmk 2.5.0 führt Version 2 der Bakery-API ein, allerdings können die beiden Versionen 1 und 2 auch in 2.5.0 noch parallel benutzt werden. Das heißt, diesem Artikel folgend erstellte Plugins werden wenigstens in Checkmk 2.5.0 noch funktionieren, sehr wahrscheinlich auch darüber hinaus.

Die zur Konfiguration von Bakery Plugins in der Checkmk-GUI verwendete Rulesets-API folgt einer eigenen Versionsgeschichte. Bitte beachten Sie für diesen Teil Ihrer Erweiterungspakete unseren Artikel zur Entwicklung von Check-Plugins.

2.3. Zugriff auf die API-Dokumentation

Die Bakery-API-Dokumentation steht im HTML-Format zur Ansicht im Web-Browser bereit. Sie ist in jeder Checkmk-Site enthalten und kann über die Checkmk-GUI geöffnet werden: über die Navigationsleiste im Menü Help > Developer resources > Plug-in API references:

Wenn Sie Plugins unabhängig von einer Checkmk-Instanz entwickeln und testen wollen, können Sie auf eine Kopie zugreifen, die auf docs.checkmk.com/plugin-api bereitgestellt ist. In der mit Sphinx generierten Dokumentation wird die gesamte für die Entwicklung von Checkmk-Plugins relevante API-Dokumentation angezeigt, d.h. Sie finden hier neben der Dokumentation zur Bakery-API zum Beispiel auch die zur Check-API.

3. Die API nutzen

3.1. Ein Beispielszenario

Wir werden den Gebrauch der API an folgendem Beispielszenario demonstrieren:

Für den Checkmk-Agenten wird ein Plugin bereitgestellt mit dem Namen hello_world.
Das Agentenplugin gibt es in drei Varianten für Linux, Solaris und Windows und soll auch für diese drei Betriebssysteme in die Agentenpakete eingebunden werden. Die zugehörigen Dateien liegen vor und heißen hello_world (für Linux), hello_world.solaris.ksh (für Solaris) und hello_world.cmd (für Windows).
Python-, Shell- und CMD-Skripte sind nur Beispiele. Ein Agentenplugin kann eine beliebige, auf dem Zielsystem ausführbare Datei sein.
Der Inhalt der Dateien interessiert uns hier nicht. Die Funktion der Agentenplugins ist nicht Gegenstand der Bakery-API. Mehr dazu erfahren Sie in der Einführung zum Entwickeln eigener agentenbasierter Check-Plugins.
Es soll konfigurierbar sein, ob die Ausgabe des Plugins zwischengespeichert werden soll (caching), d.h. in diesem Fall wird das Plugin vom Agenten erst nach Ablauf der konfigurierten Zeit (Ausführungsintervall) wieder ausgeführt.
Das Plugin soll im Setup-Menü über Einstellungen der Agentenbäckerei mit den Variablen user und content konfiguriert werden. Das Linux-Plugin liest die Konfiguration aus der Konfigurationsdatei hello_world.json und das Solaris-Plugin aus der Datei hello_world.cfg. Das Windows-Plugin liest die Einträge hello_world.user und hello_world.content aus der YAML-Konfigurationsdatei des Windows-Agenten ein.
Der Zugriff auf diese Ressourcen muss jeweils im Agentenplugin umgesetzt werden und ist nicht Gegenstand der Bakery-API.
Für Linux und Solaris gibt es zusätzlich ein Programm some_binary, das mit ausgeliefert werden soll. Das ist z.B. ein kleines Shell-Skript, um das Plugin auch per Befehl unabhängig vom Checkmk-Agenten starten zu können.
Unter Linux und Solaris soll nach der Installation des Agenten per Paketmanager-Routine in das Syslog geschrieben werden, dass hello_world installiert wurde. Nach der Deinstallation des Agenten soll analog in Syslog geschrieben werden, dass hello_world deinstalliert wurde.
Üblich sind unter Linux postinst- und prerm-Skripte: im postinst-Skript erstellt man beispielsweise einen Cache und startet einen Daemon, im prerm-Skript kann man dann den Daemon wieder stoppen und den Cache löschen. Weitere Informationen zur Verwendung von „Maintainer Scripts“ finden Sie in der Debian-Dokumentation.

3.2. Regelsatz erstellen

Zu einem Bakery Plugin muss es einen Regelsatz für das Setup geben, mit dem das Plugin über die GUI konfiguriert werden kann. Im einfachsten Fall dient der Regelsatz lediglich der Aktivierung des Plugins: So ordnen Sie Ihr Plugin bestimmten Hosts zu. Die Erstellung eines Regelsatzes ist nicht Bestandteil der Bakery-API. Sie finden zu diesem Thema eine Einführung im Artikel zum Entwickeln eigener agentenbasierter Check-Plugins. Auch die Pfadkonventionen für das Ablegen von Regelsätzen sind dort beschrieben.

Falls Sie Regelsätze, die noch bis Checkmk 2.3.0 unterstützt wurden, auf die aktuellen Programmierschnittstellen portieren wollen, öffnen Sie diesen Artikel im Handbuch der Version 2.2.0 in einem neuen Tab oder Fenster. Vergleichen Sie diesen Seite an Seite mit dem entsprechenden Abschnitt in diesem Artikel. Die vorgenommene Konfiguration ist so ähnlich, dass die Gegenüberstellung leicht als Portierungshilfe dienen kann.

Minimaler Regelsatz

Ein Beispiel für solch einen minimalen Regelsatz, der die Verteilung eines Plugins lediglich aktiviert, kann wie folgt aussehen. Die importierten Klassen sind hier umfangreicher als benötigt gewählt, um auch das erweiterte Beispiel abdecken zu können. Der auffälligste Unterschied zum Regelsatz bei agentenbasierten Check-Plugins ist die Verwendung der Klasse AgentConfig statt CheckParameters.

~/local/lib/python3/cmk_addons/plugins/hello_world/rulesets/ruleset_hello_world_bakery.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

from cmk.rulesets.v1 import Label, Title, Help
from cmk.rulesets.v1.form_specs import (
    BooleanChoice,
    DefaultValue,
    DictElement,
    Dictionary,
    String,
    TimeSpan,
    TimeMagnitude
)
from cmk.rulesets.v1.rule_specs import AgentConfig, HostCondition, Topic

def _parameter_form_bakery():
    return Dictionary(
        elements = {}
    )

rule_spec_hello_world_bakery = AgentConfig(
    name = "hello_world",
    title = Title("Hello bakery!"),
    topic = Topic.GENERAL,
    parameter_form = _parameter_form_bakery,
)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Erweiterter Regelsatz

Allerdings haben wir im Beispielszenario spezifiziert, dass ein Ausführungsintervall bestimmt und die beiden Variablen user und content gesetzt werden sollen. Diese Variablen werden als Schlüssel im Dictionary definiert, welches die als parameter_form spezifizierte Funktion zurückgibt.

~/local/lib/python3/cmk_addons/plugins/hello_world/rulesets/ruleset_hello_world_bakery.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

from cmk.rulesets.v1 import Label, Title, Help
from cmk.rulesets.v1.form_specs import (
    BooleanChoice,
    DefaultValue,
    DictElement,
    Dictionary,
    String,
    TimeSpan,
    TimeMagnitude
)
from cmk.rulesets.v1.rule_specs import AgentConfig, HostCondition, Topic

def _parameter_form_bakery():
    return Dictionary(
        elements = {
            "user": DictElement(
                parameter_form = String(
                    title = Title("User for example plugin"),
                )
            ),
            "content": DictElement(
                parameter_form = String(
                    title = Title("The actual content"),
                )
            ),
            "interval": DictElement(
                parameter_form = TimeSpan(
                    title = Title("Run asynchronously"),
                    label = Label("Interval for collecting data"),
                    displayed_magnitudes = [TimeMagnitude.SECOND, TimeMagnitude.MINUTE],
                    prefill = DefaultValue(300.0),
                )
            )
        }
    )

rule_spec_hello_world_bakery = AgentConfig(
    name = "hello_world",
    title = Title("Hello bakery!"),
    topic = Topic.GENERAL,
    parameter_form = _parameter_form_bakery,
)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Die aus diesem Regelsatz resultierende GUI zeigt der folgende Screenshot:

GUI des Regelsatzes zur Konfiguration des Plugins.

3.3. Plugin-Datei erstellen

Die Plugin-Datei hello_world.py wird im lokalen Teil der Instanzverzeichnisstruktur unter ~/local/lib/check_mk/base/cee/plugins/bakery/ abgelegt.

Ein Bakery Plugin wird in Form einer Datei angelegt, die als Python 3-Modul importiert wird. Nach Checkmk-Konvention beginnen daher auch Plugin-Dateien mit den folgenden Zeilen:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Da es sich um ein Modul handelt, müssen alle benötigten Klassen und Funktionen zu Beginn importiert werden.

3.4. Auf die API zugreifen

Alle Objekte der Bakery-API stehen unter cmk.base.cee.plugins.bakery.bakery_api.vX zur Verfügung, wobei X die API-Versionsnummer bezeichnet, im Beispiel 1. Da die Plugin-Datei selbst im Namespace cmk.base.cee.plugins.bakery liegt, funktioniert auch ein relativer Import aus .bakery_api.v1:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

from .bakery_api.v1 import (
    OS,
    DebStep,
    RpmStep,
    SolStep,
    Plugin,
    PluginConfig,
    SystemBinary,
    Scriptlet,
    WindowsConfigEntry,
    register,
    FileGenerator,
    ScriptletGenerator,
    WindowsConfigGenerator,
    quote_shell_string,
)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Im obigen Beispiel werden nur die Namen importiert, die für das Beispielszenario benötigt werden.

3.5. Die verfügbaren Objekte der API

Die Namen, die in der Bakery-API zur Verfügung stehen, werden in der API-Dokumentation detailliert beschrieben. In diesem Kapitel werden die Objekte trotzdem kurz vorgestellt, da dies hilfreich ist, um die Umsetzung des Beispielszenarios nachvollziehen zu können.

Identifier / Aufzählungen

Zur Spezifikation der einzelnen Plugin-Artefakte stehen Aufzählungen (enumerations, Enum) zur Verfügung, mit denen verschiedene Eigenschaften, meist in Form eines Arguments, angegeben werden können:

OS — Das Betriebssystem im Kontext der Bakery-API.
DebStep — Ein Transaktionsschritt für ein DEB „Maintainer Script“.
RpmStep — Ein Transaktionsschritt für ein RPM „Scriptlet“.
SolStep — Ein Transaktionsschritt für ein Solaris PKG „Installation Script“.

Artefakte

Artefakte werden die Dateien und Dateiinhalte genannt, die die eigentlichen Bestandteile eines Plugins sind. Sie werden mit Hilfe von geeigneten Klassen beschrieben, die sich in folgende Kategorien unterteilen lassen:

Dateien (Plugin, SystemBinary, PluginConfig, SystemConfig) — Jede Datei, die dem Checkmk-Agenten bereitgestellt werden soll, wird mit einem Objekt beschrieben. Der Dateityp wird durch die Klasse beschrieben. Dabei muss für jedes Betriebssystem, auf dem die Datei bereitgestellt werden soll, ein separates Objekt definiert werden.
Skriptlets (Scriptlet) — Ein DEB „Maintainer Script“, RPM „Scriptlet“ oder Solaris PKG „Installation Script“, das bei der Installation, Deinstallation oder Update des Agentenpakets zum angegebenem Transaktionsschritt (z.B. preinstall, postremove) ausgeführt werden soll.
Windows-Konfigurationseinträge (WindowsConfigEntry, WindowsConfigItems, WindowsGlobalConfigEntry, WindowsSystemConfigEntry) — Einträge in der YAML-Konfigurationsdatei für den Windows-Agenten werden ebenfalls mit Hilfe geeigneter Klassen beschrieben.

Diese Artefakte werden jeweils in Callback-Funktionen beschrieben, die ihrer Kategorie entsprechen. Die einzelnen Funktionen werden der Registrierungsfunktion mit den Argumenten files_function, scriptlets_function, windows_config_function übergeben. Dabei handelt es sich um Generatorfunktionen, die die einzelnen spezifizierten Artefakte zurückgeben. Die Auswertung übernimmt die Agent Bakery.

Den Funktionen werden als Argumente verschiedene Parameter übergeben, die zur Konstruktion und der Bestimmung der zurückgegebenen Artefakte ausgewertet werden können. Bei den Parametern handelt es sich zum einen um die GUI-Konfiguration des jeweiligen Agenten, der gerade gebacken werden soll (conf) und zum anderen um den Hash der aktuellen Agentenkonfiguration und Plugin-Dateien (aghash).

Registrierungsfunktion

Die Registrierung erfolgt mit der Funktion register, die beim Import des Bakery Plugins als Modul aufgerufen wird.

Der Funktion werden als Argumente die einzelnen Bestandteile des Bakery Plugins übergeben: der Plugin-Name (name) und die Funktionen (files_function, scriptlets_function, windows_config_function), die jeweils eine Kategorie der Artefakte zurückliefern.

Typ-Annotationen

Namen für Typ-Annotationen (FileGenerator, ScriptletGenerator, WindowsConfigGenerator, WindowsConfigContent) können optional zur Typisierung der spezifizierten Funktionen verwendet werden, z.B. so:

def get_files(conf: dict) -> FileGenerator:
    yield Plugin(...)
    yield PluginConfig(...)

def get_scriptlets(conf: dict) -> ScriptletGenerator:
    yield Scriptlet(...)

def get_windows_config(conf: dict) -> WindowsConfigGenerator:
    content: WindowsConfigContent = conf["some_entry"]
    yield WindowsGlobalConfigEntry(name="some_name",content=content)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Hilfsfunktionen

Die folgenden Hilfsfunktionen können verwendet werden:

quote_shell_string — Mit dieser Funktion lässt sich ein String-Ausdruck so umsetzen, dass er in der resultierenden Datei von der Shell als Ausdruck korrekt erkannt wird — ohne dass im Python-Code die Anführungszeichen manuell maskiert werden müssen.
password_store — Dieses Modul erlaubt den Zugriff auf Passwörter, die im Checkmk-Passwortspeicher abgelegt sind.

3.6. Registrieren

Die Registrierung des Plugins bei Checkmk mit Plugin-Namen und Funktionen erfolgt über die Funktion register.bakery_plugin:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

register.bakery_plugin(
    name = "hello_world",
    files_function = get_hello_world_plugin_files,
    scriptlets_function = get_hello_world_scriptlets,
    windows_config_function = get_hello_world_windows_config,
)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Die hier festgelegten Funktionen get_hello_world_windows_config, get_hello_world_scriptlets und get_hello_world_plugin_files werden in den folgenden Kapiteln näher erläutert.

3.7. Konfiguration für den Windows-Agenten

Im Beispiel soll das Intervall zur Ausführung festgelegt werden und die Konfiguration des Plugins über zwei Variablen erfolgen können. Achten Sie darauf, Schlüssel und Datentypen wie im oben erstellten Regelsatz zu definieren.

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

class HelloWorldConfig(TypedDict, total=False):
    interval: float
    user: str
    content: str

def get_hello_world_windows_config(conf: HelloWorldConfig) -> WindowsConfigGenerator:
    yield WindowsConfigEntry(path=["hello_world", "user"], content=conf["user"])
    yield WindowsConfigEntry(path=["hello_world", "content"], content=conf["content"])

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

In der get_hello_world_windows_config Funktion greifen wir über das conf Argument auf die Konfiguration zu, die über den Regelsatz in der Setup-GUI festgelegt wird: das Zeitintervall für die Wiederausführung bei zwischengespeicherter Ausgabe (interval) und die beiden Variablen, mit denen das Plugin konfiguriert werden kann (user, content). Dabei gehen wir davon aus, dass die Konfiguration des Regelsatzes als ein dict geliefert wird. Über das TypedDict der Klasse HelloWorldConfig können wir uns einen typisierten Zugriff darauf einrichten.

Anschließend werden mit WindowsConfigEntry die Einträge in der YAML-Konfigurationsdatei des Windows-Agenten festgelegt, aus denen die Werte für user und content gelesen werden.

3.8. Installationsskripte für Linux

Unter Linux und Solaris soll bei der Installation und Deinstallation des Agenten Syslog-Meldungen geschrieben werden. Wir zeigen hier nur die Implementierung für die Linux-Distribution Debian:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

def get_hello_world_scriptlets(conf: Any) -> ScriptletGenerator:
    installed_lines = ['logger "Installed hello_world"']
    uninstalled_lines = ['logger "Uninstalled hello_world"']

    yield Scriptlet(step=DebStep.POSTINST, lines=installed_lines)
    yield Scriptlet(step=DebStep.POSTRM, lines=uninstalled_lines)
    # yield Scriptlet(step=RpmStep.POST, lines=installed_lines)
    # yield Scriptlet(step=RpmStep.POSTUN, lines=uninstalled_lines)
    # yield Scriptlet(step=SolStep.POSTINSTALL, lines=installed_lines)
    # yield Scriptlet(step=SolStep.POSTREMOVE, lines=uninstalled_lines)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

Zuerst werden die Befehle für die Syslog-Meldungen definiert und anschließend die Installationsskripte für Debian (DebStep), die nach der Installation (POSTINST) und nach der Deinstallation (POSTRM) ausgeführt werden sollen. In den Kommentaren darunter finden Sie auch noch die entsprechenden Zeilen für Distributionen, die RPM verwenden und für Solaris.

Hinweis: Nach den von Ihnen eingefügten Befehlszeilen werden die Installationsskripte von Checkmk mit weiteren Befehlen befüllt. Schließen Sie daher Ihren Befehlssatz nicht mit einem exit 0 ab, damit auch alle Befehle der Skripte ausgeführt werden.

3.9. Agentenplugin für Linux

Die Konfiguration für das Linux-Agentenplugin sieht wie folgt aus. Achten Sie darauf, das übergebene Intervall nach Integer zu konvertieren, da Regelsatz und Bakery für Zeitspannen unterschiedliche Datentypen nutzen.

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

def get_hello_world_plugin_files(conf: HelloWorldConfig) -> FileGenerator:
    interval = conf.get('interval')

    yield Plugin(
        base_os = OS.LINUX,
        source = Path('hello_world'),
        target = Path('hello_world'),
        interval = int(interval),
    )

    yield PluginConfig(
        base_os = OS.LINUX,
        lines = _get_linux_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.json'),
        include_header = False)

    for base_os in [OS.LINUX]:
        yield SystemBinary(
            base_os = base_os,
            source = Path('some_binary'),
        )

def _get_linux_cfg_lines(user: str, content: str) -> List[str]:
    config = json.dumps({'user': user, 'content': content})
    return config.split('\n')

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

In der Funktion get_hello_world_plugin_files wird zuerst die Python-Datei hello_world als Plugin definiert, d.h. als ausführbare Datei, die vom Checkmk-Agenten als Agentenplugin ausgeführt werden soll. Dann wird mit PluginConfig die zu generierende Konfigurationsdatei hello_world.json für das Linux-Agentenplugin mit den Einträgen user und content festgelegt.

Mit der zweiten Funktion _get_linux_cfg_lines werden diese Zeilen im JSON-Format geschrieben. Dabei enthält das Python Dictionary conf die mit dem Regelsatz der Setup-GUI gesetzten Werte, die dann über einen kleinen Umweg in eine JSON-Datei verpackt werden.

Schließlich soll das zusätzlich auszuliefernde Shell-Skript some_binary als SystemBinary auf dem Zielsystem im Verzeichnis für Benutzerprogramme abgelegt werden (standardmäßig /usr/bin).

3.10. Die Plugin-Datei zum Beispielszenario

Setzt man die bisher vorgestellten Teile zusammen — und komplettiert sie, dann sieht ein mögliches, vollständiges Plugin für das Beispielszenario so aus:

~/local/lib/check_mk/base/cee/plugins/bakery/hello_world.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Shebang only needed for editor!

import json
from pathlib import Path
from typing import Iterable, TypedDict, List

from .bakery_api.v1 import (
    OS,
    DebStep,
    RpmStep,
    SolStep,
    Plugin,
    PluginConfig,
    SystemBinary,
    Scriptlet,
    WindowsConfigEntry,
    register,
    FileGenerator,
    ScriptletGenerator,
    WindowsConfigGenerator,
    quote_shell_string,
)

class HelloWorldConfig(TypedDict, total=False):
    interval: float
    user: str
    content: str

def get_hello_world_plugin_files(conf: HelloWorldConfig) -> FileGenerator:
    interval = conf.get('interval')

    yield Plugin(
        base_os = OS.LINUX,
        source = Path('hello_world'),
        target = Path('hello_world'),
        interval = int(interval),
    )
    yield Plugin(
        base_os  =OS.SOLARIS,
        source = Path('hello_world.solaris.ksh'),
        target = Path('hello_world'),
        interval = int(interval),
    )
    yield Plugin(
        base_os = OS.WINDOWS,
        source = Path('hello_world.cmd'),
        target = Path('hello_world.bat'),
        interval = int(interval),
    )

    yield PluginConfig(
        base_os = OS.LINUX,
        lines = _get_linux_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.json'),
        include_header = False
    )
    yield PluginConfig(
        base_os = OS.SOLARIS,
        lines = _get_solaris_cfg_lines(conf['user'], conf['content']),
        target = Path('hello_world.cfg'),
        include_header = True
    )

    for base_os in [OS.LINUX, OS.SOLARIS]:
        yield SystemBinary(
            base_os = base_os,
            source = Path('some_binary'),
        )

def _get_linux_cfg_lines(user: str, content: str) -> List[str]:
    config = json.dumps({'user': user, 'content': content})
    return config.split('\n')

def _get_solaris_cfg_lines(user: str, content: str) -> List[str]:
    # To be loaded with 'source' in Solaris shell script
    return [
        f'USER={quote_shell_string(user)}',
        f'CONTENT={quote_shell_string(user)}',
    ]

def get_hello_world_scriptlets(conf: HelloWorldConfig) -> ScriptletGenerator:
    installed_lines = ['logger -p local3.info "Installed hello_world"']
    uninstalled_lines = ['logger -p local3.info "Uninstalled hello_world"']

    yield Scriptlet(step=DebStep.POSTINST, lines=installed_lines)
    yield Scriptlet(step=DebStep.POSTRM, lines=uninstalled_lines)
    yield Scriptlet(step=RpmStep.POST, lines=installed_lines)
    yield Scriptlet(step=RpmStep.POSTUN, lines=uninstalled_lines)
    yield Scriptlet(step=SolStep.POSTINSTALL, lines=installed_lines)
    yield Scriptlet(step=SolStep.POSTREMOVE, lines=uninstalled_lines)

def get_hello_world_windows_config(conf: HelloWorldConfig) -> WindowsConfigGenerator:
    yield WindowsConfigEntry(path=["hello_world", "user"], content=conf["user"])
    yield WindowsConfigEntry(path=["hello_world", "content"], content=conf["content"])

register.bakery_plugin(
    name = "hello_world",
    files_function = get_hello_world_plugin_files,
    scriptlets_function = get_hello_world_scriptlets,
    windows_config_function = get_hello_world_windows_config,
)

Dateiinhalt in die Zwischenablage kopieren

Dateiinhalt erfolgreich in die Zwischenablage kopiert!

Schreibzugriff auf die Zwischenablage wurde verweigert!

3.11. Dateien bereitstellen

Damit ein Bakery Plugin funktionieren kann, müssen alle beteiligten Dateien an die jeweils korrekten Stelle in der lokalen Struktur des Instanzverzeichnisses abgelegt bzw. geschrieben werden.

Dabei handelt es sich zum einen um die Plugin-Datei selbst und zum anderen um die von der files_function zurückgegebenen Objekte. Diese Objekte beschreiben entweder Konfigurationsdateien, die direkt vom Bakery Plugin erzeugt werden, oder sie beziehen sich auf Dateien, die richtig abgelegt werden müssen, damit sie beim Verpacken der Agentenpakete gefunden werden.

Objekte der Klassen Plugin und SystemBinary bezeichnen existierende Dateien, die abgelegt werden müssen. Die als PluginConfig und SystemConfig beschriebenen Dateien werden anhand des lines-Arguments erst noch generiert, daher müssen hier keine Dateien abgelegt werden.

Schließlich gehört zum Satz der Dateien auch die Regelsatzdatei zum Plugin.

Im nächsten und letzten Kapitel finden Sie die Zusammenstellung aller Verzeichnisse.

4. Dateien und Verzeichnisse

In den folgenden Verzeichnissen müssen Dateien für die Bereitstellung eines Bakery Plugins abgelegt werden. Wie immer sind alle Angaben hier relativ zum Instanzverzeichnis (z.B. /omd/sites/mysite).

Pfad Bedeutung

Pfad	Bedeutung
`~/local/lib/check_mk/base/cee/plugins/bakery/`	Verzeichnis für das Bakery Plugin (im Beispiel `hello_world.py`).
`~/local/share/check_mk/agents/plugins/`	Verzeichnis zur Ablage der Unix-artigen Agentenplugins.
`~/local/share/check_mk/agents/windows/plugins/`	Verzeichnis zur Ablage der Windows Agentenplugins.
`~/local/share/check_mk/agents/`	Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Unix-artige Betriebssysteme (im Beispiel `some_binary`).
`~/local/share/check_mk/agents/windows/`	Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Windows.
`~/local/lib/python3/cmk_addons/plugins/<family_name>/rulesets/`	Verzeichnis für die Regelsatzdateien zur Konfiguration des Agentenplugins (im Beispiel `ruleset_hello_world_bakery.py`) und auch des zugehörigen Check-Plugins (z.B. für die Festlegung von Schwellwerten). Wählen Sie daher aussagekräftige Namen, um die Dateien auseinanderhalten zu können. Namen hier abgelegter Dateien müssen mit `ruleset_` beginnen, andernfalls ignoriert Checkmk diese.

~/local/lib/check_mk/base/cee/plugins/bakery/

Verzeichnis für das Bakery Plugin (im Beispiel hello_world.py).

~/local/share/check_mk/agents/plugins/

Verzeichnis zur Ablage der Unix-artigen Agentenplugins.

~/local/share/check_mk/agents/windows/plugins/

Verzeichnis zur Ablage der Windows Agentenplugins.

~/local/share/check_mk/agents/

Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Unix-artige Betriebssysteme (im Beispiel some_binary).

~/local/share/check_mk/agents/windows/

Verzeichnis für mitgelieferte Programme oder Shell-Skripte für Windows.

~/local/lib/python3/cmk_addons/plugins/<family_name>/rulesets/

Verzeichnis für die Regelsatzdateien zur Konfiguration des Agentenplugins (im Beispiel ruleset_hello_world_bakery.py) und auch des zugehörigen Check-Plugins (z.B. für die Festlegung von Schwellwerten). Wählen Sie daher aussagekräftige Namen, um die Dateien auseinanderhalten zu können. Namen hier abgelegter Dateien müssen mit ruleset_ beginnen, andernfalls ignoriert Checkmk diese.

Letzte Änderung: Wed, 03 Dec 2025 14:35:51 GMT via Commit 26a55327