Documentation

You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

Sidebar

Zabbix Summit 2022
Register for Zabbix Summit 2022

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 Request success information ('success' or 'failed').
version string 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) Modification time of log type items.
discovery data array (optional) Array of discovery data objects.
clock number Discovery data timestamp.
druleid number Discovery rule identifier.
dcheckid number Discovery check identifier or null for discovery rule data.
type number 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 Host IP address.
dns string Host DNS name.
port number (optional) Service port number.
key_ string (optional) 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 Autoregistration data timestamp.
host string Host name.
ip string (optional) Host IP address.
dns string (optional) Resolved DNS name from IP address.
port string (optional) Host port.
host_metadata string (optional) Host metadata sent by agent (based on HostMetadata or HostMetadataItem agent configuration parameter).
tasks array (optional) Array of tasks.
type number Task type:

0, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND_RESULT - remote command result
status number Remote-command execution status:

0, ZBX_TM_REMOTE_COMMAND_COMPLETED - remote command completed successfully
1, ZBX_TM_REMOTE_COMMAND_FAILED - remote command failed
error string (optional) Error message.
parent_taskid number 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 Proxy version (<major>.<minor>.<build>).
server→proxy:
response string Request success information ('success' or 'failed').
tasks array (optional) Array of tasks.
type number Task type:

1, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND - remote command
clock number Task creation time.
ttl number Time in seconds after which the task expires.
commandtype number 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 Remote command to execute.
execute_on number 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) Port for Telnet and SSH commands.
authtype number (optional) Authentication type for SSH commands.
username string (optional) User name for Telnet and SSH commands.
password string (optional) Password for Telnet and SSH commands.
publickey string (optional) Public key for SSH commands.
privatekey string (optional) Private key for SSH commands.
parent_taskid number Parent task ID.
hostid number Target host ID.

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 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 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 the column type in database schema.
proxy→server:
response string 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 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) Modification time of log type items.
discovery data array (optional) Array of discovery data objects.
clock number Discovery data timestamp.
druleid number Discovery rule identifier.
dcheckid number Discovery check identifier or null for discovery rule data.
type number 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 Host IP address.
dns string Host DNS name.
port number (optional) Service port number.
key_ string (optional) Item key for discovery check of type 9 SVC_AGENT
value string (optional) Value received from the service, can be empty for most services.
status number (optional) Service status:

0, DOBJECT_STATUS_UP - Service UP
1, DOBJECT_STATUS_DOWN - Service DOWN
autoregistration array (optional) Array of autoregistration data objects.
clock number Autoregistration data timestamp.
host string Host name.
ip string (optional) Host IP address.
dns string (optional) Resolved DNS name from IP address.
port string (optional) Host port.
host_metadata string (optional) Host metadata sent by agent (based on HostMetadata or HostMetadataItem agent configuration parameter).
tasks array (optional) Array of tasks.
type number Task type:

0, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND_RESULT - remote command result
status number Remote-command execution status:

0, ZBX_TM_REMOTE_COMMAND_COMPLETED - remote command completed successfully
1, ZBX_TM_REMOTE_COMMAND_FAILED - remote command failed
error string (optional) Error message.
parent_taskid number 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 Proxy version (<major>.<minor>.<build>).
server→proxy:
response string Request success information ('success' or 'failed').
upload string Upload control for historical data (history, autoregistration, host availability, network discovery):
enabled - normal operation
disabled - server is not accepting data (possibly due to internal cache over limit)
tasks array (optional) Array of tasks.
type number Task type:

1, ZBX_TM_TASK_PROCESS_REMOTE_COMMAND - remote command
clock number Task creation time.
ttl number Time in seconds after which the task expires.
commandtype number 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 Remote command to execute.
execute_on number 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) Port for Telnet and SSH commands.
authtype number (optional) Authentication type for SSH commands.
username string (optional) User name for Telnet and SSH commands.
password string (optional) Password for Telnet and SSH commands.
publickey string (optional) Public key for SSH commands.
privatekey string (optional) Private key for SSH commands.
parent_taskid number Parent task ID.
hostid number Target host ID.

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",
         "upload": "enabled",
         "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
             }
         ]
       }