Table of Contents

1 Server-proxy data exchange protocol

1 Server-proxy data exchange protocol

Overview

Server - proxy data exchange is based on JSON format.

Request and response messages must begin with header and data length.

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')
version				string	the proxy version (<major>.<minor>.<build>)

Example:

server→proxy:

{
           "request": "proxy config",
           "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,
                       "Linux",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Linux",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10050,
                       "Zabbix Agent",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "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",
         "version": "5.4.0"
       }

Proxy request

The proxy data request is used to obtain host interface availability, historical, discovery and autoregistration data from proxy. This request is sent every ProxyDataFrequency (server configuration parameter) seconds.

name		value type	description
server→proxy:
request		string	'proxy data'
proxy→server:
session		string	data session token
interface availability		array	(optional) array of interface availability data objects
	interfaceid	number	interface identifier
	available	number	Interface availability 0, INTERFACE_AVAILABLE_UNKNOWN - unknown 1, INTERFACE_AVAILABLE_TRUE - available 2, INTERFACE_AVAILABLE_FALSE - unavailable
	error	string	Interface error message or empty string
history data		array	(optional) array of history data objects
	itemid	number	item identifier
	clock	number	item value timestamp (seconds)
	ns	number	item value timestamp (nanoseconds)
	value	string	(optional) item value
	id	number	value identifier (ascending counter, unique within one data session)
	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
discovery data		array	(optional) array of discovery data objects
	clock	number	the discovery data timestamp
	druleid	number	the discovery rule identifier
	dcheckid	number	the discovery check identifier 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
auto registration		array	(optional) array of autoregistration data objects
	clock	number	the autoregistration 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)
tasks		array	(optional) array of tasks
	type	number	the task type: 0, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND_RESULT - remote command result
	status	number	the remote command execution status: 0, ZBX_TM_REMOTE_COMMAND_COMPLETED - the remote command completed successfully 1, ZBX_TM_REMOTE_COMMAND_FAILED - the remote command failed
	error	string	(optional) the error message
	parent_taskid	number	the parent task id
more		number	(optional) 1 - there are more history data to send
clock		number	(optional) data transfer timestamp (seconds)
ns		number	(optional) data transfer timestamp (nanoseconds)
version		string	the proxy version (<major>.<minor>.<build>)
server→proxy:
response		string	the request success information ('success' or 'failed')
tasks		array	(optional) array of tasks
	type	number	the task type: 1, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND - remote command
	clock	number	the task creation time
	ttl	number	the time in seconds after which task expires
	commandtype	number	the remote command type: 0, ZBX_SCRIPT_TYPE_CUSTOM_SCRIPT - use custom script 1, ZBX_SCRIPT_TYPE_IPMI - use IPMI 2, ZBX_SCRIPT_TYPE_SSH - use SSH 3, ZBX_SCRIPT_TYPE_TELNET - use Telnet 4, ZBX_SCRIPT_TYPE_GLOBAL_SCRIPT - use global script (currently functionally equivalent to custom script)
	command	string	the remote command to execute
	execute_on	number	the execution target for custom scripts: 0, ZBX_SCRIPT_EXECUTE_ON_AGENT - execute script on agent 1, ZBX_SCRIPT_EXECUTE_ON_SERVER - execute script on server 2, ZBX_SCRIPT_EXECUTE_ON_PROXY - execute script on proxy
	port	number	(optional) the port for telnet and ssh commands
	authtype	number	(optional) the authentication type for ssh commands
	username	string	(optional) the user name for telnet and ssh commands
	password	string	(optional) the password for telnet and ssh commands
	publickey	string	(optional) the public key for ssh commands
	privatekey	string	(optional) the private key for ssh commands
	parent_taskid	number	the parent task id
	hostid	number	target hostid

Example:

server→proxy:

{
         "request": "proxy data"
       }

proxy→server:

{
           "session": "12345678901234567890123456789012"
           "interface availability": [
               {
                   "interfaceid": 1,
                   "available": 1,
                   "error": ""
           },
               {
                   "interfaceid": 2,
                   "available": 2,
                   "error": "Get value from agent failed: cannot connect to [[127.0.0.1]:10049]: [111] Connection refused"
           },
               {
                   "interfaceid": 3,
                   "available": 1,
                   "error": ""
           },
               {
                   "interfaceid": 4,
                   "available": 1,
                   "error": ""
           }
           ],
           "history data":[
               {
                   "itemid":"12345",
                   "clock":1478609647,
                   "ns":332510044,
                   "value":"52956612",
                   "id": 1
               },
               {
                   "itemid":"12346",
                   "clock":1478609647,
                   "ns":330690279,
                   "state":1,
                   "value":"Cannot find information for this network interface in /proc/net/dev.",
                   "id": 2
               }
           ],
           "discovery 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
               }
           ],
           "auto registration":[
               {
                   "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"
               }
           ],
           "tasks":[
               {
                   "type": 0,
                   "status": 0,
                   "parent_taskid": 10
               },
               {
                   "type": 0,
                   "status": 1,
                   "error": "No permissions to execute task.",
                   "parent_taskid": 20
               }
           ],    
           "version":"5.4.0"
       }

server→proxy:

{
         "response": "success",
         "tasks":[
             {
                "type": 1,
                "clock": 1478608371,
                "ttl": 600,
                "commandtype": 2,
                "command": "restart_service1.sh",
                "execute_on": 2,
                "port": 80,
                "authtype": 0,
                "username": "userA",
                "password": "password1",
                "publickey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqGKukO1De7zhZj6+H0qtjTkVxwTCpvKe",
                "privatekey": "lsuusFncCzWBQ7RKNUSesmQRMSGkVb1/3j+skZ6UtW+5u09lHNsj6tQ5QCqGKukO1De7zhd",
                "parent_taskid": 10,
                "hostid": 10070
             },
             {
                "type": 1,
                "clock": 1478608381,
                "ttl": 600,
                "commandtype": 1,
                "command": "restart_service2.sh",
                "execute_on": 0,
                "authtype": 0,
                "username": "",
                "password": "",
                "publickey": "",
                "privatekey": "",
                "parent_taskid": 20,
                "hostid": 10084
             }
         ]
       }

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
version	string	the proxy version (<major>.<minor>.<build>)
server→proxy:
response	string	the request success information ('success' or 'failed')

proxy→server:

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

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
version				string	the proxy version (<major>.<minor>.<build>)
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",
         "version":"5.4.0"
       }

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,
                       "Linux",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "Linux",
                       1,
                       1,
                       "",
                       "",
                       "",
                       ""
                   ],
                   [
                       10050,
                       "Zabbix Agent",
                       3,
                       -1,
                       2,
                       "",
                       "",
                       "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"
       }

Proxy data request

The proxy data request is sent by proxy to provide host interface availability, history, discovery and autoregistration data. This request is sent every DataSenderFrequency (proxy configuration parameter) seconds.

name		value type	description
proxy→server:
request		string	'proxy data'
host		string	the proxy name
session		string	data session token
interface availability		array	(optional) array of interface availability data objects
	interfaceid	number	interface identifier
	available	number	Interface availability 0, INTERFACE_AVAILABLE_UNKNOWN - unknown 1, INTERFACE_AVAILABLE_TRUE - available 2, INTERFACE_AVAILABLE_FALSE - unavailable
	error	string	Interface error message or empty string
history data		array	(optional) array of history data objects
	itemid	number	item identifier
	clock	number	item value timestamp (seconds)
	ns	number	item value timestamp (nanoseconds)
	value	string	(optional) item value
	id	number	value identifier (ascending counter, unique within one data session)
	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
discovery data		array	(optional) array of discovery data objects
	clock	number	the discovery data timestamp
	druleid	number	the discovery rule identifier
	dcheckid	number	the discovery check identifier 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
auto registration		array	(optional) array of autoregistration data objects
	clock	number	the autoregistration 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)
tasks		array	(optional) array of tasks
	type	number	the task type: 0, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND_RESULT - remote command result
	status	number	the remote command execution status: 0, ZBX_TM_REMOTE_COMMAND_COMPLETED - the remote command completed successfully 1, ZBX_TM_REMOTE_COMMAND_FAILED - the remote command failed
	error	string	(optional) the error message
	parent_taskid	number	the parent task id
more		number	(optional) 1 - there are more history data to send
clock		number	(optional) data transfer timestamp (seconds)
ns		number	(optional) data transfer timestamp (nanoseconds)
version		string	the proxy version (<major>.<minor>.<build>)
server→proxy:
response		string	the request success information ('success' or 'failed')
tasks		array	(optional) array of tasks
	type	number	the task type: 1, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND - remote command
	clock	number	the task creation time
	ttl	number	the time in seconds after which task expires
	commandtype	number	the remote command type: 0, ZBX_SCRIPT_TYPE_CUSTOM_SCRIPT - use custom script 1, ZBX_SCRIPT_TYPE_IPMI - use IPMI 2, ZBX_SCRIPT_TYPE_SSH - use SSH 3, ZBX_SCRIPT_TYPE_TELNET - use Telnet 4, ZBX_SCRIPT_TYPE_GLOBAL_SCRIPT - use global script (currently functionally equivalent to custom script)
	command	string	the remote command to execute
	execute_on	number	the execution target for custom scripts: 0, ZBX_SCRIPT_EXECUTE_ON_AGENT - execute script on agent 1, ZBX_SCRIPT_EXECUTE_ON_SERVER - execute script on server 2, ZBX_SCRIPT_EXECUTE_ON_PROXY - execute script on proxy
	port	number	(optional) the port for telnet and ssh commands
	authtype	number	(optional) the authentication type for ssh commands
	username	string	(optional) the user name for telnet and ssh commands
	password	string	(optional) the password for telnet and ssh commands
	publickey	string	(optional) the public key for ssh commands
	privatekey	string	(optional) the private key for ssh commands
	parent_taskid	number	the parent task id
	hostid	number	target hostid

Example:

proxy→server:

{
           "request": "proxy data",
           "host": "Proxy #12", 
           "session": "12345678901234567890123456789012",
           "interface availability": [
               {
                   "interfaceid": 1,
                   "available": 1,
                   "error": ""
           },
               {
                   "interfaceid": 2,
                   "available": 2,
                   "error": "Get value from agent failed: cannot connect to [[127.0.0.1]:10049]: [111] Connection refused"
           },
               {
                   "interfaceid": 3,
                   "available": 1,
                   "error": ""
           },
               {
                   "interfaceid": 4,
                   "available": 1,
                   "error": ""
           }
           ],
           "history data":[
               {
                   "itemid":"12345",
                   "clock":1478609647,
                   "ns":332510044,
                   "value":"52956612",
                   "id": 1
               },
               {
                   "itemid":"12346",
                   "clock":1478609647,
                   "ns":330690279,
                   "state":1,
                   "value":"Cannot find information for this network interface in /proc/net/dev.",
                   "id": 2
               }
           ],
           "discovery 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
               }
           ],
           "auto registration":[
               {
                   "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"
               }
           ],
           "tasks":[
               {
                   "type": 2,
                   "clock":1478608371,
                   "ttl": 600,
                   "commandtype": 2,
                   "command": "restart_service1.sh",
                   "execute_on": 2,
                   "port": 80,
                   "authtype": 0,
                   "username": "userA",
                   "password": "password1",
                   "publickey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqGKukO1De7zhZj6+H0qtjTkVxwTCpvKe",
                   "privatekey": "lsuusFncCzWBQ7RKNUSesmQRMSGkVb1/3j+skZ6UtW+5u09lHNsj6tQ5QCqGKukO1De7zhd",
                   "parent_taskid": 10,
                   "hostid": 10070
               },
               {
                   "type": 2,
                   "clock":1478608381,
                   "ttl": 600,
                   "commandtype": 1,
                   "command": "restart_service2.sh",
                   "execute_on": 0,
                   "authtype": 0,
                   "username": "",
                   "password": "",
                   "publickey": "",
                   "privatekey": "",
                   "parent_taskid": 20,
                   "hostid": 10084
               }
           ],
           "tasks":[
               {
                   "type": 0,
                   "status": 0,
                   "parent_taskid": 10
               },
               {
                   "type": 0,
                   "status": 1,
                   "error": "No permissions to execute task.",
                   "parent_taskid": 20
               }
           ], 
           "version":"5.4.0"
       }

server→proxy:

{
         "response": "success",
         "tasks":[
             {
                "type": 1,
                "clock": 1478608371,
                "ttl": 600,
                "commandtype": 2,
                "command": "restart_service1.sh",
                "execute_on": 2,
                "port": 80,
                "authtype": 0,
                "username": "userA",
                "password": "password1",
                "publickey": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqGKukO1De7zhZj6+H0qtjTkVxwTCpvKe",
                "privatekey": "lsuusFncCzWBQ7RKNUSesmQRMSGkVb1/3j+skZ6UtW+5u09lHNsj6tQ5QCqGKukO1De7zhd",
                "parent_taskid": 10,
                "hostid": 10070
             },
             {
                "type": 1,
                "clock": 1478608381,
                "ttl": 600,
                "commandtype": 1,
                "command": "restart_service2.sh",
                "execute_on": 0,
                "authtype": 0,
                "username": "",
                "password": "",
                "publickey": "",
                "privatekey": "",
                "parent_taskid": 20,
                "hostid": 10084
             }
         ]
       }

Documentation

1 Server-proxy data exchange protocol

Overview

Passive proxy

Proxy config request

Proxy request

Active proxy

Proxy heartbeat request

Proxy config request

Proxy data request