[comment]: # ({a6d31bd3-a6d31bd3})
# 2. Пассивные и активные проверки агента

[comment]: # ({/a6d31bd3-a6d31bd3})

[comment]: # ({1b7bc303-7bd0dd61})
#### Обзор

Этот раздел подробно описывает пассивные и активные проверки, которые выполняются [Zabbix агентом](/manual/concepts/agent) и [Zabbix агентом 2](/manual/concepts/agent2).

Для взаимодействия с агентами Zabbix использует коммуникационный протокол на основе JSON.

Протоколы Zabbix агента и Zabbix агента 2 были унифицированы, начиная с версии Zabbix 7.0. Отличие между запросами/ответами Zabbix агента и Zabbix агента 2 выражается значением тега «variant».

[comment]: # ({/1b7bc303-7bd0dd61})

[comment]: # ({f0a43b2b-e6db8dd6})
#### Пассивные проверки

Пассивная проверка — это простой запрос данных. Сервер Zabbix или прокси запрашивает
некоторые данные (например, загрузку CPU), а агент Zabbix отправляет
результат обратно на сервер.

Пассивные проверки выполняются асинхронно — не требуется получать ответ на один запрос до начала других проверок. Разрешение DNS также выполняется асинхронно.

Пуллер агента будет пытаться подключиться ко всем адресам, возвращенным DNS-поиском. Это гарантирует, что если один IP-адрес недоступен, пуллер попробует следующий доступный адрес, повышая вероятность успешного подключения. Это улучшение применяется как к серверу Zabbix, так и к прокси.

Максимальная параллельность асинхронных проверок составляет 1000 (определяется параметром [MaxConcurrentChecksPerPoller](/manual/appendix/config/zabbix_server#maxconcurrentchecksperpoller)).

Количество асинхронных пуллеров агента определяется параметром [StartAgentPollers](/manual/appendix/config/zabbix_server#startagentpollers).

**Запрос сервера**

Для определения длины заголовка и данных см. [сведения о протоколе](/manual/appendix/protocols/header_datalen).

```json
{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `"passive checks"` |
| data |<| _array of object_ | yes | Элемент данных пассивной проверки. |
| | key | _string_ | yes | Ключ элемента данных с раскрытыми макросами. |
|^| timeout | _number_ | yes | Тайм-аут связи. |

**Ответ агента**

```json
{
  "version": "7.4.0",
  "variant": 2,
  "data": [
    {
      "value": "7.4.0"
    }
  ]
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| version |<| _string_ | yes | Номер версии агента. |
| variant |<| _number_ | yes | Вариант агента (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| data |<| _array of object_ | yes |Содержит результат проверки. |
| | value | _string_ | no | Значение элемента данных, если проверка выполнена успешно. |
| | error | _string_ | no | Сообщение об ошибке, если проверка не выполнена успешно. |

Например, для поддерживаемых элементов данных:

1.  Сервер открывает TCP-соединение
2.  Сервер отправляет **<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}**
3.  Агент читает запрос и отвечает
    **<HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"value":1}]}**
4.  Сервер обрабатывает данные, чтобы получить значение, в нашем случае — '1'
5.  TCP-соединение закрывается

Для неподдерживаемых элементов данных:

1.  Сервер открывает TCP-соединение
2.  Сервер отправляет **<HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size\[/nono\]","timeout":3}]}**
3.  Агент читает запрос и отвечает
    **<HEADER><DATALEN>{"version":"7.4.0","variant":2,"data":[{"error":"Unsupported item key."}]}**
4.  Сервер обрабатывает данные, изменяет состояние элемента данных на неподдерживаемое с
    указанным сообщением об ошибке
5.  TCP-соединение закрывается

[comment]: # ({/f0a43b2b-e6db8dd6})

[comment]: # ({241f3b68-d33dfdd3})
##### Переключение на старый протокол

Чтобы обеспечить совместимость сервера или прокси Zabbix с агентами версий ниже 7.2, использующими протокол в открытом виде, реализовано переключение на старый протокол.

Пассивные проверки выполняются с использованием JSON-протокола (7.0 и новее) после перезапуска или при изменении конфигурации интерфейса.  
Если в ответ не получен допустимый JSON (агент отправил "ZBX_NOTSUPPORTED"), Zabbix сохранит для интерфейса старый протокол и **повторит** проверку, отправив только ключ элемента данных.

Обратите внимание, что каждый час сервер/прокси Zabbix снова будет пытаться работать с новым протоколом со всеми интерфейсами, при необходимости переключаясь обратно на старый протокол.

[comment]: # ({/241f3b68-d33dfdd3})

[comment]: # ({86593407-ecdd6e8e})
#### Активные проверки

Активные проверки требуют более сложной обработки.
Агент сначала должен получить с сервера/прокси список элементов данных и/или [удалённых команд](/manual/config/notifications/action/operation/remote_command) для независимой обработки.

Сервера/прокси для получения активных проверок перечислены в параметре «ServerActive»  [файла конфигурации](/manual/appendix/config/zabbix_agent2) агента. Частота запросов данных проверок настраивается параметром «RefreshActiveChecks» в этом же файле конфигурации.
Однако, если обновление активных проверок завершится с ошибкой, запрос повторится через (жёстко заданные в коде) 60 секунд.

[comment]: # ({/86593407-ecdd6e8e})

[comment]: # ({e520c471-4c14cd28})
::: notetip
Начиная с версии Zabbix 6.4, агент (в активном режиме) больше не получает от сервера/прокси полную копию конфигурации раз в две минуты (по умолчанию).
Вместо этого, чтобы уменьшить сетевой трафик и использование ресурсов, каждые 5 секунд (по умолчанию) выполняется инкрементная синхронизация конфигурации, после чего сервер/прокси предоставляет полную копию конфигурации, **только** если агент ещё не получил её либо что-то изменилось в конфигурации узла сети, глобальных макросах или глобальных регулярных выражениях.
:::

[comment]: # ({/e520c471-4c14cd28})

[comment]: # ({63166bda-2f80420a})
Затем агент периодически отправляет новые значения на сервер(ы).
Если агент получил какие-либо [удалённые команды](/manual/config/notifications/action/operation/remote_command) для выполнения, также будет отправлен результат выполнения.
Обратите внимание, что удалённое выполнение команд на активном агенте поддерживается, начиная с версии Zabbix агента 7.0.

::: notetip
Если агент находится за брандмауэром, вы можете рассмотреть возможность использования исключительно Активных проверок, т.к. в этом случае вам не понадобится менять настройки брандмауэра для разрешения начальных входящих соединений.
:::

[comment]: # ({/63166bda-2f80420a})

[comment]: # ({426dc1ae-d898e135})
##### Получение списка элементов данных

**Запрос агента**

Запрос active checks используется для получения активных проверок, которые должны обрабатываться агентом.  
Этот запрос отправляется агентом при запуске, а затем с интервалами [RefreshActiveChecks](/manual/appendix/config/zabbix_agent2).

```json
{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "7.4.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
```

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| request | _string_ | yes | `active checks` |
| host | _string_ | yes | Имя узла сети. |
| host_metadata | _string_ | no | Значение конфигурационного параметра HostMetadata или метрики HostMetadataItem. |
| interface | _string_ | no | Значение конфигурационного параметра HostInterface или метрики HostInterfaceItem. |
| ip | _string_ | no | Первый IP-адрес параметра ListenIP, если он задан. |
| port | _number_ | no | Значение параметра ListenPort, если он задан и не совпадает с портом прослушивания агента по умолчанию. |
| version | _string_ | yes | Номер версии агента. |
| variant | _number_ | yes | Вариант агента (*1* - Zabbix agent, *2* - Zabbix agent 2). |
| config_revision | _number_ | no | Идентификатор конфигурации для [инкрементальной синхронизации конфигурации](#active-checks). |
| session | _string_ | no | Идентификатор сеанса для [инкрементальной синхронизации конфигурации](#active-checks). |
  
**Ответ сервера**

Ответ active checks отправляется сервером агенту после обработки запроса active checks.
  
```json
{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}

```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| info |<| _string_ | no | Информация об ошибке в случае сбоя. |
| data |<| _array of objects_ | no | Элементы данных активных проверок. Не указывается, если конфигурация узла сети не изменилась. |
| | key | _string_ | no | Ключ элемента данных с раскрытыми макросами. |
|^| itemid | _number_ | no | Идентификатор элемента данных. |
|^| delay | _string_ | no | Интервал обновления элемента данных.<br>Гибкие интервалы/интервалы по расписанию поддерживаются как Zabbix agent, так и Zabbix agent 2 начиная с Zabbix 7.0. |
|^| lastlogsize | _number_ | no | lastlogsize элемента данных. |
|^| mtime | _number_ | no | mtime элемента данных. |
|^| timeout | _string_ | no | Тайм-аут элемента данных. |
| refresh_unsupported |<| _number_ | no | Интервал обновления неподдерживаемого элемента данных. |
| regexp |<| _array of objects_ | no | Глобальные регулярные выражения. |
| | name | _string_ | no | Имя глобального регулярного выражения. |
|^| expression | _string_ | no | Глобальное регулярное выражение. |
|^| expression_type | _number_ | no | Тип глобального регулярного выражения. |
|^| exp_delimiter | _string_ | no | Разделитель глобального регулярного выражения. |
|^| case_sensitive | _number_ | no | Параметр чувствительности глобального регулярного выражения к регистру. |
| commands |<| _array of objects_ | no | Удаленные команды для выполнения. Включаются, если выполнение удаленной команды было инициировано операцией [действия](/manual/config/notifications/action/operation#operations) или ручным выполнением [скрипта](/manual/web_interface/frontend_sections/alerts/scripts). Обратите внимание, что выполнение удаленных команд на активном агенте поддерживается начиная с Zabbix agent 7.0. Более старые активные агенты будут игнорировать любые удаленные команды, включенные в ответ сервера active checks. |
| | command | _string_ | no | Удаленная команда. |
|^| id | _number_ | no | Идентификатор удаленной команды. |
|^| wait | _number_ | no | Режим выполнения удаленной команды ("0" (nowait) для команд из операций [действия](/manual/config/notifications/action/operation#operations); "1" (wait) для команд из ручного выполнения [скрипта](/manual/web_interface/frontend_sections/alerts/scripts)). |
|^| timeout | _number_ | no | Тайм-аут выполнения удаленной команды в конфигурации [сервер](/manual/appendix/config/zabbix_server#timeout)/[прокси](/manual/appendix/config/zabbix_proxy#timeout). |
| config_revision | < | _number_ | no | Идентификатор конфигурации для [инкрементальной синхронизации конфигурации](#active-checks). Не указывается, если конфигурация узла сети не изменилась. Увеличивается, если конфигурация узла сети изменена. |
  
Сервер должен ответить success.

Например:

1. Агент открывает TCP-соединение
2. Агент запрашивает список проверок
3. Сервер отвечает списком элементов данных и удаленных команд для выполнения
4. Агент разбирает ответ
5. TCP-соединение закрывается
6. Агент начинает периодический сбор данных и выполняет удаленные команды (поддерживается начиная с Zabbix agent 7.0)

::: noteimportant
Обратите внимание, что конфиденциальные данные конфигурации могут
стать доступны сторонам, имеющим доступ к порту trapper сервера Zabbix,
при использовании активной проверки. Это возможно, поскольку любой может
выдать себя за активный агент и запросить данные конфигурации элемента данных;
аутентификация не выполняется, если не используются параметры
[шифрования](/manual/encryption).
:::

[comment]: # ({/426dc1ae-d898e135})

[comment]: # ({4c963bbb-8c5ecfe1})
##### Отправка собранных данных

**Агент отправляет**

Запрос данных агента содержит собранные значения элементов данных и значения выполненных удаленных команд (если таковые имеются).
  
```json
{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "7.4.0",
  "variant": 2
}
```

| Field |<| Type | Mandatory | Value |
|-|------|--|-|-----------------------|
| request |<| _string_ | yes | `agent data` |
| data |<| _array of objects_ | yes | Значения элементов данных. |
| | id | _number_ | yes | Идентификатор значения (инкрементный счетчик, используемый для проверки дублирующихся значений в случае проблем с сетью). |
|^| itemid | _number_ | yes | Идентификатор элемента данных. |
|^| value | _string_ | no | Значение элемента данных. |
|^| lastlogsize | _number_ | no | lastlogsize элемента данных. |
|^| mtime | _number_ | no | mtime элемента данных. |
|^| state | _number_ | no | Состояние элемента данных. |
|^| source | _string_ | no | Источник журнала событий значения. |
|^| eventid | _number_ | no | eventid журнала событий значения. |
|^| severity | _number_ | no | severity журнала событий значения. |
|^| timestamp | _number_ | no | timestamp журнала событий значения. |
|^| clock | _number_ | yes | Метка времени значения (секунды с начала эпохи). |
|^| ns | _number_ | yes | Метка времени значения в наносекундах. |
| commands |<| _array of objects_ | no | Результат выполнения удаленных команд. Обратите внимание, что выполнение удаленных команд на активном агенте поддерживается начиная с Zabbix agent 7.0. Более старые активные агенты будут игнорировать любые удаленные команды, включенные в ответ сервера на активные проверки. |
| | id | _number_ | no | Идентификатор удаленной команды. |
|^| value | _string_ | no | Результат выполнения удаленной команды, если выполнение прошло успешно. |
|^| error | _string_ | no | Сообщение об ошибке выполнения удаленной команды, если выполнение завершилось неудачей. |
| session |<| _string_ | yes | Уникальный идентификатор сеанса, создаваемый каждый раз при запуске агента. |
| host |<| _string_ | yes | Имя узла сети. |
| version |<| _string_ | yes | Номер версии агента. |
| variant |<| _number_ | yes | Вариант агента (*1* - Zabbix agent, *2* - Zabbix agent 2). |

Каждому значению назначается виртуальный ID. ID значения — это простой возрастающий
счетчик, уникальный в пределах одного сеанса данных (идентифицируемого по
токену сеанса). Этот ID используется для отбрасывания дублирующихся значений, которые могут
передаваться в условиях плохого качества связи.

**Ответ сервера**

Ответ на данные агента отправляется сервером обратно агенту после обработки запроса данных агента.
  
```json
{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}
```

| Field | Type | Mandatory | Value |
|-|-|-|--------|
| response | _string_ | yes | `success` \| `failed` |
| info | _string_ | yes | Результаты обработки элементов данных. |
  
::: noteimportant
Если отправка некоторых значений на сервере завершается неудачей (например, потому что узел сети или элемент данных был отключен или удален), агент не будет повторять отправку этих значений.
:::

Например:

1.  Агент открывает TCP-соединение
2.  Агент отправляет список значений
3.  Сервер обрабатывает данные и отправляет статус обратно
4.  TCP-соединение закрывается

::: noteimportant
Сообщение об ошибке будет обрезано до 2048 символов на стороне сервера.
:::

[comment]: # ({/4c963bbb-8c5ecfe1})

[comment]: # ({a13ec4d9-ee2b7a2a})
##### Сообщение heartbeat

**Отправка агентом**

Сообщение heartbeat отправляется активным агентом на сервер/прокси Zabbix
каждые HeartbeatFrequency секунд (настраивается в файле конфигурации [Zabbix agent](/manual/appendix/config/zabbix_agentd)/
[agent 2](/manual/appendix/config/zabbix_agent2)).

Оно используется для мониторинга доступности активных проверок.

```json
{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "7.4.0",
  "variant": 2
}
```

| Поле | Тип | Обязательное | Значение |
|-|-|-|-|
| request | _string_ | yes | `active check heartbeat` |
| host | _string_ | yes | Имя узла сети. |
| heartbeat_freq | _number_ | yes | Частота heartbeat агента (параметр конфигурации HeartbeatFrequency). |
| version | _string_ | yes | Номер версии агента. |
| variant | _number_ | yes | Вариант агента (*1* - Zabbix agent, *2* - Zabbix agent 2). |

**Ответ перенаправления**

Когда узел сети был переназначен, сервер может указать агенту перенаправить его heartbeat (и последующие активные проверки) на другой экземпляр прокси или сервера.

```json
  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }
```

| Поле |<| Тип | Обязательное | Значение |
|-|------|--|-|-----------------------|
| response |<| _string_ | yes | `success` \| `failed` |
| redirect |<| _object_ | yes | Инструкции по перенаправлению. |
| | revision | _number_ | yes | Идентификатор ревизии конфигурации. |
|^| address | _string_ | yes | Адрес целевого сервера/прокси. |

[comment]: # ({/a13ec4d9-ee2b7a2a})

[comment]: # ({e66043c4-e66043c4})
#### Более старый XML протокол

::: noteclassic
Zabbix воспринимает до 16 МВ XML данных, закодированных в Base64, но одиночное декодированное значение не должно быть длиннее 64 КБ, в противном случае значение будет обрезано до 64 КБ в процессе декодирования.
:::

[comment]: # ({/e66043c4-e66043c4})