See www.zabbix.com for the official Zabbix site.

Docs/protocols/zabbix agent/1.4

From Zabbix.org
Jump to: navigation, search

Zabbix 1.4

Passive checks


Note: zabbix_get uses the agent protocol. In Zabbix 1.3.5 it changed from the basic protocol to the new one with the full ZBXD header.

The agent listens for connections on the configured agent port (default is 10050) and waits for Zabbix to connect. After connecting, Zabbix will send the following request:

 itemkey[param1,param2,param3]\n

\n means a linefeed character, byte value 0x0A (dec 10).

The agent must then respond with the value of the data item as follows:

Field Description Value
Header Fixed value ZBXD
Version Byte containing the protocol version 0x01
Data length 64 bit integer in little-endian byte order Length of the data field in bytes
Data The response to the request (base 10) Item value

All messages from the Zabbix 1.4 agent to the server are expected to use the same protocol header described above. It will simply be called "Protocol header" below. The Zabbix 1.4 server will *not* send the header in messages to the agent.

Example request:

 queue.messages.Count[DomainManager,MgmtBroker,SampleQ1]\n

Response bytes:

 5a 42 58 44 01 03 00 00 00 00 00 00 00 31 31 30
Bytes Meaning
5a 42 58 44 ZBXD
01 Protocol version 1
03 00 00 00 00 00 00 00 Data length: 3 bytes
31 31 30 110 (data value)

This protocol supports multiple requests and responses over a single TCP connection. This doesn't seem to be implemented in Zabbix yet, it might be later. After sending the result, the agent should check for more incoming request data and close the connection if there is none. This will allow future Zabbix versions to send multiple requests without having to change the agent code.

When the agent receives a request for an item it doesn't support, it should return ZBX_NOTSUPPORTED in the data value field, the response structure stays the same. The server will then disable the item and not ask for it again for some time. When the server has been configured to retry unsupported items (default after 10 minutes), it will request that data item again.

The agent is also allowed to return ZBX_ERROR for recoverable errors. The Zabbix server should then poll the agent again whenever it wants to retrieve the item value.

Note: This feature is currently broken - see ZBX-12050.

Active checks

The agent sends the following string to the server on the trapper port (10051 by default).

 Protocol header
 ZBX_GET_ACTIVE_CHECKS\n
 hostname\n

Where 'hostname' is the hostname of the agent making the request. The agent then waits for the server to send the list of active checks and close the socket. The agent should continue reading from the socket until the server closes it, however long that takes.

The response is formatted as follows:

 key:refresh time:last log size\n
 key:refresh time:last log size\n
 key:refresh time:last log size\n
 ZBX_EOF\n

The agent is now expected to send the value of the 'key's in the response every 'refresh time' seconds. The 'last log size' value is for items that monitor log files so the agent will be able to resume monitoring a log when it has been restarted.

When sending a value to the Zabbix server, the agent must connect to the trapper port (10051 by default) and send an XML fragment, formatted as follows (All on one line, no whitespace. This was just reformatted for readability):

Protocol header
<req>
  <host>Name of host in Zabbix database</host>
  <key>Name of metric</key>
  <data>String value of the metric</data>
  <lastlogsize>Size of logfile (for log monitoring)</lastlogsize>
  <timestamp>Timestamp for the metric value (for Windows eventlog)</timestamp>
  <source>Name of logged data source (for Windows eventlog)</source>
  <severity>Severity of logged data source (for Windows eventlog)</severity>
</req>

The 'host', 'key' and 'data' elements are required, all other elements are optional. When the 'timestamp' element is present, the 'source' and 'severity' elements are also required. The data in all elements must be base64 encoded to ensure that there is no possibility of characters that need to be escaped in the XML. The Zabbix server does not use a real XML parser, so using short close tags like <timestamp/> is not allowed. When an element is empty, do not include it in the XML unless it is required by the above rules. In that case leave it empty but use the long format as above.

The encoded form of the data in the elements must not exceed 2048 characters (or whatever is set in ZBX_MAX_B64_LEN). When an item requested by the server is not supported by the agent, send the literal string ZBX_NOTSUPPORTED in the 'data' element of the message. The agent is then no longer required to send data for that item until the server includes it in the active checks list again (when an administrator has re-enabled the item, for example).

The client is expected to periodically request a new list of active checks to report, at your leisure. Do not request this list too often in order to not hammer the Zabbix server (it may have to support hundreds or thousands of clients). Anywhere between 2 minutes (default) and 10 minutes seems appropriate for most environments.

Implementations of the protocol

Java

Implementation of the Zabbix protocol in Java can be found on the Zapcat page.