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