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
             }
         ]
       }