Просмотр кода страницы Usm peleng EN

[[Usm_peleng_EN|en]] | [[Usm_peleng|ru]]

{{ActivEN}}

'''USM_PELENG''' ''- is a module for interrogating managed equipment in terms of FDB table (MAC address) capture.''

'''This module is a replacement for the obsolete [[us_peleng_EN|us_peleng]] module'''


'''Module Language:''' Perl

'''Current version:''' see page: [[Modules_EN|Modules]]

'''Module Status:''' [https://www.userside.eu/en/pricing Paid]

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

For general information for all modules, see the page: [[Modules_EN|Modules]]

== Main Functions ==

* capture MAC addresses from equipment by VLAN and port
* capture ARP table from equipment ''(IP+MAC addresses)''
* accumulate MAC address history on equipment ports with the date of the first and last address appearance. This makes it possible to search for unauthorised connections, flooding, rings, virus activity
* Updating the date of activity in the network to users and equipment whose MAC address has been found
* accumulation of a base of [[Unknown MAC addresses|unknown MAC addresses]]
* on devices that allow to receive not only MAC-addresses, but also IP-MAC-address pair is performed [[Auto-assigning users to ports| MAC-address learning]] for these IP-addresses ''(if the function is enabled)''
* on polled devices with which communication is established - the date of device activity in the network is updated

The method of data capture is '''telnet''' or '''SNMP'''. The method can be specified both globally in "[[Settings - Main|Settings]]" and individually for each [[Switch  card|specific equipment]]. Also note that there is an option for SNMP to select v.1 or v.2 protocol for operation.

If the "Do not capture MAC addresses from UPLINK ports" parameter is enabled in the system configuration, MAC addresses for such ports will not be processed.

The module connects to one device at a time and tries to obtain information about it

== Install and configure the module ==

# Allocate a separate directory. A completely arbitrary one. It is better not to place it in a catalogue accessible via web. Interaction with ERP "UserSide" is performed by tools of API via http/s-protocol. This way the module is fully autonomous and can work on any separate computer in any subnet. Also create a separate directory for the module logs. Do not forget to specify write permissions for it.
# Transfer there the files from the module archive. Rename the sample configuration file "usm_peleng.conf-example" to "usm_peleng.conf". In it, configure the parameters. The list of possible parameters is given below.
# Check for additional perl packages that are required to run the module. Their list is given above. If you do not have them installed, the module will generate an error at startup and the perl-package will need to be installed ''(using CPAN or PPM)''.
# In the "[[Settings - Modules]]" section, enable the usm_peleng module
# In the [[Switch card|switches]] cards, you should enable the work with the usm_peleng module
# Start the module manually

 perl usm_peleng.pl

It should start and run without errors.

7. Write the module startup into the system cron, according to the recommendations below

'''Clarifications:'''
# When a new switch is added to the system, it automatically has the option to poll the device with the usm_peleng module enabled
# At startup, the module processes only one device

The usm_peleng module is not suitable for determining the availability of users based on their MAC addresses, as the operation of reading MAC addresses and then processing the read data is too redundant for this purpose. Use the [[usm_checker]] module to determine the availability of nodes in the network.

For most devices (switches in particular) it is sufficient to read and process MAC address data on the equipment not more often than once every 6..12 hours. We recommend to stick to these values to calculate the number of modules to be launched simultaneously in the cron system scheduler.

Run modules as often as possible with as few simultaneous runs as possible. The standard recommendation is to run a module once per minute. The number of copies that should be run simultaneously is calculated by counting the number of devices with the "Poll device with usm_peleng module" parameter active. This value can be calculated using the formula:

Number of copies = number of devices * startup period in minutes / polling cycle period for the device in minutes

For example, for 1500 devices, which should be polled once every 9 hours, to run every minute you will need 1500 * 1 / (9 * 60) = 2.8, i.e. 3 copies of usm_peleng.

Here is an example from cron of launching three copies of the module:
 * * * * * 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

In the card of the device, on which the usm_peleng module is enabled, you can view the history of polling of this device by the module and the general table of device polling using the corresponding link.

== Parameters ==

The module is configured in the '''usm_peleng.conf''' file

 $usUrl - URL to ERP "UserSide"
 $usApiKey - [[UserSide_API_Key_EN|API]]-key to ERP "UserSide"
 $logsPath - Path to the catalogue for module logs
 
 $isSilence - Flag - hide notifications to the console when the module is running
 $delay - Random time delay from 0 to n-seconds after module start. Allows you to reduce the load on the server when using a large number of modules at the same time.
 $citiesList - List of identifiers of settlements ''(comma separated)''. IP-addresses of which to poll. 0 - objects without address
 $isArpPolling - Flag whether to poll the ARP table from the device.

The usm_peleng module can be run with the ''(specify the specific device to poll)'' parameters

Example:

 perl usm_peleng s 998

will poll the switch with ID 998

== If the information is not captured/module does not work ==

1. It is necessary to differentiate and understand whether the module is not working or the information is not captured. In the equipment card - you should check the usm_peleng module run log by device.

2. You should make sure that community access, passwords are correct and the device itself is physically connected and working.

3. In the ERP "UserSide" itself, open the switch card and follow the "FDB table" link

4. To test - you should run the module specifically for a particular switch. For example:

 perl usm_peleng.pl s 998

will start the module for switch ID: 998

Check if there are no errors in the information output.

In the log files, analyse the received information.

== Run in Docker environment ==

If you use USERSIDE in a Docker environment, you will probably be interested in running external usm modules in separate Docker containers.

We provide a docker environment to run the usm_peleng module (the environment does not contain the module files - you need to download them from your personal account yourself).

You can download the docker environment at: https://github.com/userside/usm_peleng-docker-env/releases