Expression language reference

From Sanet

Jump to: navigation, search

Contents

The language

Literals

Strings

A string is a sequence of characters delimited by single quotes or double quotes:

Character escaping

Few special characters can be inserted into a string by prepending the escape character \.

Escape sequence Character Description
\t tab
\b Back Space
\n new line
\f line feed
\r Carriage Return
\" " double quote
\' ' single quote
\\ \ backslash

You can use escaped characters inside strings delimited by single (')or double quotes (").

Examples
Input string Value
"Hello\nWorld" Hello
World"
"Hello 'World'" Hello 'World'
'Hello "World"' Hello "World"
'Hello \'World\' ' Hello 'World'
"Hello \"World\"" Hello "World"

Disable string escaping

It is possible to disable string escaping by prepending the prefix r to any string.

r " ... "
r ' ... '

Examples

Input string Value Description
"Hello\nWorld" Hello
World
"Hello\\World" Hello\World
"Hello\"World" Hello"World
r"Hello\nWorld" Hello\nWorld unescaped
r"Hello\\nWorld" Hello\\World unescaped
r"Hello\"nWorld" Hello\"World unescaped

Numbers

Numbers can be expressed as:

Integer values
Sequence of decimal characters starting with a decimal.
Examples:
expression value
1 1
-1982 -1982
Floating point values
They follow the following sintax:
integer part . decimal part [ (e | E) ( - | + ) exponent ]
Examples:
expression value
1.0 1.0
3.14 3.14
4.0e+10 40000000000.0
1.0E-3 0.0001


Hexadecimals values
Sequence of hexadecimal characaters with the prefix 0x.
Examples:
expression value
0x1 1
0xff 255
0xFF 255
0x80000 32768
Octal values
Sequence of octal characters startring with 0.
Examples:
expression value
01 1
07 7
010 8
011 9

Booleans

Booleans values can be true or false. These values are represented by the constants: True or False.

Example:

Expression Value
True true
False false

OIDs

When speaking about SNMP, OIDs (or Object Identifiers) uniquely identify managed objects in a MIB hierarchy.

They are expressed with a sequence of at least three decimal strings separated by a dot ".".

IMPORTANT: An OID are a special kind of literal and can be used only inside SNMP sub-expression. You can not use OID literals inside mathematical expressions or comparisons.

Examples:

Expression
1.2.3
1.3.6.1.2.1.1.1.18.241

Variables

A variable is represented by a initial $ followed by a sequence of alphanumeric characters or _.

Every variable has a value. The value can be a string, a number, a boolean,

Examples:

Functions

Functions are represented by a sequence of alphanumeric characters or _.

Examples:

Expressions

Operators

The language supports the following operators:

Arithmetical
Operator Meaning
a + b sum
a - b subtraction
a / b division
a % b module division
a * b multiplication
+a positive
-a negative
Comparison
Operator Meaning
a == b
a != b
a =~ b a matches regular expression represented by b
a < b
a <= b
a > b
a >= b
BIT operators
Operator Meaning
a & b bit and
a | b bit or
a ^ b bit xor
~a one's complement
Logical operators
ATTENTION: binary logical operators || and && are not short-circuited.
Operator Meaning
a || b or
a && b and
 !a not

Function call

This is the syntax for function call:

function name ( [ param , param , .... ] [, name=param , name=param ] )

You can specify simple parameters, also called positional parameters, and named parameters.

All named parameters can be specified in any order, but must appear after any other positional parameter.

Not all functions support named parameters. Read functions' documentation for more details.

Examples:

myfunction1()
myfunction2( 10 )
myfunction2( "Hello", 'World', 42 )
myfunction3( "Hello", 'World', 42 , timeout=10, shorttries=(3+2))
myfunction4(timeout=10)
myfunction5(probesize=1472, "localhost") WRONG PARAMETERS SEQUENCE

SNMP Sub-expressions

An SNMP sub-expression, or simply SNMP expression, is a special syntax element of the language. It is used to reppresent the value of a managed object (OID) in the MIB hierarchy.

There are two kind of SNMP expressions and they reppresent two kind of values:

Current snmp values

These expressions reppresent the current value of an OID. When the SNMP expression is evaluated the value is read from the network throw SNMP protocol.

The syntax is:

OID subexpr [ : snmp community subexpr ] @ [ node name subexpr [ : snmp subexpr ] ]

Where:

OID subexpr
an expression returning the desired OID. It must have the following sintax:
OID literal [ . expression> [ . .... ] ]
Where expression can be any expression representing string or number.
snmp community subexprrr
expression returning the SNMP community name.
node name subexprrr
expression returning the node name.
snmp subexpr
expression returning the used SNMP port number.

If snmp community subexpr, node name subexpr or snmp subexpr are missing, the default value is taken from the execution context.

The execution context is a set of variables created when the expression evaluation starts. This is a SANET related topic and will be explained later in this document.

parameter context's variable name
snmp community subexpr $community
node name subexpr $node
snmp subexpr $snmpport

Examples:

The last examples show how to compute OIDs at runtime. You can also use variables, e.g. if $one cointains "1":

The parser is not perfect, and will be confused if you use suboids with one or two numbers in it (it will try to convert to int or float, and will traceback). If your suboids are made of one or two numbers, enclose them in double quotes:

Old snmp values

The syntax is:

OID subexpr [ : snmp community subexpr ] # [ node name subexpr [ : snmp subexpr ] ]

These sub-expressions represent the previous value of a managed object inside a MIB.

The term previous value means the value read throw SNMP the last time the expression containing the SNMP sub-expression was evaluated.

This is a SANET related topic and will be explained later in this document.

SNMP Expression Language and SANET's checks

The SNMP Expression language is used by SANET to perform nodes' basechecks.

SNMP Expression values

The SNMP subexpression evaluation (es: 1.3.6.1.2.1.1.1.0@ ) is lazy.

This means that the value is retrieved from the network only when an effective manipulation of the value is required (comparisons, arithmetical operations and so on).

Execution context

Whe a basecheck is performed, the related expression(s) is executed with a set of variabiles called execution context.

Basecheck's parameters are converted into variables and stored in the execution context.

Depending on the basecheck type (node target, interface measure, ecc...) the execution context exports several built-in variables related to the basecheck's data (path, id, ecc...).

Built-in node's variables

variable Description
$node hostname
$ipv6name hostname for ipv6
$community SNMP community
$snmpversion SNMP version
$snmpport 161

Built-in target's variables

variable Description
$id target's id number
$shorttries target's shorttries parameter
$times target's times parameter
$delta Time passed since the last check

Built-in interface's variables

These variabiles are present only when the basecheck involves a SANET interface.

variable Description
$iface interface's name
$iface_id interface's id
$ifindex interface's ifindex (current)
$instance instance value
$xform xform string expression

When an interface is part of a link, the execution context exports the following variables related to the linked interface:

variable Description
$linked_iface name
$linked_iface_id id
$linked_ifindex
$linked_instance
$linked_xform

SANET's built-in functions

This is the list of available functions.

Basic functions

hex

Syntax
hex ( bytes )
Description
Converts the input parameter bytes into a UPPERCASE hexadecimal string.
Input
bytes: a sequence of bytes.
Output
Returns a string.
Errors
If the input parameter can not be converted to a valid string the expression evaluation fails.
Examples
Expression Description Return string value
hex( 1.3.6.1.2.1.2.2.1.6.2@"mason" ) Converts into a string the MAC address of the interface with ifindex 2 01279AF7A4D

abs

Syntax
abs ( arg )
Description
Returns the absolute value of the given argument.
Input
args: number
Output
Returns a number
Errors
If the input parameter can not be converted to a valid number the expression evaluation fails.
Examples
Expression Value
abs(1) 1
abs(-1) 1



str

Syntax
str ( arg )
Description
Tries to converts the input value arg to a string.
Input
args: any value
Output
Returns a string
Errors
If the input parameter can not be converted to a valid string the expression evaluation fails.
Examples
Expression Value
str(0xFF) 255
str(1.0) 1.0
str("foo") foo

float

Syntax
float ( arg )
Description
Tries to converts the input value arg to an floating point value.
Input
args: any value
Output
Returns a floating point value.
Errors
If the input parameter can not be converted to a valid floating point value the expression evaluation fails.
Examples
Expression Value
int(0xff) 255.0
int(1.33) 1.33
int("12345") 12345.0
int("foo") ERROR

int

Syntax
int ( arg [ , base ] )
Description
Tries to converts the input value arg to an integer value. The base parameter can be 2, 8, 10, 16.
Input
args: any value
base: the
Output
Returns a string
Errors
If the input parameter can not be converted to a valid integer value the expression evaluation fails.
Examples
Expression Value
int(0xFF) 255
int(1.33) 1
int("12345") 12345
int("0x0F", 16) 15
int("foo") ERROR

oidFirst

Syntax
oidFirst ( oid )
Description
The function take in input a dot-separted OID string and returns the first node of the sequence.
Input
oid: a dot-separated string.
Output
Returns a string
Errors
Examples
Expression Return string value Description
oidFirst("9.8.7.8.5.4.3.2.1") 9
oidFirst( 1.3.6.1.2.1.1.2.0@"mason" ) 1 Extracts the first node from the node's SysOID

oidLast

Syntax
oidLast ( oid )
Description
The function takes in input a dot-separted OID string and returns the last node of the sequence.
Input
oid: a dot-separated string.
Output
Returns a string
Errors
Examples
Expression Return string value Description
oidFirst("9.8.7.8.5.4.3.2.1") 1
oidFirst( 1.3.6.1.2.1.1.2.0@"mason" ) 1 Extracts the last node from the node's SysOID

oidString

Syntax
oidString ( string )
Description
The function takes in input a string and returns an OID made with the length of the string as the first item, and the ASCII values as subsequent items. The function throws an error (becomes uncheckable) if the string is not ASCII.
Input
string: an ASCII string.
Output
Returns an OID
Errors
Examples
Expression Return string value
oidString("abc") 3.97.98.99
oidString("FIXME please" ) 12.70.73.88.77.69.32.112.108.101.97.115.101

oidIp

Syntax
oidIp ( string )
Description
The function takes in input a string representing an IPv6 address and returns an OID made with the 16 bytes of the address (16). It can be passed a valid IPv4 address, and it will simply return the same address. The function throws an error (becomes uncheckable) if the argument is not a valid IPv4 or IPv6 address.
Input
string: an ASCII string.
Output
Returns an OID
Errors
Examples
Expression Return string value
oidIp("2a01:4f8:110:3383::1") '42.1.4.248.1.16.51.131.0.0.0.0.0.0.0.1'
oidIp("78.46.45.181") '78.46.45.181'

oidMac

Syntax
oidMac ( string )
Description
The function takes in input a string representing a MAC address and returns an OID made with the 6 bytes of the address. The function throws an error (becomes uncheckable) if the argument is not a recognized MAC address.
MAC Formats supported, all case-insensitive
0001DeadBeeF no separators
00:01:De:ad:Be:eF colons
00-01-De-ad-Be-eF dashes
0:0:De:ad:Be:eF colons with 1 or 2 digits
0001.Dead.BeeF cisco
0001De-adBeeF hp
0001-Dead-BeeF huawei
0.1.222.173.190.239 base256
00 01 De ad Be eF spaces
Input
string: an ASCII string.
Output
Returns an OID
Errors
Examples
Expression Return string value
oidMac("00:01:De:ad:Be:eF") '0.1.222.173.190.239'
oidMac("0001.Dead.BeeF") '0.1.222.173.190.239'

String functions

strpos

Syntax
strpos ( string )
Description
TODO
Input
string: an ASCII string.
Output
Returns an integer value.
Errors
Examples
Expression Return string value

strsub

Syntax
strsub ( string , substring )
Description
TODO
Input
string: an ASCII string.
substring: an ASCII string.
Output
Returns an string.
Errors
Examples
Expression Return string value


strsplit

Syntax
strsplit ( string , separator )
Description
TODO
Input
string: an ASCII string.
separator: an ASCII string.
Output
Returns an vector of string.
Errors
Examples
Expression Return string value

Time functions

time

Syntax
time ( )
Description
Return the time as a floating point number expressed in seconds since the epoch (1970-01-01 00:00:00), in UTC.
Output
Returns a floating point value.
Examples
Expression Return string value
time() 1291971078.92

mtime

Syntax
mtime ( fname )
Description
Performs a stat() system call on the given path fname and returns the time of most recent content modification.
If an error occurrs the function returns 0.
Output
Returns a floating point value.
Examples
Expression Return string value
mtime("/etc/passwd") 1291971078.92
mtime("/etc2/foo") 0

Regular expressions

re_escape

Syntax
re_escape ( str )
Description
Returns a string with all non-alphanumerics backslashed.
This is useful if you want to compose a regular expression from a string that contains regular expression meta-characters (., *, ... ).
Input
str : string
Output
Returns a string.
Examples
Expression Value Description
re_escape("hello") hello nothing to escape
re_escape("192.168.0.1") 192\.168\.0\.1 dots escaped
"192.168.0.1.port1.255.255.255.0" =~ re_escape("192.168.0.1.") + ".*" + re_escape(".255.255.255.0")
 true Try to match the pattern: ip address . any character . ip address
"192.168.0.1.abcdefg.255.255.255.0" =~ re_escape("192.168.0.1.") + "\d" + re_escape(".255.255.255.0")
 false Try to match the pattern: ip address . integer value . ip address

ICMP

isReachable

Syntax
isReachable ( host [ , probesize [ , shorttries [ , keep_rtt_measure [ , timeout [ , do_frag [ , bind_address]]]]]] )
Description
Tests if a remote host identified by host responds to ICMP ECHO requests.
The parameter host can be a string containing a valid IPv4 address or a hostname string. If an hostname is given, it is resolved and the reachability test is performed for every resolved IP until the remote host responds or the test fails.
If the parameters probesize, shorttires and timeout are not specified then the function looks for the corresponding variables $probesize, $shorttries and $timeout inside the current execution context. If they are missing, the test raises an exceptions and the expression evaluation fails.
If the keep_rtt_measure parameter's value is true, the max, min and average RTT values calculated during the test are stored inside a RRD file with name: host.rrd. If the file does not exists, it will be created on the fly. (TODO: link to the file format)
If the do_frag parameter is false, the IP packets are sent with the DF flag set and they are not fragmented.
if bind_address is specified, outgoing IP packets will use bind_address as the source address.
Input
hostname : string
probesize: integer number
shorttries: interger number
keep_rtt_measure: boolean value
timeout: integer number
do_frag: boolean value
bind_address: string
Output
Returns a true or false.
Errors
If the parameter host is not valid or can not be translated into a valid IP(s) the function returns false.
If the value for
Examples
Expression Description
isReachable("mason") Pings host "mason".
isReachable($hostname)
isReachable("mason", 1472)
isReachable("mason", $packetlen)
isReachable("mason", 1472, 3)
isReachable("mason", 1472, $tries)
isReachable("mason", 1472, 3, 1)
isReachable("mason", 1472, 3, False) Disabled keep_rtt_measure.
isReachable("mason", 1472, 3, False, 3) Disabled keep_rtt_measure, 3 seconds of timeout for every ICMP packet.
isReachable("mason", 1472, 3, False, $timeout)
isReachable("mason", 1472, 3, False, $timeout, False) Sends 3 ICMP packets. The ICMP packets' payload is 1472 bytes and the IP packet is not fragmented.
isReachable("mason", 1472, bind_address="127.0.0.1") Tries to ping host 'mason' with source address 127.0.0.1. It will fail.
isReachable("localhost", 1472, bind_address="127.0.0.1") Tries to ping localhost with source address 127.0.0.1. Valid address.

isReachable6

Syntax
isReachable6 ( host [ , probesize [ , shorttries [ , keep_rtt_measure [ , timeout [ , bind_address ]]]]]]]] )
Description
This function perform the same reachability test of the isReachable() function, but uses ICMPv6 instead of ICMPv4.
See the documentation of isReachable() for more details.

icmpPmtu

Syntax
icmpPmtu ( host [ , probesize [ , shorttries [ , timeout]]] )
Description
Checks if the PMTU to a remote host is enough for an IPv4 ICMP ECHO requests with paylod probesize.
The host is pinged with DF bit set, and if it answers the value is true. If it doesn't answer (after shorttries attempts with timeout), host is pinged with DF bit clear, and if it answers the values is false. If it doesn't answer even with DF clear, the value is true. In other words:
  • If the host answers to pings with the specified payload, but the PMTU doesn't allow them through, the value is false
  • If the host is alive but doesn't anser to pings with the specified paylod, whatever DF bit we use, the value is true (i.e., it is not a PMTU problem)
  • If the host is dead, the value is true (again, it is not a PMTU problem)
If the host has multiple IPv4 addresses, each of them is tried with DF bit set, and at the first answer the value is true. Then each of them is tried with DF clear, and at the first answer the value is false. If there is no answer at all, the value is true.


packetLoss

Syntax
packetLoss ( host [ , probesize [ , shorttries [ , keep_rtt_measure [ , timeout [ , do_frag]]]]] )
Description
Calculates the percentage of packet loss for the given host.
The functions accepts the same parameters (with the same semantics) used for isReachable().
Input
hostname : string
probesize: integer number
shorttries: interger number
keep_rtt_measure: boolean value
timeout: integer number
do_frag: boolean value
Output
Returns packet loss percentage between 0 and 1.
Errors
If the parameter host is not valid or can not be translated into a valid IP(s) the function returns false.
If the value for
Examples
Expression Description
packetLoss("mason") 0.33~
isReachable("www.google.com", 1472) 0.0

TCP

isTcpOpen

Syntax
isTcpOpen ( host , port )
Description
Verifies if a TCP connection can be established with the remote peer host:port.
The parameter host can be a valid IPv4 addresso or a hostname. If a hostname is given, it is resolved and the test tries the first IP returned.
The functions returns false the address resolution fails of if the TCP connection can not be established before a 10 seconds timeout.
Input
host: hostname or IP address.
port: port number
Output
Returns a boolean
Errors
Examples
Expression Return value Description
isTcpOpen("www.google.com", 80) true
isTcpOpen("thisisnotavalidhostname", 80) false


UDP

isUdpOpen

Syntax
isUdpOpen ( host , port [ , options ] )
Description
Verifies if a UDP port is open on the remote host.
Input
host: hostname or IP address.
port: port number
timeout : Optional. set the maximum response timeout. (Default: 3 seconds)
open_on_timeout : Optional, forces to return True on timeout. (Default: True)
Output
Returns a boolean
Errors
The function returns an uncheckable value when any unmanaged network error occurs.
Examples
Expression Return value Description
isUdpOpen("mydns", 53, timeout=10) True Received 12 bytes.,udpOpen($node, 53, timeout=3) expands to True
isUdpOpen("mydns", 666,) False Connection refused. UDP port 666 closed,udpOpen($node, 666, timeout=3) expands to False
isUdpOpen("ns2.google.com", 666, open_on_timeout=True) True Connection timeout. Port 666 filtered?,udpOpen("ns2.google.com", 666, timeout=3, open_on_timeout=True) expands to True

SNMP Utils

dateandtime2timestamp

Syntax
dateandtime2timestamp ( dateandtime value )
Description
The function converts the input value (type DateAndTime) in input to local time timestamp.
Input
arg : byte array storing a DateAndTime value.
Output
Returns a local timestamp in seconds since the epoch
Errors
Exception is raised on malformed input value.
Examples
Expression Return value Description
dateandtime2timestamp( 1.3.6.1.2.1.25.1.2.0@ ) 1339421021.0 1339421021 is the local timestamp for 2012-06-11 15:23:41+02:00

SNMP Basic

byBinaryValue

Syntax
byBinaryValue ( snmpexpr , str hex )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The 'binary value of every entry in the mib is compared with the hexadecimal string stored in the parameter str hex and the first matching sub-OID is returned.
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
str hex : A string containing a valid hexadecimal string.
Output
Returns a string OID.
Errors
The function raises an exception when the matching sub-OID is not found.
Examples
Expression Return value Description
byBinaryValue(1.3.6.1.2.1.2.2.1.6@, "fefd00000000") 2 It returns the ifPhysAddress sub-oid of the interface with MAC address "fefd00000000".

byRegexpUnique

Syntax
byRegexpUnique ( snmpexpr , str_regexpr )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The value of every entry in the mib is compared with the regular expression stored in the parameter str_regexpr and the first matching sub-OID is returned.
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
snmpexpr : A string containing a valid regular expression.
Output
Returns a string OID.
Errors
The function raises an exception when the matching sub-OID is not found.
Examples
Expression Return value Description
byRegexpUnique(1.3.6.1.2.1.2.2.1.@, "eth0") 2.4 It returns the ifDescr sub-oid for the interface matching the string "eth0" ( 1.3.6.1.2.1.2.2.1.2.4 = eth0 ).


byMultiRegexpUnique

Syntax
byMultiRegexpUnique ( snmparg , [ suboid1 , regexpr1 ] , [ suboid2 , regexpr2 ] , ... )
Description
Scans the MIB identified by the SNMP expression snmparg and verifies all the sub-oids <suboid1>, <suboid2>, ect. match with the corresponding regular expressions <regexpr1>, <regexpr2>, etc. The instance of the matching table entry is returned.
The second element of each tuple rappresent the matching expression and must be a string of this form:
value type / regular expression
The value type must be b (binary) or s (string).
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
sequence of suboid1, regexpr1 : A string containing a valid regular expression.


Output
Returns a string OID.
Errors
The function raises an exception when the matching sub-OID is not found.
Examples
Expression Return value Description
byMultiRegexpUnique(1.3.6.1.2.1.25.4.2.1@ , "2" , "s/^apache.exe$", "4" , "s/^/bin/apache$" , "5", "s/^foo$" ) 4232 Searches for a process 'apache.exe' in the hrprocess MIB with path '/bin/apache' and called with parameter 'foo'
byMultiRegexpUnique(1.3.6.1.2.1.25.4.2.1@ , "2" , "s/^" + re_escape("c:\apache.exe") + "$") 123 Searches for a process 'c:\apache.exe'.

existsRegexp

Syntax
existsRegexp ( snmpexpr , str_regexpr )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The value of every entry in the mib is compared with the regular expression stored in the parameter str_regexpr. The function returns true if there is a least one matching entry in the MIB.
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
str_regexpr : A valid regular expression.
Output
Returns a string OID.
Errors
Examples
Expression Return value Description
existsRegexp( 1.3.6.1.2.1.2.2.1@, "eth0") 1 Checks if there is an interface called "eth0"

existsRegexpUnique

Syntax
existsRegexpUnique ( snmpexpr , str_regexpr )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The value of every entry in the MIB is compared with the regular expression stored in the parameter str_regexpr. The function returns true if there is only one matching entry in the MIB.
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
str_regexpr : A valid regular expression.
Output
Returns a string OID.
Errors
Examples
Expression Return value Description
existsRegexpUnique( 1.3.6.1.2.1.2.2.1@, "eth0") 1 There is only one "eth0" interface
existsRegexpUnique( 1.3.6.1.2.1.2.2.1@, "^eth") 0 There are too many interfaces with prefix "eth"

byBinaryIP

Syntax
byBinaryIP ( snmpexpr , str_ip )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The string value of every entry is compared with the hexadecimal representation of the IPv4 address str_ip.
Input
snmpexpr : A SNMP expression indentifing a valid MIB.
str_ip : A valid regular expression.
Output
Returns a string OID.
Errors
Examples
Expression Description
existsRegexp( 1.3.6.1.2.1.2.2.1@, "255.255.255.0") Checks if there is an entry in the MIB matching the string FFFFFF00.

getHCInOctets

getHCInOctets([host [, ifindex [, comm [, shorttries]]]])

getHCOutOctets

getHCOutOctets([host [, ifindex [, comm [, shorttries]]]])

walkAverage

Syntax
walkAverage' ( snmp expr )
Description
Calculates the the arithmetic average of the elements of the MIB specified by snmp expr.
Not numreic MIB's elements will be ignored
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkAverage( 1.3.6.1.2.1.2.2.1@"bar" ) 1935680570.0

walkCount

Syntax
walkCount' ( snmp expr )
Description
Returns the number of elements of the MIB specified by snmp expr.
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkCount( 1.3.6.1.2.1.2.2.1@"bar" ) 44.0

walkCountMatch

Syntax
walkCountMatch ( snmpexpr , str_regexpr_oid , str_regexpr_val )
Description
Scans the MIB identified by the SNMP expression snmpexpr. The MIB sub-oid and the value is compared with the regular expressions str_regexpr_oid and str_regexpr_val, matching at the beginning of them. The number of matching entries is returned.
Input
snmpexpr: SNMP Expression identifying the MIB to scan.
str_regexpr_oid: Regular expression string matching the sub-OIDs from the beginning
str_regexpr_val: Regular expression string matching the OIDs' value from the beginning
Output
Returns the number of matching entries
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkCountMatch( 1.2.3.4.5@ , '^' + re_escape('6.7.8') + '$', '^5$') 44.0
walkCountMatch( 1.2.3.4.5@ , '.*' + re_escape('7.8') + '$', '^5$') 44.0

walkMax

Syntax
walkMax' ( snmp expr )
Description
Returns the maximum numeric value found inside the specified MIB.
Not numreic MIB's elements will be ignored
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkMax( 1.3.6.1.2.1.2.2.1@"bar" ) 1935680570.0

walkMaxPos

Syntax
walkMaxPos' ( snmp expr )
Description
Returns the maximum positive numeric' value found inside the specified MIB.
Not numreic MIB's elements will be ignored
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkMaxPos( 1.3.6.1.2.1.2.2.1@"bar" ) 1935680570.0

walkMin

Syntax
walkMin' ( snmp expr )
Description
Returns the minimum numeric value found inside the specified MIB.
Not numreic MIB's elements will be ignored
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkMin( 1.3.6.1.2.1.2.2.1@"bar" ) 1935680570.0

walkMinPos

Syntax
walkMinPos' ( snmp expr )
Description
Returns the maximum numeric' positive value found inside the specified MIB.
Not numreic MIB's elements will be ignored
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkMaxPos( 1.3.6.1.2.1.2.2.1@"bar" ) 1935680570.0

walkSum

Syntax
walkSum ( snmp expr )
Description
Sums together all the elements of the MIB specified by snmp expr.
MIB's element not suitable for arithmetic addition are ignored.
Input
snmp expression: A SNMP expression
Output
Returns a integer
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression Return Value
walkSum( 1.3.6.1.2.1.2.2.1:"public"@"foo" ) 5294132713.0

walkDiff

Syntax
walkDiff ( snmp expr [ , threshold [ , verbose_info [ , ignore_create [ , ignore_destroy ] ] ] ] )
Description
Performs a SNMP Walk on the given snmp expr and compare the returned table content with the content of the same table fetched at the previous check.
Returns true if the content is not changed.
If threshold is specified, the table entries with ( value difference / time elapsed ) <= threshold are considered unchanged.
If verbose_info is set to 1, the function adds verbose informations to the execution text.
If ignore_create is set to 0, the function returns false when new lines are added
If ignore_destroy is set to 0, the function returns false when new lines are added
Examples
Expression Return Value
walkDiff( 1.3.6.1.2.1.2.2@) True

sumall

Syntax
sumall' ( oid , community , hostname [ , hostname ] )
Description
Retrieves the value for the given oid from every hostanme with the given community and sums all the values together.
If some hosts do not export the required MIB or an error occurs, the host is skipped.
Input
oid: String containin the OID.
community: SNMP community
hostname: node hostname
Output
Returns a number
Errors
The function raises an exception if the SNMP MIB identified by snmp expr can not be found.
Examples
Expression value
sumall("1.3.6.1.2.1.1.3.0", "public", "foo","bar") 1531782725

SNMP Advanced

adjacent

Syntax
adjacent ( [ method , method , ... ] )
Description
This function must be used only for targets of interfaces. It verifies if a link exists between the target interface and its linked interface.
The presence of a link is verified by using several methods. Supported methods are:
  • "stp"
  • "cdp"
  • "lldp"
If no methods are specified, the functions tries all the supported methods in this sequence: stp, cdp, lldp.

hrStorageNoFull

Syntax
hrStorageNoFull ( percent_threshold , [ storage_re , percent_threshold[,..]] )
Description
This function takes one mandatory argument, and optional argument pairs. When invoked with just the mandatory argument, it will check the occupation of all the filesystems of the current node, as seen in the hrstorage table, having size greater then zero and type "Fixed disk" (1.3.6.1.2.1.25.2.1.4) or "Network disk" (.1.3.6.1.2.1.25.2.1.10), against the percent_threshold. If all such filesystems are below thresholds, it will return 1, otherwise it will return 0.
Optional argument pairs of the form storage_re, percent_threshold specify a different threshold for specific filesystems. When the hrStorageDescr 1.3.6.1.2.1.25.2.3.1.3 of the filesystem matches the provided storage_re, its occupation will be checked against the percent_threshold specified next to it, instead of the first argument. You can specify 100 as a threshold to actually disable checking some filesystems.
If one of the specified filesystems regexp is not found, the function skips it without error. If no filesystems are found, or the node doesn't answer to SNMP, the function becomes uncheckable. If the node has only entries of type different from "Fixed disk" and "Network disk" in the hrStorageTable, the function returns true.

ifIndex2stp

Syntax
ifIndex2stp ( host , ifindex [ , community [, sv ] ] )

TODO

isEtherFd

Syntax
isEtherFd ( ifindex )
Description
The function tries to verify if the interface with the given ifindex is in ethernet Full-duplex mode.
The function looks inside the execution context for the following informations:
  • $node: the hostname of the remote host
  • $community: the SNMP community to use
  • $snmpversion: SNMP version to use
  • $snmpport: SNMP port to use
  • $shorttries: number of SNMP tries
Input
ifindex: integer value.
Output
Returns a boolean
Errors
The function raises an exception if it can not retrieve enough informations about the interface.
Examples
Expression Return value Description
isEtherFd( 1 ) true
isEtherFd( $myIfindex ) true
isEtherFd( 1.3.6.1.2.1.2.2.1.1.1@ ) false Retrieve the ifindex stored in the mib of the current node (1.3.6.1.2.1.2.2.1.1.1@)

ciscoSensorThresholdsOk

Syntax
ciscoSensorThresholdsOk ( ignore_when_notification_disabled=True , ignore_names_re='' , ignore_instances='' )
Description
The function checks the sensor thresholds in the CISCO-ENTITY-SENSOR-MIB and returns True if all valid readings are in threshold, False otherwise. When returning False, it will write in the context a description of the thresholds violated. This is intended for Cisco devices where the MIB is implemented, like most chassis switches.
The function will skip sensors having instance among those given in the optional parameter ignore_instances as a space-separated list. Instances are usually suboids with two components, e.g. "1042.2".
The function will also skip sensors having a name matching the regular expression given in the optional parameter ignore_names_re.
The parameter ignore_when_notification_disabled defaults to True and instructs the function to ignore thresholds for which notification (1.3.6.1.4.1.9.9.91.1.2.1.1.6) is set to false (2). If you set it to False, the function will consider also such thresholds, returning false also for threshold which are probably irrelevant.
The algorithm followed is explained in the cisco MIB, and is roughly as follows: 
if (entSensorStatus == ok) then
 if (evaluate(entSensorValue, entSensorThresholdRelation, entSensorThresholdValue)) then
  if (entSensorThresholdNotificationEnable == true)) then
   return False
  endif
 endif
endif
return true
The function will evaluate all thresholds (thus it will retrieve a lot of SNMP variables), even when finding a violation, so it will report all the violations found and the number of thresholds checked.
Input
ignore_when_notification_disabled: optional integer value.
Output
Returns a boolean
Errors
The function raises an exception if it can not retrieve enough informations to evaluate the thresholds, or if the threshold table in the CISCO-ENTITY-SENSOR-MIB is not found.

ciscoNoErrDisabled

Syntax
ciscoNoErrDisabled()
Description
The function checks the cErrDisableIfStatusTable (1.3.6.1.4.1.9.9.548.1.3.1) in the CISCO-ERR-DISABLE-MIB, and returns 1 (true) if the table i sempty, i.e. there are no errdisabled ports. If there are errdisabled ports the function returns 0 (false) and writes in the context a description of the relevant interfaces and their errdisable reason.

vtpCommunity

Syntax
vtpCommunity ( host , comm , ifindex )

TODO

Cluster management

isAssociated

Syntax
isAssociated ( )
Description
TODO

clusterNode

Syntax
clusterNode ( )
Description
TODO

clusterCommunity

Syntax
clusterNode ( )
Description
TODO

clusterInstance

Syntax
clusterInstance ( )
Description
TODO

HTTP

urlContentDoesntMatch

urlContentDoesntMatch ( url , regexpr [ , case_insensitive_flag [, optional params ] ] )
Description
Verifies if content of the given url does not match the regular expression regexpr_str.
See the function urlContentMatches() for more details.

urlContentMatches

Syntax
urlContentMatches ( url , regexpr [ , case_insensitive_flag [, optional params ] ] )
Description
Verifies if content of the given url matches the regular expression regexpr_str.
The parameter case_insensitive_flag is used to switch to case insensitive mode.
The parameter regexpr_str can be enclosed between "/" characters (eg. "/foo/"). In this case the case insensitive test can be enabled by appending a "i" at the end of the expression. (eg: "/foo/i").
The "i" character modifier has precedence on the case_insensitive parameter.
The timeout parameter is an optional parameter and is used to set the maximum connection timeout in seconds (default: 20 seconds).
Use HTTP Basic Authentication
In order to use a HTTP basic authentication, the following optional parameters must be defined:
Variable Description
basic_user Username
basic_password password
This parameters can be passed to the function as context variables too ( $basic_user, $basic_password ).
Use a proxy
In order to use a HTTP proxy, the following optional parameters must be defined:
Variable Description
proxy_server Proxy's hostname
proxy_port Proxy's port
proxy_realm Proxy's realm (Can be )
proxy_user Username
proxy_password Password
proxy_ntlm NTLM support flag. Set to 1 to enable NTLM authentication
proxy_protocol "http" (default) or "https"
Other parameters
Variable Description
include_data Boolean. When True, the retrieved data will be inserted in the verbstatus. Default is False.


This parameters can be passed to the function as context variables too ( $basic_user, $basic_password ).


Use local Proxy and HTTP Basic Authentication on remote server
You can use Proxy support and basic authentication at the same time. Remember that proxy authentication is performed first.
Use local Proxy with NTLM Authentication
IMPORTANT: this feature is enabled only if NTLM python modules are installed.
If proxy_ntlm is set to 1, NTLM Proxy Authentication is used instead of HTTP Proxy Authentication.
proxy_realm is used used as the DOMAIN name. The real user used for the authentication is:
<domain>\<user>
Es: 
 proxy_user = "foo"     \___ Real user name:  DOMAIN\foo 

 proxy_realm = "DOMAIN" /







Input



 url: The URL.

 regexpr: regualar expression.

 case_insensitive_flag:  When "i" enables case-insensitive test.





Output



 Returns a boolean





Errors



 An exception is raised if a network timeout (20 seconds) is reached. 





Examples






 Expression  Return Value




 urlContentMatches("http://www.google.com", "google")  true




 urlContentMatches("http://www.google.com", "GOOGLE")  false




 urlContentMatches("http://www.google.com", "GOOGLE", "i")  true




 urlContentMatches("http://www.google.com", "/GOOGLE/i")  true




 urlContentMatches("http://www.google.com", "/GOOGLE/i", basic_user="foo", basic_password="12345abc")  true (with HTTP Basic Authentication)





 NTP


 isNtpOk


Syntax



 isNtpOk ( hostname )





Description



 Checks if the host hostname is a valid NTP server.

 The functions performs a NTP request and checks the NTP response. It verifies if:

  •  The server's clock is syncronized

  •  THe server is among the secondary NTP servers (server stratum between 1 and 15).







Input



 hostname: the string containing the hostname of the remote server.





Output



 Returns a true or false.





Errors



 If the hostname does not respond before a 3 seconds timeout, the function returns false.





Examples






 Expression
 Return value




 isNtpOk("mason")
 true




 isNtpOk("google.com")
 false



 Windows


 wmic


 Syntax



 wmic ( getCurrent , class , member [, key_name [, key_val [, domain [, user [, password [, timeout [, node ]]]]]]]] )





Description



 This functions uses the Microsoft Windows's WMI sub-system in order to retrieve system informations about the target node.





 Parameters getCurrent, win32class, member are mandatory. The other parameters are optional, but if these values are not specified, the functions searches inside the execution context for the corresponding $parameter symbol. See the following table:








 Parameter  Variabile execution context




 key_name  $key_name




 key_val   $key_val




 node  $node




 domain  $domain




 user  $user




 password  $password




 timeout  $timeout



Input



 getCurrent: When True gets the value from the network. When False, returns the value from the last call.

 class   : The WMI class

 member  : The member of the WMI class	





 key_name: The value's ID key when the member parameter returns multiple tuples of <key, values>.

 key_val : The value for the value 's ID key.

 domain  : The WINS DOMAIN name

 user    : The user used for authentication

 password: The WINS DOMAIN name

 timeout : Maximum timeout for DNS resolution.

 node    : The target host. 





Output



 Returns a string with the value of the given class member.





Errors



 TODO





Examples



 TODO





Reference







 External


 exec


 Syntax



 exec ( current , scriptname , [ param [ , ... ] )





Description



 The function executes the external script scriptname with the given param(s) param and returns the content of the standard output produced by the script.





 When the current parameter is true, the script is executed with the given parameters. If current is false, the function returns the standard output produced by the script at the previous check of the related target.





 The script must be located in the $SANET_HOME/exec directory.





Input



 current: boolean. 

 name: string containing the script name.

 param(s): strings containt the script's param(s)





Output



 Returns a string





Errors



Examples






 Expression
 Return value
 Description




 exec(True, "mydate.sh")
 ven nov 26 16:41:30 CET 2010
 the script mydate.sh is: 

#!/bin/bash
date




 exec(0, "mydate.sh")
 ven nov 25 16:41:30 CET 2010
 Returns the output of the last execution



 Others


 isUp


 Syntax



 isUp ( path [ , un_as_down  ] )





Description



 The function returns true if the status (on DB) of the given target path is UP. 





 Returns false if the target's status is DOWN or FAILING.





 If the current target status is UNCHECKABLE or SUSPENDED the function raises an exception and the expression evaluation fails. If the optional parameter un_as_down is True, an UNCHECKABLE or SUSPENDED states are treated as DOWN.





Input



 path: string containing the target's path.

 un_as_down: boolean flag to 





Output



 Returns a boolean.





Errors



 Raises an exceptions if the specified path does not identify a valid target.





Examples






 Expression
 Return value
 Description




 isUp("mason:::reach")
 true





 isUp("foo:bar:hello:world")
 -
 EXCEPTION



 read4Vision


 Syntax



 read4Vision ( var=var )





Description



 The function reads a variable from a 4Vision domotic system, by querying a daemon that connects to the supervisor via TCP.





 The daemon must be configured in $SANET_HOME/settings.py and currently only one daemon instance, and only one domotic system supervisor, is supported. The daemon is configured like this:





import lib.fourvision
MORE_CHILDREN['fourvision'] = {
 'action': lib.fourvision.connect,
 'actionargs': {
  'udp_port': 1234,
  'server_host': 'mycontroller',
  'server_port': 7200,
  'server_password': 'passw0rd',
  'logfile': VAR_DIR + '/poller_log',
 },
}



Input



 var: name of the 4Vision variable to read





Output



 Returns a string, which can usually be converted to a number.





Errors



 Raises an exceptions if an error occurs and/or the variable cannto be read.





Examples






 Expression
 Return value
 Description




 read4Vision("0/0/1")
 0




 readFile


 Syntax



 readFile ( path )





Description



 The function returns the content of the given file.





Input



 path: string containing the file absolute path





Output



 Returns a string.





Errors



 Raises an exceptions if an error occurs while opening/reading the file





Examples






 Expression
 Return value
 Description




 readFile("/etc/hosts")
 127.0.0.1 localhost





 readFile("/tmp/nonexistent")
 -
 EXCEPTION



 redis


 Syntax



 redis ( path [, host=host][, port=port][, db=db] )





Description



 The function returns the content of the given redis key. The default redis store is db 0 on port 6379 at localhost.





Output



 Returns a string. If you know it is a number and you want to use it as such (e.g. doing arithmetic on it), convert it with int().





Errors



 Raises an exceptions if an the key does not exist or if the redis server cannot be accessed.





Examples






 Expression
 Return value
 Description




 redis("myspamcount")
 1387123




 Diagnostic functions


 pollerinfo


 Syntax



 pollerinfo ( variable_id )





Description



 The functions returns diagnostic informations about the Poller daemon. The parameter variable_id specifies the desired information. Possibile input values are:








 Id  Description




 queuesize  The function returns the number of ready basechecks queued for execution




 commitqueuesize  The function returns the number of executed basechecks waiting for commit on DB.



Input



 id: string





Output



 The output value depends on the input parameter.





Errors



Examples






 Expression
 Description




 pollerinfo("queuesize")
 10.0




 pollerinfo("commitqueuesize")
 0.0




 pollerinfo( $diagnostic_cmd )
 depends on the value of $diagnostic_cmd



 Database functions


 psql_query


 Syntax



 psql_query ( dbname , query [ , host ] [, port ] [, user] [, password]  [, timeout] )





Description



 Connect to the database dbname and executes the given query and returns the first row of the  recordset.





Input



 dbname: string

 query: string

 host: string

 port: number

 user: string 

 password: string

 timeout: the maximum timeout on connnect





Output



 tuple (a row in a record set)





Errors



 An exception is raised on connect timout or when the query returns an error.





Examples






 Expression
 Description




 psql_query("mydb", "SELECT * FROM table1")
 Connect to localhost and returns the first row of the queryset.




 psql_query("mydb", "SELECT * FROM table1")[0]
 Returns the first column value of the first row of the queryset.




 psql_query("mydb", "SELECT * FROM table1", user="foo", password="bar")[0]
 Returns the first column value of the first row of the queryset.





 RRD functions


 measureAvgInInterval


 Syntax



 measureAvgInInterval ( path, interval [, ds_index ] )





Description



 Loads RRD data stored inside the measure file identified by path in the last interval seconds.

 Returne the average of the loaded values.

 If ds_index is specified, the function loads the value for the DS number ds_index.





Input



 path: string

 interval: number

 ds_index: number





Output



 number





Errors



Examples






 Expression
 Description




 measureAvgInInterval( $path, 180)
 xxxx




 measureAvgInInterval( "foo::server-linxu:cpu-graph" , 180)
 xxxx





 pktLossAvgInInterval


 Syntax



 pktLossAvgInInterval ( interval [, discard_number [, discard_threshold ] ] )





Description



 The function returns the packet loss average in the last interval seconds for the current node.

 The packet loss statistics are loaded from the RRD file created for the current node by the reachability test function (see isReachable() ).





Input



 interval: number

 discard_number: number

 discard_threshold: number





Output



 Packet loss average value between 0.0 and 1.0.





Errors



Examples






 Expression
 Description




 pktLossAvgInInterval(180)
 Packet loss average in the last 180 seconds.










Retrieved from "https://sanet.labs.it/wiki/index.php/Expression_language_reference"

				
								
								
												

			

			
		

		
		
		

			



	
Personal tools

	




			

				



	
Namespaces

	








	
Variants

	

		
    
					

	





			

			

				








	
Actions

	

		
    
					

	










			

		

		
		
			

				
					
				
				



	
Navigation

	

				
			













	
Toolbox