This is the documentation page for an unsupported version of Zabbix.
Is this not what you were looking for? Switch to the current version or choose one from the drop-down menu.

3 Passive and active agent checks

Overview

This section provides details on passive and active checks performed by Zabbix agent.

Zabbix uses a JSON based communication protocol for communicating with Zabbix agent.

There are some definitions used in the details of protocols used by Zabbix:

<HEADER> - "ZBXD\x01" (5 bytes)
       <DATALEN> - data length (8 bytes). 1 will be formatted as 01/00/00/00/00/00/00/00 (eight bytes in HEX, 64 bit number)

To not exhaust memory (potentially) Zabbix server is limited to accept only 64MB in one connection when using the Zabbix protocol in versions 2.2.0-2.2.2 (128MB before 2.2.0, unlimited before Zabbix 2.0.3).

Since 2.2.3, it is changed back to 128MB to remain compatible with older versions of Zabbix as when a process with a data transfer limit of 128MB would send data to another with a limit of 64MB it would cause the receiver to drop the data completely due to it exceeding its size limit.

Passive checks

A passive check is a simple data request. Zabbix server or proxy asks for some data (for example, CPU load) and Zabbix agent sends back the result to the server.

Server request

<item key>\n

Agent response

<HEADER><DATALEN><DATA>

For example:

  1. Server opens a TCP connection
  2. Server sends agent.ping\n
  3. Agent reads the request and responds with <HEADER><DATALEN>1
  4. Server processes data to get the value, '1' in our case
  5. TCP connection is closed

Active checks

Active checks require more complex processing. The agent must first retrieve from the server(s) a list of items for independent processing.

The servers to get the active checks from are listed in the 'ServerActive' parameter of the agent configuration file. The frequency of asking for these checks is set by the 'RefreshActiveChecks' parameter in the same configuration file. However, if refreshing active checks fails, it is retried after hardcoded 60 seconds. The agent then periodically sends the new values to the server(s).

Getting the list of items

Agent request

<HEADER><DATALEN>{
          "request":"active checks",
          "host":"<hostname>"
       }

Server response

{
           "response":"success",
           "data":[
           {
               "key":"log[\/home\/zabbix\/logs\/zabbix_agentd.log]",
               "delay":"30",
               "lastlogsize":"0"
           },
           {
               "key":"agent.version",
               "delay":"600"
           }
           ]
       }

The server must respond with success. For each returned item, key and delay must exist. For items having type "Log", the lastlogsize must exist as well.

For example:

  1. Agent opens a TCP connection
  2. Agent asks for the list of checks
  3. Server responds with a list of items (item key, delay)
  4. Agent parses the response
  5. TCP connection is closed
  6. Agent starts periodical collection of data

Note that (sensitive) configuration data may become available to parties having access to the Zabbix server trapper port when using an active check. This is possible because anyone may pretend to be an active agent and request item configuration data; authentication does not take place.

Sending in collected data

Agent sends

<HEADER><DATALEN>{
          "request":"agent data",
          "data":[
              {
                  "host":"<hostname>",
                  "key":"log[\/home\/zabbix\/logs\/zabbix_agentd.log]",
                  "value":" 13039:20090907:184546.759 zabbix_agentd started. ZABBIX 1.6.6 (revision {7836}).",
                  "lastlogsize":80,
                  "clock":1252926015
              },
              {
                  "host":"<hostname>",
                  "key":"agent.version",
                  "value":"1.6.6",
                  "clock":1252926015
              }
          ],
          "clock":1252926016
       }

Server response

<HEADER><DATALEN>{
           "response":"success",
           "info":"Processed 2 Failed 0 Total 2 Seconds spent 0.002070"
       }

If sending of some values fails on the server (for example, because host or item has been disabled or deleted), agent will not retry sending of those values.

For example:

  1. Agent opens a TCP connection
  2. Agent sends a list of values
  3. Server processes the data and sends the status back
  4. TCP connection is closed

Older XML protocol

Zabbix will take up to 16 MB of XML Base64-encoded data, but a single decoded value should be no longer than 64 KB otherwise it will be truncated to 64 KB while decoding.

See also

  1. More details on Zabbix agent protocol