Adding support for a new OS
Adding an OS type to Observium can be relatively straight forward or it can be quite complex, depending upon the structure and design of the MIBs and SNMP implementations involved.
OS Detection
Deciding how to initially identify an OS is important, because you don't want to miss valid matches or accidentally match devices which don't fit. Some vendors make this easy, some make it fairly cumbersome.
Basic OS Detection
Primarily we'll rely on 2 common OIDs to identify a device, sysObjectID and sysDescr. These usually provide enough data to identify what OS a device is running.
You can fetch these from the device like this
# snmpget -v2c -c public localhost sysDescr.0 sysObjectID.0 -On
.1.3.6.1.2.1.1.1.0 = STRING: CISCO SPA122 1.3.1(003)
.1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.9.6.1.23.1.1.1.3
The sysObjectID is (should be) an OID which identifies the type of device, some vendors have per-model Ids, some per-family, some per-OS, some have a single id for all of their products and some ship with the default id of the SNMP stack they used. Often if you look at the Ids of a number of devices you'll see a pattern which will make it easy to identify them. sysObjectID entries are matched against the beginning of the string, for example .1.3 would match .1.3.4.1.
The sysDescr is a text string set by the vendor which usually has the vendor name, the os name, versions, model numbers and that sort of thing in. Often you can identify an OS, model and version from this alone. sysDescr entries are matched as regular expressions.
Multiple sysObjectID and sysDescr match lines can be included in the definition, and only one is required to match.
Examples:
Juniper Networks, Inc. m320 internet router, kernel JUNOS 10.1R3.7 #0: 2010-07-10 05:44:37 UTC builder@queth.juniper.net:/volume/build/junos/10.1/release/10.1R3.7/obj-i386/bsd/sys/compile/JUNIPER Build date: 2010-07-10 05:00:11 UTC Copyright (c) 1996
Redback Networks SmartEdge OS Version SEOS-12.1.1.12p1-Release
NetApp Release 8.1.2 7-Mode: Tue Oct 30 19:56:51 PDT 2012
ArubaOS (MODEL: Aruba6000), Version 6.1.3.10 (39813)
We'll use the Cisco/Linksys SPA as an example of a simple form of detection.
$os = "cisco-spa";
$config['os'][$os]['text'] = "Cisco SPA";
$config['os'][$os]['type'] = "voip";
$config['os'][$os]['vendor'] = "Cisco Small Business";
$config['os'][$os]['icon'] = "ciscosb";
$config['os'][$os]['sysObjectID'][] = ".1.3.6.1.4.1.9.6.1.23.1.1";
$config['os'][$os]['sysDescr'][] = "/^CISCO SPA/";
Lets break this down line by line, even though a lot of this is pretty obvious!
$os = "cisco-spa";
This is the OS identifier. We recommend that you include elements to identify both the vendor and the OS or product family here.
$config['os'][$os]['text'] = "Cisco SPA";
This is the OS's text. It's used in the UI in place of the OS identifier.
$config['os'][$os]['type'] = "voip";
This is used to automatically classify the type of the device. This is mostly used in the UI for search and grouping purposes.
$config['os'][$os]['vendor'] = "Cisco Small Business";
This is a string identifying the vendor of the device. If the vendor already exists, use the exact same string, otherwise use the vendor name.
$config['os'][$os]['icon'] = "ciscosb";
This is the icon name. If it's not the same as the vendor in lower case, it'll need to be defined separately. Some OSes have their own icons, and sometimes we use historical icons to help visually identify things like with Cisco's older CatOS.
$config['os'][$os]['sysObjectID'][] = ".1.3.6.1.4.1.9.6.1.23.1.1";
Here we're identifying the device by sysObjectID since all SPAs seem to have the same OID in the ciscoSB table.
$config['os'][$os]['sysDescr'][] = "/^CISCO SPA/";
Here we're identifying the device by sysDescr, matching anything that starts with "CISCO SPA" by regular expression.
Now when adding the device, we can see that it's correctly discovered :
root@zeta:/home/observium/dev# ./add_device.php cisco-spa secret
Observium 18.10.9480
Add Device(s)
Try to add cisco-spa:
Trying v2c community secret ...
+-------------+-------------------------------+
| OID | |
+-------------+-------------------------------+
| sysDescr | CISCO SPA122 1.3.1(003) |
| sysObjectID | .1.3.6.1.4.1.9.6.1.23.1.1.1.3 |
+-------------+-------------------------------+
o Detect OS matched (cisco-spa: Cisco SPA):
+-------------+---------------------------+-------------------------------+
| OID | Matched definition | |
+-------------+---------------------------+-------------------------------+
| sysObjectID | .1.3.6.1.4.1.9.6.1.23.1.1 | .1.3.6.1.4.1.9.6.1.23.1.1.1.3 |
+-------------+---------------------------+-------------------------------+
Rediscovering an existing device OS
An existing device's OS can be rediscovered by using the command ./discovery.php -h <device_id> -m os
Complex OS Detection
For instances where a device can't be matched using just sysDescr or sysObjectID, we can create more complex rules requiring multiple matches and other OIDs.
To do this we create discovery entries in the OS definition, where everything inside a single discovery entry must match.
| Field | Type | Description |
|---|---|---|
sysDescr |
(string,array) | sysObjectIDs matching this device. |
sysObjectID |
(string,array) | regexp list of sysDescr matching this device. |
sysName |
(string,array) | regexp list of sysName matching this device. |
MIB::Oid.X |
(string,array) | regexp list of any custom MIB and OID matching this device. NOTE: MIB should be defined in MIBs definitions! |
.X.X.X.X.X.X |
(string,array) | regexp list of any custom NUMERIC OID matching this device. |
For many OSes it can be sufficient to just test for the existence of an OID in a MIB specific to that OS.
It's recommended to always match against a sysObjectID and/or sysDescr first where possible, because fetching vendor-specific OIDs slows down the discovery process.
Note that when matching against a MIB:OID, the MIB must be defined in the MIB definitions so that Observium knows where to find it.
Examples
Teltonika devices return generic Linux sysObjectID and sysDescr, but in we can test for the existence of an OID in their own MIB, in this instance we use RouterName.0 in TELTONIKA-MIB. If that OID is populated, it's obviously a Teltonika device!
$config['os'][$os]['discovery'][] = array(
'sysObjectID' => '.1.3.6.1.4.1.8072.3.2.10',
'sysDescr' => '/^Linux/',
'TELTONIKA-MIB::RouterName.0' => '/.+/',
);
Quanta devices are based on Broadcom Fastpath designs and return the generic Broadcom sysObjectID. Historically sysDescr strings from vendors who use Fastpath silicon have not been reliable, so we'll match against Quanta strings in the agentInventoryMachineType and agentInventoryMachineModel OIDs in FASTPATH-MACHINE-MIB.
This rules require a sysObjectID of either .1.3.6.1.4.1.4413 (Broadcom) or .1.3.6.1.4.1.7244 (Quanta), and will then fetch and try matching against agentInventoryMachineType.0. If this doesn't match the second rule repeats this with agentInventoryMachineModel.0.
$config['os'][$os]['discovery'][] = array(
'sysObjectID' => array('.1.3.6.1.4.1.4413', '.1.3.6.1.4.1.7244'),
'FASTPATH-SWITCHING-MIB::agentInventoryMachineType.0' => '/^(Quanta )?L[A-Z]\d/i',
);
$config['os'][$os]['discovery'][] = array(
'sysObjectID' => array('.1.3.6.1.4.1.4413', '.1.3.6.1.4.1.7244'),
'FASTPATH-SWITCHING-MIB::agentInventoryMachineModel.0' => '/^(Quanta )?L[A-Z]\d/i',
);
For some vendors it's necessary to use combinations of sysDescr, sysObjectID and vendor-specific OIDs.
Adding support for new MIBs
Once Observium can correctly identify your new OS, you can add support for any collectible entities in MIBs supported by that device.
If the MIB and entities are already supported by Observium, you simply need to add the MIB to the mibs OS array element, for example:
$config['os'][$os]['mibs'][] = "TELTONIKA-MIB";
If the MIB or required entities within the MIB are not yet suppored by Observium, you can use our guide on adding new MIBs.
OS Definition Settings
There are a number of other settings that can be added to an OS definition to control how Observium treats the OS.
Polling/Discovery Settings
| Setting | Type | Description |
|---|---|---|
| vendor | (string) | vendor name for this os/group |
| group | (string) | sets os_group for this os |
| type | (string) | sets type for this os. Must be one of specified in $config['device_types |
| model | (string) | link to per hw/model specific definitions and hardware rewrites based on sysObjectID (in definitions/models.inc.php) |
| mibs | (array) | list of supported MIBs |
| mib_blacklist | (array) | list of blacklisted MIBs (exclude default and group mibs) |
| snmp -> noincrease | (bool) | do not check returned OIDs are increasing in snmpwalk if the OS does not support it correctly |
| snmp -> nobulk | (bool) | turn off bulkwalk if the OS does not support it correctly |
| snmp -> max-rep | (int) | sets maximum repetitions in SNMP getbulk PDU |
| snmp -> max-get | (int) | sets number of maximum requested Oids in SNMP multi get PDU |
| sysObjectID | (array) | list of sysObjectIDs matching this device, for OS discovery. |
| sysDescr | (array) | regexp list of sysDescr matching this device, for OS discovery. |
| discovery | (array) | list of complex arrays for Detect OS with set of combination OIDs, |
| sysDescr_regex | (array) | array of regex to match hardware/serial/... to match against sysDescr |
| snmpable | (array) | list of numeric OIDs which must check if os not have sysObjectID.0 and sysUpTime.0 |
| discovery_order | (array) | list of discovery modules with required order |
| poller_blacklist | (array) | list of blacklisted poller modules |
| discovery_blacklist | (array) | list of blacklisted discovery modules |
| discovery_os | (string) | Used when OS discovered by file does not match includes/discovery/os/$os.inc.php |
| port_label | (array) | regexp list with ports ifDescr (port_label) processing (replace text with first founded subpattern) |
| ifAlias_ifDescr | (bool) | Copies ifDescr to ifAlias if ifAlias isn't the same as ifName |
| ifType_ifDescr | (bool) | Generate ifDescr based on ifType and ifIndex if ifDescr empty |
| ifname | (bool) | use ifName instead of ifDescr as a port name (if exist) |
| ports_skip_ifType | (bool) | skip check empty ifType for ports discovery, see: is_port_valid() |
| ports_unignore_descr | (bool) | enable to show all ports on the "Device Traffic" graph bypassing ignores. |
| ports_separate_walk | (bool) | force use separate ports polling feature (currently only if ports count >10) |
| ipmi | (bool) | indicates possible support of IPMI protocol |
| syslog_msg | (array) | regexp list of known syslog message formats. When msg/tag/program reference found, than corresponding field will be overwritten. Allowed multiple tagX (0-9) references, this tags will append by comma into tag field |
| syslog_program | (array) | regexp list of known syslog program formats. When tag/program reference found, than corresponding field will be overwritten. |
| uptime_max | (array) | additional (known) uptime rollover counter in seconds, this uptimes skipped in detect reboot alert (device_rebooted) (for 'sysUpTime', 'hrSystemUptime', 'snmpEngineTime') |
Web UI Settings
| Setting | Type | Description |
|---|---|---|
| text | (string) | OS name displayed on web pages |
| icon | (string) | name of icon from html/images/os/<$icon>.png |
| icons | (array) | list if possible alternative icons, selectable in the web interface or settable by code |
| graphs | (array) | list of up to 4 graph types displayed by default for this os |
| processor_stacked | (bool) | use stacked processor graph (used for computers) |
| realtime | (int) | default interval setting (in seconds) for the realtime graph page |
| comments | (string) | Regexp! Here regular expression for ignore device comments on show device config page |
| remote_access | (array) | possible remote access methods for this device ('telnet', 'ssh', 'scp', 'http') |