Adding a new OS type

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 |
+-------------+---------------------------+-------------------------------+

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.

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')

Adding support for new MIBs