Initial Release, wireless sensor support for Openwrt (#11768)

* Initial Release, wireless sensor support for Openwrt

* Extend Openwrt support, add more sensors

* Add documentation for Openwrt Wireless Sensor support

* Moved location of Openwrt.md

* Update openwrt.json

Co-authored-by: Tony Murray <murraytony@gmail.com>
This commit is contained in:
arrmo 2020-07-09 16:13:58 -05:00 committed by GitHub
parent 0c334f130d
commit 8899ad6d5a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 518 additions and 13 deletions

157
LibreNMS/OS/Openwrt.php Normal file
View File

@ -0,0 +1,157 @@
<?php
/**
* Openwrt.php
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* @package LibreNMS
* @link http://librenms.org
* @copyright 2017 Tony Murray
* @author Tony Murray <murraytony@gmail.com>
*/
namespace LibreNMS\OS;
use LibreNMS\Device\WirelessSensor;
use LibreNMS\Interfaces\Discovery\Sensors\WirelessClientsDiscovery;
use LibreNMS\Interfaces\Discovery\Sensors\WirelessFrequencyDiscovery;
use LibreNMS\Interfaces\Discovery\Sensors\WirelessNoiseFloorDiscovery;
use LibreNMS\Interfaces\Discovery\Sensors\WirelessRateDiscovery;
use LibreNMS\Interfaces\Discovery\Sensors\WirelessSnrDiscovery;
use LibreNMS\OS;
class Openwrt extends OS implements
WirelessClientsDiscovery,
WirelessFrequencyDiscovery,
WirelessNoiseFloorDiscovery,
WirelessRateDiscovery,
WirelessSnrDiscovery
{
/**
* Retrieve (and explode to array) list of network interfaces, and desired display name in LibreNMS.
* This information is returned from the wireless device (router / AP) - as SNMP extend, with the name "interfaces".
*
* @return array Interfaces
*/
private function getInterfaces()
{
// Need to use PHP_EOL, found newline (\n) not near as reliable / consistent! And this is as PHP says it should be done.
$interfaces = explode(PHP_EOL, snmp_get($this->getDevice(), 'NET-SNMP-EXTEND-MIB::nsExtendOutputFull."interfaces"', '-Osqnv'));
$arrIfaces = array();
foreach ($interfaces as $interface) {
list($k, $v) = explode(',', $interface);
$arrIfaces[$k] = $v;
}
return $arrIfaces;
}
/**
* Generic (common / shared) routine, to create new Wireless Sensors, of the sensor Type passed as the call argument.
* type - string, matching to LibreNMS documentation => https://docs.librenms.org/Developing/os/Wireless-Sensors/
* query - string, query to be used at client (appends to type string, e.g. -tx, -rx)
* system - boolean, flag to indicate that a combined ("system level") sensor (and OID) is to be added
* stats - boolean, flag denoting that statistics are to be retrieved (min, max, avg)
* NOTE: system and stats are assumed to be mutually exclusive (at least for now!)
*
* @return array Sensors
*/
private function getSensorData($type, $query = '', $system = false, $stats = false)
{
// Initialize needed variables, and get interfaces (actual network name, and LibreNMS name)
$sensors = array();
$interfaces = $this->getInterfaces();
$count = 1;
// Build array for stats - if desired
$statstr = [''];
if ($stats) {
$statstr = ['-min', '-max', '-avg'];
}
// Loop over interfaces, adding sensors
foreach ($interfaces as $index => $interface) {
// Loop over stats, appending to sensors as needed (only a single, blank, addition if no stats)
foreach ($statstr as $stat) {
$oid = "NET-SNMP-EXTEND-MIB::nsExtendOutput1Line.\"$type$query-$index$stat\"";
$sensors[] = new WirelessSensor($type, $this->getDeviceId(), snmp_translate($oid), "openwrt$query", $count, "$interface$query$stat");
$count += 1;
}
}
// If system level (i.e. overall) sensor desired, add that one as well
if ($system and (count($interfaces) > 1)) {
$oid = "NET-SNMP-EXTEND-MIB::nsExtendOutput1Line.\"$type$query-wlan\"";
$sensors[] = new WirelessSensor($type, $this->getDeviceId(), snmp_translate($oid), "openwrt$query", $count, 'wlan');
}
// And, return all the sensors that have been created above (i.e. the array of sensors)
return $sensors;
}
/**
* Discover wireless client counts. Type is clients.
* Returns an array of LibreNMS\Device\Sensor objects that have been discovered
*
* @return array Sensors
*/
public function discoverWirelessClients()
{
return $this->getSensorData('clients', '', true, false);
}
/**
* Discover wireless frequency. This is in MHz. Type is frequency.
* Returns an array of LibreNMS\Device\Sensor objects that have been discovered
*
* @return array Sensors
*/
public function discoverWirelessFrequency()
{
return $this->getSensorData('frequency', '', false, false);
}
/**
* Discover wireless noise floor. This is in dBm. Type is noise-floor.
* Returns an array of LibreNMS\Device\Sensor objects that have been discovered
*
* @return array Sensors
*/
public function discoverWirelessNoiseFloor()
{
return $this->getSensorData('noise-floor', '', false, false);
}
/**
* Discover wireless rate. This is in bps. Type is rate.
* Returns an array of LibreNMS\Device\Sensor objects that have been discovered
*
* @return array
*/
public function discoverWirelessRate()
{
$txrate = $this->getSensorData('rate', '-tx', false, true);
$rxrate = $this->getSensorData('rate', '-rx', false, true);
return array_merge($txrate, $rxrate);
}
/**
* Discover wireless snr. This is in dB. Type is snr.
* Returns an array of LibreNMS\Device\Sensor objects that have been discovered
*
* @return array
*/
public function discoverWirelessSNR()
{
return $this->getSensorData('snr', '', false, true);
}
}

View File

@ -0,0 +1,124 @@
source: Extensions/Openwrt.md
path: blob/master/doc/
To use Wireless Sensors on Openwrt, an agent of sorts is required. The
purpose of the agent is to execute on the client (Openwrt) side, to ensure
that the needed Wireless Sensor information is returned for SNMP queries (from LibreNMS).
# Installation
## Openwrt
Two items are required on the Openwrt side - scripts to generate the necessary information (for
SNMP replies), and an SNMP extend configuration update (to return the information vs. the expected
query).
1: Install the scripts:
Copy the scripts from librenms-agent/snmp/Openwrt - preferably inside /etc/librenms on Openwrt (and add this
directory to /etc/sysupgrade.conf, to survive firmware updates).
The only file that needs to be edited is wlInterfaces.txt, which is a mapping from the wireless interfaces, to
the desired display name in LibreNMS. For example,
```
wlan0,wl-2.4G
wlan1,wl-5.0G
```
2: Update the Openwrt SNMP configuration, adding extend support for the Wireless Sensor queries:
`vi /etc/config/snmpd`, adding the following entries (assuming the scripts are installed in /etc/librenms),
and update the network interfaces as needed to match the hardware,
```
config extend
option name interfaces
option prog "/bin/cat /etc/librenms/wlInterfaces.txt"
config extend
option name clients-wlan0
option prog "/etc/librenms/wlClients.sh wlan0"
config extend
option name clients-wlan1
option prog "/etc/librenms/wlClients.sh wlan1"
config extend
option name clients-wlan
option prog "/etc/librenms/wlClients.sh"
config extend
option name frequency-wlan0
option prog "/etc/librenms/wlFrequency.sh wlan0"
config extend
option name frequency-wlan1
option prog "/etc/librenms/wlFrequency.sh wlan1"
config extend
option name rate-tx-wlan0-min
option prog "/etc/librenms/wlRate.sh wlan0 tx min"
config extend
option name rate-tx-wlan0-avg
option prog "/etc/librenms/wlRate.sh wlan0 tx avg"
config extend
option name rate-tx-wlan0-max
option prog "/etc/librenms/wlRate.sh wlan0 tx max"
config extend
option name rate-tx-wlan1-min
option prog "/etc/librenms/wlRate.sh wlan1 tx min"
config extend
option name rate-tx-wlan1-avg
option prog "/etc/librenms/wlRate.sh wlan1 tx avg"
config extend
option name rate-tx-wlan1-max
option prog "/etc/librenms/wlRate.sh wlan1 tx max"
config extend
option name rate-rx-wlan0-min
option prog "/etc/librenms/wlRate.sh wlan0 rx min"
config extend
option name rate-rx-wlan0-avg
option prog "/etc/librenms/wlRate.sh wlan0 rx avg"
config extend
option name rate-rx-wlan0-max
option prog "/etc/librenms/wlRate.sh wlan0 rx max"
config extend
option name rate-rx-wlan1-min
option prog "/etc/librenms/wlRate.sh wlan1 rx min"
config extend
option name rate-rx-wlan1-avg
option prog "/etc/librenms/wlRate.sh wlan1 rx avg"
config extend
option name rate-rx-wlan1-max
option prog "/etc/librenms/wlRate.sh wlan1 rx max"
config extend
option name noise-floor-wlan0
option prog "/etc/librenms/wlNoiseFloor.sh wlan0"
config extend
option name noise-floor-wlan1
option prog "/etc/librenms/wlNoiseFloor.sh wlan1"
config extend
option name snr-wlan0-min
option prog "/etc/librenms/wlSNR.sh wlan0 min"
config extend
option name snr-wlan0-avg
option prog "/etc/librenms/wlSNR.sh wlan0 avg"
config extend
option name snr-wlan0-max
option prog "/etc/librenms/wlSNR.sh wlan0 max"
config extend
option name snr-wlan1-min
option prog "/etc/librenms/wlSNR.sh wlan1 min"
config extend
option name snr-wlan1-avg
option prog "/etc/librenms/wlSNR.sh wlan1 avg"
config extend
option name snr-wlan1-max
option prog "/etc/librenms/wlSNR.sh wlan1 max"
```
NOTE, any of the scripts above can be tested simply by running the corresponding command.
NOTE, to check the output data from any of these extensions, on the LibreNMS machine, run (for example),
`snmpwalk -v 2c -c public -Osqnv <openwrt-host> 'NET-SNMP-EXTEND-MIB::nsExtendOutputFull."frequency-wlan0"'`
3: Restart the snmp service on Openwrt:
`service snmpd restart`
And then wait for discovery and polling on LibreNMS!

View File

@ -5,7 +5,7 @@
{
"sysName": "<private>",
"sysObjectID": ".1.3.6.1.4.1.8072.3.2.10",
"sysDescr": "Linux wap-emorris 4.9.184 #0 Thu Jun 27 12:18:52 2019 mips",
"sysDescr": "Linux wap-patio 5.4.35 #0 Sun Apr 26 12:19:33 2020 armv5tel",
"sysContact": null,
"version": null,
"hardware": null,
@ -23,16 +23,236 @@
{
"sysName": "<private>",
"sysObjectID": ".1.3.6.1.4.1.8072.3.2.10",
"sysDescr": "Linux wap-emorris 4.9.184 #0 Thu Jun 27 12:18:52 2019 mips",
"sysDescr": "Linux wap-patio 5.4.35 #0 Sun Apr 26 12:19:33 2020 armv5tel",
"sysContact": "<private>",
"version": "18.06.4",
"hardware": "TP-LINK Archer C7 v4",
"version": "snapshot",
"hardware": null,
"features": null,
"os": "openwrt",
"type": "network",
"serial": null,
"icon": "openwrt.svg",
"location": "<private>"
"location": null
}
]
}
},
"wireless": {
"discovery": {
"wireless_sensors": [
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "1",
"sensor_type": "openwrt",
"sensor_descr": "wl-2.4G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 4,
"sensor_prev": null,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.48\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "2",
"sensor_type": "openwrt",
"sensor_descr": "wl-5.0G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 1,
"sensor_prev": null,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.49\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "3",
"sensor_type": "openwrt",
"sensor_descr": "wlan",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 5,
"sensor_prev": null,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.12.99.108.105.101.110.116.115.45.119.108.97.110\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "frequency",
"sensor_index": "1",
"sensor_type": "openwrt",
"sensor_descr": "wl-2.4G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 2437,
"sensor_prev": null,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.48\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "frequency",
"sensor_index": "2",
"sensor_type": "openwrt",
"sensor_descr": "wl-5.0G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 5180,
"sensor_prev": null,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.49\"]"
}
]
},
"poller": {
"wireless_sensors": [
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "1",
"sensor_type": "openwrt",
"sensor_descr": "wl-2.4G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 4,
"sensor_prev": 4,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.48\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "2",
"sensor_type": "openwrt",
"sensor_descr": "wl-5.0G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 1,
"sensor_prev": 1,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.49\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "clients",
"sensor_index": "3",
"sensor_type": "openwrt",
"sensor_descr": "wlan",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 5,
"sensor_prev": 5,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.12.99.108.105.101.110.116.115.45.119.108.97.110\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "frequency",
"sensor_index": "1",
"sensor_type": "openwrt",
"sensor_descr": "wl-2.4G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 2437,
"sensor_prev": 2437,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.48\"]"
},
{
"sensor_deleted": 0,
"sensor_class": "frequency",
"sensor_index": "2",
"sensor_type": "openwrt",
"sensor_descr": "wl-5.0G",
"sensor_divisor": 1,
"sensor_multiplier": 1,
"sensor_aggregator": "sum",
"sensor_current": 5180,
"sensor_prev": 5180,
"sensor_limit": null,
"sensor_limit_warn": null,
"sensor_limit_low": null,
"sensor_limit_low_warn": null,
"sensor_alert": 1,
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"sensor_oids": "[\".1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.49\"]"
}
]
}

View File

@ -1,11 +1,15 @@
1.3.6.1.2.1.1.1.0|4|Linux wap-emorris 4.9.184 #0 Thu Jun 27 12:18:52 2019 mips
1.3.6.1.2.1.1.1.0|4|Linux wap-patio 5.4.35 #0 Sun Apr 26 12:19:33 2020 armv5tel
1.3.6.1.2.1.1.2.0|6|1.3.6.1.4.1.8072.3.2.10
1.3.6.1.2.1.1.3.0|67|27293979
1.3.6.1.2.1.1.3.0|67|1843099
1.3.6.1.2.1.1.4.0|4|<private>
1.3.6.1.2.1.1.5.0|4|<private>
1.3.6.1.2.1.1.6.0|4|<private>
1.3.6.1.2.1.25.1.1.0|67|59709269
1.3.6.1.2.1.25.1.4.0|4|board=ARCHER-C7-V4 mtdparts=spi0.0:128k(factory-uboot)ro,128k(u-boot)ro,1536k(kernel),13568k(rootfs),960k(config)ro,64k(art)ro,
1.3.6.1.4.1.2021.7890.1.101.1|4|OpenWrt 18.06.4
1.3.6.1.4.1.2021.7890.2.101.1|4|TP-LINK Archer C7 v4
1.3.6.1.6.3.10.2.1.3.0|2|272941
1.3.6.1.2.1.25.1.1.0|67|332615806
1.3.6.1.2.1.25.1.4.0|4|console=ttyS0,115200 mtdparts=nand_mtd:512k(uboot)ro,16k@512k(u_env),16k@528k(s_env),20m@2m(kernel),20m@2m(rootfs)fs,20m@22m(alt
1.3.6.1.4.1.2021.7890.1.101.1|4|OpenWrt snapshot
1.3.6.1.4.1.8072.1.3.2.3.1.1.12.99.108.105.101.110.116.115.45.119.108.97.110|4|5
1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.48|4|4
1.3.6.1.4.1.8072.1.3.2.3.1.1.13.99.108.105.101.110.116.115.45.119.108.97.110.49|4|1
1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.48|4|2437
1.3.6.1.4.1.8072.1.3.2.3.1.1.15.102.114.101.113.117.101.110.99.121.45.119.108.97.110.49|4|5180
1.3.6.1.4.1.8072.1.3.2.3.1.2.10.105.110.116.101.114.102.97.99.101.115|4x|776c616e302c776c2d322e34470a776c616e312c776c2d352e3047
1.3.6.1.6.3.10.2.1.3.0|2|18431