[comment]: # ({a6d31bd3-a6d31bd3})
# 2 Passive and active agent checks

[comment]: # ({/a6d31bd3-a6d31bd3})

[comment]: # ({1b7bc303-7bd0dd61})
#### Überblick

Dieser Abschnitt enthält Details zu passiven und aktiven Prüfungen, die vom
[Zabbix Agent](/manual/concepts/agent) und [Zabbix Agent 2](/manual/concepts/agent2) durchgeführt werden.

Zabbix verwendet ein JSON-basiertes Kommunikationsprotokoll für die Kommunikation mit
den Agents.

Die Protokolle von Zabbix Agent und Zabbix Agent 2 sind seit Zabbix 7.0 vereinheitlicht. Der Unterschied zwischen Anfragen/Antworten von Zabbix Agent und Zabbix Agent 2 wird durch den Wert des Tags „variant“ ausgedrückt.

[comment]: # ({/1b7bc303-7bd0dd61})

[comment]: # ({db675be2-e6db8dd6})
#### Passive checks

Ein passiver Check ist eine einfache Datenanfrage. Zabbix Server oder Proxy fragt
nach bestimmten Daten (zum Beispiel CPU-Auslastung), und der Zabbix Agent sendet das
Ergebnis an den Server zurück.

Passive Checks werden asynchron ausgeführt - es ist nicht erforderlich, die Antwort auf eine Anfrage zu erhalten, bevor andere Checks gestartet werden. Auch die DNS-Auflösung erfolgt asynchron.

Der Agent-Poller versucht, eine Verbindung zu allen Adressen herzustellen, die von der DNS-Abfrage zurückgegeben werden. Dadurch wird sichergestellt, dass der Poller bei einer nicht erreichbaren IP-Adresse die nächste verfügbare Adresse versucht, was die Wahrscheinlichkeit einer erfolgreichen Verbindung erhöht. Diese Verbesserung gilt sowohl für den Zabbix Server als auch für den Proxy.

Die maximale Parallelität asynchroner Checks beträgt 1000 (definiert durch [MaxConcurrentChecksPerPoller](/manual/appendix/config/zabbix_server#maxconcurrentchecksperpoller)).

Die Anzahl der asynchronen Agent-Poller wird durch den Parameter [StartAgentPollers](/manual/appendix/config/zabbix_server#startagentpollers) definiert.

**Serveranfrage**

Für die Definition von Header- und Datenlänge siehe bitte [Protokolldetails](/manual/appendix/protocols/header_datalen).

```json
{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `"passive checks"` |
| data |<| _array of object_ | yes | Passive check item. |
| | key | _string_ | yes | Item key with expanded macros. |
|^| timeout | _number_ | yes | Communication timeout. |

**Agent-Antwort**

```json
{
  "version": "7.0.0",
  "variant": 2,
  "data": [
    {
      "value": "7.0.0"
    }
  ]
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| version |<| _string_ | yes | The agent version number. |
| variant |<| _number_ | yes | The agent variant (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| data |<| _array of object_ | yes |Contains the result of the check. |
| | value | _string_ | no | The item value if the check was successful. |
| | error | _string_ | no | The error message if the check was not successful. |

Zum Beispiel für unterstützte Items:

1.  Server öffnet eine TCP-Verbindung
2.  Server sendet **<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}**
3.  Agent liest die Anfrage und antwortet mit
    **<HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"value":1}]}**
4.  Server verarbeitet die Daten, um den Wert zu erhalten, in unserem Fall '1'
5.  TCP-Verbindung wird geschlossen

Für nicht unterstützte Items:

1.  Server öffnet eine TCP-Verbindung
2.  Server sendet **<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size\[/nono\]","timeout":3}]}**
3.  Agent liest die Anfrage und antwortet mit
    **<HEADER><DATALEN>{"version":"7.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}**
4.  Server verarbeitet die Daten und ändert den Status des Items in nicht unterstützt mit der
    angegebenen Fehlermeldung
5.  TCP-Verbindung wird geschlossen

[comment]: # ({/db675be2-e6db8dd6})

[comment]: # ({8a5c8e4e-d33dfdd3})
##### Failover auf das alte Protokoll

Damit der Zabbix Server oder Proxy mit Agents aus Versionen vor 7.0 zusammenarbeiten kann, die das Klartextprotokoll verwenden, ist ein Failover auf das alte Protokoll implementiert.

Passive Prüfungen werden nach einem Neustart oder bei einer Änderung der Schnittstellenkonfiguration über das JSON-Protokoll (7.0 und höher) ausgeführt. Wenn als Antwort kein gültiges JSON empfangen wird (der Agent sendet "ZBX_NOTSUPPORTED"), speichert Zabbix die Schnittstelle als altes Protokoll im Cache und **wiederholt** die Prüfung, indem nur der Datenpunkt-Schlüssel gesendet wird.

Beachten Sie, dass der Zabbix Server/Proxy jede Stunde erneut versucht, mit allen Schnittstellen das neue Protokoll zu verwenden, und bei Bedarf auf das alte Protokoll zurückfällt.

[comment]: # ({/8a5c8e4e-d33dfdd3})

[comment]: # ({86593407-ecdd6e8e})
#### Aktive Checks

Aktive Checks erfordern eine komplexere Verarbeitung.
Der Agent muss zunächst vom Server/Proxy eine Liste von Datenpunkten und/oder [Remote-Befehlen](/manual/config/notifications/action/operation/remote_command) zur unabhängigen Verarbeitung abrufen.

Die Server/Proxies, von denen die aktiven Checks abgerufen werden, sind im Parameter 'ServerActive' der [Konfigurationsdatei](/manual/appendix/config/zabbix_agent2) des Agenten aufgeführt.
Die Häufigkeit der Abfrage dieser Checks wird durch den Parameter 'RefreshActiveChecks' in derselben Konfigurationsdatei festgelegt.
Wenn das Aktualisieren aktiver Checks jedoch fehlschlägt, wird der Versuch nach fest codierten 60 Sekunden wiederholt.

[comment]: # ({/86593407-ecdd6e8e})

[comment]: # ({e520c471-4c14cd28})
::: notetip
Seit Zabbix 6.4 erhält der Agent (im aktiven Modus) nicht mehr standardmäßig alle zwei Minuten eine vollständige Kopie der Konfiguration vom Server/Proxy.
Stattdessen wird zur Verringerung des Netzwerkverkehrs und des Ressourcenverbrauchs standardmäßig alle 5 Sekunden eine inkrementelle Konfigurationssynchronisierung durchgeführt, bei der der Server/Proxy **nur dann** eine vollständige Kopie der Konfiguration bereitstellt, wenn der Agent sie noch nicht erhalten hat oder sich die Host-Konfiguration, globale Makros oder globale reguläre Ausdrücke geändert haben.
:::

[comment]: # ({/e520c471-4c14cd28})

[comment]: # ({63166bda-2f80420a})
Der Agent sendet dann periodisch die neuen Werte an den/die Server.
Wenn der Agent [Remote-Befehle](/manual/config/notifications/action/operation/remote_command) zur Ausführung erhalten hat, wird auch das Ausführungsergebnis gesendet.
Beachten Sie, dass die Ausführung von Remote-Befehlen auf einem aktiven Agent seit Zabbix-Agent 7.0 unterstützt wird.

::: notetip
Wenn sich ein Agent hinter der Firewall befindet, sollten Sie erwägen,
nur aktive Prüfungen zu verwenden, da Sie in diesem Fall die Firewall
nicht ändern müssten, um eingehende Erstverbindungen zuzulassen.
:::

[comment]: # ({/63166bda-2f80420a})

[comment]: # ({fa025abc-d898e135})
##### Abrufen der Liste der Datenpunkte

**Agent-Anfrage**

Die Anfrage für aktive Prüfungen wird verwendet, um die aktiven Prüfungen abzurufen, die vom Agent verarbeitet werden sollen. Diese Anfrage wird vom Agent beim Start und anschließend in Intervallen gemäß [RefreshActiveChecks](/manual/appendix/config/zabbix_agent2) gesendet.

```json
{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "7.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
```

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| request | _string_ | yes | `active checks` |
| host | _string_ | yes | Host-Name. |
| host_metadata | _string_ | no | Der Konfigurationsparameter HostMetadata oder der Metrikwert HostMetadataItem. |
| interface | _string_ | no | Der Konfigurationsparameter HostInterface oder der Metrikwert HostInterfaceItem. |
| ip | _string_ | no | Die erste IP-Adresse des Konfigurationsparameters ListenIP, falls gesetzt. |
| port | _number_ | no | Der Wert des Konfigurationsparameters ListenPort, falls gesetzt und nicht der Standard-Listening-Port des Agent. |
| version | _string_ | yes | Die Versionsnummer des Agent. |
| variant | _number_ | yes | Die Variante des Agent (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| config_revision | _number_ | no | Konfigurationskennung für [inkrementelle Konfigurationssynchronisierung](#active-checks). |
| session | _string_ | no | Sitzungskennung für [inkrementelle Konfigurationssynchronisierung](#active-checks). |
  
**Server-Antwort**

Die Antwort auf aktive Prüfungen wird vom Server nach Verarbeitung der Anfrage für aktive Prüfungen an den Agent zurückgesendet.
  
```json
{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}

```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| info |<| _string_ | no | Fehlerinformationen im Falle eines Fehlers. |
| data |<| _array of objects_ | no | Aktive Prüfungs-Datenpunkte. Wird ausgelassen, wenn die Host-Konfiguration unverändert ist. |
| | key | _string_ | no | Datenpunkt-Schlüssel mit erweiterten Makros. |
|^| itemid | _number_ | no | Datenpunkt-ID. |
|^| delay | _string_ | no | Aktualisierungsintervall des Datenpunkts.<br>Flexible/Planungsintervalle werden seit Zabbix 7.0 von Zabbix agent und Zabbix agent 2 unterstützt. |
|^| lastlogsize | _number_ | no | lastlogsize des Datenpunkts. |
|^| mtime | _number_ | no | mtime des Datenpunkts. |
|^| timeout | _string_ | no | Timeout des Datenpunkts. |
| refresh_unsupported |<| _number_ | no | Aktualisierungsintervall für nicht unterstützte Datenpunkte. |
| regexp |<| _array of objects_ | no | Globale reguläre Ausdrücke. |
| | name | _string_ | no | Name des globalen regulären Ausdrucks. |
|^| expression | _string_ | no | Globaler regulärer Ausdruck. |
|^| expression_type | _number_ | no | Typ des globalen regulären Ausdrucks. |
|^| exp_delimiter | _string_ | no | Trennzeichen des globalen regulären Ausdrucks. |
|^| case_sensitive | _number_ | no | Groß-/Kleinschreibungseinstellung des globalen regulären Ausdrucks. |
| commands |<| _array of objects_ | no | Auszuführende Remote-Befehle. Enthalten, wenn die Ausführung des Remote-Befehls durch eine Aktions-[Operation](/manual/config/notifications/action/operation#operations) oder die manuelle Ausführung eines [Skripts](/manual/web_interface/frontend_sections/alerts/scripts) ausgelöst wurde. Beachten Sie, dass die Ausführung von Remote-Befehlen auf einem aktiven Agent seit Zabbix agent 7.0 unterstützt wird. Ältere aktive Agenten ignorieren alle Remote-Befehle, die in der Server-Antwort auf aktive Prüfungen enthalten sind. |
| | command | _string_ | no | Remote-Befehl. |
|^| id | _number_ | no | Kennung des Remote-Befehls. |
|^| wait | _number_ | no | Ausführungsmodus des Remote-Befehls ("0" (nowait) für Befehle aus Aktions-[Operationen](/manual/config/notifications/action/operation#operations); "1" (wait) für Befehle aus der manuellen Ausführung eines [Skripts](/manual/web_interface/frontend_sections/alerts/scripts)). |
|^| timeout | _number_ | no | Timeout für die Ausführung des Remote-Befehls in der Konfiguration von [Server](/manual/appendix/config/zabbix_server#timeout)/[Proxy](/manual/appendix/config/zabbix_proxy#timeout). |
| config_revision | < | _number_ | no | Konfigurationskennung für [inkrementelle Konfigurationssynchronisierung](#active-checks). Wird ausgelassen, wenn die Host-Konfiguration unverändert ist. Wird erhöht, wenn die Host-Konfiguration geändert wurde. |
  
Der Server muss mit success antworten.

Zum Beispiel:

1.  Agent öffnet eine TCP-Verbindung
2.  Agent fragt die Liste der Prüfungen an
3.  Server antwortet mit einer Liste von Datenpunkten und auszuführenden Remote-Befehlen
4.  Agent analysiert die Antwort
5.  TCP-Verbindung wird geschlossen
6.  Agent beginnt mit der periodischen Datenerfassung und führt Remote-Befehle aus (seit Zabbix agent 7.0 unterstützt)

::: noteimportant
Beachten Sie, dass (sensible) Konfigurationsdaten Parteien zugänglich werden können,
die Zugriff auf den Trapper-Port des Zabbix-Server haben, wenn eine aktive Prüfung verwendet wird.
Dies ist möglich, weil sich jeder als aktiver Agent ausgeben und die Konfiguration der Datenpunkte anfordern kann;
eine Authentifizierung findet nicht statt, sofern Sie keine Optionen für
[Verschlüsselung](/manual/encryption) verwenden.
:::

[comment]: # ({/fa025abc-d898e135})

[comment]: # ({1e8860e1-8c5ecfe1})
##### Senden der gesammelten Daten

**Agent sendet**

Die Datenanforderung des Agenten enthält die gesammelten Datenpunktwerte und die Werte für ausgeführte Remote-Befehle (falls vorhanden).
  
```json
{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "7.0.0",
  "variant": 2
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `agent data` |
| data |<| _array of objects_ | yes | Datenpunktwerte. |
| | id |<| _number_ | yes | Die Wert-ID (inkrementeller Zähler, der zur Prüfung doppelter Werte bei Netzwerkproblemen verwendet wird). |
|^| itemid | _number_ | yes | Die Datenpunkt-ID. |
|^| value | _string_ | no | Der Datenpunktwert. |
|^| lastlogsize | _number_ | no | Das lastlogsize des Datenpunkts. |
|^| mtime | _number_ | no | Die mtime des Datenpunkts. |
|^| state | _number_ | no | Der Zustand des Datenpunkts. |
|^| source | _string_ | no | Die Quelle des Ereignisprotokolls des Werts. |
|^| eventid | _number_ | no | Die eventid des Ereignisprotokolls des Werts. |
|^| severity | _number_ | no | Die severity des Ereignisprotokolls des Werts. |
|^| timestamp | _number_ | no | Der timestamp des Ereignisprotokolls des Werts. |
|^| clock | _number_ | yes | Der Zeitstempel des Werts (Sekunden seit Epoch). |
|^| ns | _number_ | yes | Die Nanosekunden des Zeitstempels des Werts. |
| commands |<| _array of objects_ | no | Ergebnis der Ausführung von Remote-Befehlen. Beachten Sie, dass die Ausführung von Remote-Befehlen auf einem aktiven Agenten seit Zabbix agent 7.0 unterstützt wird. Ältere aktive Agenten ignorieren alle Remote-Befehle, die in der Serverantwort auf aktive Prüfungen enthalten sind. |
| | id | _number_ | no | Kennung des Remote-Befehls. |
|^| value | _string_ | no | Ergebnis der Ausführung des Remote-Befehls, wenn die Ausführung erfolgreich war. |
|^| error | _string_ | no | Fehlermeldung der Ausführung des Remote-Befehls, wenn die Ausführung fehlgeschlagen ist. |
| session |<| _string_ | yes | Eindeutige Sitzungskennung, die jedes Mal generiert wird, wenn der Agent gestartet wird. |
| host |<| _string_ | yes | Hostname. |
| version |<| _string_ | yes | Die Versionsnummer des Agenten. |
| variant |<| _number_ | yes | Die Agent-Variante (*1* - Zabbix agent, *2* - Zabbix agent 2). |

Jedem Wert wird eine virtuelle ID zugewiesen. Die Wert-ID ist ein einfacher aufsteigender
Zähler, der innerhalb einer Daten-Sitzung eindeutig ist (identifiziert durch das Sitzungs-Token).
Diese ID wird verwendet, um doppelte Werte zu verwerfen, die in Umgebungen mit schlechter
Konnektivität gesendet werden könnten.

**Serverantwort**

Die Antwort auf die Agent-Daten wird vom Server nach der Verarbeitung der Agent-Datenanforderung an den Agenten zurückgesendet.
  
```json
{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
```

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| response | _string_ | yes | `success` \| `failed` |
| info | _string_ | yes | Ergebnisse der Verarbeitung der Datenpunkte. |
  
::: noteimportant
Wenn das Senden einiger Werte auf dem Server fehlschlägt (zum
Beispiel, weil der Host oder der Datenpunkt deaktiviert oder gelöscht wurde), versucht der Agent
nicht erneut, diese Werte zu senden.
:::

Zum Beispiel:

1.  Agent öffnet eine TCP-Verbindung
2.  Agent sendet eine Liste von Werten
3.  Server verarbeitet die Daten und sendet den Status zurück
4.  TCP-Verbindung wird geschlossen

::: noteimportant
Die Fehlermeldung wird serverseitig auf 2048 Zeichen gekürzt.
:::

[comment]: # ({/1e8860e1-8c5ecfe1})

[comment]: # ({12ecaf8c-ee2b7a2a})
##### Heartbeat-Nachricht

**Agent sendet**

Die Heartbeat-Nachricht wird von einem aktiven Agent an den Zabbix Server/Proxy
alle HeartbeatFrequency Sekunden gesendet (konfiguriert in der Konfigurationsdatei [Zabbix agent](/manual/appendix/config/zabbix_agentd)/
[agent 2](/manual/appendix/config/zabbix_agent2)).

Sie wird verwendet, um die Verfügbarkeit aktiver Prüfungen zu überwachen.

```json
{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "7.0.0",
  "variant": 2
}
```

| Field | Type | Mandatory | Value |
|-|-|-|-|
| request | _string_ | yes | `active check heartbeat` |
| host | _string_ | yes | Der Hostname. |
| heartbeat_freq | _number_ | yes | Die Heartbeat-Frequenz des Agent (Konfigurationsparameter HeartbeatFrequency). |
| version | _string_ | yes | Die Versionsnummer des Agent. |
| variant | _number_ | yes | Die Variante des Agent (*1* - Zabbix agent, *2* - Zabbix agent 2). |

**Redirect-Antwort**

Wenn ein Host neu zugewiesen wurde, kann der Server den Agent anweisen, seinen Heartbeat (und die nachfolgenden aktiven Prüfungen) an eine andere Proxy- oder Server-Instanz umzuleiten.

```json
  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| redirect |<| _object_ | yes | Umleitungsanweisungen. |
| | revision | _number_ | yes | Kennung der Konfigurationsrevision. |
|^| address | _string_ | yes | Adresse des Ziel-Server/Proxy. |

[comment]: # ({/12ecaf8c-ee2b7a2a})

[comment]: # ({e66043c4-e66043c4})
#### Älteres XML-Protokoll

::: noteclassic
Zabbix akzeptiert bis zu 16 MB XML-Base64-kodierte Daten, aber
ein einzelner dekodierter Wert sollte nicht länger als 64 KB sein, andernfalls wird er
während der Dekodierung auf 64 KB gekürzt.
:::

[comment]: # ({/e66043c4-e66043c4})