Update plugin documentation

2026-08-16 20:05:22 +02:00
1 parent 11ce8a4615
commit f3e3ff0282
@@ -1,178 +1,79 @@
-# Checkmk Plugins
+# 🔍 Checkmk Plugins
-Sammlung eigener Plugins und Erweiterungen für Checkmk.
+![Checkmk](https://img.shields.io/badge/Checkmk-2.5.x-15d1a0)
 ![Edition](https://img.shields.io/badge/Edition-Community-blue)
 ![Plugins](https://img.shields.io/badge/Plugins-2-informational)
-Dieses Repository enthält Checkmk-Erweiterungen, die für meine eigene Monitoring-Umgebung entwickelt und getestet werden. Die einzelnen Plugins werden jeweils mit Source-Code, Dokumentation und einem installierbaren MKP-Paket bereitgestellt.
+Sammlung eigener Plugins und Erweiterungen für **Checkmk Community 2.5.x**.
-## Umgebung
+## 📦 Verfügbare Plugins
-Die Plugins werden primär entwickelt und getestet mit:
+### 🔗 Remote Access
 Direkter SSH- und RDP-Zugriff aus der Checkmk-Weboberfläche. **Version:** `1.4.4`
- Checkmk Community Edition
+- 🐧 SSH für Linux-/Unix-Systeme
- Checkmk 2.5
+- 🪟 RDP für Windows
- Linux-Hosts
+- automatische Erkennung über Checkmk Host Labels
- Windows-Hosts
+- Integration in `Setup → Hosts` und Monitoring Views
- Checkmk Agent 2.5
+- eigene SSH-/RDP-Icons
-> Die Kompatibilität mit anderen Checkmk-Versionen oder der Enterprise Edition ist nicht grundsätzlich ausgeschlossen, wird aber nicht zwingend getestet.
+➡️ [Dokumentation](remote_access/README.md) · 📦 [MKP](remote_access/packages/remote_access-1.4.4.mkp)
---
+### 🖥️ OS Info
 Zeigt Betriebssysteminformationen als eigenen Checkmk-Service. **Version:** `1.0.0`
-## Verfügbare Plugins
+- 🐧 Linux · 🪟 Windows · 🍎 macOS
 - Betriebssystem / Distribution und Version
 - Windows-Build, Architektur und Kernel-Version
-### remote_access
+➡️ [Dokumentation](os-info/README.md) · 📦 [MKP](os-info/dist/os_info-1.0.0.mkp)
-Direkter SSH- und RDP-Zugriff auf überwachte Hosts aus der Checkmk-Weboberfläche.
+## 🛠️ Umgebung und Kompatibilität
-**Aktuelle Version:** `1.4.4`
+Primär entwickelt und getestet mit Checkmk Community Edition 2.5.x, Checkmk Agent 2.5 sowie Linux- und Windows-Hosts.
-#### Funktionen
+> Andere Checkmk-Versionen oder Editionen können funktionieren, werden aber nicht zwingend getestet.
- SSH-Zugriff auf Linux-/Unix-Hosts
+## 📂 Repository-Struktur
 - RDP-Zugriff auf Windows-Hosts
 - Automatische Betriebssystemerkennung über Checkmk Host Labels
 - Verwendung der von Checkmk ermittelten Host-IP
 - Integration in `Setup → Hosts`
 - Integration in Checkmk Monitoring Views
 - Eigene SSH- und RDP-Icons
 - Direkter SSH-Aufruf über `ssh://`
 - Direkter RDP-Aufruf über `rdpadmin://`
 Weitere Informationen:
 ```text
 remote_access/README.md
 ```
 Fertiges MKP:
 ```text
 remote_access/packages/remote_access-1.4.4.mkp
 ```
 ---
 ## Repository-Struktur
 ```text
 cmk-plugins/
 ├── README.md
 │
 ├── remote_access/
 │   ├── README.md
 │   ├── CHANGELOG.md
 │   ├── packages/
 │   │   └── remote_access-1.4.4.mkp
 │   └── src/
-│       └── local/
+└── os-info/
 │           └── share/
 │               └── check_mk/
 │
 └── weitere_plugins/
 ```
 Jedes Plugin erhält einen eigenen Ordner.
 Dabei wird grundsätzlich folgende Struktur verwendet:
 ```text
 plugin_name/
    ├── README.md
    ├── CHANGELOG.md
-├── packages/
+    ├── PROJECT.md
-│   └── plugin_name-VERSION.mkp
+    ├── LICENSE
    ├── dist/
    └── src/
    └── local/
        └── share/
            └── check_mk/
 ```
-## Installation von MKP-Paketen
+## 📥 Installation von MKP-Paketen
 Das gewünschte `.mkp`-Paket auf den Checkmk-Server übertragen.
 Anschließend als Checkmk-Site-Benutzer installieren:
 ```bash
 mkp add /pfad/zum/plugin.mkp
 ```
 Plugin aktivieren:
 ```bash
 mkp enable PLUGIN_NAME VERSION
 ```
-Beispiel für `remote_access`:
+Je nach Plugin anschließend `cmk -R` oder bei Web-Erweiterungen `omd restart apache`. Details stehen in der jeweiligen Plugin-README.
-```bash
+## 🏷️ Releases und Versionierung
 mkp add remote_access-1.4.4.mkp
 mkp enable remote_access 1.4.4
 ```
-Anschließend gegebenenfalls den Apache der Checkmk-Site neu starten:
+Plugins werden unabhängig versioniert. Git-Tags verwenden das Schema `PLUGIN_NAME-vVERSION`, z. B. `remote_access-v1.4.4` oder `os_info-v1.0.0`.
-```bash
+## ⚠️ Hinweise
 omd restart apache
 ```
-Installierte MKP-Pakete anzeigen:
+Vor dem produktiven Einsatz sollte jede Erweiterung zunächst in einer Testumgebung geprüft werden.
-```bash
+## 👤 Autor
 mkp list
 ```
-## Releases und Versionierung
+Domenik Bildhauer
-Die Plugins werden unabhängig voneinander versioniert.
+## ⚖️ Lizenz
-Git-Tags verwenden deshalb folgendes Schema:
+Die Lizenz ist im jeweiligen Plugin dokumentiert. Checkmk ist eine Marke der Checkmk GmbH.
 ```text
 PLUGIN_NAME-vVERSION
 ```
 Beispiele:
 ```text
 remote_access-v1.4.4
 os_info-v1.0.0
 ```
 Dadurch können mehrere Plugins mit unterschiedlichen Versionsständen innerhalb desselben Git-Repositories verwaltet werden.
 Fertige MKP-Pakete werden zusätzlich als Download beim jeweiligen Gitea Release bereitgestellt.
 ## Entwicklung
 Der eigentliche Checkmk-Source-Code eines Plugins befindet sich unter:
 ```text
 PLUGIN_NAME/src/
 ```
 Die Verzeichnisstruktur unterhalb von `src/` entspricht dabei möglichst der späteren Struktur innerhalb der Checkmk-Site.
 Beispiel:
 ```text
 src/local/share/check_mk/web/plugins/
 ```
 Dadurch lässt sich direkt erkennen, an welcher Stelle die jeweilige Datei auf dem Checkmk-Server installiert wird.
 ## Hinweise
 Die Plugins wurden primär für meine eigene Checkmk-Umgebung entwickelt.
 Vor dem Einsatz in produktiven Umgebungen sollte die jeweilige Erweiterung in einer Testumgebung geprüft werden.
 ## Autor
 **Domenik Bildhauer**
 ## Lizenz
 Sofern im jeweiligen Plugin keine abweichende Lizenz angegeben ist, handelt es sich um eigene Erweiterungen für Checkmk.
 Checkmk ist eine Marke der Checkmk GmbH.
@@ -1,161 +1,102 @@
-# Checkmk OS Info
+# 🖥️ Checkmk OS Info
-MKP-Erweiterung für **Checkmk Community 2.5.x**, die auf überwachten Hosts einen eigenen Service **„Betriebssystem“** bereitstellt.
+![Version](https://img.shields.io/badge/Version-1.0.0-blue)
 ![Checkmk](https://img.shields.io/badge/Checkmk-2.5.x-15d1a0)
 ![API](https://img.shields.io/badge/Check%20API-V2-informational)
 ![License](https://img.shields.io/badge/License-GPL--2.0-lightgrey)
-## Funktionen
+MKP-Erweiterung für **Checkmk Community 2.5.x**, die pro überwachten Host einen Service **„Betriebssystem“** bereitstellt.
-Der Service zeigt unter anderem:
+⬅️ [Zurück zur Plugin-Übersicht](../README.md)
 ## ✨ Funktionen
 - Betriebssystem bzw. Linux-Distribution
 - Betriebssystem-Version / Windows-Build
- Architektur
+- Architektur und Kernel-Version
 - Kernel-Version
 - OS-ID und Version-ID
 - 🐧 Linux · 🪟 Windows · 🍎 macOS
-Unterstützt werden Linux, Windows und grundsätzlich auch macOS.
+## 📥 Installation des MKP
-## Repository-Struktur
+Paket: `dist/os_info-1.0.0.mkp`
 ```text
 checkmk-os-info/
 ├── src/
 │   ├── agents/
 │   │   ├── plugins/
 │   │   │   └── os_info
 │   │   └── windows/
 │   │       └── plugins/
 │   │           └── os_info.ps1
 │   └── cmk_addons_plugins/
 │       └── os_info/
 │           ├── agent_based/
 │           │   └── os_info.py
 │           └── checkman/
 │               └── os_info
 ├── dist/
 │   └── os_info-1.0.0.mkp
 ├── CHANGELOG.md
 ├── LICENSE
 └── README.md
 ```
 ## Installation des MKP
 Das fertige Paket befindet sich unter:
 ```text
 dist/os_info-1.0.0.mkp
 ```
 Auf den Checkmk-Server kopieren und als Site-Benutzer installieren:
 ```bash
 mkp add /tmp/os_info-1.0.0.mkp
 mkp enable os_info 1.0.0
 cmk -R
 ```
 Kontrolle:
 ```bash
 mkp list
 ```
-Der Eintrag `os_info` sollte als `Enabled (active on this site)` erscheinen.
+## 🐧 Agent-Plug-in für Linux / macOS
-## Agent-Plug-in für Linux/macOS
+Nach Aktivierung:
 Nach Aktivierung des MKP liegt das Plug-in im lokalen Site-Verzeichnis:
 ```text
 ~/local/share/check_mk/agents/plugins/os_info
 ```
-Auf den Zielhost kopieren:
+Auf den Zielhost kopieren und testen:
 ```bash
 scp ~/local/share/check_mk/agents/plugins/os_info \
 root@HOST:/usr/lib/check_mk_agent/plugins/os_info
 ```
 Danach auf dem Zielhost:
 ```bash
 scp ~/local/share/check_mk/agents/plugins/os_info root@HOST:/usr/lib/check_mk_agent/plugins/os_info
 chmod 755 /usr/lib/check_mk_agent/plugins/os_info
 /usr/lib/check_mk_agent/plugins/os_info
 ```
-Die Ausgabe muss mit folgender Sektion beginnen:
+Die Ausgabe muss mit `<<<os_info:sep(9)>>>` beginnen.
-```text
+## 🪟 Agent-Plug-in für Windows
 <<<os_info:sep(9)>>>
 ```
-## Agent-Plug-in für Windows
+Quelldatei:
 Nach Aktivierung liegt die PowerShell-Datei auf dem Checkmk-Server unter:
 ```text
 ~/local/share/check_mk/agents/windows/plugins/os_info.ps1
 ```
-Auf dem Windows-Host nach folgendem Verzeichnis kopieren:
+Ziel:
 ```text
 C:\ProgramData\checkmk\agent\plugins\os_info.ps1
 ```
-## Service Discovery
+## 🔎 Service Discovery
 Auf dem Checkmk-Server zunächst prüfen, ob die Agent-Sektion ankommt:
 ```bash
 cmk -d HOSTNAME | grep -A2 '^<<<os_info'
 ```
 Danach die Service-Erkennung ausführen:
 ```bash
 cmk -vI HOSTNAME
 cmk -R
 ```
-Anschließend erscheint beim Host der Service:
+Anschließend erscheint der Service **Betriebssystem**.
-```text
+## 🧰 Fehlersuche
 Betriebssystem
 ```
 ## Fehlersuche
 Installierte Dateien des MKP suchen:
 ```bash
 find ~/local -type f -name 'os_info*'
 ```
 Status des Pakets:
 ```bash
 mkp list
 ```
 Agent-Ausgabe kontrollieren:
 ```bash
 cmk -d HOSTNAME | grep -A2 '^<<<os_info'
 ```
-## Kompatibilität
+## 📂 Repository-Struktur
-Entwickelt für:
+```text
 os-info/
 ├── src/
 │   ├── agents/
 │   └── cmk_addons_plugins/os_info/
 ├── dist/
 │   └── os_info-1.0.0.mkp
 ├── CHANGELOG.md
 ├── PROJECT.md
 ├── LICENSE
 └── README.md
 ```
- Checkmk Community 2.5.x
+## 🛠️ Kompatibilität
 - Check API V2
 - Linux-Agent
 - Windows-Agent
-Aktuelle Paketversion: **1.0.0**
+Checkmk Community 2.5.x · Check API V2 · Linux-Agent · Windows-Agent · macOS grundsätzlich unterstützt
-## Lizenz
+## ⚖️ Lizenz
 GPL-2.0
@@ -1,240 +1,78 @@
-# Checkmk Remote Access
+# 🔗 Checkmk Remote Access
-Direkter SSH- und RDP-Zugriff auf überwachte Hosts aus der Checkmk-Weboberfläche.
+![Version](https://img.shields.io/badge/Version-1.4.4-blue)
 ![Checkmk](https://img.shields.io/badge/Checkmk-Community%202.5-15d1a0)
 ![SSH](https://img.shields.io/badge/Access-SSH-informational)
 ![RDP](https://img.shields.io/badge/Access-RDP-informational)
-**Aktuelle Version:** 1.4.4  
+Direkter **SSH- und RDP-Zugriff** auf überwachte Hosts aus der Checkmk-Weboberfläche.
 **Autor:** Domenik Bildhauer  
 **Zielplattform:** Checkmk Community 2.5
-## Funktionen
+**Version:** `1.4.4` · **Autor:** Domenik Bildhauer · **Zielplattform:** Checkmk Community 2.5
-Das Plugin erweitert Checkmk um Remote-Access-Funktionen für Linux-/Unix- und Windows-Hosts.
+⬅️ [Zurück zur Plugin-Übersicht](../README.md)
-### Linux / Unix
+## ✨ Funktionen
-Für Linux- und Unix-Systeme wird automatisch ein SSH-Zugriff angeboten.
+### 🐧 Linux / Unix
-Beispiel:
+Automatischer SSH-Zugriff, z. B. `ssh://192.168.188.125`. Unterstützt werden Linux, Unix, FreeBSD, OpenBSD, Solaris und AIX.
-```text
+### 🪟 Windows
 ssh://192.168.188.125
 ```
-Unterstützte Betriebssystemfamilien:
+RDP über `rdpadmin://192.168.188.122`. Der eigene Windows Protocol Handler startet anschließend `mstsc.exe`.
- Linux
+## 🔌 Checkmk-Integration
 - Unix
 - FreeBSD
 - OpenBSD
 - Solaris
 - AIX
-### Windows
+In `Setup → Hosts` erscheinen abhängig vom Betriebssystem SSH- bzw. RDP-Aktionen. Zusätzlich werden die Aktionen in die Icons-Spalte der Monitoring Views integriert.
-Für Windows-Systeme wird ein RDP-Zugriff angeboten.
+## 🔎 Automatische Betriebssystemerkennung
-Beispiel:
+Die Auswahl von SSH oder RDP erfolgt anhand der Checkmk Host Labels, insbesondere `cmk/os_family`. Als Ziel wird bevorzugt `host_address` verwendet.
-```text
+## 📥 Installation
 rdpadmin://192.168.188.122
 ```
-`rdpadmin://` verwendet einen eigenen Windows Protocol Handler, der anschließend den Microsoft Remote Desktop Client (`mstsc.exe`) startet.
+Paket: `packages/remote_access-1.4.4.mkp`
 ## Checkmk-Integration
 ### Setup → Hosts
 In der Checkmk-Hostverwaltung werden abhängig vom Betriebssystem zusätzliche Remote-Access-Aktionen angezeigt:
 - SSH-Icon für Linux-/Unix-Systeme
 - RDP-Icon für Windows-Systeme
 - `Open SSH ↗`
 - `Open RDP ↗`
 ### Monitoring
 Das Plugin integriert SSH und RDP zusätzlich in die Icons-Spalte der Checkmk Monitoring Views.
 Bei einem Linux-Host kann dadurch beispielsweise direkt aus einer Service-Problemansicht eine SSH-Verbindung gestartet werden.
 ## Automatische Betriebssystemerkennung
 Die Entscheidung zwischen SSH und RDP erfolgt anhand der von Checkmk ermittelten Host-Labels.
 Beispiel Linux:
 ```text
 cmk/os_family: linux
 cmk/os_platform: ubuntu
 cmk/os_name: Ubuntu
 cmk/os_version: 22.04
 ```
 Beispiel Windows:
 ```text
 cmk/os_family: windows
 ```
 Als Ziel für die Verbindung verwendet das Plugin bevorzugt `host_address`.
 Beispiel:
 ```text
 Host:
 test-ssh.bildhauerd.com
 Adresse:
 192.168.188.125
 OS-Familie:
 linux
 ```
 Daraus entsteht:
 ```text
 ssh://192.168.188.125
 ```
 ## Installation
 Das fertige MKP befindet sich unter:
 ```text
 packages/remote_access-1.4.4.mkp
 ```
 Das Paket auf den Checkmk-Server kopieren und als Site-Benutzer installieren:
 ```bash
 mkp add /pfad/zu/remote_access-1.4.4.mkp
 mkp enable remote_access 1.4.4
 ```
 Danach den Apache der Checkmk-Site neu starten:
 ```bash
 omd restart apache
 ```
 Installation kontrollieren:
 ```bash
 mkp list
 ```
-## Upgrade
+## ⬆️ Upgrade
 Eine vorherige Version zunächst deaktivieren, beispielsweise:
 ```bash
 mkp disable remote_access 1.4.3
 ```
 Danach die neue Version installieren und aktivieren:
 ```bash
 mkp add /pfad/zu/remote_access-1.4.4.mkp
 mkp enable remote_access 1.4.4
 omd restart apache
 ```
-Anschließend im Browser einen Hard-Reload durchführen.
+Danach gegebenenfalls einen Hard-Reload im Browser durchführen.
-## Source-Code
+## 🧑‍💻 Source-Code
 Der Source-Code befindet sich unter:
 ```text
 src/local/share/check_mk/
 ```
 Wichtige Dateien:
 ```text
 src/local/share/check_mk/web/plugins/wato/remote_access_setup.py
 src/local/share/check_mk/web/plugins/views/remote_access_views.py
 src/local/share/check_mk/web/htdocs/images/icons/remote_access_ssh.svg
 src/local/share/check_mk/web/htdocs/images/icons/remote_access_rdp.svg
 ```
-### remote_access_setup.py
+## 🖥️ Windows SSH / RDP
-Integration der Remote-Access-Funktionen in:
+Für `ssh://` muss unter Windows ein geeigneter SSH-Client zugeordnet sein; getestet wurde PuTTY. Für RDP startet der `rdpadmin://`-Handler `mstsc.exe`, ohne `.rdp`-Dateien herunterzuladen.
-```text
+## 🧰 Fehlerdiagnose
 Setup → Hosts
 ```
 ### remote_access_views.py
 Integration der Remote-Access-Icons in die Checkmk Monitoring Views.
 Die Registrierung erfolgt über Checkmks Legacy-Web-Plugin-Schnittstelle:
 ```python
 multisite_icons_and_actions
 ```
 ## Windows SSH
 Damit ein Klick auf `ssh://` unter Windows funktioniert, muss das Protokoll einem geeigneten SSH-Client zugeordnet sein.
 Getestet wurde die Verbindung mit PuTTY.
 Ein direkter Aufruf funktioniert beispielsweise mit:
 ```text
 putty.exe 192.168.188.125
 ```
 ## Windows RDP
 Für RDP wird das benutzerdefinierte Protokoll
 ```text
 rdpadmin://
 ```
 verwendet.
 Beispiel:
 ```text
 rdpadmin://192.168.188.122
 ```
 Der auf dem Windows-Client installierte Protocol Handler startet anschließend `mstsc.exe`.
 Dadurch müssen keine `.rdp`-Dateien heruntergeladen werden.
 ## Fehlerdiagnose
 Checkmk Web-Log:
 ```bash
 tail -n 50 ~/var/log/web.log
 ```
 Log vor einem Test leeren:
 ```bash
 : > ~/var/log/web.log
 omd restart apache
 ```
-Danach die betreffende Seite neu laden und prüfen:
+## ✅ Status 1.4.4
 ```bash
 cat ~/var/log/web.log
 ```
 ## Status 1.4.4
 | Funktion | Status |
 |---|---|
@@ -247,7 +85,7 @@ cat ~/var/log/web.log
 | Verwendung der Host-IP | ✅ |
 | RDP aus Monitoring-Problemansicht | ⏳ Noch abschließend zu testen |
-## Repository-Struktur
+## 📂 Repository-Struktur
 ```text
 remote_access/
@@ -256,24 +94,9 @@ remote_access/
 ├── packages/
 │   └── remote_access-1.4.4.mkp
 └── src/
-    └── local/
+    └── local/share/check_mk/
        └── share/
            └── check_mk/
                └── web/
                    ├── plugins/
                    │   ├── wato/
                    │   │   └── remote_access_setup.py
                    │   └── views/
                    │       └── remote_access_views.py
                    └── htdocs/
                        └── images/
                            └── icons/
                                ├── remote_access_ssh.svg
                                └── remote_access_rdp.svg
 ```
-## Lizenz
+## ⚖️ Lizenz
-Dieses Plugin wurde für den Einsatz mit Checkmk Community entwickelt.
+Dieses Plugin wurde für den Einsatz mit Checkmk Community entwickelt. Checkmk ist eine Marke der Checkmk GmbH.
 Checkmk ist eine Marke der Checkmk GmbH.