The Zabbix get protocol is really simple and easy to implement. Practically, you only need to send data to your Zabbix server at the port 10050.

This protocol is so simple that you can implement it with a shell script as well:

This is a textual protocol and is used to retrieve data from the agent directly. [root@zabbixserver]# telnet 127.0.0.1 10050
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
agent.version
ZBXD2.0.6Connection closed by foreign host.

This example shows you how to retrieve the agent version simply with a telnet. Please note that the data is returned with a header that is ZBXD, followed by the data that represents the actual response 2.0.6.

This simple protocol is useful to retrieve data directly from the agent installed into our server and use it in a shell script.

This protocol is useful to identify the agent version without logging on to the server and to check all the instances of UserParameter defined against an agent.

The Zabbix sender protocol is a JSON-based protocol. The message composition is the following:

<HEADER><DATA_LENGTH><DATA>

The <HEADER> section is of 5 bytes, and it is in the form ZBXDx01. Actually, only the first 4 bytes are the header; the next byte is used to specify the protocol version. Currently, only Version 1 is supported (0 x 01 HEX).

The <DATA_LENGTH> section is 8 bytes in length and in the hex format. So, for instance, 1 is formatted as 01/00/00/00/00/00/00/00, an 8-byte (or 64-bit) number in the hex format.

It is followed by <DATA>. This section is expressed in the JSON format.

To send the value, the JSON message needs to be in the following form:

<HEADER><DATALEN>{
  "request":"sender data",
  "data":[
  {
    "host":"Host name 1",
    "key":"item_key",
    "value":"XXX",
    "clock":unix_time_format
  },

  {
    "host":"Host name 2",
    "key":"item_key",
    "value":"YYY"
  }
  ], 
"clock":unix_time_format
}

In the previous example, as you can see, multiple items are queued on the same message if they come from different hosts or are referred to as different item keys.

Once all the items are received, the server will send back the response. The response has the following structure:

<HEADER><DATALEN>{ 
  "response":"success",
  "info":"Processed 6 Failed 1 Total 7 Seconds spent 0.000283"
}

This example reports a response message; the following are some considerations:

Unfortunately, this protocol does not give you feedback on which items failed and the reason for failure. At the time of writing this, there are two requested features that are still pending:

Now you know how the Zabbix sender protocol works on version 1.8 and higher.

Another issue is that the Zabbix sender protocol until now doesn't support any kind of encryption, which can cause an issue in the case of sensitive data that is sent in clear text. We also need to consider the case of a hacker who would like to hide his activity behind a large number of alarms or triggers on fire. With this protocol, the hacker can easily send a false alarm in order to set the trigger on fire and then proceed with his activity unnoticed.

Fortunately, this feature has now been taken into consideration, and the team is working on an SSL version or, better, a TLS version.

For more information, you can have a look at the ticket at https://support.zabbix.com/browse/ZBXNEXT-1263.

zbx_json_addobject(&sentdval_args.json, NULL);
zbx_json_addstring(&sentdval_args.json, ZBX_PROTO_TAG_HOST, hostname, ZBX_JSON_TYPE_STRING);
zbx_json_addstring(&sentdval_args.json, ZBX_PROTO_TAG_KEY, key, ZBX_JSON_TYPE_STRING);
zbx_json_addstring(&sentdval_args.json, ZBX_PROTO_TAG_VALUE, key_value, ZBX_JSON_TYPE_STRING);

"host":"Host name 1",
"key":"item_key",
"value":"XXX",

if (1 == WITH_TIMESTAMPS)
   zbx_json_adduint64(&sentdval_args.json, ZBX_PROTO_TAG_CLOCK, atoi(clock));

zbx_json_close(&sentdval_args.json);

This protocol is a bit more complex because it involves more phases and the dialogue is more articulated. When an active agent starts, the first thing it does is connect to the server and ask for a task to perform, in particular, which item is to be retrieved and the relative timing.

Also, in the following code, the form of the protocol is the same as used previously:

<HEADER><DATA_LENGTH><DATA>

The <HEADER>, <DATA_LENGTH>, and <DATA> tags are as explained in the previous section.

The dialogue begins when the agent sends the following request to the server:

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

With this kind of request, the agent is going to ask for a specified hostname in the active checklist. The server response will, for instance, be as follows:

<HEADER><DATALEN>{
  "response":"success",
  "data":[{
    "key":"log[/var/log/localmessages,@errors]",
    "delay":1,
    "lastlogsize":12189,
    "mtime":0
  },
  {
    "key":"agent.version",
    "delay":"900"
    }]
"regexp":[
  {
    "name":"errors",
    "expression":"error",
    "expression_type":0,
    "exp_delimiter":",",
    "case_sensitive":1
  }]
}

The Zabbix server must respond with success, followed by the list of items and the relative delay.

"regexp", which, in this example, is the response back to the agent, will exist only if you have defined global or regular expressions. Note that if a user macro is used, the parameter key is resolved and the original key is sent as key_orig. The original key is the user macro name.

Once the response is received, the agent will close the TCP connection and will parse it. Now, the agent will start to collect the items at their specified period. Once collected, the items will be sent back to the server:

<HEADER><DATALEN>{
   "request":"agent data",
   "data":[
       {
            "host":"HOSTNAME",
"key":"log[/var/log/localmessages]",
"value":"Sep 16 18:26:44 linux-h5fr dhcpcd[3732]: eth0: adding default route via 192.168.1.1 metric 0",
"lastlogsize":4315,
"clock":1360314499,
"ns":699351525
},       
       {
           "host":"<hostname>",
           "key":"agent.version",
           "value":"2.0.1",
           "clock":1252926015
       }
   ],
   "clock":1252926016
}

The server will respond with:

{
  "response":"success",
  "info":"Processed 2 Failed 0 Total 2 Seconds spent 0.000110"
}

Also, there is a possibility that some items have not been accepted, but, currently, there isn't a way to know which ones they are.

<HEADER><DATALEN>{
  "response":"failed",
  "info":"host [Host name] not monitored"
}

<HEADER><DATALEN>{
  "response":"failed",
  "info":"host [Host name] not found"
}

<HEADER><DATALEN>{
  "response":"success",
  "data":[]
}