Update README design and documentation

2026-08-16 20:28:28 +02:00
1 parent f3e3ff0282
commit 3148acc2df
@@ -6,33 +6,64 @@

 Sammlung eigener Plugins und Erweiterungen für **Checkmk Community 2.5.x**.

+Die Erweiterungen werden für die eigene Monitoring-Umgebung entwickelt und getestet. Jedes Plugin besitzt einen eigenen Ordner mit Dokumentation, Source-Code und installierbarem MKP-Paket.
+
 ## 📦 Verfügbare Plugins

 ### 🔗 Remote Access
-Direkter SSH- und RDP-Zugriff aus der Checkmk-Weboberfläche. **Version:** `1.4.4`

- 🐧 SSH für Linux-/Unix-Systeme
- 🪟 RDP für Windows
- automatische Erkennung über Checkmk Host Labels
- Integration in `Setup → Hosts` und Monitoring Views
- eigene SSH-/RDP-Icons
+Direkter SSH- und RDP-Zugriff auf überwachte Hosts aus der Checkmk-Weboberfläche.

-➡️ [Dokumentation](remote_access/README.md) · 📦 [MKP](remote_access/packages/remote_access-1.4.4.mkp)
+**Aktuelle Version:** `1.4.4`
+
+<p>
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/linux.svg" width="22" height="22" alt="Linux"> SSH für Linux-/Unix-Systeme&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="22" height="22" alt="Windows"> RDP für Windows-Systeme
+</p>
+
+- 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://`
+
+➡️ [Dokumentation](remote_access/README.md)  
+📦 [MKP-Paket](remote_access/packages/remote_access-1.4.4.mkp)

 ### 🖥️ OS Info
-Zeigt Betriebssysteminformationen als eigenen Checkmk-Service. **Version:** `1.0.0`

- 🐧 Linux · 🪟 Windows · 🍎 macOS
- Betriebssystem / Distribution und Version
- Windows-Build, Architektur und Kernel-Version
+Zeigt Betriebssysteminformationen eines überwachten Hosts als eigenen Checkmk-Service an.

-➡️ [Dokumentation](os-info/README.md) · 📦 [MKP](os-info/dist/os_info-1.0.0.mkp)
+**Aktuelle Version:** `1.0.0`
+
+<p>
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/linux.svg" width="24" height="24" alt="Linux"> <strong>Linux</strong>&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> <strong>Windows</strong>&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/apple.svg" width="24" height="24" alt="macOS"> <strong>macOS</strong>
+</p>
+
+- Betriebssystem bzw. Distribution
+- Version / Windows-Build
+- Architektur
+- Kernel-Version
+- OS-ID und Version-ID
+
+➡️ [Dokumentation](os-info/README.md)  
+📦 [MKP-Paket](os-info/dist/os_info-1.0.0.mkp)

 ## 🛠️ Umgebung und Kompatibilität

-Primär entwickelt und getestet mit Checkmk Community Edition 2.5.x, Checkmk Agent 2.5 sowie Linux- und Windows-Hosts.
+Primär entwickelt und getestet mit:

-> Andere Checkmk-Versionen oder Editionen können funktionieren, werden aber nicht zwingend getestet.
+- Checkmk Community Edition
+- Checkmk 2.5.x
+- Checkmk Agent 2.5
+- Linux-Hosts
+- Windows-Hosts
+
+> Die Kompatibilität mit anderen Checkmk-Versionen oder Editionen ist nicht grundsätzlich ausgeschlossen, wird aber nicht zwingend getestet.

 ## 📂 Repository-Struktur

@@ -53,22 +84,59 @@ cmk-plugins/
    └── src/
 ```

+Jedes Plugin wird unabhängig versioniert und dokumentiert.
+
 ## 📥 Installation von MKP-Paketen

+Das gewünschte `.mkp`-Paket auf den Checkmk-Server übertragen und als Site-Benutzer installieren:
+
 ```bash
 mkp add /pfad/zum/plugin.mkp
 mkp enable PLUGIN_NAME VERSION
 ```

-Je nach Plugin anschließend `cmk -R` oder bei Web-Erweiterungen `omd restart apache`. Details stehen in der jeweiligen Plugin-README.
+Je nach Plugin anschließend beispielsweise:
+
+```bash
+cmk -R
+```
+
+oder bei Web-Erweiterungen:
+
+```bash
+omd restart apache
+```
+
+Installierte Pakete anzeigen:
+
+```bash
+mkp list
+```
+
+Die plugin-spezifischen Installationsschritte stehen in der jeweiligen README.

 ## 🏷️ Releases und Versionierung

-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`.
+Die Plugins werden unabhängig voneinander versioniert. Git-Tags verwenden das Schema:
+
+```text
+PLUGIN_NAME-vVERSION
+```
+
+Beispiele:
+
+```text
+remote_access-v1.4.4
+os_info-v1.0.0
+```
+
+## 🧑‍💻 Entwicklung
+
+Der Source-Code befindet sich im jeweiligen Plugin-Verzeichnis unter `src/`. Die Verzeichnisstruktur orientiert sich möglichst an der späteren Struktur innerhalb der Checkmk-Site.

 ## ⚠️ Hinweise

-Vor dem produktiven Einsatz sollte jede Erweiterung zunächst in einer Testumgebung geprüft werden.
+Die Plugins wurden primär für die eigene Checkmk-Umgebung entwickelt. Vor dem Einsatz in produktiven Umgebungen sollte die jeweilige Erweiterung zunächst in einer Testumgebung geprüft werden.

 ## 👤 Autor

@@ -5,56 +5,104 @@
 ![API](https://img.shields.io/badge/Check%20API-V2-informational)
 ![License](https://img.shields.io/badge/License-GPL--2.0-lightgrey)

-MKP-Erweiterung für **Checkmk Community 2.5.x**, die pro überwachten Host einen Service **„Betriebssystem“** bereitstellt.
+MKP-Erweiterung für **Checkmk Community 2.5.x**, die auf überwachten Hosts einen eigenen Service **„Betriebssystem“** bereitstellt.

 ⬅️ [Zurück zur Plugin-Übersicht](../README.md)

 ## ✨ Funktionen

+Der Service zeigt:
+
 - Betriebssystem bzw. Linux-Distribution
 - Betriebssystem-Version / Windows-Build
- Architektur und Kernel-Version
+- Architektur
+- Kernel-Version
 - OS-ID und Version-ID
- 🐧 Linux · 🪟 Windows · 🍎 macOS
+
+### Unterstützte Plattformen
+
+<p>
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/linux.svg" width="24" height="24" alt="Linux"> <strong>Linux</strong>&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> <strong>Windows</strong>&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/apple.svg" width="24" height="24" alt="macOS"> <strong>macOS</strong>
+</p>
+
+## 📂 Repository-Struktur
+
+```text
+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
+├── PROJECT.md
+├── LICENSE
+└── README.md
+```

 ## 📥 Installation des MKP

-Paket: `dist/os_info-1.0.0.mkp`
+Das fertige Paket befindet sich unter `dist/os_info-1.0.0.mkp`.

 ```bash
 mkp add /tmp/os_info-1.0.0.mkp
 mkp enable os_info 1.0.0
 cmk -R
+```
+
+Kontrolle:
+
+```bash
 mkp list
 ```

-## 🐧 Agent-Plug-in für Linux / macOS
+Der Eintrag `os_info` sollte als `Enabled (active on this site)` erscheinen.

-Nach Aktivierung:
+## <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/linux.svg" width="24" height="24" alt="Linux"> Agent-Plug-in für Linux / macOS
+
+Nach Aktivierung des MKP liegt das Plug-in unter:

 ```text
 ~/local/share/check_mk/agents/plugins/os_info
 ```

-Auf den Zielhost kopieren und testen:
+Auf den Zielhost kopieren:
+
+```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 `<<<os_info:sep(9)>>>` beginnen.

-## 🪟 Agent-Plug-in für Windows
+## <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> Agent-Plug-in für Windows

-Quelldatei:
+Quelldatei auf dem Checkmk-Server:

 ```text
 ~/local/share/check_mk/agents/windows/plugins/os_info.ps1
 ```

-Ziel:
+Ziel auf dem Windows-Host:

 ```text
 C:\ProgramData\checkmk\agent\plugins\os_info.ps1
@@ -68,7 +116,7 @@ cmk -vI HOSTNAME
 cmk -R
 ```

-Anschließend erscheint der Service **Betriebssystem**.
+Anschließend erscheint beim Host der Service **Betriebssystem**.

 ## 🧰 Fehlersuche

@@ -78,24 +126,15 @@ mkp list
 cmk -d HOSTNAME | grep -A2 '^<<<os_info'
 ```

-## 📂 Repository-Struktur
-
-```text
-os-info/
-├── src/
-│   ├── agents/
-│   └── cmk_addons_plugins/os_info/
-├── dist/
-│   └── os_info-1.0.0.mkp
-├── CHANGELOG.md
-├── PROJECT.md
-├── LICENSE
-└── README.md
-```
-
 ## 🛠️ Kompatibilität

-Checkmk Community 2.5.x · Check API V2 · Linux-Agent · Windows-Agent · macOS grundsätzlich unterstützt
+- Checkmk Community 2.5.x
+- Check API V2
+- Linux-Agent
+- Windows-Agent
+- macOS grundsätzlich unterstützt
+
+**Aktuelle Paketversion:** `1.0.0`

 ## ⚖️ Lizenz

@@ -13,21 +13,58 @@ Direkter **SSH- und RDP-Zugriff** auf überwachte Hosts aus der Checkmk-Weboberf

 ## ✨ Funktionen

-### 🐧 Linux / Unix
+Das Plugin erweitert Checkmk um Remote-Access-Funktionen für Linux-/Unix- und Windows-Hosts.

-Automatischer SSH-Zugriff, z. B. `ssh://192.168.188.125`. Unterstützt werden Linux, Unix, FreeBSD, OpenBSD, Solaris und AIX.
+### <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/linux.svg" width="24" height="24" alt="Linux"> Linux / Unix

-### 🪟 Windows
+Für Linux- und Unix-Systeme wird automatisch ein SSH-Zugriff angeboten:

-RDP über `rdpadmin://192.168.188.122`. Der eigene Windows Protocol Handler startet anschließend `mstsc.exe`.
+```text
+ssh://192.168.188.125
+```
+
+Unterstützt werden Linux, Unix, FreeBSD, OpenBSD, Solaris und AIX.
+
+### <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> Windows
+
+Für Windows-Systeme wird ein RDP-Zugriff angeboten:
+
+```text
+rdpadmin://192.168.188.122
+```
+
+`rdpadmin://` verwendet einen eigenen Windows Protocol Handler, der `mstsc.exe` startet.

 ## 🔌 Checkmk-Integration

-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.
+### Setup → Hosts
+
+Abhängig vom Betriebssystem werden ein SSH- bzw. RDP-Icon sowie `Open SSH ↗` oder `Open RDP ↗` angezeigt.
+
+### Monitoring
+
+SSH und RDP werden zusätzlich in die Icons-Spalte der Checkmk Monitoring Views integriert.

 ## 🔎 Automatische Betriebssystemerkennung

-Die Auswahl von SSH oder RDP erfolgt anhand der Checkmk Host Labels, insbesondere `cmk/os_family`. Als Ziel wird bevorzugt `host_address` verwendet.
+Die Entscheidung zwischen SSH und RDP erfolgt anhand der von Checkmk ermittelten Host-Labels.
+
+Linux:
+
+```text
+cmk/os_family: linux
+cmk/os_platform: ubuntu
+cmk/os_name: Ubuntu
+cmk/os_version: 22.04
+```
+
+Windows:
+
+```text
+cmk/os_family: windows
+```
+
+Als Ziel verwendet das Plugin bevorzugt `host_address`.

 ## 📥 Installation

@@ -49,7 +86,7 @@ mkp enable remote_access 1.4.4
 omd restart apache
 ```

-Danach gegebenenfalls einen Hard-Reload im Browser durchführen.
+Anschließend im Browser gegebenenfalls einen Hard-Reload durchführen.

 ## 🧑‍💻 Source-Code

@@ -60,9 +97,27 @@ 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
 ```

-## 🖥️ Windows SSH / RDP
+`remote_access_setup.py` integriert die Funktionen in `Setup → Hosts`.

-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.
+`remote_access_views.py` integriert die Remote-Access-Icons in die Monitoring Views über `multisite_icons_and_actions`.
+
+## <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> Windows SSH
+
+Damit `ssh://` unter Windows funktioniert, muss das Protokoll einem geeigneten SSH-Client zugeordnet sein. Getestet wurde PuTTY.
+
+```text
+putty.exe 192.168.188.125
+```
+
+## <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/windows.svg" width="24" height="24" alt="Windows"> Windows RDP
+
+Für RDP wird `rdpadmin://` verwendet:
+
+```text
+rdpadmin://192.168.188.122
+```
+
+Der Protocol Handler startet `mstsc.exe`; dadurch müssen keine `.rdp`-Dateien heruntergeladen werden.

 ## 🧰 Fehlerdiagnose

@@ -70,6 +125,7 @@ Für `ssh://` muss unter Windows ein geeigneter SSH-Client zugeordnet sein; gete
 tail -n 50 ~/var/log/web.log
 : > ~/var/log/web.log
 omd restart apache
+cat ~/var/log/web.log
 ```

 ## ✅ Status 1.4.4
@@ -99,4 +155,6 @@ remote_access/

 ## ⚖️ Lizenz

-Dieses Plugin wurde für den Einsatz mit Checkmk Community entwickelt. Checkmk ist eine Marke der Checkmk GmbH.
+Dieses Plugin wurde für den Einsatz mit Checkmk Community entwickelt.
+
+Checkmk ist eine Marke der Checkmk GmbH.