Зміст

Опитування світчів за допомогою SNMP

В Ubilling починаючи з релізу 0.4.1 з'явилася можливість опитування активного мережевого обладнання за допомогою SNMP (вимагає встановленого net-snmp). Механіка опитування шаблонізована і дає змогу опитувати обладнання за будь-якими OID-ами. Також модуль “Опитування світчів” використовує у своїй роботі кешування результатів, що дає змогу зробити відображення результатів прийнятним за часом.

Підтримуване з коробки обладнання

І багато-багато інших, про які ми вже задовбалися писати. Давайте ви самі подивитеся що буде працювати з коробки заглянувши в директорію config/snmptemplates?

Налаштування

У загальному випадку налаштування зводитися до додавання моделі світча з правильним шаблоном SNMP

Після чого слід додати пристрій із потрібною моделькою і зазначеним SNMP ком'юніті, а також підрядком SWPOLL в описі, який сигналізує Ubilling про те, що для цього пристрою слід застосувати стандартні механізми опитування щодо обраного шаблону.

Якщо все додано правильно - у світча в колонці дії має з'явитися іконка “Опитування за допомогою SNMP”

Набір параметрів, що запитуються з пристрою, повністю залежить від обраного шаблону і може бути практично довільним. Також можливе відображення FDB з пристрою.

Враховуючи, що опитування пристрою відбувається не надто швидко, для прискорення відображення результатів використовується механіка кешування. Для періодичного опитування всіх пристроїв, з метою заповнення кешу сирих даних слід використовувати виклик swpoll з API віддаленого виклику процедур.

Формат шаблону для опитування пристрою

Шаблони всіх пристроїв лежать у /config/snmptemplates/ і мають, наприклад, якийсь такий вигляд:

megaswitch9000
[define]
DEVICE="ZIZITRA MegaSwitch-9000 2ports"
FDB=true
FDB_MODE=default
 
[PORTSTATE]
NAME="Port states"
OIDS=".1.3.6.1.2.1.2.2.1.8.1,.1.3.6.1.2.1.2.2.1.8.2"
PARSER=sp_parse_zyportstates
 
[UPTIME]
NAME="Uptime"
OIDS=".1.3.6.1.2.1.1.3.0"
PARSER=sp_parse_raw

або такий для OLT:

BDCOM_GP3608
[define]
DEVICE="BDCOM OLT GP3600-8"
PON_ONU_PORT_MAX=128
 
[signal]
SIGNALMODE="GPBDCOM"
SIGINDEX=".1.3.6.1.4.1.3320.10.3.4.1.2"
MACINDEX=".1.3.6.1.4.1.3320.10.3.3.1.2"
SIGVALUE="INTEGER:"
MACVALUE="STRING:"
OFFSET="10"
OFFSETMODE="div"
DOWNVALUE="2147483648"
 
[misc]
ONUINDEX=".1.3.6.1.4.1.3320.10.3.3.1.2"
ONUVALUE="STRING:"
FDBINDEX=".1.3.6.1.2.1.17.7.1.2.2.1.1"
FDBVALUE="Hex-STRING:"
FDBDEVINDEX=".1.3.6.1.2.1.17.7.1.2.2.1.2"
FDBDEVVALUE="INTEGER:"
DISTINDEX=".1.3.6.1.4.1.3320.10.3.1.1.33"
DISTVALUE="INTEGER:"
INTERFACEINDEX=".1.3.6.1.2.1.2.2.1.2"
INTERFACEVALUE="STRING:"
RTTINDEX=".1.3.6.1.4.1.3320.101.11.1.1.8"
 
[system]
CPULOAD=".1.3.6.1.2.1.25.3.3.1.2"

Як бачимо файл складається із секцій.
Секція [define] є обов'язковою. У ній описуються такі характеристики пристрою як DEVICE (повне найменування моделі) і булевий параметр FDB, який означає, що для пристрою слід спробувати дістати FDB, а також необов'язковий параметр FDB_MODE, який вказує на метод опитування FDB таблиць. Він може приймати значення default (за замовчуванням) або dlp (для деяких моделей світчів Dlink) і tlp5428ev2 для відповідного tp-link. У разі, якщо параметр FDB_MODE не вказано, за замовчуванням вважатиметься, що він встановлений у значення default.
Також існують необов'язкові параметри:

Слід зазначити, що параметр FDB_ALLOW_ONLY_PORTS має перевагу і, якщо номер порту буде зазначено одночасно в обох цих опціях, - перевага буде за FDB_ALLOW_ONLY_PORTS і МАСи з цього порту таки потраплять до FDB-кешу.

Далі кожна із секцій описує унікальний набір параметрів, за яким буде опитуватися пристрій. Ім'я секції особливого значення не має і просто має бути унікальним. Кожна секція складається з щонайменше трьох обов'язкових змінних. Це NAME - відображувана назва опитуваної характеристики (буде локалізовано), OIDS - список OID-ів через кому, які буде опитано для конкретної моделі, і PARSER - парсер даних, через який буде пропущено дані, отримані від кожного OID-а в поточній секції. З вищенаведеного прикладу можна зробити висновок, що цей шаблон відображатиме стан двох перших портів світча і його аптайм, а також намагатиметься показувати таблицю відповідності MAC-ів за портами.
Починаючи з релізу Ubilling 0.8.5 також можна зберігати ваші шаблони в content/documents/mysnmptemplates/. Вони матимуть пріоритет перед базовими і будуть нормально переживати оновлення білінгу. Також, якщо вам потрібно змінити поведінку якогось наявного шаблону (наприклад, порти FDB, які ігноруються), потрудіться перед модифікацією, скопіювати його в content/documents/mysnmptemplates/ і редагувати його вже там.

Наразі доступні такі парсери отриманих з OID даних:

Також доступні наступні режими FDB:

Формат "кумулятивного" шаблону для опитування пристрою

Повністю базується на базовому форматі шаблонів, але має свої особливості, про які буде розказано нижче. Власне вся “кумулятивність” полягає в тому, що нам не потрібно вказувати конкретний порт для кожної секції наприкінці OID'а - ми вказуємо тільки OID необхідної нам таблиці, чи то dot1dFdb, dot1qFdb, банальний ifDescr або трохи менш банальний ifAlias. А далі наш модуль уже самостійно перебере всі наявні порти і за їхніми індексами постарається дістати все, що зможе (ну, з того, що ми вкажемо в шаблоні, звісно).

Отже, нові параметри секції [define]:

Далі трохи про “особливі” секції:

PORTIFACE - у цій секції вказуються OID'и для отримання індексів портів, дескрипшинів і аліасів портів. На закономірне запитання: “А навіщо і дескрипшини, і аліаси?” - даємо не менш закономірну відповідь: “А навіщо вони взагалі існують окремо?”. Але, якщо серйозно - логіка тут вельми проста: деякі девайси зберігають найменування інтерфейсів в ifDescr, а деякі - в ifAlias. Тому наш модуль спочатку намагається знайти опис порту в ifDescr, а якщо не знаходить - тоді вже в ifAlias. І нам абсолютно не потрібно над цим морочитися. Зручно, чи не так? 

[PORTIFACE]
PORTINDEX=".1.3.6.1.2.1.2.2.1.1"
PORTDESCR=".1.3.6.1.2.1.2.2.1.2"
PORTALIAS=".1.3.6.1.2.1.31.1.1.1.18"

PORTDESC - як і випливає з коментаря до цієї секції, у кумулятивних шаблонах - це просто заглушка. Коли кумулятивний обробник “зустрічає” в шаблоні цю секцію - він просто запускає спеціальний парсер для обробки описів/найменувань портів пристрою. 

[PORTDESC]
; just a placeholder
NAME="Desc"

PORT.1D_FDB, PORT.1Q_FDB - ще дві секції, характерні тільки для кумулятивного режиму обробки, які не передбачають використання будь-якого парсера. Призначені для отримання FDB-таблиці девайса. Таблиця PORT.1Q_FDB, як докладніша і детальніша, використовується для отримання номерів VLAN для МАС-адрес з опитуваних портів. 

[PORT.1D_FDB]
PORTTABLE=".1.3.6.1.2.1.17.4.3.1.2"
PORTSTATUS=".1.3.6.1.2.1.17.4.3.1.3"
 
[PORT.1Q_FDB]
PORTTABLE=".1.3.6.1.2.1.17.7.1.2.2.1.2"
PORTSTATUS=".1.3.6.1.2.1.17.7.1.2.2.1.3"

А ще ми тепер можемо вказувати в секціях одиниці виміру і величину, на яку потрібно поділити повернуте OID'ом значення, використовуючи параметри DIV і UNITS. Ці параметри можуть жити абсолютно окремо, тобто: для будь-якої секції ми можемо вказати тільки один із них. Наприклад, якщо OID нам повертає одразу коректне значення, яке не потрібно ні на що ділити і нам потрібно тільки причепити до нього одиниці виміру, то для секції достатньо вказати тільки один лише параметр UNITS. Так само варто зазначити, що для коректної обробки цього всього потрібно використовувати нові парсери. Виглядає це якось так: 

[SFPTXPOWER]
NAME="SFP TX power"
OIDS=".1.3.6.1.4.1.14988.1.1.19.1.1.9"
DIV=1000
UNITS="dBm"
PARSER=sp_parse_division_units
 
[CPU TEMP]
NAME="CPU temperature"
SECTPOLLMODE="noncumulative"
OIDS=".1.3.6.1.4.1.14988.1.1.3.11.0"
DIV=10
UNITS="C"
PARSER=sp_parse_division_units_noport

Нові парсери:

То як же в підсумку матиме вигляд кумулятивний шаблон для пристрою? Покажемо на прикладі досить відомого девайса Mikrotik RB260GSP / CSS106-1G-4P-1S: 

[define]
DEVICE=Mikrotik-CSS106_RB260GSP_SW_SFP
POLLMODE=cumulative
SFPSTARTPORT=5
SFPENDPORT=5
POESTARTPORT=2
POEENDPORT=5
FDB=true
FDB_MODE=sw_cumulative
FDB_ALLOW_ONLY_PORTS=
FDB_IGNORE_PORTS=
 
[PORTIFACE]
PORTINDEX=".1.3.6.1.2.1.2.2.1.1"
PORTDESCR=".1.3.6.1.2.1.2.2.1.2"
PORTALIAS=".1.3.6.1.2.1.31.1.1.1.18"
 
[PORT.1D_FDB]
PORTTABLE=".1.3.6.1.2.1.17.4.3.1.2"
PORTSTATUS=".1.3.6.1.2.1.17.4.3.1.3"
 
[PORT.1Q_FDB]
PORTTABLE=".1.3.6.1.2.1.17.7.1.2.2.1.2"
PORTSTATUS=".1.3.6.1.2.1.17.7.1.2.2.1.3"
 
[PORTSTATE]
NAME="Port states"
OIDS=".1.3.6.1.2.1.2.2.1.8"
PARSER=sp_parse_zyportstates
 
[PORTDESC]
; just a placeholder
NAME="Desc"
 
[PORTTX]
NAME="Bytes transmitted"
OIDS=".1.3.6.1.2.1.2.2.1.16"
PARSER=sp_parse_zyportbytes
 
[PORTRX]
NAME="Bytes received"
OIDS=".1.3.6.1.2.1.2.2.1.10"
PARSER=sp_parse_zyportbytes
 
[PORTERRTX]
NAME="TX errors"
OIDS=".1.3.6.1.2.1.2.2.1.20"
PARSER=sp_parse_zyportbytes
 
[PORTERRRX]
NAME="RX errors"
OIDS=".1.3.6.1.2.1.2.2.1.14"
PARSER=sp_parse_zyportbytes
 
[PORTMULTTX]
NAME="Multicast TX"
OIDS=".1.3.6.1.2.1.31.1.1.1.12"
PARSER=sp_parse_zyportbytes
 
[PORTMULTRX]
NAME="Multicast RX"
OIDS=".1.3.6.1.2.1.31.1.1.1.8"
PARSER=sp_parse_zyportbytes
 
[PORTBRODTX]
NAME="Broadcast TX"
OIDS=".1.3.6.1.2.1.31.1.1.1.13"
PARSER=sp_parse_zyportbytes
 
[PORTBRODRX]
NAME="Broadcast RX"
OIDS=".1.3.6.1.2.1.31.1.1.1.9"
PARSER=sp_parse_zyportbytes
 
[SFPWAVELENGTH]
NAME="SFP wave length"
OIDS=".1.3.6.1.4.1.14988.1.1.19.1.1.5"
DIV=100
UNITS="nm"
PARSER=sp_parse_division_units
 
[SFPTEMP]
NAME="SFP temperature"
OIDS=".1.3.6.1.4.1.14988.1.1.19.1.1.6"
UNITS="C"
PARSER=sp_parse_division_units
 
[SFPVOLTAGE]
NAME="SFP voltage"
OIDS=".1.3.6.1.4.1.14988.1.1.19.1.1.7"
DIV=1000
UNITS="V"
PARSER=sp_parse_division_units
 
[SFPCURRENT]
NAME="SFP current"
OIDS=".1.3.6.1.4.1.14988.1.1.19.1.1.8"
UNITS="mA"
PARSER=sp_parse_division_units
 
[POESTATUS]
NAME="POE status"
OIDS=".1.3.6.1.4.1.14988.1.1.15.1.1.3"
PARSER=sp_parse_mikrotik_poe
 
[POECURRENT]
NAME="POE current"
OIDS=".1.3.6.1.4.1.14988.1.1.15.1.1.5"
UNITS="mA"
PARSER=sp_parse_division_units
 
[POEPOWER]
NAME="POE power"
OIDS=".1.3.6.1.4.1.14988.1.1.15.1.1.6"
DIV=10
UNITS="W"
PARSER=sp_parse_division_units
 
[UPTIME]
NAME="Uptime"
SECTPOLLMODE="noncumulative"
OIDS=".1.3.6.1.2.1.1.3.0"
PARSER=sp_parse_raw_trim_tab
 
[SYSTEM VOLTAGE]
NAME="System voltage"
SECTPOLLMODE="noncumulative"
OIDS=".1.3.6.1.4.1.14988.1.1.3.8.0"
DIV=10
UNITS="V"
PARSER=sp_parse_division_units_noport
 
[SYSTEM TEMP]
NAME="System temperature"
SECTPOLLMODE="noncumulative"
OIDS=".1.3.6.1.4.1.14988.1.1.3.10.0"
DIV=10
UNITS="C"
PARSER=sp_parse_division_units_noport
 
[SYSTEM VERSION]
NAME="System version"
SECTPOLLMODE="noncumulative"
OIDS=".1.3.6.1.2.1.1.1.0"
PARSER=sp_parse_raw_trim_tab

А якщо потрібно робити ще й snmpset?

Починаючи з релізу 0.8.4 з'явилася можливість у процесі опитування робити пристроям snmp set. Для цього в кожній секції за винятком “define” додано можливість вказати опцію SETOIDS у форматі: 

SETOIDS="oid|type|value,oid|type|value"

Де oid є власне oid-ом, value є значенням, яке буде встановлено, а type вказує на тип і може набувати таких значень:

Слід також зауважити, що секція з SETOIDS може бути самодостатньою і не потребує вказівки інших опцій, як-от NAME, OIDS чи скажімо PARSER. У такому разі, вона просто проведе по черзі всі write операції і завершить свою роботу. Ось приклад зазначення port description для двох портів: 

[portnames]
SETOIDS=".1.3.6.1.2.1.31.1.1.1.18.4|s|testport1,.1.3.6.1.2.1.31.1.1.1.18.5|s|testport2"

Хоча так, ніхто не забороняє бути їй при цьому звичайною інтерактивною секцією і показувати в процесі своєї роботи якісь результати. Наприклад якось так: 

[portnames]
SETOIDS=".1.3.6.1.2.1.31.1.1.1.18.4|s|testport1,.1.3.6.1.2.1.31.1.1.1.18.5|s|testport2"
NAME="Ports"
OIDS=".1.3.6.1.2.1.31.1.1.1.18.4,.1.3.6.1.2.1.31.1.1.1.18.5"
PARSER=sp_parse_raw

У такому разі слід завжди пам'ятати про те, що спочатку завжди виконуються всі snmp set операції, а потім вже проводитиметься опитування і рендер зазначених в опції OIDS даних. 

[define]
PON_ONU_PORT_MAX=128

Якщо ви використовуєте дві технології ПОН у себе в мережі і вам потрібно перекрити глобальний обов'язковий параметр alter.ini PON_ONU_PORT_MAX - то додайте цей параметр у SNMP-шаблони для OLT, і у вас буде нормально відображатися статистика та інші параметри.

Генератор шаблонів

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