Table of Contents

Server-proxy data exchange protocol

Server-proxy data exchange protocol

Overview

Server - proxy data exchange is based on JSON format.

Passive proxy

Proxy config request

The proxy config request is sent by server to provide proxy configuration data. This request is sent every ProxyConfigFrequency (server configuration parameter) seconds.

name				value type	description
server→proxy:
request				string	'proxy config'
<table>				object	one or more objects with <table> data
	fields			array	array of field names
		-		string	field name
	data			array	array of rows
		-		array	array of columns
			-	string,number	column value with type depending on column type in database schema
proxy→server:
response				string	the request success information ('success' or 'failed')

Example:

server→proxy:

{
           "globalmacro":{
               "fields":[
                   "globalmacroid",
                   "macro",
                   "value"
               ],
               "data":[
                   [
                       2,
                       "{$SNMP_COMMUNITY}",
                       "public"
                   ]
               ]
           },
           "hosts":{
               "fields":[
                   "hostid",
                   "host",
                   "status",
                   "ipmi_authtype",
                   "ipmi_privilege",
                   "ipmi_username",
                   "ipmi_password",
                   "name",
                   "tls_connect",
                   "tls_accept",
                   "tls_issuer",
                   "tls_subject",
                   "tls_psk_identity",
                   "tls_psk"
               ],
               "data":[
                   [
                       10001,
                       "Template OS Linux",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Template OS Linux",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10050,
                       "Template App Zabbix Agent",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Template App Zabbix Agent",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10105,
                       "Logger",
                       0,
                       -1,
                       2,
                       "",
                       "",
                       "Logger",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ]
               ]
           },
           "interface":{
               "fields":[
                   "interfaceid",
                   "hostid",
                   "main",
                   "type",
                   "useip",
                   "ip",
                   "dns",
                   "port",
                   "bulk"
               ],
               "data":[
                   [
                       2,
                       10105,
                       1,
                       1,
                       1,
                       "127.0.0.1",
                       "",
                       "10050",
                       1
                   ]
               ]
           },
           ...
       }

proxy→server:

{
         "response": "success"
       }

Host availability request

The host availability request is used to obtain host availability data from proxy. This request is sent every ProxyDataFrequency (server configuration parameter) seconds.

name		value type	description
server→proxy:
request		string	'host availability'
proxy→server:
data		array	array of host availability data objects
	hostid	number	host identifier
	available	number	Zabbix agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	error	string	Zabbix agent error message or empty string
	snmp_available	number	SNMP agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	snmp_error	string	SNMP agent error message or empty string
	ipmi_available	number	IPMI agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	ipmi_error	string	IPMI agent error message or empty string
	jmx_available	number	JMX agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	jmx_error	string	JMX agent error message or empty string
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

server→proxy:

{
         "request": "host availability"
       }

proxy→server:

{
         "data": [
           {
             "hostid": 10106,
             "available": 1,
             "error": "",
             "snmp_available": 0,
             "snmp_error": "",
             "ipmi_available": 0,
             "ipmi_error": "",
             "jmx_available": 0,
             "jmx_error": ""
           },
           {
             "hostid": 10107,
             "available": 1,
             "error": "",
             "snmp_available": 0,
             "snmp_error": "",
             "ipmi_available": 0,
             "ipmi_error": "",
             "jmx_available": 0,
             "jmx_error": ""
           }
         ]
       }

server→proxy:

{
         "response": "success"
       }

History data request

The history data request is used to obtain item history data from proxy. This request is sent every ProxyDataFrequency (server configuration parameter) seconds.

name		value type	description
server→proxy:
request		string	'history data'
proxy→server:
data		array	array of history data objects
	host	number	host identifier
	key	number	item key
	clock	number	item value timestamp (seconds)
	ns	number	item value timestamp (nanoseconds)
	value	string	(optional) item value
	timestamp	number	(optional) timestamp of log type items
	source	string	(optional) eventlog item source value
	severity	number	(optional) eventlog item severity value
	eventid	number	(optional) eventlog item eventid value
	state	string	(optional) item state 0, ITEM_STATE_NORMAL 1, ITEM_STATE_NOTSUPPORTED
	lastlogsize	number	(optional) last log size of log type items
	mtime	number	(optional) modify time of log type items
clock		number	data transfer timestamp (seconds)
ns		number	data transfer timestamp (nanoseconds)
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

server→proxy:

{
         "request": "history data"
       }

proxy→server:

{
           "data":[
               {
                   "host":"Logger1",
                   "key":"system.cpu.switches",
                   "clock":1478609647,
                   "ns":332510044,
                   "value":"52956612"
               },
               {
                   "host":"Logger2",
                   "key":"net.if.in[vboxnet0]",
                   "clock":1478609647,
                   "ns":330690279,
                   "state":1,
                   "value":"Cannot find information for this network interface in /proc/net/dev."
               }
           ],
           "clock":1478609648,
           "ns":157729208
       }

server→proxy:

{
         "response": "success"
       }

Discovery data request

The discovery data request is used to obtain network discovery data from proxy. This request is sent every ProxyDataFrequency (server configuration parameter) seconds.

name		value type	description
server→proxy:
request		string	'discovery data'
proxy→server:
data		array	array of discovery data objects
	clock	number	the discovery data timestamp
	druleid	number	the discovery rule identifier
	dcheckid	number	the discovery check indentifier or null for discovery rule data
	type	number	the discovery check type: -1 discovery rule data 0, SVC_SSH - SSH service check 1, SVC_LDAP - LDAP service check 2, SVC_SMTP - SMTP service check 3, SVC_FTP - FTP service check 4, SVC_HTTP - HTTP service check 5, SVC_POP - POP service check 6, SVC_NNTP - NNTP service check 7, SVC_IMAP - IMAP service check 8, SVC_TCP - TCP port availability check 9, SVC_AGENT - Zabbix agent 10, SVC_SNMPv1 - SNMPv1 agent 11, SVC_SNMPv2 - SNMPv2 agent 12, SVC_ICMPPING - ICMP ping 13, SVC_SNMPv3 - SNMPv3 agent 14, SVC_HTTPS - HTTPS service check 15, SVC_TELNET - Telnet availability check
	ip	string	the host IP address
	dns	string	the host DNS name
	port	number	(optional) service port number
	key_	string	(optional) the item key for discovery check of type 9 SVC_AGENT
	value	string	(optional) value received from the service, can be empty for most of services
	status	number	(optional) service status: 0, DOBJECT_STATUS_UP - Service UP 1, DOBJECT_STATUS_DOWN - Service DOWN
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

server→proxy:

{
         "request": "discovery data"
       }

proxy→server:

{
           "data":[
               {
                   "clock":1478608764,
                   "drule":2,
                   "dcheck":3,
                   "type":12,
                   "ip":"10.3.0.10",
                   "dns":"vdebian",
                   "status":1
               },
               {
                   "clock":1478608764,
                   "drule":2,
                   "dcheck":null,
                   "type":-1,
                   "ip":"10.3.0.10",
                   "dns":"vdebian",
                   "status":1
               }
           ],
           "clock":1478608768
       }

server→proxy:

{
         "response": "success"
       }

Auto registration data request

The auto registration request is used to obtain agent auto registration data from proxy. This request is sent every ProxyDataFrequency (server configuration parameter) seconds.

name		value type	description
server→proxy:
request		string	'auto registration'
proxy→server:
data		array	array of auto registration data objects
	clock	number	the auto registration data timestamp
	host	string	the host name
	ip	string	(optional) the host IP address
	dns	string	(optional) the resolved DNS name from IP address
	port	string	(optional) the host port
	host_metadata	string	(optional) the host metadata sent by agent (based on HostMetadata or HostMetadataItem agent configuration parameter)
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

server→proxy:

{
         "request": "auto registration"
       }

proxy→server:

{
           "data": [
               {
                   "clock": 1478608371,
                   "host": "Logger1",
                   "ip": "10.3.0.1",
                   "dns": "localhost",
                   "port": "10050"
               },
               {
                   "clock": 1478608381,
                   "host": "Logger2",
                   "ip": "10.3.0.2",
                   "dns": "localhost",
                   "port": "10050"
               }
           ],
           "clock": 1478608390
       }

server→proxy:

{
         "response": "success"
       }

Active proxy

Proxy heartbeat request

The proxy heartbeat request is sent by proxy to report that proxy is running. This request is sent every HeartbeatFrequency (proxy configuration parameter) seconds.

name	value type	description
proxy→server:
request	string	'proxy heartbeat'
host	string	the proxy name
server→proxy:
response	string	the request success information ('success' or 'failed')

proxy→server:

{
          "request": "proxy heartbeat",
          "host": "Proxy #12"
       }

server→proxy:

{
         "response": "success"
       }

Proxy config request

The proxy config request is sent by proxy to obtain proxy configuration data. This request is sent every ConfigFrequency (proxy configuration parameter) seconds.

name				value type	description
proxy→server:
request				string	'proxy config'
host				string	proxy name
server→proxy:
request				string	'proxy config'
<table>				object	one or more objects with <table> data
	fields			array	array of field names
		-		string	field name
	data			array	array of rows
		-		array	array of columns
			-	string,number	column value with type depending on column type in database schema
proxy→server:
response				string	the request success information ('success' or 'failed')

Example:

proxy→server:

{
         "request": "proxy config",
         "host": "Proxy #12",
       }

server→proxy:

{
           "globalmacro":{
               "fields":[
                   "globalmacroid",
                   "macro",
                   "value"
               ],
               "data":[
                   [
                       2,
                       "{$SNMP_COMMUNITY}",
                       "public"
                   ]
               ]
           },
           "hosts":{
               "fields":[
                   "hostid",
                   "host",
                   "status",
                   "ipmi_authtype",
                   "ipmi_privilege",
                   "ipmi_username",
                   "ipmi_password",
                   "name",
                   "tls_connect",
                   "tls_accept",
                   "tls_issuer",
                   "tls_subject",
                   "tls_psk_identity",
                   "tls_psk"
               ],
               "data":[
                   [
                       10001,
                       "Template OS Linux",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Template OS Linux",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10050,
                       "Template App Zabbix Agent",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Template App Zabbix Agent",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10105,
                       "Logger",
                       0,
                       -1,
                       2,
                       "",
                       "",
                       "Logger",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ]
               ]
           },
           "interface":{
               "fields":[
                   "interfaceid",
                   "hostid",
                   "main",
                   "type",
                   "useip",
                   "ip",
                   "dns",
                   "port",
                   "bulk"
               ],
               "data":[
                   [
                       2,
                       10105,
                       1,
                       1,
                       1,
                       "127.0.0.1",
                       "",
                       "10050",
                       1
                   ]
               ]
           },
           ...
       }

proxy→server:

{
         "response": "success"
       }

Host availability request

The host availability request is sent by proxy to provide host availability data. This request is sent every DataSenderFrequency (proxy configuration parameter) seconds.

name		value type	description
proxy→server:
request		string	'host availability'
host		string	the proxy name
data		array	array of host availability data objects
	hostid	number	host identifier
	available	number	Zabbix agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	error	string	Zabbix agent error message or empty string
	snmp_available	number	SNMP agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	snmp_error	string	SNMP agent error message or empty string
	ipmi_available	number	IPMI agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	ipmi_error	string	IPMI agent error message or empty string
	jmx_available	number	JMX agent availability 0, HOST_AVAILABLE_UNKNOWN - unknown 1, HOST_AVAILABLE_TRUE - available 2, HOST_AVAILABLE_FALSE - unavailable
	jmx_error	string	JMX agent error message or empty string
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

proxy→server:

{
         "request": "host availability",
         "host": "Proxy #12", 
         "data": [
           {
             "hostid": 10106,
             "available": 1,
             "error": "",
             "snmp_available": 0,
             "snmp_error": "",
             "ipmi_available": 0,
             "ipmi_error": "",
             "jmx_available": 0,
             "jmx_error": ""
           },
           {
             "hostid": 10107,
             "available": 1,
             "error": "",
             "snmp_available": 0,
             "snmp_error": "",
             "ipmi_available": 0,
             "ipmi_error": "",
             "jmx_available": 0,
             "jmx_error": ""
           }
         ]
       }

server→proxy:

{
         "response": "success"
       }

History data request

The history data request is sent by proxy to provide item history data. This request is sent every DataSenderFrequency (proxy configuration parameter) seconds.

name		value type	description
proxy→server:
request		string	'history data'
host		string	the proxy name
data		array	array of history data objects
	host	number	host identifier
	key	number	item key
	clock	number	item value timestamp (seconds)
	ns	number	item value timestamp (nanoseconds)
	value	string	(optional) item value
	timestamp	number	(optional) timestamp of log type items
	source	string	(optional) eventlog item source value
	severity	number	(optional) eventlog item severity value
	eventid	number	(optional) eventlog item eventid value
	state	string	(optional) item state 0, ITEM_STATE_NORMAL 1, ITEM_STATE_NOTSUPPORTED
	lastlogsize	number	(optional) last log size of log type items
	mtime	number	(optional) modify time of log type items
clock		number	data transfer timestamp (seconds)
ns		number	data transfer timestamp (nanoseconds)
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

proxy→server:

{
           "request": "history data",
           "host": "Proxy #12", 
           "data":[
               {
                   "host":"Logger1",
                   "key":"system.cpu.switches",
                   "clock":1478609647,
                   "ns":332510044,
                   "value":"52956612"
               },
               {
                   "host":"Logger2",
                   "key":"net.if.in[vboxnet0]",
                   "clock":1478609647,
                   "ns":330690279,
                   "state":1,
                   "value":"Cannot find information for this network interface in /proc/net/dev."
               }
           ],
           "clock":1478609648,
           "ns":157729208
       }

server→proxy:

{
         "response": "success"
       }

Discovery data request

The discovery data request is sent by proxy to provide network discovery data. This request is sent every DataSenderFrequency (proxy configuration parameter) seconds.

name		value type	description
proxy→server:
request		string	'discovery data'
host		string	the proxy name
data		array	array of discovery data objects
	clock	number	the discovery data timestamp
	druleid	number	the discovery rule identifier
	dcheckid	number	the discovery check indentifier or null for discovery rule data
	type	number	the discovery check type: -1 discovery rule data 0, SVC_SSH - SSH service check 1, SVC_LDAP - LDAP service check 2, SVC_SMTP - SMTP service check 3, SVC_FTP - FTP service check 4, SVC_HTTP - HTTP service check 5, SVC_POP - POP service check 6, SVC_NNTP - NNTP service check 7, SVC_IMAP - IMAP service check 8, SVC_TCP - TCP port availability check 9, SVC_AGENT - Zabbix agent 10, SVC_SNMPv1 - SNMPv1 agent 11, SVC_SNMPv2 - SNMPv2 agent 12, SVC_ICMPPING - ICMP ping 13, SVC_SNMPv3 - SNMPv3 agent 14, SVC_HTTPS - HTTPS service check 15, SVC_TELNET - Telnet availability check
	ip	string	the host IP address
	dns	string	the host DNS name
	port	number	(optional) service port number
	key_	string	(optional) the item key for discovery check of type 9 SVC_AGENT
	value	string	(optional) value received from the service, can be empty for most of services
	status	number	(optional) service status: 0, DOBJECT_STATUS_UP - Service UP 1, DOBJECT_STATUS_DOWN - Service DOWN
server→proxy:
response		string	the request success information ('success' or 'failed')

Example:

proxy→server:

{
          "request": "discovery data",
          "host": "Proxy #12", 
          "data":[
               {
                   "clock":1478608764,
                   "drule":2,
                   "dcheck":3,
                   "type":12,
                   "ip":"10.3.0.10",
                   "dns":"vdebian",
                   "status":1
               },
               {
                   "clock":1478608764,
                   "drule":2,
                   "dcheck":null,
                   "type":-1,
                   "ip":"10.3.0.10",
                   "dns":"vdebian",
                   "status":1
               }
           ],
           "clock":1478608768
       }

server→proxy:

{
         "response": "success"
       }

Auto registration data request

The auto registration request is sent by proxy to provide agent auto registration data data. This request is sent every DataSenderFrequency (proxy configuration parameter) seconds.

name		value type	description
proxy→server:
request		string	'auto registration'
host		string	the proxy name
data		array	array of auto registration data objects
	clock	number	the auto registration data timestamp
	host	string	the host name
	ip	string	(optional) the host IP address
	dns	string	(optional) the resolved DNS name from IP address
	port	string	(optional) the host port
	host_metadata	string	(optional) the host metadata sent by agent (based on HostMetadata or HostMetadataItem agent configuration parameter)
server→proxy:
response		string	the request success information ('success' or 'failed')

proxy→server:

{
          "request": "auto registration",
          "host": "Proxy #12", 
          "data": [
               {
                   "clock": 1478608371,
                   "host": "Logger1",
                   "ip": "10.3.0.1",
                   "dns": "localhost",
                   "port": "10050"
               },
               {
                   "clock": 1478608381,
                   "host": "Logger2",
                   "ip": "10.3.0.2",
                   "dns": "localhost",
                   "port": "10050"
               }
           ],
           "clock": 1478608390
       }

server→proxy:

{
         "response": "success"
       }

Documentation

Server-proxy data exchange protocol

Overview

Passive proxy

Proxy config request

Host availability request

History data request

Discovery data request

Auto registration data request

Active proxy

Proxy heartbeat request

Proxy config request

Host availability request

History data request

Discovery data request

Auto registration data request