Checkmk/TSM/README.md

# TSM Backup Monitoring für CheckMK

Ein vollständiges CheckMK-Plugin zur Überwachung von IBM Spectrum Protect (TSM) Backups mit intelligenter Backup-Typ-Erkennung, umfassenden Labels und flexiblen Schwellwerten.

## 📋 Inhaltsverzeichnis

- [Features](#features)
- [Anforderungen](#anforderungen)
- [Installation](#installation)
- [Konfiguration](#konfiguration)
- [Verwendung](#verwendung)
- [Architektur](#architektur)
- [Troubleshooting](#troubleshooting)
- [Changelog](#changelog)

---

## ✨ Features

### Kernfunktionen
- **Umfassende Backup-Typ-Erkennung**: Unterstützung für 18+ Backup-Typen
- **Flexible Labels**: Umfassende Service-Labels für erweiterte Filterung und Reporting
- **Typ-spezifische Schwellwerte**: Individuelle Warn- und Kritisch-Schwellen für verschiedene Backup-Typen
- **Redundanz-Support**: Normalisierung von RRZ*/NFRZ* Node-Namen
- **Aggregierte Überwachung**: Pro-Node-Aggregierung mehrerer Backup-Jobs
- **Intelligentes Error-Handling**: Tolerantes vs. striktes Verhalten je nach Backup-Typ

### Unterstützte Backup-Typen

#### Datenbanken (strikte Überwachung)
- MSSQL (26h/48h)
- SAP HANA (26h/48h)
- Oracle (26h/48h)
- DB2 (26h/48h)
- MySQL/MariaDB (26h/48h)
- PostgreSQL (26h/48h)
- Sybase (26h/48h)
- MongoDB (26h/48h)

#### Dateisysteme (tolerante Überwachung)
- FILE (36h/72h)
- SCALE (36h/72h)
- DM (36h/72h)
- Datacenter (36h/72h)

#### Virtualisierung (tolerante Überwachung)
- Virtual/VMware (36h/72h)
- Hyper-V (36h/72h)

#### Applikationen
- Mail/Exchange (26h/48h)
- Transaction Logs (4h/8h)

---

## 🔧 Anforderungen

### CheckMK Server
- CheckMK Version: **2.3.0p40** oder höher
- Python 3.8+
- Zugriff auf `/omd/sites/<site>/local/lib/python3/cmk_addons/`

### Überwachte Hosts
- Python 3.6+
- Lesezugriff auf TSM CSV-Export-Verzeichnis
- CheckMK Agent installiert

### TSM Server
- CSV-Export der Backup-Statistiken
- Export-Format: `YYYY-MM-DD HH:MM:SS,<field>,NODE_NAME,SCHEDULE,STATUS`

---

## 📦 Installation

### Schritt 1: Agent-Plugin installieren

Das Agent-Plugin muss auf **jedem Host** installiert werden, der TSM-Backups überwachen soll.

```bash
# Als root auf dem überwachten Host
cd /usr/lib/check_mk_agent/plugins

# Plugin herunterladen oder kopieren
wget https://your-repo/tsm_backups_agent.py -O tsm_backups
# ODER
scp user@server:tsm_backups_agent.py /usr/lib/check_mk_agent/plugins/tsm_backups

# Ausführbar machen
chmod +x /usr/lib/check_mk_agent/plugins/tsm_backups

# Test
./tsm_backups
```

**Erwartete Ausgabe:**
```
<<<tsm_backups:sep(0)>>>
{"SERVER_MSSQL": {"statuses": ["Completed"], "schedules": ["DAILY_FULL"], "last": 1736693420, "count": 1}, ...}
```

### Schritt 2: CSV-Verzeichnis vorbereiten

```bash
# CSV-Verzeichnis erstellen
mkdir -p /mnt/CMK_TSM
chmod 755 /mnt/CMK_TSM

# TSM-CSV-Dateien bereitstellen
# Option A: NFS-Mount vom TSM Server
mount -t nfs tsm-server:/exports/backup-stats /mnt/CMK_TSM

# Option B: Regelmäßiger SCP/Rsync
# Crontab-Eintrag:
*/15 * * * * rsync -az tsm-server:/path/to/*.CSV /mnt/CMK_TSM/
```

**Erwartete CSV-Struktur:**
```
/mnt/CMK_TSM/
├── TSM_BACKUP_SCHED_24H.CSV
├── TSM_DB_SCHED_24H.CSV
└── TSM_FILE_SCHED_24H.CSV
```

### Schritt 3: Check-Plugin installieren

Das Check-Plugin wird auf dem **CheckMK Server** installiert.

```bash
# Als Site-User
OM=/omd/sites/monitoring
cd $OM

# Plugin-Verzeichnis erstellen
mkdir -p local/lib/python3/cmk_addons/plugins/tsm/agent_based

# Plugin kopieren
cp tsm_backups.py local/lib/python3/cmk_addons/plugins/tsm/agent_based/

# Rechte setzen
chmod 644 local/lib/python3/cmk_addons/plugins/tsm/agent_based/tsm_backups.py

# CheckMK Cache leeren
cmk -R
```

### Schritt 4: Service Discovery

```bash
# Service Discovery für einen Host
cmk -II hostname

# Bulk Discovery für alle Hosts
cmk -II --all

# WebUI: Setup > Hosts > <Host> > Service Discovery > Full Scan
```

---

## ⚙️ Konfiguration

### Schwellwerte anpassen

Die Schwellwerte können direkt im Check-Plugin angepasst werden:

**Datei:** `local/lib/python3/cmk_addons/plugins/tsm/agent_based/tsm_backups.py`

```python
THRESHOLDS = {
    "log": {"warn": 4 * 3600, "crit": 8 * 3600},      # 4h/8h
    "mssql": {"warn": 26 * 3600, "crit": 48 * 3600},  # 26h/48h
    # ... weitere Typen ...
    "default": {"warn": 26 * 3600, "crit": 48 * 3600},
}
```

### Neue Backup-Typen hinzufügen

**Szenario:** Ein neuer Typ "SAPASE" soll unterstützt werden.

**Schritt 1: Typ zur known_types Liste hinzufügen**

```python
# In extract_backup_type() Funktion
known_types = [
    'MSSQL', 'HANA', 'FILE', 'ORACLE', 'DB2', 'SCALE', 'DM',
    'DATACENTER', 'VIRTUAL', 'MAIL', 'MYSQL', 'POSTGRES', 
    'MARIADB', 'EXCHANGE', 'VMWARE', 'HYPERV', 'SYBASE', 'MONGODB',
    'SAPASE',  # NEU
]
```

**Schritt 2: Schwellwerte definieren (optional)**

```python
THRESHOLDS = {
    # ... bestehende ...
    "sapase": {"warn": 26 * 3600, "crit": 48 * 3600},
}
```

**Schritt 3: Kategorie zuweisen (optional)**

```python
DATABASE_TYPES = {
    'mssql', 'hana', 'db2', 'oracle', 'mysql',
    'postgres', 'mariadb', 'sybase', 'mongodb',
    'sapase',  # NEU
}
```

**Nach Änderungen:**
```bash
cmk -R
cmk -II --all
```

### Tolerantes Error-Handling konfigurieren

Backup-Typen mit tolerantem Verhalten (Failed → WARNING statt CRITICAL):

```python
TOLERANT_TYPES = {
    'file', 'virtual', 'scale', 'dm', 'datacenter',
    'vmware', 'hyperv', 'mail', 'exchange',
    'custom_tolerant_type'  # NEU
}
```

### CSV-Verzeichnis ändern

Im Agent-Plugin (`/usr/lib/check_mk_agent/plugins/tsm_backups`):

```python
CSV_DIR = Path("/mnt/CMK_TSM")  # Hier anpassen
```

---

## 🚀 Verwendung

### Service-Labels nutzen

Jeder TSM-Backup-Service erhält automatisch folgende Labels:

| Label | Werte | Beschreibung |
|-------|-------|--------------|
| `backup_type` | `mssql`, `hana`, `file`, ... | Erkannter Backup-Typ |
| `backup_category` | `database`, `virtualization`, `filesystem`, `application`, `other` | Kategorie |
| `backup_system` | `tsm` | Backup-System |
| `frequency` | `hourly`, `daily`, `weekly`, `monthly` | Backup-Frequenz |
| `backup_level` | `log`, `full`, `incremental`, `differential` | Backup-Level |
| `error_handling` | `tolerant`, `strict` | Fehlerbehandlung |
| `node_name` | Original Node-Name | TSM-Node |

### Beispiele: Label-basierte Filterung

#### Views erstellen

**CheckMK GUI:**  
`Setup > General > Custom views > Create new view`

**Filter-Beispiele:**
- **Alle Datenbank-Backups:**  
  `Service labels: backup_category = database`

- **Alle fehlgeschlagenen strikten Backups:**  
  `State: CRIT` + `Service labels: error_handling = strict`

- **Alle MSSQL-Backups mit täglicher Frequenz:**  
  `Service labels: backup_type = mssql AND frequency = daily`

#### Business Intelligence (BI)

```python
# BI-Aggregation: Alle DB-Backups OK?
{
    "type": "bi_aggregation",
    "title": "Database Backups",
    "filter": {
        "service_labels": {
            "backup_category": "database"
        }
    }
}
```

### Status-Bewertungslogik

| Bedingung | Error Handling | Ergebnis |
|-----------|---------------|----------|
| ≥ 1x Completed | - | OK ✅ |
| Only Pending/Started (<2h) | - | OK ✅ |
| Only Pending/Started (>2h) | - | WARN ⚠️ |
| Failed/Missed | Tolerant | WARN ⚠️ |
| Failed/Missed | Strict | CRIT 🔴 |
| Age > Threshold | - | WARN/CRIT ⚠️🔴 |

---

## 🏗️ Architektur

### Komponenten-Übersicht

```
┌─────────────────────────────────────────────────────────┐
│                    TSM Server                            │
│  ┌────────────────────────────────────────────────┐    │
│  │  Backup Jobs → CSV Export                       │    │
│  │  (via TSM Queries oder Export-Scripts)         │    │
│  └────────────────┬───────────────────────────────┘    │
└───────────────────┼──────────────────────────────────────┘
                    │ CSV-Dateien
                    │ (z.B. via NFS, SCP, Rsync)
                    ▼
┌─────────────────────────────────────────────────────────┐
│              Überwachter Host                            │
│  ┌────────────────────────────────────────────────┐    │
│  │  /mnt/CMK_TSM/*.CSV                            │    │
│  └────────────────┬───────────────────────────────┘    │
│                   │                                      │
│  ┌────────────────▼───────────────────────────────┐    │
│  │  Agent Plugin: tsm_backups                     │    │
│  │  - Liest CSV-Dateien                           │    │
│  │  - Normalisiert Node-Namen                     │    │
│  │  - Aggregiert pro Node                         │    │
│  │  - Gibt JSON aus                               │    │
│  └────────────────┬───────────────────────────────┘    │
└───────────────────┼──────────────────────────────────────┘
                    │ JSON via CheckMK Agent
                    ▼
┌─────────────────────────────────────────────────────────┐
│              CheckMK Server                              │
│  ┌────────────────────────────────────────────────┐    │
│  │  Check Plugin: tsm_backups                     │    │
│  │  - Parsed JSON                                 │    │
│  │  - Erstellt Services mit Labels               │    │
│  │  - Bewertet Status                             │    │
│  │  - Prüft Schwellwerte                          │    │
│  │  - Erzeugt Metriken                            │    │
│  └────────────────┬───────────────────────────────┘    │
│                   │                                      │
│  ┌────────────────▼───────────────────────────────┐    │
│  │  CheckMK Services                              │    │
│  │  - TSM Backup SERVER_MSSQL                     │    │
│  │  - TSM Backup VM_HYPERV_01                     │    │
│  │  - ...                                          │    │
│  └────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
```

### Datenfluss

1. **TSM Server**: Exportiert Backup-Statistiken als CSV
2. **Host**: Agent-Plugin liest CSV, aggregiert und normalisiert Daten
3. **CheckMK**: Check-Plugin empfängt JSON, erstellt Services, bewertet Status
4. **Output**: Services mit Labels, Metriken, Status

### Node-Normalisierung

**Problem:** Redundante TSM-Server-Nodes  
**Beispiel:**  
- `RRZ01_MYSERVER_MSSQL`
- `RRZ02_MYSERVER_MSSQL`
- `NFRZ01_MYSERVER_MSSQL`

**Lösung:** Normalisierung entfernt `RRZ*/NFRZ*`-Präfixe  
**Ergebnis:** Ein Service `MYSERVER_MSSQL` aggregiert alle Nodes

---

## 🔍 Troubleshooting

### Problem: Keine Services gefunden

**Diagnose:**
```bash
# Agent-Ausgabe prüfen
check_mk_agent | grep -A 20 "<<<tsm_backups"

# Sollte JSON zurückgeben
<<<tsm_backups:sep(0)>>>
{"NODE1": {...}, "NODE2": {...}}
```

**Lösungen:**
- CSV-Verzeichnis `/mnt/CMK_TSM` existiert?
- CSV-Dateien vorhanden? (`ls -lh /mnt/CMK_TSM/*.CSV`)
- Agent-Plugin ausführbar? (`ls -l /usr/lib/check_mk_agent/plugins/tsm_backups`)
- Manuell testen: `/usr/lib/check_mk_agent/plugins/tsm_backups`

### Problem: Services bleiben UNKNOWN

**Diagnose:**
```bash
# Check-Plugin testen
cmk -nv --debug hostname | grep "TSM Backup"
```

**Lösungen:**
- Check-Plugin korrekt installiert?
- Plugin-Cache löschen: `cmk -R`
- Discovery erneut: `cmk -II hostname`

### Problem: Falsche Backup-Typen erkannt

**Node-Namen-Konvention überprüfen:**
```
✅ KORREKT:
- SERVER_MSSQL
- DATABASE_HANA_01
- FILESERVER_FILE
- VM_HYPERV_123

❌ FALSCH:
- MSSQL (zu kurz)
- SERVER (kein Typ)
- SERVER_12345 (Typ unklar)
```

**Lösung:** Node-Namen-Schema anpassen oder `extract_backup_type()` erweitern

### Problem: CSV-Dateien werden nicht gelesen

**CSV-Format prüfen:**
```bash
head -n 5 /mnt/CMK_TSM/TSM_BACKUP_SCHED_24H.CSV
```

**Erwartetes Format:**
```
2026-01-12 08:00:00,FIELD,SERVER_MSSQL,DAILY_FULL,Completed
2026-01-12 09:15:00,FIELD,DATABASE_HANA,HOURLY_LOG,Completed
```

**Spalten:**
1. Timestamp (`YYYY-MM-DD HH:MM:SS`)
2. Beliebiges Feld
3. **Node-Name**
4. **Schedule-Name**
5. **Status**

### Problem: Logs analysieren

```bash
# CheckMK-Log
tail -f /omd/sites/monitoring/var/log/cmc.log | grep tsm

# Agent-Plugin debuggen
/usr/lib/check_mk_agent/plugins/tsm_backups 2>&1 | tee /tmp/tsm_debug.log
```

---

## 📊 Metriken

### Erzeugte Metriken

| Metrik | Beschreibung | Einheit | Schwellwerte |
|--------|--------------|---------|--------------|
| `backup_age` | Zeit seit letztem Backup | Sekunden | Typ-spezifisch |
| `backup_jobs` | Anzahl Backup-Jobs | Count | - |

### Grafana-Integration

**Beispiel-Query (InfluxDB):**
```sql
SELECT mean("backup_age") 
FROM "tsm_backups" 
WHERE "backup_type" = 'mssql' 
  AND time > now() - 7d 
GROUP BY time(1h), "node_name"
```

---

## 🔄 Changelog

### Version 5.0 (2026-01-12)
- ✨ **Dynamische Backup-Typ-Erkennung**: Keine feste Liste mehr nötig
- ✨ **Backup-Kategorien**: Zusätzliches Label `backup_category`
- ✨ **Erweiterte Kommentierung**: Vollständige Docstrings
- ✨ **Neue Typen**: PostgreSQL, MariaDB, MongoDB
- 🐛 **Bugfix**: ServiceLabel API für CheckMK 2.3.0p40

### Version 4.0 (2026-01-10)
- ✨ ServiceLabel API-Kompatibilität mit CheckMK 2.3.0p40
- 📝 Erweiterte Dokumentation

### Version 3.0 (2025-12-15)
- ✨ Node-Normalisierung für Redundanz
- ✨ Aggregation pro logischem Node
- 🔧 Typ-spezifische Schwellwerte

### Version 2.0 (2025-11-20)
- ✨ Tolerantes Error-Handling
- ✨ Service-Labels

### Version 1.0 (2025-11-01)
- 🎉 Initiales Release

---

## 📝 Lizenz

MIT License - Siehe LICENSE Datei

## 👤 Autor

**Marius Gielnik**  
IT Product Owner - CheckMK Monitoring  
GC-Gruppe (Cordes und Gräfe KG)

## 🤝 Support

- **Issues:** GitHub Issues
- **Fragen:** CheckMK Community Forum
- **Email:** [deine-email]@example.com

---

## 📚 Weiterführende Links

- [CheckMK Plugin Development](https://docs.checkmk.com/latest/de/devel_check_plugins.html)
- [IBM Spectrum Protect Documentation](https://www.ibm.com/docs/en/spectrum-protect)
- [CheckMK Labels](https://docs.checkmk.com/latest/de/labels.html)

---

**Letzte Aktualisierung:** 2026-01-12  
**Version:** 4.1