# 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:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**error**|*string*|Zabbix agent error message or empty string|
|<|**snmp\_available**|*number*|SNMP agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**snmp\_error**|*string*|SNMP agent error message or empty string|
|<|**ipmi\_available**|*number*|IPMI agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**ipmi\_error**|*string*|IPMI agent error message or empty string|
|<|**jmx\_available**|*number*|JMX agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**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:

``` {.javascript}
{
  "request": "host availability"
}
```

proxy→server:

``` {.javascript}
{
  "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:

``` {.javascript}
{
  "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<br>**0**, *ITEM\_STATE\_NORMAL*<br>**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:

``` {.javascript}
{
  "request": "history data"
}
```

proxy→server:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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:<br><br>**-1** discovery rule data<br>**0**, *SVC\_SSH* - SSH service check<br>**1**, *SVC\_LDAP* - LDAP service check<br>**2**, *SVC\_SMTP* - SMTP service check<br>**3**, *SVC\_FTP* - FTP service check<br>**4**, *SVC\_HTTP* - HTTP service check<br>**5**, *SVC\_POP* - POP service check<br>**6**, *SVC\_NNTP* - NNTP service check<br>**7**, *SVC\_IMAP* - IMAP service check<br>**8**, *SVC\_TCP* - TCP port availability check<br>**9**, *SVC\_AGENT* - Zabbix agent<br>**10**, *SVC\_SNMPv1* - SNMPv1 agent<br>**11**, *SVC\_SNMPv2* - SNMPv2 agent<br>**12**, *SVC\_ICMPPING* - ICMP ping<br>**13**, *SVC\_SNMPv3* - SNMPv3 agent<br>**14**, *SVC\_HTTPS* - HTTPS service check<br>**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:<br><br>**0**, *DOBJECT\_STATUS\_UP* - Service UP<br>**1**, *DOBJECT\_STATUS\_DOWN* - Service DOWN|
|server→proxy:|<|<|<|
|**response**|<|*string*|the request success information ('success' or 'failed')|

Example:

server→proxy:

``` {.javascript}
{
  "request": "discovery data"
}
```

proxy→server:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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:

``` {.javascript}
{
  "request": "auto registration"
}
```

proxy→server:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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:

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

server→proxy:

``` {.javascript}
{
  "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:

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

server→proxy:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**error**|*string*|Zabbix agent error message or empty string|
|<|**snmp\_available**|*number*|SNMP agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**snmp\_error**|*string*|SNMP agent error message or empty string|
|<|**ipmi\_available**|*number*|IPMI agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**2**, *HOST\_AVAILABLE\_FALSE* - unavailable|
|<|**ipmi\_error**|*string*|IPMI agent error message or empty string|
|<|**jmx\_available**|*number*|JMX agent availability<br><br>**0**, *HOST\_AVAILABLE\_UNKNOWN* - unknown<br>**1**, *HOST\_AVAILABLE\_TRUE* - available<br>**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:

``` {.javascript}
{
  "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:

``` {.javascript}
{
  "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<br>**0**, *ITEM\_STATE\_NORMAL*<br>**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:

``` {.javascript}
{
    "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:

``` {.javascript}
{
  "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:<br><br>**-1** discovery rule data<br>**0**, *SVC\_SSH* - SSH service check<br>**1**, *SVC\_LDAP* - LDAP service check<br>**2**, *SVC\_SMTP* - SMTP service check<br>**3**, *SVC\_FTP* - FTP service check<br>**4**, *SVC\_HTTP* - HTTP service check<br>**5**, *SVC\_POP* - POP service check<br>**6**, *SVC\_NNTP* - NNTP service check<br>**7**, *SVC\_IMAP* - IMAP service check<br>**8**, *SVC\_TCP* - TCP port availability check<br>**9**, *SVC\_AGENT* - Zabbix agent<br>**10**, *SVC\_SNMPv1* - SNMPv1 agent<br>**11**, *SVC\_SNMPv2* - SNMPv2 agent<br>**12**, *SVC\_ICMPPING* - ICMP ping<br>**13**, *SVC\_SNMPv3* - SNMPv3 agent<br>**14**, *SVC\_HTTPS* - HTTPS service check<br>**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:<br><br>**0**, *DOBJECT\_STATUS\_UP* - Service UP<br>**1**, *DOBJECT\_STATUS\_DOWN* - Service DOWN|
|server→proxy:|<|<|<|
|**response**|<|*string*|the request success information ('success' or 'failed')|

Example:

proxy→server:

``` {.javascript}
{
   "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:

``` {.javascript}
{
  "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:

``` {.javascript}
{
   "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:

``` {.javascript}
{
  "response": "success"
}
```