Ad Widget

Collapse

Ubiquiti UniFi + zabbix

Collapse
X
 
  • Time
  • Show
Clear All
new posts
  • sadman
    Senior Member
    • Dec 2010
    • 1611

    #1

    Ubiquiti UniFi + zabbix

    Use actual release of UniFi Miner, please. So, if u need to monitor a lot UniFi metrics, try UniFi Proxy too

    Пожалуйста используйте последнюю версию UniFi Miner. Так же, если вам необходимо наблюдать за большим количеством метрик UniFi, попробуйте UniFi Proxy.

    Волею судеб я являюсь администратором небольшой беспроводной сети, построенной на оборудовании Ubiquiti UniFi. Основным недостатком этого оборудования, лично для меня, является отсутствие взаимодействия со внешними системами мониторинга. Эта необходимость заставила меня накидать скрипт, которым я хочу с вами поделиться. Он устанавливается на контроллер UniFi и дергает статистику прямо из базы данных. Взаимодействие с Zabbix осуществляется через UserParameter.

    Собратья по несчастью, жду от вас откликов и предложений по поводу параметров системы, которые стоило бы мониторить.

    Не забывайте установить модуль для работы с MongoDB для Perl.

    Code:
    #!/usr/bin/perl
    #
    # 21/03/2014
    #
    # UniFi database miner for Zabbix monitoring system. Tested with v3.1.6 controller Software
    # 
    # Just add some UserParameter to zabbix_agentd.conf and create proper items for Zabbix system.
    # Example:
    #           UserParameter = unifi.stat.ap[*],/usr/local/sbin/unifi_miner.pl $1 APCurrentState $2 $3
    #           Zabbix item  =>  unifi.stat.ap[default, UAP_01, rx_bytes]
    #           where 'default' is UniFi sitename, 'UAP_01' is Access Point Alias, 'rx_bytes' is counter name from UniFi database (ace > stat_current > ...)
    #
    #        or 
    #           Zabbix item  =>  unifi.stat.ap[default, UAP_01, num_guests_clients]
    #           where 'default' is UniFi sitename, 'UAP_01' is Access Point Alias, 'num_guests_clients' is alias for function that count guest numbers
    #
    # Some intersting counters is:	
    #        rx_bytes - The number of bytes received by the UAP.
    #        tx_bytes - The number of bytes transmitted by the UAP.
    #        tx_dropped - The number of packets dropped during transmission.
    #        ...see UniFi database for more ;)
    #
    # Tanx to Ubiquiti, UniFi Community and phpMoAdmin
    #
    #
    # Mail all suggestion to sadman(a)sfi.komi.com
    #
    use MongoDB;
    use Switch;
    
    sub getSiteID{
       # sitename is first param of subroutine 
       return $db->get_collection('site')->find_one({'name' => "@_[0]"})->{_id};
    }
    
    sub getSiteDesc{
       # sitename is first param of subroutine 
       return $db->get_collection('site')->find_one({'name' => "@_[0]"})->{desc};
    }
    
    sub getAPID{
       # sitename is first param of subroutine 
       return $db->get_collection('device')->find_one({'name' => "@_[0]"})->{_id};
    }
    
    sub getAPMAC{
       # sitename is first param of subroutine 
       return $db->get_collection('device')->find_one({'name' => "@_[0]"})->{mac};
    }
    
    sub getAPCurrentState{
       # sitename is first param of subroutine 
       return $db->get_collection('stat_current')->find_one({'ap' => "@_[0]", 'o' => "ap"})->{@_[1]};
    }
    
    sub getAPCurrentClientsNum{
       # sitename is first param of subroutine 
       my $vaptable= $db->get_collection('cache_device')->find_one({'mac' => "@_[0]"})->{'vap_table'};
       # is guests data always at [0] and users data always at [1]?
       switch (@_[1]) {
          case "num_guests_clients" { return $vaptable->[0]{num_sta};}
          case "num_users_clients"  { return $vaptable->[1]{num_sta};}
          else          { return ($vaptable->[0]{num_sta}+$vaptable->[1]{num_sta});}
       }  
    }
    
    # Param0 = sitename
    # if Param1 = APCurrentState, then Param2 = AP name, Param3 = Counter name
    #
    $param0=$ARGV[0];
    $param1=$ARGV[1];
    $param2=$ARGV[2];
    $param3=$ARGV[3];
    
    $dbhost="mongodb://localhost:27117";
    $sitename=$param0;
    
    $db = MongoDB::Connection->new(host => $dbhost)->get_database('ace');
    $siteid=getSiteID($sitename);
    
    #print "[*] Working with $siteid\n";
    
    switch ($param1) {
       case "APCurrentState" {
          $apmac=getAPMAC($param2);
          switch ($param3) {
              case "num_guests_clients" { $res=getAPCurrentClientsNum($apmac, $param3); }
              case "num_users_clients"  { $res=getAPCurrentClientsNum($apmac, $param3); }
              case "num_all_clients"    { $res=getAPCurrentClientsNum($apmac, $param3); }
              # on default take value of counter (for example 'rx_bytes') from collection stat_current
              else                      { $res=getAPCurrentState($apmac, $param3); }
          }
       }
    }
    print "$res\n";
    Last edited by sadman; 20-01-2016, 13:39.
  • Egor4ik
    Member
    • May 2012
    • 68

    #2
    Мониторингом Unifi ещё не занимался, хотя парочка мне может быть доступна для теста. Интересует именно работа через zabbix-agent + UserParameter.

    С Монго не работал, поэтому такой вопрос: а что вообще можно найти в базе?

    Из структуры Unifi уже чувстую, что придётся писать скрипт discovery для автообнаружения всех девайсов подключённых к контроллеру. Можно ли найти это в базе?

    Comment

    • sadman
      Senior Member
      • Dec 2010
      • 1611

      #3
      В базе можно найти больше того, что представляется возможным переварить скриптом. И именно поэтому я и собираю мнения по поводу того, что хотелось бы видеть на выходе.
      Покопаться в базе можно с помощью phpMoAdmin, например.
      Правда, в основном, приходится применять телепатические возможности для понимания сути того или иного параметра из базы.

      Если обзорно, то (по моим соображениям) коллекции данных содержат:

      device - предустановленные параметры точек, то есть то, что "засасывается" ими с контроллера при включении. Например: ip, mac, name (alias), channel, tx_power, version (software), wlangroup_id, флаг adopted, etc.

      alarm/event - события, регистрируемые контроллером. Закладка "Recent Events" веб-интерфейса.

      cache_sta - текущие коннекты: mac, rssi, ccq, noise, signal, hostname, tx_power, rx/tx_bytes, etc.

      cache_scan - результаты background scanning.

      cache_device - текущее состояние точки: adopted, isolated, locating, channel, tx_power, tx_rates (полагаю, что скорости по активным клиентам), vap_table (таблица с параметрами точки, разнесенным по виртуальным AP), некоторые параметры, через которые можно вычислить величины с закладки Access Point -> Perfomance

      stat_current, stat_daily, stat_minute... - данные для формирования графиков, отображаемых на закладке Statistic.

      session - данные о сессиях в целом, связанные через users с cache_sta: roam_count, rx/tx_bytes, etc.

      Правда, я не являюсь программистом на perl, поэтому приму любую помощь, связанную со сложными обработками mongodb-объектов (hashes, arrays) и общим причесыванием кода.

      Comment

      • AbyssMoon
        Member
        • Nov 2012
        • 51

        #4
        Так же в данное время занимаюсь настройкой мониторинга UniFi инфраструктуры...
        Огромное спасибо за скрипт!
        Подскажите, вы не могли бы так же поделиться и шаблоном?

        Comment

        • AbyssMoon
          Member
          • Nov 2012
          • 51

          #5
          Спасибо товарищу sadman
          Поделился со мной своими наработками, я по скрипту сделал шаблон для удобства.
          И так, что бы использовать:

          1. apt-get install libmongodb-perl libswitch-perl
          2. Кладем в zabbix_agentd.d/ файлик unifi.conf
          3. Кладем в /etc/zabbix/externalscripts файлик unifi_miner.pl
          4. Импортим шаблон в zabbix, я выложил два шаблона, один на одно устройства, другой на три. У кого unifi девайсов больше можно ручками создать по примеру клонов.
          5. В настройках хоста нужно добавить макросы {$SITE}, {$AP1}, {$AP2} и т.д.
          6. Лучше в конфиге заббикс агента увеличить таймаут хотя бы до 10 секунд.

          Click image for larger version

Name:	unifi.jpg
Views:	1
Size:	50.9 KB
ID:	312855

          Comment

          • AbyssMoon
            Member
            • Nov 2012
            • 51

            #6
            Проверено на 3.2.8

            Comment

            • sadman
              Senior Member
              • Dec 2010
              • 1611

              #7
              Ищу добровольцев с контроллерами версий 2.x, 3.x для тестирования новой версии скрипта.

              Теперь он умеет делать LLD, считать кол-во произвольных метрик (например кол-во adopted или isolated тарелок) и суммировать значения произвольных метрик (например посчитать всех клиентов на всех тарелках или весь tx_bytes).

              Пишите в PM.

              Comment

              • sadman
                Senior Member
                • Dec 2010
                • 1611

                #8
                Use actual release of UniFi Miner, please. So, if u need to monitor a lot UniFi metrics, try UniFi Proxy too

                Пожалуйста используйте последнюю версию UniFi Miner. Так же, если вам необходимо наблюдать за большим количеством метрик UniFi, попробуйте UniFi Proxy.

                Итак, накидана продвинутая версия скрипта добычи данных у контроллера UBNT UniFi. Выкладываю для массового тестирования.
                Так, как в реализации v4 контроллера разработчики отказались от идеи хранить текущие данные в mongodb и вообще повеселились, ничего не остается, как медленно и печально парсить JSON, получаемый по HTTPS от контроллера. Но, невысокая скорость скомпенсирована разными фичами.

                Скрипт эксплуатируется на контроллере v4.x, немного проверялся на v3.x, и вовсе не проверялся с v2.x. Так что при некорректной работе с последними шлите фидбеки.

                Что умеет скрипт:
                - генерировать LLD-совместимый JSON для групп объектов: точек доступа (UAP) и существующих на контроллере сетей (WLAN);
                - отдавать запрошенную метрику, основываясь на JSON-ключе;
                - -"-"- из подтаблиц основываясь на составном ключе;
                - подсчитывать количество / суммировать значения метрик, находящихся в списке объектов (UAP/WLAN/..), основываясь на JSON-ключе;
                - -"-"- из подтаблиц;
                - вываливать кучи информации, осмысленной и не очень. Можно использовать их для отладки.

                Что нужно скрипту: libwww-perl, libio-socket-ssl-perl, возможно libjson-perl (у меня не установлено из репозитория, но все работает)

                Запускаем так:
                unifi_miner.pl [-o object] [-i id] [-k key] [-l location] [-s site] [-u username] [-p password] [-v controller_ver] [-a action] [-d debug_level] [-n null_replacer]
                где:
                -o [ wlan ] исследуемый объект контроллера: `uap` или `wlan`
                -i внутренний ID объекта. Узнать его можно через LLD-ответ;
                -k ключ метрики, значение которой запрашивается;
                -l [ https://127.0.0.1:84443 ] местонахождение интерфейса контроллера;
                -s [ default ] имя сайта, заведенного в контроллере UniFi;
                -u [ stat ] имя пользователя для доступа к API. Должен существовать на контроллере UniFi;
                -p [ stat ] пароль пользователя для доступа к API;
                -v [ v4 ] версия контроллера: `v2`, `v3`, `v4`
                -a [ count ] действие, производимое над метриками в том случае, если обрабатывается список объектов (например - все UAP): `count`, `sum`;
                -d [ 0 ] - уровень отладки: 0..3
                -n - заменитель значения JSON:null

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

                Так же существует небольшая проблема с null-значениями. Так, некоторые метрики (например ng_ast_txto) иногда содержат значение 0, а иногда null. В результате, при получении значения такой метрики Zabbix-сервером, соответствующий элемент данных переходит в состояние unsupported. Если вам не нравится такое поведение, то можете использовать параметр -n для замены null на заданное в параметре значение, например `0`. Однако, я рекомендую пользоваться данным способом с осторожностью, чтобы не замаскировать настоящие значения проблемных метрик контроллера.

                Несколько примеров работы скрипта:

                # Получение LLD-совместимого JSON для группы объектов по умолчанию
                ./unifi_miner.pl

                # Получение LLD-совместимого JSON для группы объектов `точка доступа`
                ./unifi_miner.pl -o uap

                # То же самое, но при работе с контроллером v3, отвечающим по https://127.0.0.2:8443
                ./unifi_miner.pl -o uap -v v3 -l https://127.0.0.2:8443

                # Количество UAP, зарегистрированных на контроллере
                ./unifi_miner.pl -o uap -k items_num

                # Количество UAP, находящихся в состоянии `adopted`
                # * Небольшое примечание: некоторые метрики, такие как adopted/isolated/is_guest имеют
                # * булеву природу и их количество подсчитывается простым суммированием значений.
                ./unifi_miner.pl -o uap -k adopted -a sum

                # Количество клиентов, обслуживаемых на данный момент всеми UAP
                ./unifi_miner.pl -o uap -k num_sta -a sum

                # Количество клиентов, обслуживаемых на данный момент конкретной UAP
                ./unifi_miner.pl -o uap -i 5523fe519932508ffaf3b404 -k guest-num_sta

                # Значение параметра tx_dropped в таблице stat конкретной UAP
                ./unifi_miner.pl -o uap -i 5523fe519932508ffaf3b404 -k stat.tx_dropped

                # Версия прошивки (ПО) конкретной UAP
                ./unifi_miner.pl -o uap -i 5523fe519932508ffaf3b404 -k version

                # Количество гостевых сетей, поддерживаемых конкретной UAP
                ./unifi_miner.pl -o uap -i 5523fe519932508ffaf3b404 -k vap_table.is_guest -a sum

                На вопрос `откуда взять имена ключей и ID точек` есть простой ответ: ./unifi_miner.pl -o uap -d 3 > report.txt

                C Zabbix скрипт может быть интегрирован через UserParameter.

                Code:
                UserParameter=unifi.discovery[*],/usr/local/bin/zabbix/unifi_miner.pl -o $1 -u $2 -p $3
                UserParameter=unifi.uap.state[*],/usr/local/bin/zabbix/unifi_miner.pl -o uap -i $1 -k $2
                UserParameter=unifi.site.state[*],/usr/local/bin/zabbix/unifi_miner.pl -o $1 -k $2 -a $3
                Примеры ключей Zabbix:

                unifi.discovery[uap, {$USERNAME}, {$PASSWORD}] - для правила LLD, получающего в ответ перечень UAP's.
                unifi.uap.state[{#ID}, num_sta] - для прототипа элемента данных LLD, получающего текущее количество клиентов на заданной UAP
                unifi.site.state[uap, isolated, count] - количество UAP, находящихся в состоянии `isolated`

                Скрипт предлагаю тестировать с шаблонами, совместимыми с Zabbix v 2.4 и v 2.0, в которых вы так же сможете подсмотреть способы использования данного скрипта.
                Для их корректной работы не забудьте завести макросы {$SITENAME}, {$USERNAME}, {$PASSWORD}
                Attached Files
                Last edited by sadman; 18-07-2015, 22:32. Reason: URL actualizing

                Comment

                • sadman
                  Senior Member
                  • Dec 2010
                  • 1611

                  #9
                  Исправления, новые фичи, новые баги...

                  В ходе доводки шаблона и исследования кишков контроллера выявлен стратегический просчет - отсутствие отбора с учетом типа UniFi устройства.
                  Предполагаю, что UBNT цепляет (или будет цеплять) к контроллеру коммутаторы/гейтвеи и voip-телефоны. Так как у меня в распоряжении есть только точки доступа, то проверить данную гипотезу не могу. Если у кого-то есть в наличии устройства вышеупомянутые устройства - проведите тест или свяжитесь со мной.

                  В связи с этим в код внесены поправки и исправления:
                  • объект `ap` переименован в `uap` (!);
                  • добавлены объекты `switch`, `voip`;
                  • внутренние выборки производятся с учетом типа объекта.

                  Для ускорения работы скрипта проведена следующая модернизация:
                  1. Введена возможность кэширования ответов контроллера. Период устаревания кэшированных данных задается в секундах через аргумент командной строки -c <сек>.
                    При обнаруженнии истечения периода устаревания, данные запрашиваются с контроллера и записываются в кэш. Этим достигается как увеличение скорости получения данных другими экземплярами скрипта, так и некоторая синхронизация получаемых данных, например - обеспечивающая совпадение суммы количеств клиентов на всех UAP с общим числом клиентов unifi-сайта. Очень полезно для комплексных экранов и отчетов.
                    При использовании -c 0 все процедуры кэширования отключаются, данные запрашиваются напрямую с контроллера.
                    Путь к каталогу для кэш-файлов задается внутри скрипта, параметр cacheroot. Рекомендую использовать RAM-диск, например `/run/shm`.
                    Время устаревания не стоит устанавливать менее 15 сек, так как меньший период обновления данных в веб-интерфейсе разработчики системы UniFi не применяют.
                    Значение по умолчанию составляет 30 сек, его так же можно изменить внутри скрипта.

                    Примеры:
                    # Получение LLD-совместимого JSON для группы объектов `точка доступа` напрямую с контроллера
                    ./unifi_miner.pl -o uap -c 0
                    # Количество UAP, зарегистрированных на контроллере с проверкой актуальности кэша (60 сек)
                    ./unifi_miner.pl -o uap -k items_num -c 60
                    .
                  2. Добавлена возможность быстрого получения данных по объекту, имеющему MAC-адрес. Эта возможность поддерживается контроллером v4. Во всяком случае проверка на v3 не принесла необходимого результата.
                    При данном способе запроса данных анализируется ответ, полученный по '.../stat/device/<MAC>', а не производится поиск по всем объектам, выданым по '.../stat/device'. Данный способ получения данных активируется при использовании аргумента командной строки -m <MAC>. При этом указания ID объекта (-i <ID>) не требуется.

                    Примеры:
                    # Самые актуальные данные о количестве клиентов, подключенных на данный момент к UAP с MAC 00:27:22:d8:33:23
                    ./unifi_miner.pl -o uap -m 00:27:22:d8:33:23 -k guest-num_sta -с 0

                  Новый .conf для интеграции в Zabbix-agent в архиве со скриптом.

                  Так же прилагаю два дополненных всякими штуками шаблона. Добавьте макрос {$FW_UAP_LATEST_VER} для триггера проверяющего актуальность прошивки UAP.
                  Attached Files
                  Last edited by sadman; 15-04-2015, 13:19.

                  Comment

                  • miragecze
                    Junior Member
                    • May 2015
                    • 6

                    #10
                    Ubiquiti UniFi + zabbix - English

                    Hi Everyone,

                    Could you please make a short manual in English, how to setup Unifi and Zabbix?
                    Few steps...

                    Thank you very very much.

                    Comment

                    • tolleiv
                      Junior Member
                      • May 2015
                      • 1

                      #11
                      Hi Sadman,

                      thanks for sharing. If Google Translate worked correctly, you were asking for feedback from v2 users. For me your scripts worked fine with the exception that the AP status and the TX * related items don't work yet (even though the script seems to return some values).

                      Anyways - I had to make few adjustments to get your script to work. To avoid that you've to compare by yourself, I've created a Github-Repo which has may changes in a separate branch and which brings in easy ways for comparison: https://github.com/tolleiv/zabbix-un...djustments_2.0

                      Hope this helps.

                      Cheers,
                      Tolleiv

                      Comment

                      • sadman
                        Senior Member
                        • Dec 2010
                        • 1611

                        #12
                        Originally posted by tolleiv
                        If Google Translate worked correctly, you were asking for feedback from v2 users.
                        Yes, i do that. I was used v2 for two or three month a lot years ago, but not using api.

                        Tanx for testing.

                        Originally posted by tolleiv
                        For me your scripts worked fine with the exception that the AP status and the TX * related items don't work yet (even though the script seems to return some values).
                        I think that v2 can have not keys, which used in template written for v4.
                        U can send me output of /api/device from v2 controller and keys of broken items (msg to PM, please)?
                        Or u can seeking problem keys in JSON-output.

                        Anyways - I had to make few adjustments to get your script to work.
                        Yes, some addons is helpful. I include that in next version of miner. I wait for answer from owner of voip and other UBNT network stuff to append some subroutines to script.

                        But I want to clarify some points.
                        1. In last version of script u must use object name 'uap' (not 'ap') in unifi.conf. It is important, because i will add other objects at soon.
                        2. U can place username and password into script or just into unifi.conf (unifi_miner.pl -v v2 -o $1 -k $2 -a $3 -u <admin> -p <adminpass>) for reducing Zabbix items keys. And then u do not need to make radical changes to the template.
                        3. I recommend create special user for api reading on UniFi controller.


                        I was used Google Translate too

                        Comment

                        • sadman
                          Senior Member
                          • Dec 2010
                          • 1611

                          #13
                          Originally posted by miragecze
                          Hi Everyone,

                          Could you please make a short manual in English, how to setup Unifi and Zabbix?
                          Few steps...

                          Thank you very very much.
                          At first u must setting up Zabbix and make sure that it works: https://www.zabbix.com/documentation...l/installation
                          Second step - install UniFi controller to _linux_box_ or just install linux box for miner script executing. I use Debian 7.

                          ...then be back to topic for further instructions.

                          Comment

                          • miragecze
                            Junior Member
                            • May 2015
                            • 6

                            #14
                            Originally posted by sadman
                            At first u must setting up Zabbix and make sure that it works: https://www.zabbix.com/documentation...l/installation
                            Second step - install UniFi controller to _linux_box_ or just install linux box for miner script executing. I use Debian 7.

                            ...then be back to topic for further instructions.
                            Hi Sadman,

                            my fault, my question was incomplete.
                            I am not new to Zabbix and Unifi, but I do not understand what excatly I have to do.

                            I am using Debian 7 on my monitoring proxy.
                            I have unifi_miner.pl in /usr/lib/zabbix/externalscripts
                            All dependecies installed
                            Command ./unifi_miner.pl -o ap -v v3 -l https://IP_address_of_UnFi_Ctrl -u user -password is working
                            Template is imported to Zabbix.

                            OK, what now?

                            Thank you very much for your help.

                            Comment

                            • sadman
                              Senior Member
                              • Dec 2010
                              • 1611

                              #15
                              Ough, OK

                              I hope that u get archives with template and latest release of miner from

                              It's so important, because i change 'ap' to 'uap' in a script routines and templates.

                              That .zip contain two file - .pl and .conf
                              As i see, u already found unifi_miner.pl and try to run it. Now u must point zabbix agent to use UserParameter from unifi.conf. Three way of that is exist:
                              1. copy content of unifi.conf to zabbix_agentd.conf
                              2. using Include=..../.../unifi.conf options with zabbix_agentd.conf
                              3. using Include=/usr/local/etc/zabbix_agentd.conf.d/ and place unifi.conf to .../zabbix_agentd.conf.d/ dir.

                              Choose one, change zabbix_agentd.conf and restart agent if need. Be sure that zabbix user have right permission for executing unifi_miner.pl.

                              Now Zabbix agent know about unifi.* keys. Agent can perform unifi_miner.pl with appropriate parameters, take result and send answer back to server when that ask about values of this keys.

                              P.S. I see, that u place unifi_miner.pl in /usr/lib/zabbix/externalscripts. U must change path to script in unifi.conf->UserParameter
                              Last edited by sadman; 18-05-2015, 15:14.

                              Comment

                              Working...