Документація

Якщо файл конфігурації (config/vars.php) ще не створено, замість сайту показується форма setup.php, яка просить:

• MYSQL host / db / user / pass - доступ до бази даних, яку PonControl використовує для власних таблиць (olts, onus, fdb, settings тощо). База даних має вже існувати; таблиці створюються автоматично при збереженні цієї форми.
• telnet user / pass - облікові дані, якими PonControl за замовчуванням заходить на OLT по telnet для команд, що не підтримуються через SNMP (наприклад збереження конфігурації).
• enable pass - пароль привілейованого режиму (enable), якщо OLT цього вимагають.
• TFTP address - адреса TFTP-сервера, якщо операції збереження конфігурації OLT використовують TFTP.

Після збереження цих даних наступні кроки:

1. Створіть облікові записи співробітників (Налаштування → Адміністратори) - перший створений користувач стає адміністратором.
2. Додайте OLT (Список OLT → Додати OLT): IP-адреса, SNMP read/write community, кількість SFP-портів.
3. За потреби налаштуйте розділи нижче - Zabbix, Userside, Сповіщення, OpenObserve.

Єдине поле тут - Таймзона PHP (date_default_timezone_set()) - визначає, в якому часовому поясі PHP показує дати/час на сторінках сайту (журнал дій, останній зв'язок ONU тощо). Обирається зі списку - неможливо ввести неправильне значення.

Потрібен для графіків сигналу/трафіку ONU та статусу батареї/генератора OLT (розділ "Живлення" в бічному меню). Без налаштованого Zabbix ці графіки просто не показуються - решта функціоналу працює незалежно від цього розділу.

• Zabbix API user / password - облікові дані користувача Zabbix, яким PonControl логіниться в API (user.login). Рекомендується окремий технічний користувач з мінімально потрібними правами (читання історії).
• Посилання на Zabbix - базова URL-адреса вашого інстансу Zabbix (без /api_jsonrpc.php на кінці - PonControl додає цей шлях сам).
• Період на графіку за замовчуванням - який період (у годинах) показується одразу при відкритті графіка.

Пряме підключення до бази даних вашого біллінгу Userside (окреме від бази даних самого PonControl). Коли увімкнено, розблоковує: пошук абонента за адресою/кодом при прив'язці ONU, картку абонента з балансом при перегляді ONU, карту (координати точок з Userside), автоматичне визначення датчика живлення PING3 для OLT (якщо не вказано вручну на картці OLT), а також клієнтський портал (прив'язку ONU абонента до його облікового запису Userside).

• Userside MYSQL host / database / user / password - прямий доступ до бази даних Userside (не до його API) - потрібні права читання потрібних таблиць (tbl_base, tbl_house, tbl_ip, tbl_switch, tbl_map та інші).
• Посилання на UserSide - базова адреса вашого Userside, для прямих посилань на картку абонента.
• Пошукова адреса в UserSide - шлях (додається до посилання вище) для переходу напряму на MAC-адресу в Userside.

Вимикання цієї інтеграції не видаляє введені дані - лише ховає розділ і залежний від нього функціонал (Карта, Сповіщення) до повторного увімкнення.

Доступно лише коли увімкнено Userside - усі поля тут це назви власних полів, які вже мають існувати на картці абонента в самому Userside, а не довільні дані:

• Поле "User ID" в Userside - назва поля в Userside, де зберігається Telegram User ID абонента.
• Поле "Відправляти користувачу" / "Відправляти адміністратору" - назви полів-прапорців в Userside, якими вмикається/вимикається надсилання сповіщень.
• Токен публічного бота Telegram - токен бота, яким надсилаються сповіщення абонентам.
• Токен адмінського бота Telegram / ID адмінського чату - окремий бот і чат для сповіщень адміністраторам/технічній підтримці.

Створити резервну копію вивантажує усі дані бази (кожну таблицю, як вона є зараз) в один файл і одразу починає його завантаження в браузері - стиснутий JSON (не прямий SQL-дамп), а не архів ZIP, оскільки на цьому сервері немає розширення PHP ZipArchive. Зберігаються останні 5 таких файлів - список під кнопкою дозволяє завантажити чи видалити будь-який з них пізніше, без повторного створення; шосту й старіші копії видаляє автоматично кожне наступне створення нової.

Файл vars.php не входить у резервну копію. Він містить доступи до бази даних, секрети автентифікації та інші налаштування, специфічні для цього сервера, і не зберігається в базі - тримайте окрему копію цього файлу самостійно.

Відновити з резервної копії приймає файл, отриманий кнопкою вище (.json або .json.gz), і повністю замінює поточний вміст кожної таблиці, згаданої у файлі, її вмістом з файлу - без можливості скасування, тому форма вимагає підтвердження. Таблиці й окремі стовпці з файлу, яких вже не існує в поточній базі, просто пропускаються (не помилка, решта таблиці все одно відновлюється) - дозволяє відновити файл з дещо іншої версії схеми. Максимальний розмір файлу на цьому сервері - 2 МБ (обмеження PHP upload_max_filesize). Відновлення виконується у фоні з живим прогресом (та сама консоль, що й при оновленні PonControl) - рядки/таблиці, які довелось пропустити, видно прямо в цьому лозі.

Перед запуском оновлення PonControl (кнопка "Оновити"/"Force update") тепер показується попередження з тими самими двома кнопками (створити копію, продовжити) - оновлення більше не запускається одразу по кліку.

Підключає сторінку Логи в бічному меню до зовнішнього OpenObserve, який вже збирає syslog ваших OLT в один потік (stream) - PonControl лише читає з нього через API, нічого сам не приймає й не зберігає. Кожен рядок логу повинен мати поле source_ip зі значенням IP того OLT, з якого він прийшов - саме за цим полем відбувається фільтрація.

• OpenObserve URL - адреса вашого інстансу OpenObserve.
• OpenObserve Organization - ідентифікатор організації в OpenObserve.
• OpenObserve Stream - назва потоку, куди потрапляють логи OLT.
• OpenObserve User / Password/token - облікові дані для API (рекомендовано окремий Service Account, а не особистий логін).

Як знайти ці значення в OpenObserve

1. Переконайтесь, що логи OLT вже потрапляють в OpenObserve. Кожен рядок логу обов'язково повинен містити поле source_ip зі значенням IP-адреси OLT. Якщо у вашому конвеєрі збору логів (наприклад Fluent Bit/Vector/rsyslog → OpenObserve) це поле називається інакше - перейменуйте/змапте його на source_ip ще на етапі збору, до потрапляння в OpenObserve.

2. Знайдіть свій Organization. Увійдіть у веб-інтерфейс OpenObserve. Ідентифікатор організації видно в адресному рядку після входу (/web/organizations/<org>/...), а також у будь-якому готовому curl-прикладі на сторінці джерела даних (Data Sources).

3. Знайдіть назву потрібного Stream. У розділі Streams (або Logs → Streams) оберіть потік, у який потрапляють логи ваших OLT.

4. Створіть облікові дані для API (рекомендовано - Service Account). Технічно підійде звичайний логін/пароль вашого акаунту OpenObserve, але надійніше створити окремий Service Account (IAM → Service Accounts → Add Service Account) - він не може заходити в веб-інтерфейс OpenObserve, лише авторизовувати API-запити. Використайте email цього Service Account як "OpenObserve User", а виданий токен/пароль - як "OpenObserve Password/token".

5. Заповніть картку "OpenObserve integration" у Налаштуваннях PonControl значеннями з кроків вище і натисніть "Зберегти".

Огляд по OLT. Пункт меню "Логи" (без прив'язки до конкретного OLT) показує плитку для кожного OLT з кількістю повідомлень за обраний період (за замовчуванням останні 24 години). Там же можна обрати період і застосувати готовий фільтр або власний текстовий пошук - тоді кожна плитка показує кількість повідомлень саме за цим фільтром. Плитка червона, якщо повідомлень немає (з урахуванням фільтра). Якщо при цьому OLT онлайн, і немає взагалі жодного повідомлення (незалежно від фільтра чи періоду - перевіряється окремо, за ~10 років), і при наведенні на плитку, і на самій сторінці логів цього OLT з'явиться підказка, що для нього ще не налаштовано надсилання логів - фільтр чи період, які просто нічого не знайшли, такою підказкою не позначаються. Клік на плитку відкриває логи саме цього OLT з тим самим періодом і фільтром/пошуком, що були обрані на плитках.

Період та фільтри. На сторінці логів конкретного OLT (і на огляді по OLT вище) можна обрати період вибірки (1 година, 6 годин, 24 години, 7 днів або 30 днів) - за замовчуванням для конкретного OLT показуються записи лише за останню годину. Там же можна застосувати готовий текстовий фільтр (розділ "Фільтри логів" нижче) або ввести довільний текст у поле пошуку - обидва працюють однаково ("повідомлення містить цей текст") і взаємно виключають один одного. Якщо ввести власний текст, поруч з'явиться кнопка "Зберегти фільтр" (лише для адміністраторів), яка додає цей текст у список готових фільтрів.

Назва OLT. На сторінці логів конкретного OLT назва в заголовку (разом з IP) - посилання, що відкриває звичну картку цього OLT (не логи) у новій вкладці.

Графік кількості повідомлень. На сторінці логів конкретного OLT над таблицею завжди показується стовпчикова діаграма кількості повідомлень за обраний період - вісь X - час, вісь Y - кількість. Враховує той самий фільтр/пошук, що й таблиця нижче, і показується незалежно від того, чи є зараз результати в таблиці (наприклад, покаже сплеск повідомлень, який вже закінчився). Ширина одного стовпця підлаштовується під обраний період так, щоб діаграма лишалась читабельною (не більше ~60 стовпців), і ніколи не буває меншою за 5 хвилин. Клік на стовпець показує лише повідомлення саме за той відрізок часу - поруч із кнопками періоду (1г/6г/24г/7д/30д) з'являється чіп з обраним відрізком і кнопкою "×", яка знімає цей вибір і повертає до звичного періоду; клік на будь-яку з кнопок періоду теж знімає вибір відрізка.

Позначки логів. На відміну від фільтрів, розділ "Позначки логів" (також під OpenObserve integration) не приховує жодного рядка - кожне правило додає назву (для власного орієнтування у списку), іконку і/або злегка тонований фон рядкам, повідомлення яких містить вказаний текст, наприклад, позначити іконкою "power" рядки з "DYING_GASP" (ONU пропала через втрату живлення). Потрібно обрати хоча б щось одне - іконку чи колір фону (обидва не обов'язкові одночасно, але можуть бути застосовані разом) - кнопка "Скинути" біля кожного пікера знімає вибір. Колір обирається з тайлової палітри (як у виборі емодзі), іконка - зі списку (усі іконки теми, які має сенс використати як позначку, тобто без брендових логотипів); обидва пікери відкриваються власною кнопкою і закриваються по кліку поза ними. Колір застосовується лише як легкий, неконтрастний тон фону, ніколи як суцільна заливка. У кожного правила є текст для пошуку і де його застосовувати - три незалежні позначки (не взаємовиключний вибір): OLT логи (сторінка логів, відкрита з картки OLT чи плитки), ONU логи (відкрита з картки ONU - визначається тим, звідки відкрито сторінку, а не тим, що зараз введено в пошук), і логи кастомних пристроїв; усі три позначені за замовчуванням, і хоча б одна має лишатись позначеною. Готове правило можна редагувати (посилання "Редагувати" відкриває цю саму форму з уже заповненими полями) або видалити. Налаштувати правила можна лише з веб-версії (додавання, редагування - лише для адміністраторів); результат (іконки й колір фону) показується однаково і у веб, і в Android.

Кастомні пристрої. Розділ "Кастомні пристрої" (також під OpenObserve integration) додає джерела логів, які не є OLT - лише назва та IP-адреса, за якою шукаються повідомлення (те саме поле source_ip, що й для OLT). Потік (необов'язково) - якщо вказати, саме він використовується для запитів цього пристрою замість потоку, вказаного в основних налаштуваннях OpenObserve integration вище (поле показує його як підказку, поки не вказано власного значення). На відміну від OLT (логи якого бачить будь-хто, хто увійшов), логи кастомного пристрою за замовчуванням видно лише адміністраторам - позначка "Видимий для звичайних користувачів" у формі пристрою відкриває його логи й іншим. Якщо додано хоча б один кастомний пристрій, на сторінці "Логи" (без вибору конкретного OLT) завжди першою з'являється плитка "Кастомні пристрої" - вона відкриває окрему сторінку з плиткою на кожен такий пристрій, а клік на плитку відкриває для нього ту саму сторінку логів (з графіком, фільтрами й позначками), що і для звичного OLT. Плитки OLT мають дуже легкий синій відтінок фону, плитки кастомних пристроїв - дуже легкий жовтий; плитка без жодного повідомлення за обраний період (з урахуванням фільтра) лишається червоною незалежно від цього відтінку.

Технічні деталі: PonControl звертається до пошукового API OpenObserve (POST {URL}/api/{Organization}/_search) із SQL-запитом вигляду SELECT * FROM "{Stream}" WHERE source_ip = '<IP OLT>' [AND match_all('*<текст фільтра>*')] ORDER BY _timestamp DESC (обгортка в *...* - це синтаксис OpenObserve для пошуку "містить", без неї match_all шукає точний токен і не знайде, наприклад, "loop" всередині "loopback"), авторизуючись через HTTP Basic Auth (User/Password), і показує записи обраного періоду зі сторінковою навігацією по 20 записів. Кількість повідомлень (лічильник "Показано X-Y із Z" та плитки OLT) рахується окремим агрегатним запитом SELECT COUNT(*) ..., а не полем "total" з пошукового запиту вище - те поле на деяких розгортаннях OpenObserve не відображає справжню кількість збігів.