Definition Reference

OS Definitions

OS definition location

OS definitions should be stored in separate files in sub-dirrectory includes/definitions/os/, with a filename equal to the vendor parameter (<vendor>.inc.php). Where the vendor is minor and there will only ever be a single entry, it can be placed in includes/definitions/os.inc.php.

OS definition is contained within the os sub-array of the $config array. Each OS is itself a sub-array of this. We usually define the OS name as a variable $os so as to facilitate easy copy/pasting. For example:

$os = "linux";
$config['os'][$os]['text']                  = "Linux";
$config['os'][$os]['type']                  = "server";
$config['os'][$os]['group']                 = "unix";

The group option specifies an os_group to be merged with the os definition. This allows common shared options to be applied to multiple OSes. OS Groups are defined the same way as OSes, but in the os_group sub-array.

$os_group = "unix";
$config['os_group'][$os_group]['type']              = "server";
$config['os_group'][$os_group]['processor_stacked'] = 1;

Polling / Discovery

Option	Suboption	Format	Description
vendor		string	Vendor name for hardware in this os/group (same os can have different vendors)
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 os definitions)
mibs		array	List of supported MIBs
mib_blacklist		array	List of blacklisted MIBs (useful to exclude default and group mibs)
vendortype_mib		string	MIB name which contains vendor specific OIDs translations. Useful to translate OIDs in ENTITY-MIB
noincrease		bool	Do not check returned OIDs are increasing in snmpwalk if the OS does not support it correctly
nobulk		bool	Turn off bulkwalk if the OS does not support it correctly
virtual		bool	Allow detect SNMP engines in virtual tables (vrf/vdom/vr)
virtual_oid		string	Default MIB::Oid for detect SNMP engines in virtual tables (default is BRIDGE-MIB::dot1dBasePortIfIndex)
max-rep		int	Sets maximum repetitions in SNMP getbulk PDU. Net-SNMP default is usually 20
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 defining OS detection criteria with set of combination OIDs, should match all OIDs in set (but each single OID can be array too), see examples.
	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	string,array	Regexp list of any custom NUMERIC OID matching this device.
sysDescr_regex		array	Array of regex to match hardware/serial/... to match against sysDescr
entPhysical		array	Polling hardware/version/serial and other os metatypes by ENTITY-MIB::entPhysical table (cached by inventory module)
	oids	array	In case when need only fetch entPhysical array, use this (ie cisco, when detect hardware is hard)
	$metatype	array	oid, transform, etc params (same as for mib definitions)
	containedin	string	entPhysicalContainedIn index to fetch cached chassis entPhysical array (default is 0)
	class	string	Same as for containedin but by field entPhysicalClass (default is chassis)
packages		array	Detect version/type/features metatypes via unix-agent packages or HOST-RESOURCES-MIB::hrSWInstalledName
	name	array	Exact package name for version detection
	regex	string	Regex for version detection
	$metatype	string	Some extra metatypes (type, features)
snmpable		array	List of numeric OIDs to use for checking SNMP reachability if the OS doesn't support sysObjectID.0 and sysUpTime.0
discovery_order		array	List of discovery modules with required order. key: module name, value: name of module after which should run or special words - first, last)
modules	$module	bool	Enable/disable specific module (set to 0/1 the same as poller_blacklist or discovery_blacklist definition. It is possible to enable/disable submodules, ie: ports_ipifstats
`poller_blacklist		array	List of blacklisted poller modules
discovery_blacklist		array	List of blacklisted discovery modules
discovery_os		string	This is used only for detecting OS in get_device_os(). Used when OS discovered by filename 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)
ifDescr_ifAlias		bool	Copies ifDescr to ifAlias when ifDescr isn't the same as ifName (see allienwareplus and allied)
ifType_ifDescr		bool	Generates a ifDescr based on ifType and ifIndex if ifDescr empty
ifname		bool	Use ifName instead of ifDescr as a port name (if it exists)
ports_ignore'		array	Ignore ports via regular expression matching with ifType, ifAlias, ifName or ifDescr, see: is_port_valid()
	label	array	Regexp by ifName or ifDescr
	ifDescr	array	Regexp by ifDescr
	ifName	array	Regexp by ifName
	ifAlias	array	Regexp by ifAlias
	ifType	array	Exact match ifType
	allow_empty	bool	Skip check empty ifType for ports discovery. By default ports with a blank ifType are not discovered
ports_unignore_descr		bool	Enable to show all ports on the "Device Traffic" graph bypassing ignores. By default ifTypes which identify 'virtual' ports aren't included.
ports_separate_walk		bool	Force use separate ports polling feature (currently only if ports count >10). This cause each OID to be snmpgetted instead of using snmpwalk on each table.
sensors_poller_walk		bool	Force use snmpwalk in sensors/statuses poller (by default used multi get by numeric oids)
ipmi		bool	Indicates possible support of IPMI protocol
rancid	array	Rancid os mapping with rules
	name	string	Rancid name for this os
	rancid_min	string	Minimum rancid version where this os support added
	version_min	string	Minimum device os version for this os mapping
	hardware	string	Regexp for device hardware where this os map supported
syslog_msg		array	Regexp list of known syslog message formats. When msg/tag/program reference found, the corresponding field will be overwritten. Multiple tagX (0-9) references allowed, these tags will appended to tag field with commas
syslog_program		array	Regexp list of known syslog program formats. When tag/program reference found, the 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 / Cosmetic

Option	Suboption	Format	Description
text		string	OS name displayed on web pages
icon		string	Icon to be displayed for os. Requires icon to be placed in html/images/os/ with the format <icon>.png and <icon>_2x.png for high dpi versions
icons		array	List if possible alternative icons, selectable in the web interface or settable by code
graphs		array	List of graphtypes to be displayed on the overview page and in the device header. Default: ['device_bits','device_uptime','device_ping','device_poller_perf']
processor_stacked		bool	Use stacked area processor graph instead of multiple line graph. The line graph is more appropriate on network hardware where different processors have different characteristics.
realtime		int	Default interval setting (in seconds) for the realtime graph page. This can be changed to accomodate devices with different counter update frequencies.
comments		string	Regular expression to comments in device configurations shown in the config tab
remote_access		array	Possible remote access methods for this device ('telnet', 'ssh', 'scp', 'http')

MIB Definitions

MIB definition location

MIB definitions must be stored in separate files in sub-dirrectory includes/definitions/mibs/, with a filename equal to the mib_dir parameter (<mib_dir>.inc.php). Except for the common dirs rfc and net-snmp. They should be loaded at first, kept in includes\definitions\mibs.inc.php.

MIB definition is contained within the mibs sub-array of the $config array. Each MIB is itself a sub-array of this. We usually define the MIB name as a variable $mib so as to facilitate easy copy/pasting. For example:

MIB Global Definitions

$mib = '<MIB NAME>';
$config['mibs'][$mib][<OPTION NAME>] = OPTION VALUE 

To set the descr option on TCP-MIB, you'd do something like

$config['mibs'][$mib]['descr'] = "TCP Statistics MIB";

Option	Suboption	Format	Description
enable		integer	1 to enable, should always be 1 here - overwritable in configuration
identity_num		string	MODULE-IDENTITY numeric OID for this MIB. Leave out if MIB has no such attribute. Make sure to add the leading dot!
mib_dir		string	MIB subdirectory to use for this MIB
descr		string	Description of the MIB. This can often be copied from the MIB itself
serial		array	Array of possible OIDs names containing the device's serial number, first match wins
	oid	string	Textual OID for attribute
	oid_num	string	Numeric OID for attribute (takes precedence over textual OID)
	transform	array	Array of string transformations to be done, in order of definition. See string_transform() documentation for possible transformations and parameters.
version		array	Array of possible OIDs names containing the device's version number, first match wins. See serial.
hardware		array	Array of possible OIDs names containing the device's hardware description, first match wins. See serial.
features		array	Array of possible OIDs names containing the device's feature set, first match wins. See serial.
asset_tag		array	Array of possible OIDs names containing the device's asset tag, first match wins. See serial.
ra_url_http		array	Array of possible OIDs names containing the device's HTTP management URL, first match wins. See serial.
sysdescr		array	Array of possible OIDs names containing the device's sysDescr, first match wins. See serial.
syslocation		array	Array of possible OIDs names containing the device's sysLocation, first match wins. See serial.
syscontact		array	Array of possible OIDs names containing the device's sysContact, first match wins. See serial.
sysname		array	Array of possible OIDs names containing the device's sysName, first match wins. See serial.
uptime		array	Array of possible OIDs names containing the device's sysUptime, first match wins. See serial.

Load Average

The la MIB definition allows setting of OIDs to be used to collect "load average" metrics. These are provided on some systems based on Linux or other Unix-like variants. Be sure not to provide CPU percentage utilisation metrics here, they're not the same!

// WR-SWITCH-MIB::wrsCPULoadAvg1min.0 = INTEGER: 29
// WR-SWITCH-MIB::wrsCPULoadAvg5min.0 = INTEGER: 27
// WR-SWITCH-MIB::wrsCPULoadAvg15min.0 = INTEGER: 25
$config['mibs'][$mib]['la'] = [
  'scale'     => 0.01,
  'oid_1min'  => 'wrsCPULoadAvg1min.0',  'oid_1min_num'  => '.1.3.6.1.4.1.96.100.7.1.5.1.0',
  'oid_5min'  => 'wrsCPULoadAvg5min.0',  'oid_5min_num'  => '.1.3.6.1.4.1.96.100.7.1.5.2.0',
  'oid_15min' => 'wrsCPULoadAvg15min.0', 'oid_15min_num' => '.1.3.6.1.4.1.96.100.7.1.5.3.0',
];

Option	Suboption	Format	Description
la		array	Automatic definition-based discovery of Load Average (LA) in this device
	scale	float	LA scale multiplier
	oid_1min	string	Textual OID for LA 1 minute value
	oid_1min_num	string	Numeric OID for LA 1 minute value (snmptranslated from 'oid' if not set)
	oid_5min	string	Textual OID for LA 5 minute value
	oid_5min_num	string	Numeric OID for LA 5 minute value (snmptranslated from 'oid' if not set)
	oid_15min	string	Textual OID for LA 15 minute value
	oid_15min_num	string	Numeric OID for LA 15 minute value (snmptranslated from 'oid' if not set)

Processor

Processor entity definitions are contained within the $config['mibs'][$mib]['processor'] array. Each processor definition is a sub-array of this. We usually define the processor OID as a variable to use as the array key for easy copy/pasting.

Example

$mib = 'FORTINET-FORTIWEB-MIB';
$config['mibs'][$mib]['processor']['cPUusage'] = [ 'type' => 'table',
                                                   'descr' => 'Processor %index%', 
                                                   'oid' => 'cPUusage', 
                                                   'oid_num' => '.1.3.6.1.4.1.12356.107.2.2.2.1.2' ];

Option	Format	Description
descr	string	Description of processor. Supports templating of fields like %oid_descr% and %index%.
type	string	Definition type ('static' for single OID where OID includes the index, 'table' for standard table based discovery). This is deprecated, always use table.
idle	bool	TRUE if idle value is returned in OID instead of used value
table	string	Textual OID name of table to walk in case 'type' is set to 'table'
oid_descr	string	Textual OID name of table to walk/get for descriptions
oid	string	Textual OID for processor value
oid_num	string	Numeric OID for processor value (snmptranslated from 'oid' if not set)
oid_count	string	FIXME undocumented? "processor count"
scale	float	Processor scale multiplier
rename_rrd	string	Rename a supplied RRD file name to the new naming convention. Only used when migrating old definitions.
skip_if_valid_exist	bool

Memory Pool

Memory Pool definitions are contained within the $config['mibs'][$mib]['mempool'] array. Each memory Pool definition is a sub-array of this. We usually define the memory pool table OID as a variable to use as the array key for ease of copy/pasting.

To function, the Memory Pool entity poller needs to know any two of the total size, free, or used space in the memory pool. It will calculate the missing value.

Example

MY-MEMORY-MIB::myMemoryPoolIndex.1 = INTEGER: 1
MY-MEMORY-MIB::myMemoryPoolName.1 = STRING: memory
MY-MEMORY-MIB::myMemoryPoolCurrentUtilization.1 = INTEGER: 42
MY-MEMORY-MIB::myMemoryPoolLowestUtilization.1 = INTEGER: 29
MY-MEMORY-MIB::myMemoryPoolLargestUtilization.1 = INTEGER: 65
MY-MEMORY-MIB::myMemoryPoolSize.1 = INTEGER: 524288
MY-MEMORY-MIB::myMemoryPoolUsed.1 = INTEGER: 219556
MY-MEMORY-MIB::myMemoryPoolFree.1 = INTEGER: 304728
MY-MEMORY-MIB::myMemoryPoolWarning.1 = INTEGER: 90
MY-MEMORY-MIB::myMemoryPoolCritical.1 = INTEGER: 100

$config['mibs'][$mib]['mempool']['myMemoryPoolUtilizationTable'] = array('type' => 'table',
                                                                         'oid_descr' => 'myMemoryPoolName', 
                                                                         'oid_used'  => 'myMemoryPoolUsed', 
                                                                         'oid_total' => 'myMemoryPoolSize' );

Option	Format	Description
descr	string	Description of memory pool (hard-coded)
type	string	Processor type ('static' for single OID, 'table' for table walk) FIXME only static for now
oid_descr	string	Textual OID name of table to walk/get for descriptions
oid_free	string	Textual OID for memory free value
oid_free_num	string	Numeric OID for memory free value (snmp translated from 'oid' if not set)
oid_used	string	Textual OID for memory used value
oid_used_num	string	Numeric OID for memory used value (snmp translated from 'oid' if not set)
total	int	Hardcoded memory total
oid_total	string	Textual OID for memory total
oid_total_num	string	Numeric OID for memory total value (snmptranslated from 'oid' if not set)
oid_perc	string	Textual OID for memory used percentage value
oid_perc_num	string	Numeric OID for memory used percentage value (snmp translated from 'oid' if not set)
scale	float	Mempool default scale multiplier
scale_total	float	Mempool total scale multiplier (if not passed, use default)
scale_used	float	Mempool used scale multiplier (if not passed, use default)
scale_free	float	Mempool free scale multiplier (if not passed, use default)
rename_rrd	string	Rename 'this' RRD file to the new naming convention

Status

Example

$config['mibs'][$mib]['status'][] = array(
  'table'               => 'wsSFPTable',
  'oid'                 => 'wsSFPStatus',
  'descr'               => '%port_label% SFP status (%wsSFPPartNumber%)',
  'oid_num'             => '.1.3.6.1.4.1.9303.4.1.4.1.2',
  'measured'            => 'port',
  'measured_match'      => [ ['entity_type' => 'port', 'field' => 'ifIndex', 'match' => '%index%' ] ],
  'type'                => 'wsSFPStatus'
);
$type = 'wsSFPStatus';
$config['mibs'][$mib]['states'][$type][0] = array('name' => 'ok',      'event' => 'ok');
$config['mibs'][$mib]['states'][$type][1] = array('name' => 'missing', 'event' => 'exclude');
$config['mibs'][$mib]['states'][$type][2] = array('name' => 'invalid', 'event' => 'alert');

Option	Suboption	Format	Description
descr		string	Description of sensor (hard-coded). Key replaced: %oid_descr% replaced with value from 'oid_descr'. %index% - index from walk, %i% - counter started from 1, Multipart indexes (ie: 0.1) can used as keys with part number: %index0%, %index1%, ...
oid_descr		string	Numeric OID for description of sensor (dynamic) used as descr alone if descr not set
type		string	Status sensor type (name as used in MIB)
oid		string	Textual OID for status value
oid_num		string	Numeric OID for status value (snmp translated from 'oid' if not set)
oid_map		string	Textual/numeric OID for events status map value
measured		string	Measured entity (device, port, ...)
measured_match		array	Array of rules used to link this entity to another. See example for format.
descr_transform		array	Array of string transformations to be done, in order of definition. See string_transform() documentation for possible transformations and parameters.
table		string	Textual OID with table name (if not set, used $tablename from key)
table_walk		boolean	If set to FALSE, walked separate OIDs from definition. By default walked whole table
rename_rrd_array		array	Rename old RRD file to the new naming convention, used array of discover_status() params
	descr	string	Old status name
	type	string	Old status type
	index	string	Old status index

Shared Functions

String Transform

The string_transform() function is used by a number of modules to manipulate text strings, particularly descriptions. This can be used to remove repeated text or pick a particular element of a string to be used.

In definitions the function is usually used by defining a set of transform rules, where each rule is an array containing an action element, and additional elements defined by the action. Multiple rules are executed in the order they're presented.

Examples

This example removes " Temperature", "(degrees Celsius)" and "(degrees Celcius)" from a string. Vendors often add superfluous text that makes descriptions longer and more difficult to display in limited space.

[ ['action' => 'regexp_replace', 'from' => '/ \(degrees Cel[cs]ius\)/', 'to' => ''],
  ['action' => 'regexp_replace', 'from' => '/ Temperature/', 'to' => ''] ]

This example replaces some MIB-defined strings to more human readable strings for use in a description.

[ 'action' => 'replace', 'from' => [ 'eIsdn', 'eSipPbx', 'eSipProvider', 'eAnalog' ], 
                         'to'   => [ 'ISDN', 'SIP PBX', 'SIP Provider', 'Analog' ] ]

This example also replaces some MIB-defined strings, but uses the map action.

[ 'action' => 'map', 'map' => [ 'vin14' => '14VIN', 'vs2_5' => '2.5VS', 'cpu_dsp_afe' => 'CPU/DSP/AFE' ] ]

Actions

Action	Description
prepend	Prepend static string
append	Append static string
trim	Trim characters from both sides of the string
ltrim	Trim characters from the left of the string
rtrim	Trim characters from the right of the string
upper	Call strtoupper(). This is a PHP function that converts the entire string to upper case
lower	Call strtolower(). This is a PHP function that converts the entire string to lower case
nicecase	Call nicecase(). This is an internal Observium function that correctly capitalises and de-abbreviates several common intialisms, acronyms and abbreviations. See includes/definitions/rewrites.inc.php
replace	Case-sensitively replace from string with to. from can be an array of strings [ 'action' => 'replace', 'from' => [ 'poeDot3af', 'poePlusDot3at' ], 'to' => [ '802.3af PoE', '802.3at PoE+' ]]
ireplace	Case-insensitively replace from string by to. from can be an array of strings
regex_replace preg_replace	Regular expression replace from with to. [ 'action' => 'preg_replace', 'from' => '/psu(\d+V)(AC|DC)(\d+W)/', 'to' => '$1, $3, $2' ] In the example above, psu230VAC75W is converted to 230V, 75W, AC
timeticks	Convert standard Timeticks to seconds
uptime age	Convert any human readable age/uptime to seconds (also support timeticks)
explode	Explode string by delimiter (default ' ') and fetch array element index (first (default), second, last or number)
map	Map string by key -> value, where key-value pairs to eb substituted passed via array 'map'. [ 'action' => 'map', 'map' => [ 'mac' => 'MAC', 'cpu' => 'CPU', 'phy' => 'PHY' ] ]
map_match	Map string by regular expression pattern -> value, where pattern-value pairs passed via array 'map' [ 'action' => 'map_match', 'map' => [ '/^active$/' => 'up', '/^no carrier/' => 'down', '/.+/' => 'unknown' ]]
units	Convert byte/bit string with units to bytes/bits
asdot	Call bgp_asdot_to_asplain()
entity_name	Call rewrite_entity_name()
urlencode	Call rawurlencode()
urldecode	Call rawurldecode()
escape	Call escape_html()