Драйвер SNMP

SNMP (Simple Network Management Protocol) — стандартный протокол для управления сетевыми устройствами в IP-сетях. Он часто используется для обмена сервисной информацией с устройствами и представляет данные в виде отдельных переменных. Поддержка протокола встречается в сетевых коммутаторах, маршрутизаторах, системах бесперебойного питания (UPS), серверах и т.п. Подробнее о протоколе читайте в Wikipedia.

В контроллер Wiren Board добавлен драйвер для получения данных от SNMP-устройств. Но вы можете настроить и отправку данных (агент на контроллере), для этого нужно установить Агент SNMP настроив демон snmpd.

Установка и настройка на контроллере

Для установки и настройки подключитесь к контроллеру по SSH.

Установка

Сначала нужно установить пакет wb-mqtt-snmp, для этого введите в консоли команды:

apt update
apt install wb-mqtt-snmp

Настройка

Структура конфигурации похожа на wb-mqtt-serial.

Пример конфигурационного файла /etc/wb-mqtt-snmp.conf:

{
    "debug": false,
    "num_workers": 4,
    "devices": [
        {
            "address": "192.168.0.1",
            "name": "My SNMP server",
            "community": "public",
            "oid_prefix": "SNMPv2-MIB",
            "channels": [
                {
                    "name": "Number of services",
                    "oid": "sysServices.0",
                    "poll_interval": 1000
                },
                {
                    "name": "Boot string",
                    "oid": "HOST-RESOURCES-MIB::hrSystemInitialLoadParameters.0",
                    "poll_interval": 10000
                },
                {
                    "name": "System location",
                    "oid": ".1.3.6.1.2.1.1.6.0"
                }
            ]
        },
        {
            "address": "test.net-snmp.org",
            "name": "Test SNMP server",
            "device_type": "test-snmp"
        }
    ]
}

О структуре файла и назначении параметров читайте ниже.

Файл конфигурации

• debug — флаг включения режима отладки. Если true, то в процессе работы демона в лог-файл будет выноситься также отладочная информация (по умолчанию — false).
• num_workers — максимальное количество одновременно устанавливаемых SNMP-соединений. Если опрашивается много SNMP-устройств, то увеличение этого параметра может ускорить опрос. Но помните, что увеличение этого параметра также увеличивает максимальную нагрузку на сеть. В большинстве случаев можно оставить значение по умолчанию — 4.
• devices — список опрашиваемых устройств.

Описание устройства

Имя параметра	Тип	Описание	Обязательный	Значение по умолчанию
name	string	Имя устройства	Нет	SNMP [address]_[community]
id	string	ID устройства в MQTT	Нет	snmp_[address]_[community]
address	string	Сетевой адрес устройства	Да	-
device_type	string	Тип устройства, нужен для загрузки шаблона	Нет	-
enabled	bool	Включает или выключает опрос устройства	Нет	true
community	string	Имя сообщества SNMP	Да	-
oid_prefix	string	Префикс (имя MIB) для текстовых OID каналов, где он не указан явно	Нет	-
snmp_version	string	Версия SNMP, поддерживается только 2с	Нет	2c
snmp_timeout	integer	Время ожидания ответа, в секундах	Нет	5
poll_interval	integer	Минимальное время опроса для каждого канала по умолчанию	Нет	-
channels	array	Описание каналов устройства (переменных SNMP)	Нет	-

Описание каналов

Имя параметра	Тип	Описание	Обязательный	Значение по умолчанию
name	string	Имя канала	Да	-
oid	string	OID в числовом или текстовом виде	Да	-
enabled	boolean	Включает или выключает опрос устройства	Нет	true
control_type	string	Тип данных, согласно Conventions	Нет	text
units	string	Обозначение единиц измерения, для control_type == value	Нет	-
scale	float	Множитель, для числовых значений	Нет	1.0
poll_interval	int	Минимальный интервал опроса канала, в мс	Нет	poll_interval из описания устройства, либо 1000

Преобразование OID

При запуске демона происходит попытка преобразовать записанные в конфигурации текстовые OID в числовые:

• OID числовой: начинается с точки: .1.2.3.4 — преобразование не происходит.
• OID текстовый: например, SNMPv2-MIB::sysName.0 — происходит преобразование в числовой. В системе должен быть установлен MIB, который содержит описание этой переменной.

Преобразование имен происходит с помощью вызова утилиты snmptranslate, так что можно проверить наличие MIB вручную с помощью команды.

Параметр oid_prefix в описании устройства позволяет опустить имя MIB (префикс: SNMPv2-MIB::sysName.0). В этом случае префикс из oid_prefix будет автоматически присоединён ко всем OID каналам устройства, где он явно не указан. Например, при oid_prefix равном SNMPv2-MIB:

• sysName.0 → SNMPv2-MIB::sysName.0
• sysLocation.0 → SNMPv2-MIB::sysLocation.0
• HOST-RESOURCES-MIB::hrSystemUptime.0 → HOST-RESOURCES-MIB::hrSystemUptime.0
• .1.3.6.1.2.1.1.6.0 → .1.3.6.1.2.1.1.6.0

Установка MIB

Если у вас есть нужный MIB-файл, то достаточно скопировать его в директорию /root/.snmp/mibs:

# cp your-mibs-file.mib /root/.snmp/mibs

Если на контроллере нет директории /root/.snmp/mibs — создайте ее:

# mkdir -p /root/.snmp/mibs

После копирования MIB-файла проверьте правильность преобразования snmptranslate с каким-либо известным OID.

Проверка работы преобразования

Для проверки введите команду, где yourOid — известный вам OID:

# snmptranslate -On yourOid

Шаблоны

Для описания устройств не обязательно, но удобно использовать шаблоны.

Шаблон (тип устройства) — это внешний конфигурационный файл с именем config-[device-type-name].json, который располагается в /usr/share/wb-mqtt-snmp/templates. Например, /usr/share/wb-mqtt-snmp/templates/config-test-snmp.json. В файле шаблона содержится описание устройства: имя сообщества SNMP и базовое описание всех его каналов.

Для использования шаблона в описании устройства в конфигурационном файле укажите поле device_type. Среди всех представленных шаблонов будет выбран тот, где такое же значение device_type и все неопределенные в конфигурационном файле поля примут значения из шаблона.

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

Пример

Шаблон config-my-device.json:

{
    "device_type": "my-device",
    "community": "public",
    "channels": [
        {
            "name": "Channel 1",
            "oid": ".1.2.3.4.1"
        },
        {
            "name": "Channel 2",
            "oid": ".1.2.3.4.2",
            "poll_interval": 3000
        }
    ]
}

Конфигурационный файл:

{
    "devices": [
        {
            "name": "Device 1",
            "device_type": "my-device",
            "address": "192.168.0.5",
            "snmp_timeout": 1
        },
        {
            "name": "Device 2",
            "device_type": "my-device",
            "address": "my-device.example.org",
            "snmp_timeout": 5,
            "channels": [
                {
                    "name": "Channel 2",
                    "poll_interval": 10000
                }
            ]
        }
    ]
}

В примере мы описали один шаблон my-device, по которому определили два разных устройства Device 1 и Device 2 с одинаковым набором каналов.

Поскольку Device 1 находится в локальной сети, то логично выставить ему небольшое значение таймаута — это позволит быстрее определить неисправность устройства. Все остальные настройки берутся из шаблона.

Device 2 — удалённый сервер, потому для него стоит увеличить таймаут, чтобы не считать устройство неисправным при задержке пакета. Более того, для канала Channel 2 здесь мы переопределяем интервал опроса на больший — это снизит нагрузку на сеть.

Таким образом, шаблоны удобно использовать для описания группы однотипных устройств.

Список шаблонов

В поставке wb-mqtt-snmp прилагается набор шаблонов для типовых устройств:

Устройство	Имя шаблона	Протестировано	Комментарии
Тестовый сервер Net-SNMP	test-snmp	Да	адрес тестового сервера test.net-snmp.org
APC UPS	apc-ups	Нет	Требуется локально установленный PowerNet-MIB Описание устройства такое же, как в wb-mqtt-apcsnmp