SNMP Quick Start Guide

Simple statement:

Expression ;

List statement where the final value is the concatenation of both expressions:

Expression 1 Expression 2 ;

Example: 1 + 2 3 + 4

• In C, there needs to be a joining operation between the 2 and the 3 because they are considered two disjointed expressions–which would result in a syntax error.

• In S3, this is seen as two separate expressions next to each other: 1 + 2 and 3 + 4. The result of the statement is 37. The white space does not matter unless it is enclosed in quotes.

An expression is anything that evaluates to a value. This value does not have to be numeric. A piece of text evaluates to itself. An expression might be the number 7, the word Hello, or a complex mathematical formula. Expressions can be chains of symbols and operators as long as the entire expression evaluates to a single value.

• Number

7

• String:

'Hello'

• Complex Formula:

( ( 1 + 2 ) / 12 + 34 ) * 10

• Variable or OID that evaluates to a number or string:

[INDEX]
.1.3.6.1.2.1.1.1.0

• Multiple grouped expressions (enclosed within parentheses) concatenated together:

( 7 'Hello' ( ( 1 + 2 ) / 12 + 34 ) * 10 [INDEX] .1.3.6.1.2.1.1.1.0 )

A variable is a name surrounded by square brackets. Variable names consist of the following characters: a-z, A-Z, 0-9, and - .

[Variable Name]

A variable assignment is an expression. The evaluation of the assignment is the new variable value. A variable assignment uses the = operator.

[Variable name] = Expression

S3 uses the following conventions to differentiate SevOne system variables from user variables. This prevents user variables from overwriting system variables. There is no rule to enforce this.

• SevOne system variables use capital letters and underscores for spaces. [MY_VARIABLE]

• User variables use lowercase letters, a capital letter in the next word, and no underscore for spaces. [myVariable]

S3 can treat and evaluate variables as OIDs. Each variable must be declared before use. There is no special declaration syntax, but a variable must have an assigned value before being used in an expression. Both scalar variables and vector variables are evaluated and inserted raw into the expression.

S3 does nothing special to scalar variables when scalar variables are evaluated.

When a vector variable is evaluated, each of the vector variable's components is written and separated by . . Elements in vector variables are zero-indexed numerically. The first element starts at 0, and the second starts at 1, etc. To access a particular element of a vector variable, surround the element index in curly braces after the variable.

[Variable Name ]{Index number }

A variable cannot be used as an index number. The index number must be an actual number.

Each element in a vector variable is usually a scalar variable. However, there are exceptions when an element in a vector variable is another vector variable.

Some variables should not be evaluated as an OID. Enclose the variable in backticks (`) to prevent the variable from being evaluated as an OID. If a variable simply contains a number, the variable is treated as a normal number if not backticked. However, it is always safe to backtick a variable to prevent improper evaluation. Text evaluates to itself. Text is considered anything enclosed in quotes. Backticks may be in a single quoted string, and that single quote string may be in a backtick quoted string.

• Single quotes (') - Single quotes are used for raw text. The content of the text is not processed in any way, for example, 'Anything here'.

• Backticks (`) - Backticks are used for variable interpolation. Any variables present in the text is evaluated, for example, `Anything here, including variables`.

1 + 2 * 3

(which is 7)

Is not the same as:

( 1 + 2 ) * 3

(which is 9).

Parentheses can change two expressions into one expression.

Example:

( 1 + 2 3 + 4 )

Evaluates to the single value 37, which could be used by further expressions.

Multiplication (Standard multiplication)

Left expression * Right expression

Division (Standard division)

Left expression / Right expression

Addition (Standard addition)

Left expression + Right expression

Subtraction (Standard subtraction)

Left expression - Right expression

Equal to, Boolean == returns 1 if the left and right side are equal.

Left expression == Right expression

Not equal to, Boolean != returns 1 if the left and right side are not equal.

Left expression != Right expression

Less than, Boolean < returns 1 if the left side is less than the right side.

Left expression < Right expression

Less than or equal to, Boolean <= returns 1 if the left side is less than or equal to the right side.

Left expression <= Right expression

Greater than, Boolean > returns 1 if the left side is greater than the right side.

Left expression > Right expression

Greater than or equal to, Boolean >= returns 1 if the left side is greater than or equal to the right side.

Left expression >= Right expression

• Binary

Binary logical operators operate on two expressions.

Logical AND, Boolean && returns 1 if the left and right side evaluate to true. Otherwise, it returns 0.

Left expression && Right expression

Logical OR, Boolean || returns 1 if the left side evaluates to true, the right side evaluates to true, or both evaluate to true. Otherwise, it returns 0.

Left expression || Right expression

Bamboo, ||| is actually a shortcut for a particularly common case of the ?? ternary operator. It returns the value on the left if it is set. Otherwise, it returns the value on the right regardless of its value.

Left expression ||| Right expression

This is equivalent to the following:

Left expression ?? Left expression : Right expression

• Ternary

Ternary logical operators operate on three expressions. S3 has two ternary operators.

Logical ternary operator, ? evaluates the left expression for a test that is greater than 0 (numerically) or for a string that has length and is not 0. Otherwise, it evaluates the right expression. For this reason, the test is usually a logical Boolean expression that returns 0 or 1, guaranteed.

test ? Left expression : Right expression

Existential ternary operator, ?? evaluates the left expression for a test that has a value that is not the empty string. Otherwise, it evaluates the right expression.

test ?? Left expression : Right expression

To count the number of CPUs on a Linux device to determine what the maximum CPU utilization could be: net-snmp returns up to 800% utilization for a box with eight CPUs.

#count OID

Example:

#count .1.3.6.1.2.1.25.3.3.1.2

Can evaluate to 8.

Conversion from OID

OID-to-ASCII-string (with length), $s converts the expression to an ASCII string.

$s Expression

The expression should be an OID with the following format:

n.ASCII 1.ASCII 2.....ASCII n

Example:

$s '5.72.101.108.108.111'

Evaluates to Hello.

OID-to-ASCII-string (no length), $S converts the expression to an ASCII string.

$S Expression

The expression should be an OID with the following format:

ASCII 1.ASCII 2

Example:

$S '72.101.108.108.111'

Evaluates to Hello.

OID-to-numbers (with length), $v converts the expression to a string.

$v Expression

The expression should be an OID with the following format:

n.Number 1.Number 2.....Number n

Example:

$v '4.192.168.0.1'

Evaluates to 192.168.0.1.

OID-to-numbers (no length), $V Identity operation. The value should be the same as the expression.

$V Expression

This converts the expression to a string. The expression should be an OID with the following format:

Number 1.Number 2.

Example:

$V '192.168.0.1'

Evaluates to 192.168.0.1.

Conversion to OID

String-to-OID (with length), #s converts the expression to an OID with the length prefixed. The expression should be ASCII text.

#s Expression

Example:

#s 'Hello'

Evaluates to 5.72.101.108.108.111.

String-to-OID (no length), $s converts the expression to a string with no length information. The expression should be ASCII text.

#S Expression

Example:

#S 'Hello'

Evaluates to 72.101.108.108.111.

Numbers-to-OID (with length), #v converts the expression to an OID with the length prefixed. The expression should be text consisting of numbers separated by the use of . .

#v Expression

Example:

#v '192.168.0.1'

Evaluates to 4.192.168.0.1.

Numbers-to-OID (no length), #V Identity operation. The value should be the same, as the expression converts the expression to an OID with no length information. The expression should be text consisting of numbers separated by the use of . .

#V Expression

Example:

#V '192.168.0.1'

Evaluates to 192.168.0.1.

Grouping

Parameters to the conversion operators should be enclosed in parentheses to avoid confusion.

To get the OID index representation of the text 37 (which is 2.51.55), you can try:

#s 1 + 2 3 + 4

However, the #s only applies to the 1 which yields 1.49. (49 is ASCII for 1). The value of that is added to 2 (1.49 + 2 = 3.49), which is then concatenated with 7 (to yield 3.497). You must use parentheses:

#s ( 1 + 2 3 + 4 )

Evaluates to 2.51.55 (which, as a string, is 37).

1. [bothXandY] = `[x]` && `[y]`;

2. [eitherXorYorBoth] = `[x]` || `[y]`;

3. [eitherXorY] = ( `[x]` && (`[y]` ? 0 : 1) ) || ( `[y]` && (`[x]` ? 0 : 1) );

4. [notX] = `[x]` ? 0 : 1;

The following example selects the value of ifName if it is present. Otherwise, it selects the he value of ifDescr.

[bamboo] = ifName ||| ifDescr;

The following examples demonstrate the use of the ternary operator.

1. [sevenOrEight1] = `[x]` ? 7 : 8;

2. [sevenOrEight2] = `[x]` ? 6 + 1 : 2 * 2 + 4;

#s 'CPU'

The result of this is 3.67.80.85 (includes a length prefix).

#S 'CPU'

The result of this is 67.80.85 (no length prefix).

The following examples convert the specified OID indexes into strings.

$s '3.67.80.85'

The result of this is CPU.

$S '67.80.85'

The result of this is also CPU.

"grpcomm1"."".0.noAuthNoPriv."read"

• String (for example, grpcomm1) - According to the MIB, this is the name of the group for this entry.

• String (for example, "") - According to the MIB, this is the prefix that a name must match to gain access rights.

• Integer (for example, 0) - According to the MIB, this is the security model in use. This roughly corresponds with the SNMP version (where 0 = any).

• Integer (for example, noAuthNoPriv, which is, 1) - According to the MIB, this is the minimum level of security required to gain access rights.

• String (for example, read) - According to the MIB, this is the type of processing to apply the specified view to.

S3 has the following information:

• [INDEX] is 8.103.114.112.99.111.109.109.49.0.0.1.4.114.101.97.100.

• [INDEX]{0} is 8.103.114.112.99.111.109.109.49.

• [INDEX]{1} is 0.

• [INDEX]{2} is 0.

• [INDEX]{3} is 1.

• [INDEX]{4} is 4.114.101.97.100.

Naming

S3 uses the following information to name an object for a VACM entry.

Group group name [ matching prefix ] using {any version|security model } with security level , providing processing

S3, revision 1

The security level is an enumeration. S3 creates a variable with the appropriate textual representation for its value.

Necessary S3:

1. [securityLevel] = ( `[INDEX]{3}` == 1 ? 'noAuthNoPriv' : ( `[INDEX]{3}` == 2

2. ? 'authNoPriv' : ( `[INDEX]{3}` == 3 ? 'authPriv' : '(unknown)' ) ) );

Name:

1. 'Group '( $s `[INDEX]{0}` )( ($s `[INDEX]{1}`) ?? (' matching '($s `[INDEX]{1}`)) : '')

2. 'using'( `[INDEX]{2}` ? `v[INDEX]{2}` : 'any version' )` with [securityLevel], providing`

3. ( $s `[INDEX]{4}` )

Evaluates to:

Group grpcomm1 uses any version with noAuthNoPriv, providing read

S3, revision 2

The first Name S3 is too long and is not very readable. In the second revision, S3 assigns various parts of the name to variables and links the names at the end.

Necessary S3:

1. [groupName] = ( $s `[INDEX]{0}` );

2. [matchText] = ( ($s `[INDEX]{1}`) ?? (' matching '($s `[INDEX]{1}`)) : '' );

3. [versionText] = ( `[INDEX]{2}` ? `v[INDEX]{2}` : 'any version' );

4. [securityLevel] = ( `[INDEX]{3}` == 1 ? 'noAuthNoPriv' : ( `[INDEX]{3}` == 2 ? 'authNoPriv' :

5. ( `[INDEX]{3}` == 3 ? 'authPriv' : '(unknown)' ) ) );

6. [processingText] = ( $s `[INDEX]{4}` );

Name:

`Group [groupName][matchText] using [versionText] with [securityLevel], providing [processingText]`

Evaluates to:

Group grpcomm1 using any version with noAuthNoPriv, providing read

The end result is the same, but the name is easier to read and understand. The difference is that each component S3 is broken up into separate variables. This allows the name to be a single interpolated string.

First Pass

The first pass is an expansion pass. It expands any OID encountered by adding the full index value to the end of it. This is equivalent to having every OID end in .[INDEX]. The result of this pass is saved and no real values should be generated.

Second Pass

The second pass then evaluates (normally) the results of the first pass. If this pass results in a numeric value, then the indicator is presumed to exist. The results of the first pass are stored for use by the poller.

it is important to use standard mathematical expressions (and not the extra S3 operations) to perform indicator expressions. These expressions must conform to normal mathematical rules (for example, you cannot have two expressions next to each other with no joining operator). These expressions may include the following operators:

/ + -

And the following grouping symbols:

( )

To have every interface report, as an indicator, the total number of interfaces on the device (multiplied by 10), the following indicator expression does not work:

ifNumber.0 * 10

ifNumber.0 is expanded with the default index, which in this case could be .2, for example (yielding ifNumber.0.2, which is not the desired outcome):

ifNumber.0.2 * 10

However, the following tricks the system into accepting the OID:

`ifNumber.0` * 10

This yields:

ifNumber.0 * 10

This is the desired outcome.

Summary of the Two-Pass System

1. Pass 1

   1. OIDs are expanded.

   2. Text is unquoted.

2. Pass 2

   1. Pass 1 is evaluated.