Zabbix Maintenance als User aktivieren / deaktivieren

Ein kleines How-To, zum Aktivieren / Deaktivieren der Zabbix Maintenance als Zabbix User ohne „Configuration Zugriff“.

Da ein Zabbix User keinen Zugriff auf das Menü „Configuration“ hat, kann er im Default auch den Wartungsmodus weder aktivieren noch deaktivieren. Hier hilft ein kleiner Workaround über ein Zabbix Maintenance Script. Dafür wird benötigt:

Zabbix: https://www.zabbix.com/download 😉
Eine „Dummy Host Group“: https://www.zabbix.com/documentation/current/manual/config/hosts/host#creating_a_host_group
Eine Maintenance samt Period: https://www.zabbix.com/documentation/current/manual/maintenance
Einen Zabbix API User: https://www.zabbix.com/documentation/current/manual/config/users_and_usergroups
User Macros: https://www.zabbix.com/documentation/current/manual/config/macros/user_macros
Die Zabbix API: https://www.zabbix.com/documentation/current/manual/api
Ein wenig Linux Bash Scripting
Ein bzw. zwei Global Scripts: https://www.zabbix.com/documentation/current/manual/web_interface/frontend_sections/administration/scripts

Fangen wir an dieser Stelle mit 2. an und erstellen unter „Configuration“ -> „Host groups“ eine dummy Host Group:
Group name: Maintenance Mode active

Anlegen der Host Group „Maintenance Mode active“

Sobald die „Maintenance Mode active“ Host Group erstellt ist, öffnen wir diese und lesen in der URL die passende GroupID ab. Diese werden wir später im Script benötigen.

Weiter geht es mit der Erstellung einer Wartung unter „Configuration“ -> „Maintenance“ -> „Create maintenance period“:
Name: Always Maintenance
Maintenance type: With data collection
Active since: <Heutiges Datum>
Active till: 2038-01-18 00:00 (Ein längerer Zeitraum ist nicht möglich)
Description: <Kreativ sein> 🙂

Als nächstes wird im vierten Schritt unter „Administration“ -> „Users“ ein „API User“ erstellt, der über die Gruppe „No access to the frontend“ keinen Zugriff auf das Web-Frontend erhält. Sollte Zabbix per LDAP angebunden sein, sollte der Benutzer im entsprechenden Active Directory / LDAP Verzeichnis erstellt werden. Der Einfachheit halber wird der API User ebenfalls in die „Zabbix administrators“ Gruppe gesteckt sowie zum „Super Admin“ gemacht:

„Wegen der Sicherheit“ werden jetzt in „Administration“ -> „Generel“ -> „Macros“ noch zwei User Macros „{$API.USER}“ und „{$API.PASS}“ als „Secret Text“ erstellt:

API User und Passwort als User Macro mit „Secret Text“

Nachdem die Vorbereitungen getroffen sind, schauen wir uns die Zabbix API an und suchen uns die benötigten Methoden:

Authentifizierung (Zabbix API Authentication):

# https://www.zabbix.com/documentation/current/manual/api#authentication

Request:
{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "user": "Admin",
        "password": "zabbix"
    },
    "id": 1,
    "auth": null
}

Result:
{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Host suche (host.get):

# https://www.zabbix.com/documentation/current/manual/api/reference/host/get

Request:
{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "filter": {
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    },
    "auth": "038e1d7b1735c6a5436ee9eae095879e",
    "id": 1
}

Result:
{
    "jsonrpc": "2.0",
    "result": [
        {
            "maintenances": [],
            "hostid": "10160",
            ...
            "tls_psk": ""
        },
        {
            "maintenances": [],
            "hostid": "10167",
            ...
            "tls_psk": ""
        }
    ],
    "id": 1
}

Hinzufügen eines Hosts zur Zabbix Maintenance Host Group (hostgroup.massupdate):

# https://www.zabbix.com/documentation/current/manual/api/reference/hostgroup/massupdate
{
    "jsonrpc": "2.0",
    "method": "hostgroup.massupdate",
    "params": {
        "groups": [
            {
                "groupid": "6"
            }
        ],
        "hosts": [
            {
                "hostid": "30050"
            }
        ]
    },
    "auth": "f223adf833b2bf2ff38574a67bba6372",
    "id": 1
}

Entfernen eines Hosts aus der Zabbix Maintenance Host Group (hostgroup.massremove):

# https://www.zabbix.com/documentation/current/manual/api/reference/hostgroup/massremove
{
    "jsonrpc": "2.0",
    "method": "hostgroup.massremove",
    "params": {
        "groupids": [
            "5",
            "6"
        ],
        "hostids": [
            "30050",
            "30001"
        ]
    },
    "auth": "038e1d7b1735c6a5436ee9eae095879e",
    "id": 1
}

Der Ablauf im späteren Script kann jetzt also anhand der API Methoden folgendermaßen skizziert werden:

Absenden eines HTTP POST Requests im JSON-Format zur Authentifizierung.
Abspeichern des generierten AuthTokens in einer Variable zur weiteren Verwendung.
Absenden eines HTTP POST Requests zur Suche der passenden HostID zum Host.
Ablegen der HostID in einer Variable zur weiteren Verwendung.
Absenden eines HTTP POST Requests, um den Host anhand der HostID in die „Maintenance Mode active“ Host Group aufzunehmen oder ihn zu entfernen.

Kommen wir nun mit dem Bash Script (maintenance_mode.sh) zum Hauptdarsteller bzw. Schritt 7. Das Script kann bspw. unter „/usr/lib/zabbix/externalscripts/maintenance_mode.sh“ gespeichert werden. Die Variable „GroupID“ wird mit der passenden Host group ID der Dummy Host group aus Schritt 2 ersetzt:

sudoedit /usr/lib/zabbix/externalscripts/maintenance_mode.sh
# Inhalt des Script Code-Blocks einfügen, speichern und das Script ausführbar machen
sudo chmod +x /usr/lib/zabbix/externalscripts/maintenance_mode.sh

#!/bin/bash

GroupID=17

if [ ! -z "$5" ]
then
        echo Host: $1
        if [ $2 -eq 1 ]
        then
                echo Wartungsmodus aktivieren: $2
        else
                echo Wartungsmodus deaktivieren: $2
        fi
        echo API User: $3
        echo API Pass: $4
        echo Debug: $5
fi

# Api Authentifizierung / AuthToken erstellen:
AuthToken="$(curl -H "Content-type: application/json-rpc" -X POST http://localhost/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "user.login",
            "params": {
                    "user": "'$3'",
                    "password": "'$4'"
            },
            "id": 1
        }' 2>&1 | grep -oP '(?<="result":")[^"]*')"

if [ ! -z "$5" ]
then
        echo AuthToken: $AuthToken
fi

# Prüfen, ob Wartungsmodus an (1) /aus (2)
if [ $2 -eq 1 ]
then
        # API Suche nach dem ausgewählten Host {HOST.HOST}
        HostID="$(curl -H "Content-type: application/json-rpc" -X POST http://localhost/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "host.get",
            "params": {
                "filter": {
                              "host": [
                              "'$1'"
                              ]
                },
                "output": [
                "hostid",
                "host"
                ]
           },
           "id": 2,
           "auth": "'$AuthToken'"
        }' 2>&1 | grep -oP '(?<="hostid":")[^"]*')"

        if [ ! -z "$5" ]
        then
                echo HostID: $HostID
        fi

        # Hinzufügen des Hosts in die Wartungsmodus Host Gruppe
        curl --silent -H "Content-type: application/json-rpc" -X POST http://localhost/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "hostgroup.massadd",
            "params": {
                "groups": [
                    {
                         "groupid": "'$GroupID'"
                    }
                ],
                "hosts": [
                    {
                         "hostid": "'$HostID'"
                    }
                ]
            },
            "auth": "'$AuthToken'",
            "id": 1
        }' > /dev/null
        echo Wartungsmodus aktiviert: $1
else
        # API Suche nach dem ausgewählten Host {HOST.HOST}
        HostID="$(curl -H "Content-type: application/json-rpc" -X POST http://localhost/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "host.get",
            "params": {
                "filter": {
                              "host": [
                              "'$1'"
                              ]
                },
                "output": [
                "hostid",
                "host"
                ]
           },
           "id": 2,
           "auth": "'$AuthToken'"
        }' 2>&1 | grep -oP '(?<="hostid":")[^"]*')"

        if [ ! -z "$5" ]
        then
                echo HostID: $HostID
        fi

        # Entfernen des Hosts aus der Wartungsmodus Host Gruppe
        curl --silent -H "Content-type: application/json-rpc" -X POST http://localhost/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "hostgroup.massremove",
            "params": {
                "groupids": [
                    "'$GroupID'"
                ],
                "hostids": [
                   "'$HostID'"
                ]
            },
        "auth": "'$AuthToken'",
        "id": 1
        }' > /dev/null
        echo Wartungsmodus deaktiviert: $1
fi

Zwischengeschoben noch eine Anmerkung, sofern Zabbix per https (SSL) erreichbar ist und http-Anfragen per Redirect auf https umleitet, so sollte anstatt „http://localhost“ der korrekte Host „https://<FQDN>/..“ genutzt werden. Ebenfalls kann es nicht schaden, „curl“ um den Parameter „-k“ zu erweitern:

AuthToken="$(curl -k -H "Content-type: application/json-rpc" -X POST https://<FQDN des Zabbix Servers>/zabbix/api_jsonrpc.php -d'
        {
            "jsonrpc": "2.0",
            "method": "user.login",
            "params": {
                    "user": "'$3'",
                    "password": "'$4'"
            },
            "id": 1
        }' 2>&1 | grep -oP '(?<="result":")[^"]*')"

Zu guter Letzt werden jetzt noch zwei Scripts zum Aktivieren bzw. Deaktivieren der Maintenance benötigt. Diese können unter „Administration“ -> „Scripts“ erstellt werden:
Name: Wartungsmodus/Aktivieren bzw. Wartungsmodus/Deaktivieren
Type: Script
Execute on: Zabbix Server
Command: /usr/lib/zabbix/externalscripts/maintenance_mode.sh {HOST.HOST} 1 {$API.USER} {$API.PASS} bzw. /usr/lib/zabbix/externalscripts/maintenance_mode.sh {HOST.HOST} 0 {$API.USER} {$API.PASS}
Description: Wartungsmodus aktivieren bzw. Wartungsmodus deaktivieren
User group: All
Host group: All
Requiered Host permission: Read

Zabbix Scripte zum Aktivieren / Deaktivieren des Wartungsmodus

Wie wird das Script „maintenance_mode.sh“ aufgerufen und was macht es eigentlich?

Der Aufruf: Das Script muss mit vier Parametern aufgerufen werden. Der fünfte Parameter wäre Optional und würde den „Debug Mode“ aktivieren.
1. Der erste Parameter „{HOST.HOST}“ entspricht dem im Frontend markierten Namen des Hosts
2. Der zweite Parameter aktiviert (1) oder deaktiviert (0) den Wartungsmodus
3. Die Parameter 3 und 4 übergeben die User Macros {$API.USER} sowie {$API.PASS}, also API Benutzer und Passwort
4. Der optionale fünfte Parameter (1) würde einen Debug Output aktivieren
Das Script:
1. Die GroupID der dummy Host group wird definiert
2. Wenn der Debug-Mode aktiv ist, werden die übergebenen Parameter ausgegeben
3. Mit „curl“ wird der passende Authentication JSON HTTP POST Request an die API gesendet und das Token in die Variable „AuthToken“ gespeichert
  1. Im Debug-Mode würde das AuthToken ausgegeben
4. Es wird geprüft, ob der Wartungsmodus aktiviert oder deaktiviert wird
5. Die passende HostID wird per API Methode gesucht und gespeichert
  1. Im Debug-Mode wird die HostID ausgegeben
6. Der Wartungsmodus wird aktiviert oder eben deaktiviert
7. Es wird ausgegeben, ob der Wartungsmodus aktiviert oder deaktiviert wurde