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

Якщо файл конфігурації (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. За потреби налаштуйте розділи нижче - у Налаштування → Інтеграції (Userside, Zabbix, OpenObserve, Telegram), а також Безпека і Планувальник.

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

Назва мережі - необов'язковий підпис, який показується перед "PonControl" у заголовку вкладки браузера та в назві запису двофакторної автентифікації в застосунку-автентифікаторі - щоб цю інсталяцію легко було відрізнити від інших. Якщо залишити порожнім, використовується домен сервера.

Двофакторна автентифікація (2FA) для акаунтів співробітників, які заходять за логіном і паролем. Акаунти, що заходять лише через прив'язаний Google-акаунт, її не використовують - Google уже виконує цей другий крок.

• Як увімкнути (кожен для свого акаунту) - відкрийте меню акаунту (ваш логін угорі) → Змінити пароль → вкладка Двофакторна автентифікація. Відскануйте QR-код застосунком-автентифікатором (Google Authenticator, Microsoft Authenticator, Authy або будь-яким іншим, що підтримує TOTP), потім введіть 6-значний код, який він покаже, для підтвердження.
• Резервні коди - десять одноразових кодів показуються один раз, коли 2FA вмикається. Збережіть їх у надійному місці: кожен працює один раз, якщо ви втратите телефон. Новий набір можна згенерувати з тієї самої вкладки - це анулює старі.
• Вхід з 2FA - після пароля введіть поточний код із застосунку або один із резервних кодів.
• Вимагати 2FA для входу за паролем (перемикач адміністратора, Налаштування → Безпека) - співробітники без 2FA при наступному завантаженні сторінки потрапляють на сторінку налаштування і не можуть користуватися рештою сайту, доки її не налаштують. Вхід за паролем у Android-застосунку діє за тим самим правилом.
• Показувати банер-нагадування про 2FA (перемикач адміністратора) - нагадування вгорі кожної сторінки для акаунтів, що заходять за паролем і ще не увімкнули 2FA. Не показується, поки обов'язковий режим увімкнено - сторінка налаштування вже покриває цей випадок.
• Заблоковано? Адміністратор може скинути 2FA користувача в списку користувачів (кнопка "Скинути 2FA" у його рядку). Після цього акаунт заходить лише за паролем, доки користувач знову не налаштує 2FA.

Фонова робота PonControl виконується однією службою, poncontrol.service, а не записами cron. Її завдання перелічено в Налаштування → Планувальник → Завдання, кожне з перемикачем увімкнення та інтервалом:

• Опитування всіх OLT - оновлює стан і сигнал кожної ONU з кожного OLT. За замовчуванням кожні 2 хвилини; мінімум - 1 хвилина.
• Сповіщення про обрані ONU - перевіряє ONU, які співробітники додали в обрані, і фіксує відключення та повернення в мережу (з причиною) - Android-застосунок перетворює це на сповіщення. За замовчуванням кожну хвилину; мінімум - 30 секунд.
• Перевірка оновлень - шукає новішу збірку PonControl. За замовчуванням кожні 10 хвилин; мінімум - 1 хвилина. Лише перевіряє - оновлення застосовуються тільки коли адміністратор натисне "Оновити".
• MAC Peleng (повний перегляд FDB) - читає повну таблицю MAC з кожного OLT. Це важке завдання, тому воно вимкнене за замовчуванням.

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

Заплановані перезавантаження (Налаштування → Планувальник → Заплановані перезавантаження) - оберіть OLT, дату й час, і OLT перезавантажиться через telnet, щойно настане цей час. Виконання відбувається на наступному циклі опитування після цього часу, а не з точністю до секунди. Дата й час не можуть бути в минулому - перевіряє сторінка і сервер. Очікуване перезавантаження можна скасувати з того самого списку.

Якщо служба не працює, адміністраторська панель показує попередження з командами для її встановлення.

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

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

Zabbix не обов'язково має працювати на тій самій машині, що й PonControl. Сповіщення про обрані ONU від нього не залежать - їх надсилає служба планувальника. Якщо Zabbix працює на цьому сервері, його скрипти сповіщень мають могти читати кілька файлів 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 не відображає справжню кількість збігів.