From Observium

Contents 1 Database Functions 1.1 Functions 1.2 Fetch single cell 1.3 Fetch single row 1.4 Iterate over row(s) 1.5 Update row(s) 1.6 Insert row 1.7 Delete row(s) 2 Discovery Functions 2.1 discover_sensor 3 SNMP Functions

Database Functions

Observium uses a set of functions to abstract MySQL database access in order to simplify safe handling of MySQL queries.

Functions

$parameters are used to replace ? in the SQL with sanitised variables as in the examples below

• dbInsert($data, $table)
• dbUpdate($data, $table, $where, $parameters)
• dbDelete($table, $where, $parameters)

• dbFetchRow($sql, $parameters)
• dbFetchRows($sql, $parameters)
• dbFetchCell($sql, $parameters)
• dbFetchColumn($sql, $parameters)

$sql can be passed as either a complete query where there needs be no variable checking or you can use ? to denote where a sanitised variable needs inserted and pass an array of variables to be sanitised and inserted.

All variables should be sanitised when used in a SQL query, whether they come from the database, from SNMP or from the web interface.

For example:

$row = dbFetchRow("SELECT * FROM `table` WHERE `key` = ? AND `key2` = ?", array($key, $key2))

This will be the same as:

$query = mysql_query("SELECT * FROM `table` WHERE `key` = '".mysql_real_escape_string($key)."' AND `key2` = '".mysql_real_escape_string($key2)."'");
$row = mysql_fetch_assoc($query);

If you don't want a variable to be scaped, you can pass it as a value within an array as an indicator that it should be left alone:

$row = dbFetchRow("SELECT * FROM `table` WHERE `key` = ? AND `key2` = ?", array($key, array($key2)))

This would be the same as:

$query = mysql_query("SELECT * FROM `table` WHERE `key` = '".mysql_real_escape_string($key)."' AND `key2` = '".$key2."'");
$row = mysql_fetch_assoc($query);

Fetch single cell

Traditional method

$cell = mysql_result(mysql_query("SELECT `value` FROM `table` WHERE `field` = '".$value."'"),0)

Observium method with SQL-injection protection

$cell = dbFetchCell("SELECT `value` FROM `table` WHERE `field` = ?", array($value))

Note that you can put variables in-line within the text portion of the query, but that is unsafe and not recommended.

Fetch single row

Traditional method

$query = mysql_query("SELECT * FROM `table` WHERE `field` = '".$value."'")
$row = mysql_fetch_assoc($query)

Observium method with SQL-injection protection

$row = dbFetchRow("SELECT * FROM `table` WHERE `field` = ?, array($value))

Iterate over row(s)

Traditional method

$query = mysql_query("SELECT * FROM `table` WHERE `field` = '".$value."'");
while(mysql_fetch_assoc($query) = $row) { ... }

Observium method with SQL-injection protection

foreach(dbFetchRows("SELECT * FROM `table` WHERE `field` = ?", array($value))) { ... }

Update row(s)

Traditional method

mysql_query("UPDATE `table` SET `field` = '".$value."' WHERE `key` = '".$id."'")

Observium method with SQL-injection protection

dbUpdate(array('field' => $value), 'table', '`key` = ?' array($id))

Insert row

Traditional method

mysql_query("INSERT INTO `table` (`key`, `field`) VALUES ('".$id."','".$value."')")

Observium method with SQL-injection protection

dbInsert(array('key' => $id, 'field' => $value), 'table');

Delete row(s)

Traditional method

mysql_query("DELETE FROM `table` WHERE `field` = '".$value."'");

Observium method

The table name is passed as the first argument, the WHERE statement as second and an array of variables for the WHERE statement as the third.

dbDelete('devices', "`field` =  ?", array($value));

Discovery Functions

The discovery funtions are used within each discovery module to add the entry to the database and do any important checks and generate thresholds where they aren't set by the module.

discover_sensor

discover_sensor($valid, $class, $device, $oid, $index, $type, $descr, $divisor, $multiplier, $low_limit, $low_warn_limit, $warn_limit, $high_limit, 
                $current, $poller_type)

Variable	Default	Description
$valid		Passes an array that valid sensors should be appended to. This usually should be kept the same as all other modules
$class		Specifies the class of sensor. Examples include "temperature", "fanspeed" and "current"
$device		Passes the $device array
$oid		Specifies the OID that contains the value being monitored
$index		Specifies the Index used on the device for this $type
$type		Specifies a Type of sensor, usually specific to one SNMP table, for example "cisco-entity-sensor" for CISCO-ENTITY-SENSOR-MIB
$descr		A text description of the sensor. If there is no description in the MIB, you can generate one, probably using the $index
$divisor	1	value that the entry retrieved from $oid should be divided by
$multiplier	1	value that the entry retrieved from $oid should be multiplied by
$low_limit	NULL	Lower limit
$low_limit_warn	NULL	Lower warning limit
$warn_limit	NULL	Upper limit
$high_limit	NULL	Upper warning limit
$current	NULL	Current measurement
$poller_type	snmp	Poller type. Should be snmp for SNMP.

function discover_juniAtmVp(&$valid, $interface_id, $vp_id, $vp_descr)

function discover_link($local_interface_id, $protocol, $remote_interface_id, $remote_hostname, $remote_port, $remote_platform, $remote_version)

function discover_storage(&$valid, $device, $index, $type, $mib, $descr, $size, $units, $used = NULL)

function discover_processor(&$valid, $device, $oid, $index, $type, $descr, $precision = "1", $current = NULL, $entPhysicalIndex = NULL, $hrDeviceIndex = NULL)

function discover_mempool(&$valid, $device, $index, $type, $descr, $precision = "1", $entPhysicalIndex = NULL, $hrDeviceIndex = NULL)

function discover_toner(&$valid, $device, $oid, $index, $type, $descr, $capacity = NULL, $current = NULL)

function sensor_low_limit($class, $current)
function sensor_limit($class, $current)
function check_valid_sensors($device, $class, $valid)

SNMP Functions

• We prefer to use the "cache" snmp functions rather than doing a direct walk.

function snmp_get($device, $oid, $options = NULL, $mib = NULL, $mibdir = NULL)
function snmp_walk($device, $oid, $options = NULL, $mib = NULL, $mibdir = NULL)
function snmp_get_multi($device, $oids, $options = "-OQUs", $mib = NULL, $mibdir = NULL)

function snmpwalk_cache_cip($device, $oid, $array, $mib = 0)
function snmp_cache_ifIndex($device)
function snmpwalk_cache_oid($device, $oid, $array, $mib = NULL, $mibdir = NULL)
function snmpwalk_cache_multi_oid($device, $oid, $array, $mib = NULL, $mibdir = NULL)
function snmpwalk_cache_double_oid($device, $oid, $array, $mib = NULL, $mibdir = NULL)
function snmpwalk_cache_triple_oid($device, $oid, $array, $mib = NULL, $mibdir = NULL)
function snmpwalk_cache_twopart_oid($device, $oid, $array, $mib = 0)
function snmpwalk_cache_threepart_oid($device, $oid, $array, $mib = 0)
function snmp_cache_slotport_oid($oid, $device, $array, $mib = 0)
function snmp_cache_oid($oid, $device, $array, $mib = 0)
function snmp_cache_port_oids($oids, $port, $device, $array, $mib=0)
function snmp_cache_portIfIndex($device, $array)
function snmp_cache_portName($device, $array)