SNMP exporter

В составе Памир поставляется доработанная сборка snmp_exporter 0.20.0. От стандартной она отличается одним: версию протокола и параметры аутентификации SNMP можно передать в параметрах запроса, а не только задать в конфигурации модуля. Набор модулей, списки OID и правила преобразования значений работают как в стандартной сборке.

Конфигурация экспортера хранится в Redis по ключу /exporters/snmp; после её изменения экспортер перечитывает конфигурацию без перезапуска контейнера. Экспортер слушает порт 9116:

Путь	Назначение
/snmp	опрос устройства — сюда обращается агент сбора метрик
/metrics	метрики самого экспортера
/config	текущая конфигурация, секреты заменены на <secret>
/-/reload	перечитать конфигурацию, метод POST

Параметры запроса

Параметр	Обязательный	Допустимые значения	Если не передан
target	да, ровно один раз	адрес или адрес:порт устройства	—
module	нет, не более одного раза	имя модуля из конфигурации экспортера	if_mib
version	нет	1, 2, 2c, 3	версия из модуля, по умолчанию 2
community	нет	строка	значение из модуля, по умолчанию public
security_level	нет	noAuthNoPriv, authNoPriv, authPriv	значение из модуля, по умолчанию noAuthNoPriv
username	нет	строка	значение из модуля
password	нет	строка	значение из модуля
auth_protocol	нет	MD5, SHA, SHA224, SHA256, SHA384, SHA512	значение из модуля, по умолчанию MD5
priv_protocol	нет	DES, AES, AES192, AES256	значение из модуля, по умолчанию DES
priv_password	нет	строка	значение из модуля
context_name	нет	строка	значение из модуля

Порт в target по умолчанию — 161. Значения 2 и 2c равнозначны и означают SNMPv2c.

community используется в SNMPv1 и SNMPv2c. Остальные параметры аутентификации — security_level, username, password, auth_protocol, priv_protocol, priv_password, context_name — относятся к SNMPv3: password и auth_protocol нужны при security_level: authNoPriv и authPriv, priv_password и priv_protocol — только при authPriv.

Приоритет параметров запроса и конфигурации

Значение берётся первым из тех, что заданы:

1. параметр запроса, если он передан и не пуст;
2. соответствующее поле модуля, указанного в module;
3. встроенное значение по умолчанию (public, версия 2, noAuthNoPriv, MD5, DES).

Слияние идёт по отдельным полям, а не блоком целиком: если в запросе передан только community, остальные настройки аутентификации возьмутся из модуля. Пустое значение (community=) равносильно отсутствию параметра. Параметры действуют только на текущий запрос — конфигурацию модуля они не меняют, на другие задания и устройства не влияют.

Экспортер не проверяет, согласованы ли параметры запроса с версией протокола. Если запросом переключить модуль на SNMPv3, обязательные для v3 значения (username, при authPriv — пароли) нужно передать в том же запросе или иметь в модуле, иначе опрос завершится ошибкой.

Неизвестные параметры и некорректные значения

Ситуация	Ответ экспортера
target не передан или передан несколько раз	400, 'target' parameter must be specified once
module передан несколько раз	400, 'module' parameter must only be specified once
модуля нет в конфигурации	400, Unknown module '<имя>'
значение version, security_level, auth_protocol или priv_protocol вне списка допустимых	400 с названием параметра и перечнем допустимых значений
устройство не ответило, ошибка SNMP или таймаут	500 с текстом ошибки, таргет в агенте сбора метрик переходит в up=0

Неизвестные параметры запроса экспортер игнорирует — они не считаются ошибкой. Если параметр передан несколько раз (все, кроме target и module), используется первое значение.

Пример запроса

curl 'http://snmp-exporter:9116/snmp?target=10.61.0.15&module=if_mib&version=2c&community=s3cr3t'

Настройка задания и relabel_configs

Параметр доходит до экспортера, только если у таргета есть метка __param_<имя параметра>: агент сбора метрик превращает такие метки в параметры запроса, а сами метки после relabel отбрасывает и в метрики не записывает. Поэтому community и другие секреты передают именно так — обычная метка попала бы в каждый ряд и осталась бы в хранилище метрик.

Конфигурация задания:

job_name: snmp
metrics_path: /snmp
scrape_timeout: 30s
relabel_configs:
  # адрес устройства из таргета — в параметр target
  - source_labels: [__address__]
    target_label: __param_target
  # понятное имя таргета — в метку instance
  - source_labels: [__name]
    target_label: instance
  # запрос уходит не на устройство, а на экспортер
  - target_label: __address__
    replacement: snmp-exporter:9116

Адрес источника таргетов (http_sd_configs) Памир подставляет в задание самостоятельно, в конфигурации задания его указывать не нужно.

Шаблон таргета в метрике шаблона мониторинга:

- labels:
    ci_id: '[[fields.ci_id]]'
    module: if_mib
    __name: '[[fields.ci_name]]'
    __param_module: if_mib
    __param_version: '2c'
    __param_community: '[[attributes.snmp_community]]'
  targets:
    - '[[attributes.ip_address]]:161'

На что обратить внимание:

• значения меток — строки, числа берите в кавычки: __param_version: '2c';
• один параметр задавайте одним способом. Если в задании есть правило source_labels: [module] → __param_module, а метки module у таргета нет, правило запишет пустое значение и затрёт __param_module, заданный в шаблоне;
• если на одно устройство заводится несколько таргетов (например, по одному на модуль), оставьте обычную метку, которая их различает, — в примере это module. Без неё наборы меток у таргетов совпадут и метрики станут неразличимы.

Безопасность

Community и пароли SNMPv3, переданные параметрами запроса, видны в списке таргетов агента сбора метрик и в ответе источника таргетов. Если устройства опрашиваются с одинаковыми учётными данными, надёжнее держать их в конфигурации модуля, а параметрами запроса передавать только то, что различается между устройствами.

Экспортер не публикует свой порт за пределы сети Памир, внешних вызовов с параметрами аутентификации в URL он принимать не должен. Шифрование обращений к экспортеру описано в разделе SSL.