Usm peleng EN
 |
This function is one of the possibilities |
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 module
Module Language: Perl
Current version: see page: Modules
Module Status: 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
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
- on devices that allow to receive not only MAC-addresses, but also IP-MAC-address pair is performed 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" and individually for each 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 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 - 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