Skip to content

UniFi Miner guide in Russian

Jump to bottom
Grigory Prigodin edited this page Mar 5, 2021 · 19 revisions

Содержание

  • Обзор
  • Системные требования
  • Установка и настройка
  • Опции командной строки
  • Фильтры
  • Использование
    • Примеры запросов
  • Интеграция с системой мониторинга
    • Zabbix
  • Советы
    • Ускорение UniFi Miner
    • Получение данных, синхронизированных во времени
  • Решение проблем
    • Отказ в соединении с UniFi сервером
    • Ошибка SSL23_GET_SERVER_HELLO:unknown protocol
    • Проблемы, появляющиеся после подключения PPerl
    • Не выполняется правило автообнаружения или в элементы данных перестает поступать новая информация
    • Переход элемента данных Zabbix в состояние "Not supported"
    • Нарушена периодичность поступления данных в Zabbix, наблюдаются "дыры" в графиках, растет очередь Zabbix
    • Некорректная работа в конфигурации с несколькими сайтами

Обзор

UniFi Miner - это небольшой, написанный на Perl инструмент, который помогает передать в систему мониторинга (Zabbix) оперативные данные - показатели и настройки, полученные от контроллера UniFi через API, предоставленный компанией Ubiquiti. Протокол Zabbix Low-level Discovery (LLD) поддерживается. Так же, у UniFi Miner существует клиент-серверный аналог с повышенным быстродействием: UniFi Proxy

Практическим итогом взаимодействия UniFi Miner и Zabbix являются графики, подобные представленным ниже.

Количество клиентов, обслуживаемых точками доступа (UAP)

Zabbix: connected clients

Траффик в беспроводной сети

Zabbix: wireless traffic

Системные требования

  1. ОС Linux;
  2. UniFi контроллер v2, v3, v4, v5.

Так, как Perl является кроссплатформенным языком программирования, то UniFi Miner, теоретически, может быть адаптирован под множество операционных систем. Однако, возможность запуска ПО под ОС, отличной от среды разработки - Debian Linux, не исследовалась.

Основное тестирование идет на контроллере UniFi v5. Дополнительное, но менее тщательное (по причине отсутствия его в эксплуатации) - на v3 и v4. Программный код для v2 пишется с предположением, что он близок к v3 за некоторыми исключениями. Такими как, например, отсутствие сайтов.

Установка

Установка UniFi Miner достаточно незамысловата. Для ее осуществления необходимо:

  1. Получить ПО с сайта GitHub: git clone https://github.com/zbx-sadman/unifi_miner;
  2. Установить необходимые модули Perl. Для этого можно воспользоваться как штатным средством Perl - cpan JSON JSON::XS LWP LWP::Protocol::https IO::Socket::SSL Data::Dumper Time::HiRes, так и пакетным менеджером вашей ОС - aptitude install libjson-perl libjson-xs-perl libwww-perl liblwp-protocol-https-perl libio-socket-ssl-perl libdata-dumper-simple-perl libtime-hires-perl;
  3. Выставить необходимый для выполнения Perl-сценария режим доступа к файлу: chmod 0755 unifi_miner/unifi_miner.pl.

На этом этапе UniFi Miner уже готов к работе, но стоит потратить еще немного времени и внести в Perl-сценарий правки под вашу операционную систему и UniFi контроллер. Большинство параметров, необходимых для получения корректных результатов, можно задать при помощи опций командной строки, которые будут подробно описаны ниже. Однако, изменение некоторых важных настроек возможно произвести только прямым редактированием исходного кода. Будьте предельно внимательны при проведении этой операции - не удаляйте кавычки, запятые и иные знаки, которые могут вам показаться не очень красивыми и ненужными. Если вы понимаете, что написано в комментариях к программному коду - не стесняйтесь читать их.

Итак, воспользуйтесь самым простым текстовым редактором в вашей ОС, чтобы не превратить Perl-сценарий в документ PDF или HTML-страницу.

Пожалуй, единственное, что будет необходимо проделать в обязательном порядке - убедиться, что каталог, указанный в переменной cachedir действительно существует. Без него Miner работать не сможет, так как пользуется быстрым кэшем вместо осуществления медленных запросов к контроллеру UniFi каждый раз, когда вам будет необходимо узнать что-либо о его состоянии. Если в вашей системе нет указанного в данной переменной каталога, вы можете указать любой существующий. При этом необходимо учесть, что он должен быть доступен для чтения/записи пользователю, с учетными данными которого будет выполнятся UniFi Miner (например, пользователю zabbix). Для достижения максимальной эффективности при использовании кэша, я рекомендую располагать его в каталоге на RAM-диске. В этом случае экземпляр UniFi Miner, обнаруживший устаревшие данные (см описание опции -c), быстрее заменит их вновь полученными, а в случае расположения ОС на диске SSD - продлит время его жизни. В Linux вы можете найти такие каталоги по ключевому слову tmpfs в выводе команды df. Ими могут быть /run/shm, /dev/shm и пр.

Так же вам стоит обратить внимание на переменные cachemaxage (см. описание опции -c), unifilocation (опции -l), unifiuser и unifipass (-u и -p соответственно), unifiversion (-v), и sitename (-s), если на вашем контроллере существует не более одного сайта. Установка значений этих переменных в коде сценария позволит вам сократить количество опций командной строки, используемых при осуществлении запросов к контроллеру UniFi. Это даст вам сосредоточится на решении конкретной задачи, а не на работе с клавиатурой.

Возможно, что в некоторых вариантах инсталляции операционной системы вам будет недоступен пакет JSON::XS, поэтому, начиная с v1.3.5, применяется пакет JSON, позволяющий указать желаемый (доступный) парсер.

Опции командной строки

Практически при любом запуске UniFi Miner вы будете использовать те или иные опции командной строки. Обратите внимание на то, что значения всех опций вводятся в нижнем регистре. Экономия на функции проверки и преобразования регистра сделала Miner немножко быстрее - а это на данный момент очень важно. В описании опций вы будете видеть отсылки к формату JSON. Разъяснение этому факту будет дано в разделе "Использование".

Итак, общий формат интерфейса командной строки таков:
unifi_miner.pl [-o object_type] [-i {id | mac} | -m mac] [-k key] [-a action] [-l unifi_location] [-s sitename] [-u unifi_username] [-p unifi_password] [-v unifi_controller_version] [-d debug_level] [-j stringify_method] [-n null_replacer] [-c cachemaxage_sec]

где:

-o [ wlan ]

Тип искомого объекта.

На данный момент поддерживаются следующие типы:

  • site - сайт UniFi. Тип актуален для контроллеров v3, v4 и v5;
  • wlan - беспроводная сеть (конфигурации), рассматриваемая в рамках какого-либо сайта (для контроллеров v3, v4, v5) либо вне его (v2);
  • uap - UniFi Access Point (беспроводная точка доступа), так же рассматриваемая в рамках сайта или вне его;
  • usw - UniFi Switch (коммутатор UniFi);
  • ugw - UniFi Security Gateway (роутер UniFi);
  • uph - UniFi Phone (UVP);
  • extension - информация о зарегистрированных на контроллере voip-устройствах;
  • number - информация о сопоставленных voip-устройствам абонентских номерах;
  • alluser - пользователь, внесенный в архив контроллера. Т.е. когда-либо подключавшийся через любое, поддерживаемое контроллером устройство;
  • user - пользователь, подключенный в момент запроса через любое, поддерживаемое контроллером, устройство;
  • voucher - ваучер (см. Voucher Manager контроллера);
  • dpi - информация из раздела DPI, появившегося в выпуске v5;
  • sitedpi - информация из раздела DPI в измененном с v5.6 API;
  • health - текущее состояние модулей контроллера UniFi (см. Dashboard контроллера v4);
  • sysinfo - объект, содержащий некоторые системные данные о контроллере;
  • setting - объект, связанный с хранилищем настроек (см. закладку Settings > Site в web-интерфейсе контролера);
  • network - определенная на контроллере сеть (см. Settings > Networks);
  • usergroup - пользовательская группа (см. Settings > User Groups);

Также, в связи с тем, что Miner версии 1.1.0 и выше имеет возможность построения LLD-JSON по произвольному поддереву JSON, пользователем могут быть созданы виртуальные типы объектов. Эти типы используются при формировании LLD-JSON и их список может быть дополнен самостоятельно, путем редактирования исходного кода сценария perl. Для примера можно использовать специально созданные типы:

  • uap_vap_table - список виртуальных точек доступа определенной UAP;
  • usw_port_table - таблица портов UniFi Switch.

Стоит отметить, что объект wlan практически всегда присутствует на контроллере, что позволяет использовать операцию discovery для данного объекта в целях отладки.

-i [ ]

Внутренний ID или MAC искомого объекта.

Как правило - это значение JSON-ключа _id. Он генерируется непосредственно контроллером и, похоже, никак не соотносится с какими-либо настройками подключенного устройства. Узнать ID конкретного устройства объекта можно из соответствующего LLD-JSON при выполнении операции discovery, а так же изучая вывод на консоль при высоком уровне отладки (-d 3).

Однако, начиная с версии 1.1.0 Miner позволяет указывать в параметре -i MAC-адрес сетевого устройства UniFi. При этом применение ключа -m не является необходимым, хотя он и продолжает поддерживаться. Распознавание типа заданного идентификатора объекта происходит автоматически.

-m [ ]

MAC-адрес сетевого устройства UniFi.

Значение JSON-ключа mac. Опция актуальна только при использовании совместно с контроллером v4 и позволяет ускорить получение информации о данном объекте, так как поиск будет произведен самим контроллером, а не достаточно медленным в этом отношении Perl-сценарием. Я рекомендую в обязательном порядке использовать этот способ адресации объекта при большом количестве UniFi устройств, находящихся в одном сайте. При использовании опции -m, применение -i не требуется.

Внимание! В последующих выпусках UniFi Miner поддержка этого параметра будет прекращена. Вместо него следует использовать -i.

-k [ ]

Ключ метрики или настройки, значение которой необходимо получить.

Представляет собой имя JSON-, составного или виртуального ключа. Составные ключи - конструкции, представляющие собой путь к JSON-ключу по JSON-поддереву. Так, к примеру, составной ключ stat.tx_dropped, означает, что запрашивается метрика, ассоциированная с JSON-ключом tx_dropped, находящемся во вложенном JSON-объекте stat.

Составной ключ так же может включать в себя выражение фильтра. Это необходимо для адресации не имеющих мнемонических имён элементов массива JSON. Например, фильтр может быть применен для получения значений из объекта таблицы port_table, которая содержит оперативные данные физических портов коммутатора UniFi Switch (USW). Подробнее о фильтрах можно почитать в соответствующем разделе.

Кроме того, Perl-сценарий поддерживает обработку виртуального ключа items_num. Он предназначен для быстрого подсчета количества отобранных объектов, например - количества устройств определенного типа в выборке.

Увидеть доступные JSON-ключи объектов можно как при помощи API, обратившись по соответствующей ссылке (например https://unifi:8443/api/s/default/stat/device), так и изучив файл кэша или вывод на консоль команды discovery (см. -a) при высоком уровне отладки (-d 3).

Применение составных и иных видов ключей будет рассмотрено в разделе "Примеры запросов".

-a [ discovery ]

Групповая операция или действие, производимое над JSON-ключами в том случае, если обрабатывается список объектов (например - все UAP в пределах сайта). На данный момент поддерживаются следующие виды действий:

  • discovery - получение ответа в формате JSON, предназначенного для низкоуровневого обнаружения, используемого Zabbix;
  • get - получение значения метрики, заданной ключом (-k) содержащейся в единственном или первом подходящем под условия фильтра объекте;
  • count - получение количества найденных JSON-ключей, подходящих под условие фильтра;
  • sum - вычисление суммы метрик, принадлежащим разным объектам одного типа;
  • max - нахождение максимального значения среди результатов отбора;
  • min - нахождение минимального значения среди результатов отбора;
  • pcount - вычисление процента найденных при применении фильтра JSON-ключей от их общего количества;
  • psum - вычисление процента суммы значений отфильтрованных JSON-ключей от их общей сумм;
  • amean - вычисление среднего арифметического суммы значений отфильтрованных JSON-ключей;
  • median - вычисление среднего медианного значений отфильтрованных JSON-ключей.
  • raw - возвращение фрагмента обрабатываемого дерева JSON, подпадающего под фильтр. Выражение фильтра при этом должно завершаться виртуальным ключом *

Несомненно, что некоторые групповые операции дублируют функциональность системы мониторинга, но существуют ситуации, в которых вычисления на стороне UniFi Miner применять предпочтительней. Так, например, доставка значений метрик в Zabbix, как правило, не синхронизирована во времени. Метрика num_sta (количество обслуживаемых клиентов) одной беспроводной точки доступа, ко времени получения аналогичной метрики со второй или третьей точки, может измениться весьма значительно. Таким образом, в Zabbix будет невозможно произвести какую-либо групповую операцию в рамках одного временного промежутка и получить результат, отражающий действительность. Так же, на мой взгляд, не имеет смысла доставлять в систему мониторинга и хранить в ней метрики, предназначенные только для суммирования или подсчета: например, состояние authorized подключенного к точке доступа клиента при необходимости наблюдения за ростом неавторизованных подключений (pending users).

В силу того, что определенные метрики, такие как adopted, isolated, is_guest и пр. имеют булеву природу, результат подсчета (count) количества объектов, находящихся в состоянии, которое отражают данные метрики, совпадает с результатом суммы (sum) таковых метрик. В ряде случаев замена count на sum даст выигрыш во времени выполнения. Например, вычисление суммы метрики vap_table.is_guest будет произведено быстрее, чем подсчет метрик vap_table.[is_guest=1].essid за счет исключения стадии отбора по фильтру.

-l [ https://127.0.0.1:8443 ]

Местонахождение интерфейса контроллера.

Несмотря на то, что при помощи опции -l можно указать местонахождение интерфейса контроллера отличное от localhost, на мой взгляд продуктивней использовать UniFi Miner на том же узле, где установлен сам UniFi контроллер. Выигрыш от этого будет наблюдаться на системах, обслуживающих значительное количество устройств или опрашиваемых через публичные или иные медленные или высоконагруженные сети, так как получение большого JSON-ответа контроллера в пределах одного узла будет происходить гораздо быстрее.

-s [ ]

Имя сайта, в котором располагается искомый объект или устройство UniFi.

Опция актуальна для контроллеров v3, v4, v5. Начиная с версии 1.1.0, в случае отсутствия имени, Miner произведет запрос списка всех существующих на контроллере сайтов и последовательно применит к ним заданную групповую операцию. Результат будет обобщен.

Внимание! Обратите внимание на особенность UniFi Controller v4: имя сайта, которое вы видите в web-интерфейсе, является его описанием. Настоящее имя, которое требуется указывать в данном параметре, находится в адресной строке - https://unifi:8443/manage/s/**имя-сайта**/dashboard. В пределах сайта оно представляет собой уникальную случайную строку. Таким образом, для сайта 'Tokio Office' именем, которое следует указывать при запуске UniFi Miner для работы с v4, может являться, к примеру 'zc6h0sgv'.

-u [ stat ]

Имя учетной записи, применяемой для доступа к API контроллера.

Данная учетная запись к моменту использования UniFi Miner уже должна существовать на контроллере UniFi. Т.е. вы должны иметь возможность авторизоваться с ее помощью по ссылке https://unifi:8443.

Конечно, вы можете применить для доступа к API имя и пароль пользователя admin, создаваемого при первичной настройке контроллера, но при этом вам необходимо учитывать, что для доступа по протоколу ssh к физическим устройствам UniFi применяются учетные данные этого же пользователя и их публикация в открытом виде может привести к определенным неприятностям. Поэтому, в случае интеграции UniFi Miner с системой мониторинга, разумным выглядит использование в режиме Read-only учетной записи другого пользователя, созданного на контроллере. Дополнительной защитой может указание имени и пароля учетной записи непосредственно в сценарии через переменные unifiuser и unifipass - в этом случае они не будут передаваться через сеть.

-p [ stat ]

Пароль учетной записи, применяемой для доступа к API контроллера.

См. примечания к опции -u

-v [ v5 ]

Версия контроллера: v2, v3, v4, v5.

Для успешной обработки запроса Miner должен использовать правильные методы получения данных от контроллера UniFi. Это обеспечивается указанием версии контроллера, с которой предстоит работать. Однако, если вы не планируете использование UniFi Miner с контроллерами разных версий, гораздо удобнее установить значение переменной unifiversion в программном коде Perl-сценария.

-d [ 0 ]

Уровень отладки: 0..3.

При использовании любой программы не исключены случаи, когда она не запускается или выдает неверные результаты, но почему так происходит - непонятно. Если такое случилось с UniFi Miner, то выяснить причину непонятного поведения поможет режим отладки, при котором на консоль будет выведен отчет о выполнении внутренних процедур и состоянии некоторых ключевых переменных. Подробность отчета определяется числом, задающим уровень отладки: 0 - отсутствует, 3 - самая подробная. Максимальная подробность так же полезна тем пользователям, которые хотят узнать, какие метрики объектов и устройств UniFi они могут контролировать.

-j [ pretty ]

Способ преобразования JSON-объекта в текстовый формат.

Результатом некоторых операций является JSON-объект, преобразуемый перед выдачей пользователя в текстовый формат. Начиная с выпуска v1.3.8 UniFi Miner позволяет использовать следующие методы:

  • inline - текст выводится единой строкой с ограничением объёма в 65Kb, что одновременно является для Zabbix предельным размером входящего текстового фрагмента (строки), завершенного символом LF (EOL, '\n');
  • pretty - форматированный текст, содержащий отступы, выравнивание и состоящий более, чем из одной строки. Это позволяет обойти ограничение, свойственное методу inline, и передать в Zabbix результат работы UniFi Miner, превышающий объём 65k.

В ранних выпусках фактически использовался только метод inline.

-n [ ]

Заменитель значения JSON:null.

Значения некоторых метрик могут принимать значение null (например, ng_ast_txto объекта UAP, для которого ожидаются цифровые значения). Или, при использовании фильтров в результате отбора может не оказаться ни одного значения, но отсутствие значение на графике в Zabbix будет выглядеть логически неправильным. Однако, такое же значение сценарий возвращает в том случае, если заданный ключ не обнаружен или указывает на вложенный объект. Для пользователя результат обработки такого ключа выглядит, как пустая строка.

В случае использования Miner совместно с Zabbix, это вызывает переход элементов данных "цифрового типа" в состояние UNSUPPORTED. Если вас не устраивает такое поведение, то в качестве обходного пути вы можете использовать опцию -n и заменить null (пустую строку) на 0 или иное удобное число. Так, к примеру, при отсутствии данных по уровню шума радиосреды, стоит вернуть значение -100.

Но учитывайте, что необдуманное использование данной опции приведет к маскировке реальных проблем и затруднит понимание результатов работы UniFi Miner.

-c [ 60 ]

Время устаревания кэша.

Miner применяет кэширование JSON данных, полученных от контроллера UniFi. Это позволяет в разы ускорить выполнение запросов пользователя. Также, при этом достигается некоторая синхронизация передаваемых Zabbix-серверу значений ключей (проблема обозначена в описании опции -a). Такое свойство позволяет получать красивые комплексные графики и составлять не расходящиеся в показателях отчеты.

Каждый запущенный экземпляр Perl-сценария проверяет "возраст" хранимых данных, с которыми он собирается работать и, в случае их устаревания, производит обновление при помощи достаточно медленного запроса к API контроллера. Значение параметра равное 0 отключает все процедуры, связанные с кэшированием, а данные запрашиваются напрямую с контроллера. На мой взгляд - "возраст" не должен быть меньше минимального времени обновления данных в веб-интерфейсе контроллера и минимального времени опроса элемента данных в применяемой системе мониторинга.

Данный параметр стоит задать напрямую в программном коде Perl-сценария, отыскав переменную cachemaxage

Фильтры

В процессе использования Miner вы можете столкнуться с необходимостью применения агрегирующих функций к метрикам некоторой части объектов заданного типа. Например - к UAP, работающих только в режиме NG или к пользователям, с уровнем сигнала не выше 20dBm.

Для выделения такой части объектов следует применять фильтры. Фильтр представляет собой часть составного ключа и должен быть заключен в квадратные скобки. Фильтр может содержать одно или несколько выражений. В последнем случае выражения должны быть соединены с помощью знака логического оператора:

  • & (операция AND);
  • | (операция OR, применима к версии 1.1.0 и выше).

Внимание! Одновременное использование разных логических операторов в одном выражении фильтра не поддерживается.

Выражение фильтра записывается, как "JSON-ключусловиезначение". Условие определяется знаками:

  • = - равенства;
  • <> - неравенства (применимо к версии 1.1.0 и выше);
  • <, >, <=, >= - меньше, больше, меньше или равно, больше или равно (применимо к версии 1.3.0 и выше).
  • =~, !~ - сравнение значения ключа по маске, определяемой выражением RegExp (применимо к версии 1.3.6 и выше). Значение ключа при анализе будет подставлено в RegExp оператор: m/значение/s

Внимание! Пробельные символы слева и справа знака условия будут рассматриваться как части JSON-ключа и значения соответственно.

Так, как выражение фильтра может содержать двоеточия, пробельные и прочие нестандартные символы, я рекомендую при запуске UniFi Miner заключать в кавычки составной ключ, содержащий фильтр.

Примеры фильтров можно увидеть в разделе "Примеры использования UniFi Miner".

Использование

Важно знать, что UniFi контроллер использует JSON для обмена данными со внешними программами. Это поможет понять принцип составления запросов, осуществляемых при помощи UniFi Miner.

Основная структура хранения сведений об устройствах, подключенных к UniFi контроллеру - массив JSON объектов, содержащих ключи, отражающие какие-либо метрики или настройки устройства (например - точки доступа, коммутатора и пр.) или внутренней сущности (например сайта, беспроводной сети и пр). Адресация конкретного объекта производится по принадлежащему ему JSON-ключу _id.

По вашему запросу UniFi Miner применит групповую операцию или действие ко всем значениям метрики, ассоциированной с ключом, заданным параметром -k. Значения метрик берутся из списка объектов, определенного через -o типа (или типа по умолчанию) в заданном сайте (-s). В том случае, если будет указан идентификатор (-i или -m), действие будет выполнено в отношении одного объекта. При выполнении групповой операции discovery опция -k игнорируется.

Результатом работы сценария является значение метрики, групповой операции, LLD-JSON в формате Zabbix или пустая строка (null). Последнее значение возвращается при неверно заданном ключе или отсутствии ассоциированного с ним JSON-ключа в объекте (например, при выключенном физическом устройстве). Однако, ряд существующих JSON-ключей могут иметь значение null (см. описание опции -n).

Примеры использования UniFi Miner

Получение списка объектов по умолчанию в формате Zabbix Low-level Discovery (LLD) из всех сайтов (только для v3, v4)

./unifi_miner.pl

Получение самого актуального списка объектов "точка доступа UniFi" (UAP) в формате LLD из сайта 'zc6h0sgv' (см. примечание к опции командной строки -s). Данные берутся напрямую с контроллера (без применения кэша)

./unifi_miner.pl -a discovery -o uap -s zc6h0sgv -c 0

То же самое, но при работе с контроллером v3, находящимся по адресу https://127.0.0.2:8443

./unifi_miner.pl -a discovery -o uap -s zc6h0sgv -v v3 -l https://127.0.0.2:8443 -c 0

Получение количества UAP, зарегистрированных на контроллере

./unifi_miner.pl -a sum -o uap -k items_num

Количество активных UAP во всех сайтах контроллера

./unifi_miner.pl -a count -o uap -k "[state=1].state"

Процент активных UAP от их общего числа во всех сайтах контроллера

./unifi_miner.pl -a pcount -o uap -k "[state=1].state"

Получение количества UAP в сайте 'zc6h0sgv', находящихся в состоянии adopted

./unifi_miner.pl -a sum -o uap -s zc6h0sgv -k adopted

Получение количества клиентов, обслуживаемых на данный момент всеми UAP сайта 'zc6h0sgv'. Обратите внимание, что второй способ сработает быстрее, но может быть применен только совместно с контроллерами v3, v4

./unifi_miner.pl -a sum -o uap  -s zc6h0sgv -k num_sta
./unifi_miner.pl -a get -o site -s zc6h0sgv -k num_sta

Получение количества клиентов в статусе 'гость', обслуживаемых на данный момент конкретной UAP. Заметьте, что при указании имени сайта, Miner обработает запрос быстрее

./unifi_miner.pl -a get -o uap -k guest-num_sta -i 5523fe519932508ffaf3b404 
./unifi_miner.pl -a get -o uap -s zc6h0sgv -k guest-num_sta -i 5523fe519932508ffaf3b404

Получение значения ключа tx_dropped, находящегося в таблице (вложенном объекте) stat конкретной UAP

./unifi_miner.pl -a get -o uap -s zc6h0sgv -k stat.tx_dropped -i 5523fe519932508ffaf3b404

Получение количества гостевых сетей, обслуживаемых конкретной UAP

./unifi_miner.pl -a sum -o uap -s zc6h0sgv -k vap_table.is_guest -i 5523fe519932508ffaf3b404

Получение имен ключей и внутренних идентификаторов точек доступа в файл report.txt

./unifi_miner.pl -o uap -d 3 > report.txt

Получение данных о количестве клиентов, подключенных на данный момент к UAP с MAC 00:27:22:d8:33:23 с проверкой актуальности кэша в 1ч (3600 сек). Обратите внимание на то, что во втором способе MAC-адрес указан в параметре -i. Это справедливо для Miner 1.1.0 и выше

./unifi_miner.pl -a get -o uap -s zc6h0sgv -k guest-num_sta -m 00:27:22:d8:33:23 -с 3600
./unifi_miner.pl -a get -o uap -s zc6h0sgv -k guest-num_sta -i 00:27:22:d8:33:23 -с 3600

LLD-JSON для портов определенного коммутатора UniFi. Заметьте, что в -k указан JSON-ключ, определяющий JSON-поддерево, по которому производится построение LLD-ответа. Виртуальный объект usw_port_table применяется только для определения включаемых в LLD-JSON макросов

./unifi_miner.pl -a discovery -o usw_port_table -s zc6h0sgv -k port_table -i 5523fd299932508fda3fe987

Получение количества портов определенного коммутатора UniFi, находящихся в состоянии 'POE enable'. Групповая операция sum применена по причине того, что применение count приведет к вычислению количества ключей "up" вне зависимости от их значения, а следовательно - состояния портов

./unifi_miner.pl -a sum -o usw -s zc6h0sgv -k "port_table.[poe_enable=1].up" -i 5523fd299932508fda3fe987

Получение значения потребляемой мощности POE порта #13 (ключ poe_power), коммутатора с заданным ID

./unifi_miner.pl -a get -o usw -s zc6h0sgv -k "port_table.[port_idx=13].poe_power" -i 5523fd299932508fda3fe987

Получение количества портов определенного коммутатора UniFi, находящихся в состоянии 'POE enable' и работающих на скорости 1Gbit/sec

./unifi_miner.pl -a sum -o usw -s zc6h0sgv -k "port_table.[poe_enable=1&speed=1000].up" -i 5523fd299932508fda3fe987

Получение значения ключа jumbo, относящегося к порту коммутатора, имеющему алиас "Port 1"

./unifi_miner.pl -a get -o usw -s zc6h0sgv -k "port_table.[name=Port 1].jumbo" -i 5571c343e4b0c5f69fea8d2c

Получение количества байт принятых совокупно виртуальными точками доступа, работающими в гостевом режиме с шифрованием отличным от WEP и принадлежащим физическим точкам доступа с именами "UAP01" и "UAP08"

./unifi_miner.pl -a sum -o uap -s zc6h0sgv -k "[name=UAP01|name=UAP08]vap_table.[is_guest=1&is_wep<>1].rx_bytes"

Процент активных пользователей, подключенных с помощью любых иных устройств, кроме продукции фирмы Apple

./unifi_miner.pl -a pcount -o user -s zc6h0sgv -k "[oui<>Apple].oui"

Процент когда-либо подключавшихся пользователей, использовавших продукцию фирмы Apple или Samsung

./unifi_miner.pl -a pcount -o alluser -s zc6h0sgv -k "[oui=Apple|oui=SamsungE]"

Средний уровень шума, для активных клиентов, зарегистрированных на точке доступа с заданным MAC-адресом

./unifi_miner.pl -a amean -o user -s zc6h0sgv -k "[ap_mac=00:27:22:d8:33:23].noise"

Количество клиентов, зарегистрированных на точках доступа, MAC-адрес которых содержит в себе фрагменты "16:5c" и "73:13"

./unifi_miner.pl -a count -o uap -s default -k "[mac=~16:5c|mac=~73:13].num_sta"

Версия ПО контроллера UniFi

./unifi_miner.pl -a get -o sysinfo -k version

Состояние модуля WLAN, отображаемого на dashboard веб-интерфейса контроллера UniFi

./unifi_miner.pl -a get -o health -s zc6h0sgv -k "[subsystem=wlan].status"

JSON, получаемый с контроллера UniFi при обработке объекта site

./unifi_miner.pl -a raw -o site -s default -k "*"

LLD-JSON для VOIP-устройств, зарегистрированных на контроллере

./unifi_miner.pl -a discovery -o extension -s zc6h0sgv

Абонентский номер VOIP-устройства, ассоциированный с extension с заданным ID

./unifi_miner.pl -a get -o number -s zc6h0sgv -k "[extension_id=5698e7779932af54c74bad18].number"

Интеграция с системой мониторинга.

Zabbix

Zabbix использует несколько вариантов взаимодействия с пользовательскими программами:

Самым простым и безопасным мне видится способ с расширением функциональности Zabbix-агента установленного на сервере, обслуживающем контроллер UniFi. В этом случае необходимо включить в конфигурационный файл Zabbix-агента или вынести в отдельный, подключив его при помощи директивы Inclide=:

# (1) Для использования UniFi Miner в режиме совместимости с шаблоном UniFi Proxy
UserParameter=unifi.proxy[*],/usr/local/bin/zabbix/unifi_miner.pl -a "$1" -o "$2" -s "$3" -k "$4" -i "$5" -n "$6" -c "$7"

Затем следует перезапустить Zabbix агент и проверить корректность работы UniFi Miner: zabbix_agentd -t unifi.proxy[discovery,wlan].

Макросы, применяемые в LLD ({#MACRO}) можно увидеть в результате выполнения групповой операции discovery над интересующим вас типом объекта.

Советы

Ускорение UniFi Miner

Если ваш узел в Zabbix или шаблон содержит большое количество элементов данных, вызывающих запуск Perl-сценария, то, скорее всего, вы столкнетесь с проблемой, заключающейся в высокой загрузке CPU. Повышение нагрузки происходит при любом обновлении элемента данных Zabbix, влекущем за собой запуск внешней программы. Таким образом, чем чем чаще будут обновляться элементы данных, тем больше экземпляров UniFi Miner будет одновременно выполнятся вашим сервером. И тем выше будет его загрузка. К сожалению, на данный момент, нет простой возможности радикально улучшить эту ситуацию, но есть ряд уловок, позволяющих сократить время выполнения Perl-сценария (или обратитесь к UniFi Proxy, если вас не удовлетворяет скорость работы Miner).

  1. Самая простая - сократить количество наблюдаемых метрик и/или увеличить время их опроса. Кроме того: использовать более простые ключи, избегать применения фильтров в составных ключах и неоправданных групповых операций (например, значение ключа num_sta из объекта site будет получено быстрее, чем сумма значений ключа num_sta в объектах uap), идентифицировать сетевые устройства по MAC-адресу. При использовании совместно с Zabbix - указывать тип элемента данных как Zabbix-agent (active) - в этому случае полученные результаты будут отсылаться на сервер группой.

  2. Посложнее - отключить неиспользуемые модули в Perl-сценарии, уменьшив время его инициализации. Таковыми можно считать библиотеку 'Data::Dumper' (при отключении вы не сможете пользоваться отладкой, применяя опцию -d), прагмы 'strict', 'warnings'. Просто запретите их подключение в начале unifi_miner.pl символом #.

  3. Наиболее действенная - применить Persistent Perl. Его установка производится как из CPAN командой cpan PPerl, так и из системного репозитория aptitude install pperl. Затем следует заменить вызов perl на вызов pperl в первой строке Perl-сценария. Впрочем, этот способ не зря является самым сложным - скорее всего вы столкнетесь с проблемами использования этой утилиты. Как решить часть из них - описано в разделе "Решение проблем".

Получение данных, синхронизированных во времени

Использование инструмента, позволяющего получить только одно значение за запуск, при анализе ситуации, требующей сопоставления нескольких параметров, связано с опасностью получения сведений за разные периоды времени, что может привести к недостоверным выводам.

Miner позволяет избежать такой ситуации в силу того, что кэширует полученные от контроллера UniFi данные. Использовать эту особенность можно применяя последовательные запросы:

#!/bin/bash
# запрос, обновляющий кэш данных устройств UniFi - актуальность кэша 1 сек
NA_TX_DROPPED = `./unifi_miner.pl -a get -o uap -s zc6h0sgv -k stat.na-tx_dropped -i 5523fe519932508ffaf3b404 -с 1`
# запросы, использующие обновленный кэш - актуальность 60 сек
NG_TX_DROPPED = `./unifi_miner.pl -a get -o uap -s zc6h0sgv -k stat.ng-tx_dropped -i 5523fe519932508ffaf3b404 -с 60`
NA_NUM_STA = `./unifi_miner.pl -a get -o uap -s zc6h0sgv -k na-num_sta -i 5523fe519932508ffaf3b404 -с 60`
NG_NUM_STA = `./unifi_miner.pl -a get -o uap -s zc6h0sgv -k ng-num_sta -i 5523fe519932508ffaf3b404 -с 60`
CCQ = `./unifi_miner.pl -a amean -o uap -s zc6h0sgv -k vap_table.ccq -i 5523fe519932508ffaf3b404 -с 60`
# Передача значений в базу данных
rrdtool update stat_uap_01.rrd N:${NA_TX_DROPPED}:${NG_TX_DROPPED}:${NA_NUM_STA}:${NG_NUM_STA}:${CCQ}

Разумеется, вы должны быть уверены, что все запросы будут выполнены в течении 60 секунд.

Решение проблем

Отказ в соединении с UniFi сервером

Проявление: отказ в соединении с сервером при заведомо действительных учетных данных пользователя, имеющего право на доступ к API контроллера.

Возможная причина: неверно указана версия контроллера.

Исправление: проверьте значение опции -v или содержание переменной $globalConfig->{'version'} (вы можете использовать -d 2 для ее просмотра).

Ошибка SSL23_GET_SERVER_HELLO:unknown protocol

Проявление: отказ в соединении с сервером с кодом ошибки 500. При использовании опции -d 3 наблюдается строка 'SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol'.

Возможная причина: изменения в актуальном модуле LWP - более не поддерживается опция 'SSL_verify_mode', осуществляется попытка соединения с применением SSLv2/SSLv3 вместо используемого контроллером UniFi TLSv1.

Исправление: раскомментируйте в начале кода UniFi Miner строки:

#use IO::Socket::SSL;
#IO::Socket::SSL::set_default_context(new IO::Socket::SSL::SSL_Context(SSL_version => 'TLSv12', SSL_verify_mode => Net::SSLeay::VERIFY_NONE()));

Проблемы, появляющиеся после подключения PPerl

Проявление: после замены в файле Perl-сценария вызова perl на pperl UniFi Miner перестает нормально работать, запускается через раз. Видны ошибки типа 'Cannot open lock file'.

Возможная причина (1): отсутствует директория .pperl в домашнем каталоге пользователя или права на запись в нее, либо не существует домашний каталог пользователя, под учетной записью которого выполняется Perl-сценарий. В ранних версиях PPerl существовала опция -T, позволявшая задать каталог размещения рабочих файлов, но в современной (0.25) путь к каталогу прописан в программном коде и недоступен для изменения.

Исправление (1): создайте домашний каталог пользователя и/или директорию .pperl, откорректируйте права доступа. Путь к домашнему каталогу можно уточнить при помощи команды cat /etc/passwd | grep zabbix (если запуск производится из-под учетной записи zabbix).

Возможная причина (2): отсутствует свободное место на разделе, где должны располагаться рабочие файлы PPerl.

Исправление (2): освободите занятое место.

Не выполняется правило автообнаружения или в элементы данных перестает поступать новая информация

Проявление: Perl-сценарий завершается аварийно с ошибкой вида '...unlink error' или 'Presumably no rights to unlink', что отражается в веб-интерфейсе Zabbix. Правило автообнаружения выдает ошибку "Value should be a JSON object".

Возможная причина: был произведен однократный или многократный запуск сценария, работающего в обычном режиме из под учетной записи ограниченного пользователя (например zabbix), под учетной записью иного пользователя (например root). В результате чего файлы кэша были созданы таким образом, что их невозможно удалить под учетной записью ограниченного пользователя.

Исправление: Измените группу/владельца файлов кэша или самостоятельно удалите их из cachedir. В последнем случае они будут пересозданы при следующем запуске UniFi Miner. Для ускорения процесса можно удалить все файлы кэша.

Переход элемента данных в состояние "Not supported"

Проявление: Использование составных ключей, содержащих фильтр вызывает переход элемента данных Zabbix в состояние "Not supported".

Возможная причина: Zabbix агент не может обработать ключ, содержащий в себе знаки '[', '&', ']' и пр.

Исправление: используйте директиву UnsafeUserParameters=1 в конфигурационном файле Zabbix-агента.

Нарушена периодичность поступления данных в Zabbix, наблюдаются "дыры" в графиках, растет очередь Zabbix

Проявление: Линии в графиках Zabbix имеют "пробелы" или вместо них отображаются редкие опорные точки. На странице "Последние данные" для какого-либо элемента данных видно, что периодичность поступления не совпадает с ожидаемой. В очереди опроса Zabbix видны задержки в получении данных от Zabbix-агента

Возможная причина: агент пропускает запуск проверок, осуществляемых последовательно, в активном режиме (тип пулера Zabbix agent (active)) по причине их большого количества или медленного выполнения.

Исправление: снижайте количество элементов данных, проверяемых с помощью в активного режима или переводите их в пассивный режим (Zabbix agent) с одновременным увеличением количества пулеров (StartPollers) Zabbix сервера. Так же вы можете перейти на использование UniFi Proxy.

Некорректная работа в конфигурации с несколькими сайтами

Проявление: В результатах работы отсутствуют данные с одного, нескольких или всех сайтов, за исключением 'default'.

Возможная причина: Miner использует специально созданную для него учетную запись для доступа к контроллеру. Эта учетная запись не имеет доступа к сайтам, данные которых не учитываются при работе.

Исправление: создайте используемую учетную запись с одинаковым паролем во всех сайтах контроллера или воспользуйтесь учетной записью, созданной по умолчанию.

Clone this wiki locally