[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]: # ({db675be2-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
    }
  ]
}
```

| Поле |<| Тип | Обязательное | Значение |
|-|------|--|-|-----------------------|
| request |<| _строка_ | да | `"passive checks"` |
| data |<| _массив объектов_ | да | Элемент данных пассивной проверки. |
| | key | _строка_ | да | Ключ элемента данных с раскрытыми макросами. |
|^| timeout | _число_ | да | Время ожидания коммуникации. |

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

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

| Поле |<| Тип | Обязательное | Значение |
|-|------|--|-|-----------------------|
| version |<| _строка_ | да | Номер версии агента. |
| variant |<| _число_ | да | Вариант агента (*1* — Zabbix агент, *2* — Zabbix агент 2). |
| data |<| _массив объектов_ | да | Содержит результат проверки. |
| | value | _строка_ | нет | Значение элемента данных, если проверка была успешной. |
| | error | _строка_ | нет | Сообщение об ошибке, если проверка была неуспешной. |

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

1.  Сервер открывает TCP-соединение
2.  Сервер отправляет: **<ЗАГОЛОВОК><ДЛИНАДАННЫХ>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}**
3.  Агент читает запрос и отвечает: **<ЗАГОЛОВОК><ДЛИНАДАННЫХ>{"version":"7.0.0","variant":2,"data":[{"value":1}]}**
4.  Сервер обрабатывает данные, чтобы извлечь значение, в нашем случае «1»
5.  TCP-соединение закрывается

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

1.  Сервер открывает TCP-соединение
2.  Сервер отправляет: **<ЗАГОЛОВОК><ДЛИНАДАННЫХ>{"request":"passive checks","data":[{"key":"vfs.fs.size\[/nono\]","timeout":3}]}**
3.  Агент читает запрос и отвечает: **<ЗАГОЛОВОК><ДЛИНАДАННЫХ>{"version":"7.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}**
4.  Сервер обрабатывает данные, меняет состояние элемента данных на неподдерживаемое с приведённым сообщением об ошибке
5.  TCP-соединение закрывается

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

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

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

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

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

[comment]: # ({/8a5c8e4e-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]: # ({fa025abc-d898e135})
##### Получение списка элементов данных

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

Запрос на активные проверки используется для получения списка активных проверок, обрабатываемых агентом.
Этот запрос отсылается агентом после старта и затем с интервалом [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.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}
```

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

Ответ активных проверок посылается сервером обратно агенту после обработки запроса на активные проверки.
  
```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
    }
  ]
}

```

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

Например:

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

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

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

[comment]: # ({1e8860e1-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.0.0",
  "variant": 2
}
```

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


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

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

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

| Поле| Тип| Обязательный| Значение|
|-|-|-|--------|
| response | _строка_ | да| `success` \| `failed` |
| info | _строка_ | да|Результаты обработки элементов данных. |
  
::: noteimportant
Если отправка некоторых значений завершилась неудачей на сервере (например, по причине того, что узел сети или элемент данных был деактивирован или удалён), агент не будет повторять отправку этих элементов данных
:::

Например:

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

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

[comment]: # ({/1e8860e1-8c5ecfe1})

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

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

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

Используется для контроля доступности активных проверок

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

| Поле|Тип|Обязательный|Значение|
|-|-|-|--------|
| request | _строка_ |да| `active check heartbeat` |
| host | _строка_ |да|Имя узла сети. |
| heartbeat_freq | _число_ |да|Частота сигналов «Я жив» (параметр конфигурации HeartbeatFrequency). |
| version | _строка_ |да|Номер версии агента. |
| variant | _число_ |да| Вариант агента (*1* — Zabbix агент, *2* — Zabbix агент 2). |

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

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

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

| Поле|<| Тип|Обязательный|Значение |
|-|------|--|-|-----------------------|
| response |<| _строка_ | да| `success` \| `failed` |
| redirect |<| _массив объектов_ | да| Команды пренаправления. |
| | revision | _число_ | да| Идентификатор ревизии конфигурации. |
|^| address | _строка_ | да| Адрес целевого сервера/прокси. |

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

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

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

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