Usm peleng: различия между версиями

Материал из WiKi - UserSide
Нет описания правки
 
(не показано 26 промежуточных версий 3 участников)
Строка 1: Строка 1:
[[Usm_peleng_EN|en]] | [[Usm_peleng|ru]]
{{activ}}
{{activ}}


'''USM_PELENG''' ''- это модуль для опроса управляемого оборудования в части съема FDB-таблиц (MAC-адреса).''  
'''USM_PELENG''' ''- это модуль для опроса управляемого оборудования в части съема FDB-таблиц (MAC-адреса).''  


'''Данный модуль является более заменой устаревшему модулю [[us_peleng]]'''
'''Данный модуль является заменой устаревшему модулю [[us_peleng]]'''




Строка 19: Строка 21:
  URI::Escape
  URI::Escape
  LWP::UserAgent
  LWP::UserAgent
LWP::Protocol::https
  JSON
  JSON
  Data::Dumper
  Data::Dumper
  Net::Telnet()
  Net::Telnet
  Net::SNMP
  Net::SNMP


Строка 28: Строка 31:
== Основные функции ==
== Основные функции ==


* съем MAC-адресов с оборудования в разрезе портов
* съем MAC-адресов с оборудования в разрезе VLAN и портов
* съем ARP-таблицы с оборудования (IP+MAC-адреса)
* съем ARP-таблицы с оборудования ''(IP+MAC-адреса)''
* накопление истории MAC-адресов на портах оборудования с указанием даты первого и последнего появления адреса. Это даёт возможность искать несанкционированные подключения, флуд, кольца, вирусную активность
* накопление истории MAC-адресов на портах оборудования с указанием даты первого и последнего появления адреса. Это даёт возможность искать несанкционированные подключения, флуд, кольца, вирусную активность
* обновление даты активности в сети абонентам и оборудованию, чей MAC-адрес был найден
* обновление даты активности в сети абонентам и оборудованию, чей MAC-адрес был найден
* накопление базы [[Неизвестные MAC-адреса|неизвестных MAC-адресов]]
* накопление базы [[Неизвестные MAC-адреса|неизвестных MAC-адресов]]
* на устройствах, которые позволяют получать не только MAC-адреса, но и пару IP-MAC-адрес выполняется [[Автопривязка абонентов к портам|обучение MAC-адресов]] для этих IP-адресов (если функция включена)
* на устройствах, которые позволяют получать не только MAC-адреса, но и пару IP-MAC-адрес выполняется [[Автопривязка абонентов к портам|обучение MAC-адресов]] для этих IP-адресов ''(если функция включена)''
* на опрошенных устройствах, с которым установлена связь - обновляется дата активности устройства в сети
* на опрошенных устройствах, с которым установлена связь - обновляется дата активности устройства в сети


Строка 40: Строка 43:
Если в настройке системы включен параметр "Не фиксировать MAC-адреса с UPLINK-портов", то MAC-адреса для таких портов обработаны не будут.
Если в настройке системы включен параметр "Не фиксировать MAC-адреса с UPLINK-портов", то MAC-адреса для таких портов обработаны не будут.


За один запуск модуль подключается к одному устройству и пытается получить информацию. Весь лог общения с устройством хранится в файле вида ''outputlog_ТИПУСТРОЙСТВА_КОДКОММУТАТОРА.txt''
За один запуск модуль подключается к одному устройству и пытается получить информацию
 
== Установка и настройка модуля ==
 
# Выделите отдельный каталог. Абсолютно произвольный. Лучше его не размещать в каталоге, доступном через web. Взаимодействие с ERP "UserSide" осуществляется средствами API по http/s-протоколу. Таким образом модуль полностью автономен и может работать на любом отдельном компьютере в любой подсети. Также создайте отдельный каталог для логов модуля. Не забудьте указать для него права на запись.
# Перенесите туда файлы из архива модуля. Пример файла конфигурации "usm_peleng.conf-example" переименуйте в "usm_peleng.conf". В нём выполните настройку параметров. Перечень возможных параметров указан ниже.
# Проверьте наличие дополнительных perl-пакетов, которые требуются для запуска модуля. Их список приведён выше. Если у вас они не установлены - модуль выдаст ошибку при запуске и perl-пакет необходимо будет установить ''(с помощью CPAN или PPM)''.
# В разделе "[[Настройка - Модули]]" включите работу с модулем usm_peleng
# В карточках [[Карточка коммутатора|коммутаторов]] следует включить работу с модулем usm_peleng
# Запустите модуль руками
 
perl usm_peleng.pl
 
Он должен запуститься и отработать без ошибок.


Например:
7. Впишите запуск модуля в системный cron, согласно рекомендациям ниже


''outputlog_1_120.txt'' - коммутатор №120
'''Уточнения:'''
# При добавлении нового коммутатора в систему, у него автоматически включается параметр - опрашивать устройство модулем usm_peleng
# При запуске модуль обрабатывает только одно устройство


''outputlog_2_122.txt'' - wi-fi-устройство №122
Модуль usm_peleng не предназначен для определения доступности абонентов по наличию их MAC адресов, так как операция чтения MAC адресов с последующей обработкой считанных данных слишком избыточна для этого. Используйте модуль [[usm_checker]] для определения доступности узлов в сети.


Код устройства можно посмотреть в адресе карточки оборудования. Это параметр CODE.
Для большинства устройств (в частности коммутаторов) достаточно считывать и обрабатывать данные по MAC-адресам на оборудовании не чаще раза в 6..12 часов. Мы рекомендуем придерживаться этих значений для рассчета количества одновременно запускаемых модулей в системном планировщике cron.


== Установка и настройка модуля ==
Запускайте модули как можно чаще с как можно меньшим количеством одновременных запусков. Стандартной рекомендацией будет запуск модуля раз в минуту. Количество копий, которое должно быть запущено одновременно, вычисляется из рассчета количества устройств с активным параметром "Опрашивать устройство модулем usm_peleng". Это значение можно вычислить по формуле:


# В разделе "[[Настройка - Модули]]" включите работу с us_peleng
Количество копий = количество устройств * период запуска в минутах / период цикла опроса для устройства в минутах
# В карточках [[Карточка коммутатора|управляемых устройств]] следует включить работу с пеленгатором.
# В системный cron следует записать вызов необходимого количества пеленгаторов.


При указании количества пеленгатора следует исходить из следующего: в САП "UserSide" по-умолчанию время активности в сети составляет 15 минут ''(т.е. это время, через которое абонент/дом/узел будет считаться неактивным)''. Следовательно, в течении 15 минут пеленгаторы должны успевать обрабатывать все устройства. Пеленгатор при запуске обрабатывает одно устройство. Следовательно за 15 минут пеленгатор успеет обработать 15 устройств. Если устройств больше - то необходимо использовать второй пеленгатор, третий и т.д. Пеленгаторов можно назначать любое количество. Для того чтобы одновременный запуск большого количества копий пеленгатора не приводил к увеличенной нагрузке на базу данных и процессор ''(ведь при запуске будут выполняться одни и те же однотипные задачи)'' предназначен параметр us_delay (указан выше). Указав в нём цифру произвольное задержки например в "20" - можно добиться что пеленгаторы будут запускаться с 1 по 20 секунду в произвольном порядке и нагрузка распределится.
Например, для 1500 устройств, которые должны опрашиватся раз в 9 часов, для ежеминутного запуска понадобится 1500 * 1 / (9 * 60) = 2.8, т.е. 3 копии usm_peleng.


Пример из cron запуска пяти пеленгаторов:
Пример из cron запуска трех копий модуля:
  * * * * * perl /home/userside_peleng/us_peleng.pl &> /dev/null
  * * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null
  * * * * * perl /home/userside_peleng/us_peleng.pl &> /dev/null
  * * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null
* * * * * perl /home/userside_peleng/us_peleng.pl &> /dev/null
  * * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null
  * * * * * perl /home/userside_peleng/us_peleng.pl &> /dev/null
* * * * * perl /home/userside_peleng/us_peleng.pl &> /dev/null


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


== Параметры ==
== Параметры ==


Настройка модуля осуществляется в файле '''us_config.tmp'''
Настройка модуля осуществляется в файле '''usm_peleng.conf'''


  $zuserver - адрес сервера с UserSide
  $usUrl - URL к ERP "UserSide"
  $zubase - имя базы данных UserSide
  $usApiKey - [[UserSide_API_Key|API]]-ключ к ERP "UserSide"
$zuuser - имя пользователя для доступа к базе UserSide
  $logsPath - Путь к каталогу для логов модуля
  $zupass - пароль для доступа к базе UserSide
   
$zucp - кодировка базы UserSide
  $isSilence - Флаг - скрывать уведомления в консоль при работе модуля
$ps_logpath - путь к логам модуля
  $delay - Произвольная временная задержка от 0 до n-секунд после запуска модуля. Позволяет уменьшить нагрузку на сервер при одновременном использовании большого количества модулей
  $ps_timeout - время ожидание ответа от устройства (секунды)
  $citiesList - Перечень идентификаторов населенных пунктов ''(через запятую)'' IP-адреса которых опрашивать. 0 - объекты без адреса
  $ps_updlasttime - ставить ли у найденных абонентов ''(по MAC-адресу)'' свежее время [[Активность|активности]] в сети
$isArpPolling - Флаг - опрашивать ли ARP-таблицу с устройства
$ps_dont_upd_act_equip - запретить обновление активности у оборудования ''(по MAC-адресу)''
  $ps_delay - произвольная временная задержка от 0 до n-секунд после запуска пеленгатора. Позволяет уменьшить нагрузку на сервер с пеленгатором при одновременном использовании большого количества пеленгаторов.
$zsilence - не выводить уведомления о работе модуля в консоль
$z_arp_off - флаг - отключить опрос ARP-таблицы
  $zcity_list - перечень населенных пунктов ''(tbl_adr_city.CODE)'' IP-адреса которых опрашивать ''(через запятую)''. 0 - объекты без адреса


Модуль us_peleng можно запускать с параметрами (указать конкретное устройство, которое необходимо опросить)
Модуль usm_peleng можно запускать с параметрами ''(указать конкретное устройство, которое необходимо опросить)''


Пример:
Пример:


  perl us_peleng s 998
  perl usm_peleng s 998


опросит коммутатор с CODE: 998
опросит коммутатор с ID 998


== Рекомендации по настройке модуля ==
== Если информация не снимается/модуль не работает ==


== Если информация не снимается/пеленгатор не работает ==
1. Необходимо разграничить и понять - не работает модуль или не снимается информация. В карточке оборудования - следует проверить лог запусков модуля usm_peleng по устройству.


1. Необходимо разграничить и понять - не работает модуль или не снимается информация. В карточке оборудования - следует проверить лог запусков пеленгатора по устройству.
2. Следует убедиться, что верны community доступа, пароли и само устройство физически подключено и работает.


2. Следует запустить модуль вручную в консоли и проверить нет ли ошибок в выводе информации.
3. В самой ERP "UserSide" откройте карточку коммутатора и перейдите по ссылке "FDB-таблица"


3. Для теста - следует запустить пеленгатор конкретно для определенного коммутатора. Например:
4. Для теста - следует запустить модуль конкретно для определенного коммутатора. Например:


perl us_peleng.pl s 998
perl usm_peleng.pl s 998


запустит пеленгатор для коммутатора CODE: 998
запустит модуль для коммутатора ID: 998
 
Проверяем нет ли ошибок в выводе информации.


В файлах логов анализируем полученную информацию.
В файлах логов анализируем полученную информацию.


4. Следует проверить файл outputlog_ТИПОБОРУДОВАНИЯ_КОДУСТРОЙСТВА.txt что выводит модуль. Возможно указан неверный пароль к устройству.
== Запуск в Docker-окружении ==
 
Если Вы используете USERSIDE в Docker-окружении, то вам наверняка будет интересно запускать в отдельных Docker-контейнерах и внешние модули usm.
 
Мы предоставляем docker-окружение для запуска модуля usm_peleng (окружение не содержит файлов модуля - их необходимо загрузить из личного кабинета самостоятельно).


5. Также следует убедиться, что верны community доступа, пароли и само устройство физически подключено и работает.
Загрузить docker-окружение можно по ссылке: https://github.com/userside/usm_peleng-docker-env/releases

Текущая версия от 13:57, 28 ноября 2023

en | ru

Эта функция является одной из возможностью
обновления даты активности у объекта

USM_PELENG - это модуль для опроса управляемого оборудования в части съема FDB-таблиц (MAC-адреса).

Данный модуль является заменой устаревшему модулю us_peleng


Язык модуля: Perl

Текущая версия: см. на странице: Модули

Статус модуля: Платный

Необходимые модули Perl:

Time::Local
Socket
FindBin
URI
URI::Escape
LWP::UserAgent
LWP::Protocol::https
JSON
Data::Dumper
Net::Telnet
Net::SNMP

Общую информацию для всех модулей см. на странице: Модули

Основные функции

  • съем MAC-адресов с оборудования в разрезе VLAN и портов
  • съем ARP-таблицы с оборудования (IP+MAC-адреса)
  • накопление истории MAC-адресов на портах оборудования с указанием даты первого и последнего появления адреса. Это даёт возможность искать несанкционированные подключения, флуд, кольца, вирусную активность
  • обновление даты активности в сети абонентам и оборудованию, чей MAC-адрес был найден
  • накопление базы неизвестных MAC-адресов
  • на устройствах, которые позволяют получать не только MAC-адреса, но и пару IP-MAC-адрес выполняется обучение MAC-адресов для этих IP-адресов (если функция включена)
  • на опрошенных устройствах, с которым установлена связь - обновляется дата активности устройства в сети

Метод съема данных - telnet или SNMP. Метод можно указать как глобально в "Настройке", так и индивидуально для каждого конкретного оборудования. Также следует обратить внимание, что есть возможность для SNMP выбрать протокол v.1 или v.2 для работы.

Если в настройке системы включен параметр "Не фиксировать MAC-адреса с UPLINK-портов", то MAC-адреса для таких портов обработаны не будут.

За один запуск модуль подключается к одному устройству и пытается получить информацию

Установка и настройка модуля

  1. Выделите отдельный каталог. Абсолютно произвольный. Лучше его не размещать в каталоге, доступном через web. Взаимодействие с ERP "UserSide" осуществляется средствами API по http/s-протоколу. Таким образом модуль полностью автономен и может работать на любом отдельном компьютере в любой подсети. Также создайте отдельный каталог для логов модуля. Не забудьте указать для него права на запись.
  2. Перенесите туда файлы из архива модуля. Пример файла конфигурации "usm_peleng.conf-example" переименуйте в "usm_peleng.conf". В нём выполните настройку параметров. Перечень возможных параметров указан ниже.
  3. Проверьте наличие дополнительных perl-пакетов, которые требуются для запуска модуля. Их список приведён выше. Если у вас они не установлены - модуль выдаст ошибку при запуске и perl-пакет необходимо будет установить (с помощью CPAN или PPM).
  4. В разделе "Настройка - Модули" включите работу с модулем usm_peleng
  5. В карточках коммутаторов следует включить работу с модулем usm_peleng
  6. Запустите модуль руками
perl usm_peleng.pl

Он должен запуститься и отработать без ошибок.

7. Впишите запуск модуля в системный cron, согласно рекомендациям ниже

Уточнения:

  1. При добавлении нового коммутатора в систему, у него автоматически включается параметр - опрашивать устройство модулем usm_peleng
  2. При запуске модуль обрабатывает только одно устройство

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

Для большинства устройств (в частности коммутаторов) достаточно считывать и обрабатывать данные по MAC-адресам на оборудовании не чаще раза в 6..12 часов. Мы рекомендуем придерживаться этих значений для рассчета количества одновременно запускаемых модулей в системном планировщике cron.

Запускайте модули как можно чаще с как можно меньшим количеством одновременных запусков. Стандартной рекомендацией будет запуск модуля раз в минуту. Количество копий, которое должно быть запущено одновременно, вычисляется из рассчета количества устройств с активным параметром "Опрашивать устройство модулем usm_peleng". Это значение можно вычислить по формуле:

Количество копий = количество устройств * период запуска в минутах / период цикла опроса для устройства в минутах

Например, для 1500 устройств, которые должны опрашиватся раз в 9 часов, для ежеминутного запуска понадобится 1500 * 1 / (9 * 60) = 2.8, т.е. 3 копии usm_peleng.

Пример из cron запуска трех копий модуля:

* * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null
* * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null
* * * * * perl /opt/userside/usm_peleng/usm_peleng.pl &> /dev/null

В карточке устройства, на котором включен модуль usm_peleng можно по соответствующей ссылке посмотреть историю опроса этого устройства модулем и общую таблицу опроса устройств.

Параметры

Настройка модуля осуществляется в файле usm_peleng.conf

$usUrl - URL к ERP "UserSide"
$usApiKey - API-ключ к ERP "UserSide"
$logsPath - Путь к каталогу для логов модуля

$isSilence - Флаг - скрывать уведомления в консоль при работе модуля
$delay - Произвольная временная задержка от 0 до n-секунд после запуска модуля. Позволяет уменьшить нагрузку на сервер при одновременном использовании большого количества модулей
$citiesList - Перечень идентификаторов населенных пунктов (через запятую) IP-адреса которых опрашивать. 0 - объекты без адреса
$isArpPolling - Флаг - опрашивать ли ARP-таблицу с устройства

Модуль usm_peleng можно запускать с параметрами (указать конкретное устройство, которое необходимо опросить)

Пример:

perl usm_peleng s 998

опросит коммутатор с ID 998

Если информация не снимается/модуль не работает

1. Необходимо разграничить и понять - не работает модуль или не снимается информация. В карточке оборудования - следует проверить лог запусков модуля usm_peleng по устройству.

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

3. В самой ERP "UserSide" откройте карточку коммутатора и перейдите по ссылке "FDB-таблица"

4. Для теста - следует запустить модуль конкретно для определенного коммутатора. Например:

perl usm_peleng.pl s 998

запустит модуль для коммутатора ID: 998

Проверяем нет ли ошибок в выводе информации.

В файлах логов анализируем полученную информацию.

Запуск в Docker-окружении

Если Вы используете USERSIDE в Docker-окружении, то вам наверняка будет интересно запускать в отдельных Docker-контейнерах и внешние модули usm.

Мы предоставляем docker-окружение для запуска модуля usm_peleng (окружение не содержит файлов модуля - их необходимо загрузить из личного кабинета самостоятельно).

Загрузить docker-окружение можно по ссылке: https://github.com/userside/usm_peleng-docker-env/releases