RFC 4011
Policy Based Management MIB
Pages: 121
Proposed Standard
Proposed Standard
Part 3 of 4 – Pages 59 to 89
8.3. Utility Library Functions
Utility Library Functions are provided to enable more efficient policy scripts.8.3.1. regexp()
integer regexp(string pattern, string str, integer case [, string &match]) regexp searches 'str' for matches to the regular expression given in `pattern`. regexp uses the POSIX extended regular expressions defined in POSIX 1003.2. If `case` is 0, the search will be case insensitive; otherwise, it will be case sensitive. If a match is found, 1 is returned, otherwise 0 is returned. If the optional argument 'match' is provided and a match is found, 'match' will be replaced with the text of the first substring of 'str' that matches 'pattern'. If no match is found, it will be unchanged.
8.3.2. regexpReplace()
string regexpReplace(string pattern, string replacement, string str, integer case) regexpReplace searches 'str' for matches to the regular expression given in 'pattern', replacing each occurrence of matched text with 'replacement'. regexpReplace uses the POSIX extended regular expressions defined in POSIX 1003.2. If `case` is 0, the search will be case insensitive; otherwise, it will be case sensitive. The modified string is returned (it would be the same as the original string if no matches were found).8.3.3. oidlen()
integer oidlen(string oid) oidlen returns the number of subidentifiers in 'oid'. 'oid' is a string containing an ASCII dotted-decimal representation of an object identifier (e.g., "1.3.6.1.2.1.1.1.0").8.3.4. oidncmp()
integer oidncmp(string oid1, string oid2, integer n) Arguments 'oid1' and 'oid2' are strings containing ASCII dotted-decimal representations of object identifiers (e.g., "1.3.6.1.2.1.1.1.0"). oidcmp compares not more than n subidentifiers of 'oid1' and 'oid2' and returns -1 if 'oid1' is less than 'oid2', 0 if they are equal, and 1 if 'oid1' is greater than 'oid2'.8.3.5. inSubtree()
integer inSubtree(string oid, string prefix) Arguments 'oid' and 'prefix' are strings containing ASCII dotted-decimal representations of object identifiers (e.g., "1.3.6.1.2.1.1.1.0"). inSubtree returns 1 if every subidentifier in 'prefix' equals the corresponding subidentifier in 'oid', otherwise it returns 0. The is equivalent to oidncmp(oid1, prefix, oidlen(prefix))
is provided because this is an idiom and because it avoids
evaluating 'prefix' twice if it is an expression.
8.3.6. subid()
integer subid(string oid, integer n)
subid returns the value of the nth (starting at zero)
subidentifier of 'oid'. 'oid' is a string containing an ASCII
dotted-decimal representation of an object identifier (e.g.,
"1.3.6.1.2.1.1.1.0").
If n specifies a subidentifier beyond the length of 'oid', a
value of -1 is returned.
8.3.7. subidWrite()
integer subidWrite(string oid, integer n, integer subid)
subidWrite sets the value of the nth (starting at zero)
subidentifier of 'oid' to 'subid'. 'oid' is a string
containing an ASCII dotted-decimal representation of an object
identifier (e.g., "1.3.6.1.2.1.1.1.0").
If n specifies a subidentifier beyond the length of 'oid', a
value of -1 is returned. Note that appending subidentifiers
can be accomplished with the string concatenation '+' operator.
If no error occurs, zero is returned.
8.3.8. oidSplice()
string oidSplice(string oid1, integer offset, integer len, string
oid2)
oidSplice returns an OID formed by replacing 'len'
subidentifiers in 'oid1' with all of the subidentifiers from
'oid2', starting at 'offset' in 'oid1' (the first subidentifier
is at offset 0). The OID length will be extended, if
necessary, if 'offset' + 'len' extends beyond the end of
'oid1'. If 'offset' is larger than the length of oid1, then an
RTE will occur.
The resulting OID is returned.
For example:
oidSplice("1.3.6.1.2.1", 5, 1, "7") => "1.3.6.1.2.7"
oidSplice("1.3.6.1.2.1", 4, 2, "7.7") => "1.3.6.1.7.7"
oidSplice("1.3.6.1.2.1", 4, 3, "7.7.7") => "1.3.6.1.7.7.7"
8.3.9. parseIndex()
ParseIndex is provided to make it easy to pull index values from OIDs into variables. var parseIndex(string oid, integer &index, integer type, integer len) parseIndex pulls values from the instance identification portion of 'oid', encoded as per Section 7.7, "Mapping of the INDEX Clause", of the SMIv2 [2]. 'oid' is the OID to be parsed. 'index' describes which subid to begin parsing at. 'index' will be modified to indicate the subid after the last one parsed (even if this points past the last subid). The first subid is index 0. If any error occurs, 'index' will be set to -1 on return. If the input index is less than 0 or refers past the end of the OID, 'index' will be set to -1 on return and the function will return 0. If 'type' is Integer, 'len' will not be consulted. The return value is the integer value of the next subid. If 'type' is String and 'len' is greater than zero, 'len' subids will be parsed. For each subid parsed, the chr() value of the subid will be appended to the returned string. If any subid is greater than 255, 'index' will be set to -1 on return, and an empty string will be returned. If there are fewer than 'len' subids left in 'oid', 'index' will be set to -1 on return, but a string will be returned containing a character for each subid that was left. If 'type' is String and 'len' is zero, the next subid will be parsed to find N, the length of the string. Then, that many subids will be parsed. For each subid parsed, the chr() value of the subid will be appended to the returned string. If any subid is greater than 255, 'index' will be set to -1 on return, and an empty string will be returned. If there are fewer than N subids left in 'oid', 'index' will be set to -1 on return, but a string will be returned containing a character for each subid that was left. If 'type' is String and 'len' is -1, subids will be parsed until the end of 'oid'. For each subid parsed, the chr() value of the subid will be appended to the returned string. If any
subid is greater than 255, 'index' will be set to -1 on return,
and an empty string will be returned.
If 'type' is Oid and 'len' is greater than zero, 'len' subids
will be parsed. For each subid parsed, the decimal-encoded
value of the subid will be appended to the returned string,
with a '.' character appended between each output subid, but
not after the last subid. If there are fewer than 'len' subids
left in 'oid', 'index' will be set to -1 on return, but a
string will be returned containing an encoding for each subid
that was left.
If 'type' is Oid and 'len' is zero, the next subid will be
parsed to find N, the number of subids to parse. For each
subid parsed, the decimal-encoded value of the subid will be
appended to the returned string, with a '.' character appended
between each output subid but not after the last subid. If
there are fewer than N subids left in 'oid', 'index' will be
set to -1 on return, but a string will be returned containing
an encoding for each subid that was left.
If 'type' is Oid and 'len' is -1, subids will be parsed until
the end of 'oid'. For each subid parsed, the decimal-encoded
value of the subid will be appended to the returned string,
with a '.' character appended between each output subid, but
not after the last subid.
For example, to decode the index component of an instance of the
ipForward table:
oid = "ipForwardIfIndex.0.0.0.0.13.0.192.168.1.1";
index = 11;
dest = parseIndex(oid, index, String, 4);
proto = parseIndex(oid, index, Integer, 0);
policy = parseIndex(oid, index, Integer, 0);
nextHop = parseIndex(oid, index, String, 4);
// proto and policy now contain integer values
// dest and nextHop now contain 4 byte IP addresses. Use
// stringToDotted to get them to dotted decimal notation:
// e.g.: stringToDotted(nextHop) => "192.168.1.1"
8.3.10. stringToDotted()
stringToDotted() is provided to encode strings suitable for the index
portion of an OID or to convert the binary encoding of an IP address
to a dotted-decimal encoding.
string stringToDotted(string value)
If 'value' is the zero-length string, the zero-length string is
returned.
The decimal encoding of the first byte of 'value' is appended
to the output string. Then, for each additional byte in
'value', a '.' is appended to the output string, followed by
the decimal encoding of the additional byte.
8.3.11. integer()
integer integer(var input)
integer converts 'input' into an integer by using the rules
specified for ToInteger(), returning the integer-typed results.
8.3.12. string()
string string(var input)
string converts 'input' into a string by using the rules
specified for ToString(), returning the string-typed results.
8.3.13. type()
string type(var variable)
type returns the type of its argument as either the string
'String' or the string 'Integer'.
8.3.14. chr()
string chr(integer char)
Returns a one-character string containing the character
specified by the ASCII code contained in 'char'.
8.3.15. ord()
integer ord(string str)
Returns the ASCII value of the first character of 'str'. This
function complements chr().
8.3.16. substr()
string substr(string &str, integer offset [, integer len, string replacement]) Extracts a substring out of 'str' and returns it. The first octet is at offset 0. If the offset is negative, the returned string starts that far from the end of 'str'. If 'len' is positive, the returned string contains up to 'len' octets, up to the end of the string. If 'len' is omitted, the returned string includes everything to the end of 'str'. If 'len' is negative, abs(len) octets are left off the end of the string. If a substring is specified that is partly outside the string, the part within the string is returned. If the substring is totally outside the string, a zero-length string is produced. If the optional 'replacement' argument is included, 'str' is modified. 'offset' and 'len' act as above to select a range of octets in 'str'. These octets are replaced with octets from 'replacement'. If the replacement string is shorter or longer than the number of octets selected, 'str' will shrink or grow, respectively. If 'replacement' is included, the 'len' argument must also be included. Note that to replace everything from offset to the end of the string, substr() should be called as follows: substr(str, offset, strlen(str) - offset, replacement)8.4. General Functions
The following POSIX standard library functions are provided: strncmp() strncasecmp() strlen() random() sprintf() sscanf()9. International String Library
This library is optional for systems that wish to have support for collating (sorting) and verifying equality of international strings in a manner that will be least surprising to humans. International
strings are encoded in the UTF-8 transformation format described in [14]. This library is registered with the name "pmInternationalStringLibrary". When verifying equality of international strings in the Unicode character set, it is recommended to normalize the strings with the stringprep() function before checking for equality. When attempting to sort international strings in the Unicode character set, normalization should also be performed, but note that the result is highly context dependent and hard to implement correctly. Just ordering by Unicode Codepoint Value is in many cases not what the end user expects. See Unicode technical note 9 for more information about sorting.9.1. stringprep()
integer stringprep(string utf8Input, string &utf8Output) Performs the Stringprep [13] transformation for appropriate comparison of internationalized strings. The transformation is performed on 'utf8Input'; if the transformation finishes without error, the resulting string is written to utf8Output. The stringprep profile used is specified below in Section 9. If it is successful, the function returns 1. If the stringprep transformation encounters an error, 0 is returned, and the utf8Output parameter remains unchanged. For example, to compare UTF8 strings 'one' and 'two': if (stringprep(one, a) && stringprep(two, b)){ if (a == b){ // strings are identical } else { // strings are different } } else { // strings couldn't be transformed for comparison } See Stringprep [13] for more information.9.1.1. Stringprep Profile
The Stringprep specification [13] describes a framework for preparing Unicode text strings in order to increase the likelihood that string input and string comparison work in ways that make sense for typical
users throughout the world. Specifications that specify stringprep
(as this one does) are required to fully specify stringprep's
processing options by documenting a stringprep profile.
This profile defines the following, as required by Stringprep:
- The intended applicability of the profile: internationalized
network management information.
- The character repertoire that is the input and output to
stringprep: Unicode 3.2, as defined in Stringprep [13], Appendix
A.1.
- The mapping tables used: Table B.1 from Stringprep [13].
- Any additional mapping tables specific to the profile: None.
- The Unicode normalization used: Form KC, as described in Stringprep
[13].
- The characters that are prohibited as output: As specified in the
following tables from Stringprep [13]:
Table C.2
Table C.3
Table C.4
Table C.5
Table C.6
Table C.7
Table C.8
Table C.9
- Bidirectional character handling: not performed.
- Any additional characters that are prohibited as output: None.
9.2. utf8Strlen()
integer utf8Strlen(string str)
Returns the number of UTF-8 characters in 'str', which may be
less than the number of octets in 'str' if one or more
characters are multi-byte characters.
9.3. utf8Chr()
string utf8Chr(integer utf8) Returns a one-character string containing the character specified by the UTF-8 code contained in 'utf8'. Although it contains only 1 UTF-8 character, the resulting string may be more than 1 octet in length.9.4. utf8Ord()
integer utf8Ord(string str) Returns the UTF-8 code-point value of the first character of 'str'. Note that the first UTF-8 character in 'str' may be more than 1 octet in length. This function complements chr().9.5. utf8Substr()
string utf8Substr(string &str, integer offset [, integer len, string replacement]) Extracts a substring out of 'str' and returns it, keeping track of UTF-8 character boundaries and using them, instead of octets, as the basis for offset and length calculations. The first character is at offset 0. If offset is negative, the returned string starts that far from the end of 'str'. If 'len' is positive, the returned string contains up to 'len' characters, up to the end of the string. If 'len' is omitted, the returned string includes everything to the end of 'str'. If 'len' is negative, abs(len) characters are left off the end of the string. If you specify a substring that is partly outside the string, the part within the string is returned. If the substring is totally outside the string, a zero-length string is produced. If the optional 'replacement' argument is included, 'str' is modified. 'offset' and 'len' act as above to select a range of characters in 'str'. These characters are replaced with characters from 'replacement'. If the replacement string is shorter or longer than the number of characters selected, 'str' will shrink or grow, respectively. If 'replacement' is included, the 'len' argument must also be included.
Note that to replace everything from offset to the end of the
string, substr() should be called as follows:
substr(str, offset, strlen(str) - offset, replacement)
10. Schedule Table
This table is an adapted form of the policyTimePeriodCondition class
defined in the Policy Core Information Model, RFC 3060 [18]. Some of
the objects describing a schedule are expressed in formats defined in
the iCalendar specification [15].
The policy schedule table allows control over when a valid policy
will be ready, based on the date and time.
A policy's pmPolicySchedule variable refers to a group of one or more
schedules in the schedule table. At any given time, if any of these
schedules are active, the policy will be ready (assuming that it is
enabled and thus valid), and its conditions and actions will be
executed, as appropriate. At times when none of these schedules are
active, the policy will not be ready and will have no effect. A
policy will always be ready if its pmPolicySchedule variable is 0.
If a policy has a non-zero pmPolicySchedule that doesn't refer to a
group that includes an active schedule, then the policy will not be
ready, even if this is due to a misconfiguration of the
pmPolicySchedule object or the pmSchedTable.
A policy that is controlled by a schedule group immediately executes
its policy condition (and conditionally the policyAction) when the
schedule group becomes active, periodically re-executing these
scripts as appropriate until the schedule group becomes inactive
(i.e., all schedules are inactive).
An individual schedule item is active at those times that match all
the variables that define the schedule: pmSchedTimePeriod,
pmSchedMonth, pmSchedDay, pmSchedWeekDay, and pmSchedTimeOfDay. It
is possible to specify multiple values for each schedule item. This
provides a mechanism for defining complex schedules. For example, a
schedule that is active the entire workday each weekday could be
defined.
Months, days, and weekdays are specified by using the objects
pmSchedMonth, pmSchedDay, and pmSchedWeekDay of type BITS. Setting
multiple bits in these objects causes an OR operation. For example,
setting the bits monday(1) and friday(5) in pmSchedWeekDay restricts
the schedule to Mondays and Fridays.
The matched times for pmSchedTimePeriod, pmSchedMonth, pmSchedDay
pmSchedWeekDay, and pmSchedTimeOfDay are ANDed together to determine
the time periods when the schedule will be active; in other words,
the schedule is only active for those times when ALL of these
schedule attributes match. For example, a schedule with an overall
validity range of January 1, 2000, through December 31, 2000; a month
mask that selects March and April; a day-of-the-week mask that
selects Fridays; and a time-of-day range of 0800 through 1600 would
represent the following time periods:
Friday, March 5, 2000, from 0800 through 1600
Friday, March 12, 2000, from 0800 through 1600
Friday, March 19, 2000, from 0800 through 1600
Friday, March 26, 2000, from 0800 through 1600
Friday, April 2, 2000, from 0800 through 1600
Friday, April 9, 2000, from 0800 through 1600
Friday, April 16, 2000, from 0800 through 1600
Friday, April 23, 2000, from 0800 through 1600
Friday, April 30, 2000, from 0800 through 1600
Wildcarding of schedule attributes of type BITS is achieved by
setting all bits to one.
It is possible to define schedules that will never cause a policy to
be activated. For example, one can define a schedule that should be
active on February 31st.
11. Definitions
POLICY-BASED-MANAGEMENT-MIB DEFINITIONS ::= BEGIN
IMPORTS
MODULE-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE,
Counter32, Gauge32, Unsigned32,
mib-2 FROM SNMPv2-SMI
RowStatus, RowPointer, TEXTUAL-CONVENTION,
DateAndTime, StorageType FROM SNMPv2-TC
MODULE-COMPLIANCE, OBJECT-GROUP,
NOTIFICATION-GROUP FROM SNMPv2-CONF
SnmpAdminString FROM SNMP-FRAMEWORK-MIB;
-- Policy-Based Management MIB
pmMib MODULE-IDENTITY
LAST-UPDATED "200502070000Z" -- February 7, 2005
ORGANIZATION "IETF SNMP Configuration Working Group"
CONTACT-INFO
"
Steve Waldbusser
Phone: +1-650-948-6500
Fax: +1-650-745-0671
Email: waldbusser@nextbeacon.com
Jon Saperia (WG Co-chair)
JDS Consulting, Inc.
84 Kettell Plain Road.
Stow MA 01775
USA
Phone: +1-978-461-0249
Fax: +1-617-249-0874
Email: saperia@jdscons.com
Thippanna Hongal
Riverstone Networks, Inc.
5200 Great America Parkway
Santa Clara, CA, 95054
USA
Phone: +1-408-878-6562
Fax: +1-408-878-6501
Email: hongal@riverstonenet.com
David Partain (WG Co-chair)
Postal: Ericsson AB
P.O. Box 1248
SE-581 12 Linkoping
Sweden
Tel: +46 13 28 41 44
E-mail: David.Partain@ericsson.com
Any questions or comments about this document can also be
directed to the working group at snmpconf@snmp.com."
DESCRIPTION
"The MIB module for policy-based configuration of SNMP
infrastructures.
Copyright (C) The Internet Society (2005). This version of
this MIB module is part of RFC 4011; see the RFC itself for
full legal notices."
REVISION "200502070000Z" -- February 7, 2005
DESCRIPTION
"The original version of this MIB, published as RFC4011."
::= { mib-2 124 }
PmUTF8String ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"An octet string containing information typically in
human-readable form.
To facilitate internationalization, this
information is represented by using the ISO/IEC
IS 10646-1 character set, encoded as an octet
string using the UTF-8 transformation format
described in RFC 3629.
As additional code points are added by
amendments to the 10646 standard from time
to time, implementations must be prepared to
encounter any code point from 0x00000000 to
0x10FFFF. Byte sequences that do not
correspond to the valid UTF-8 encoding of a
code point or that are outside this range are
prohibited.
The use of control codes should be avoided.
When it is necessary to represent a newline,
the control code sequence CR LF should be used.
For code points not directly supported by user
interface hardware or software, an alternative
means of entry and display, such as hexadecimal,
may be provided.
For information encoded in 7-bit US-ASCII,
the UTF-8 encoding is identical to the
US-ASCII encoding.
UTF-8 may require multiple bytes to represent a
single character/code point; thus, the length
of this object in octets may be different from
the number of characters encoded. Similarly,
size constraints refer to the number of encoded
octets, not the number of characters represented
by an encoding.
Note that when this TC is used for an object
used or envisioned to be used as an index, then
a SIZE restriction MUST be specified so that the
number of sub-identifiers for any object instance
does not exceed the limit of 128, as defined by
RFC 3416.
Note that the size of PmUTF8String object is
measured in octets, not characters."
SYNTAX OCTET STRING (SIZE (0..65535))
-- The policy table
pmPolicyTable OBJECT-TYPE
SYNTAX SEQUENCE OF PmPolicyEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The policy table. A policy is a pairing of a
policyCondition and a policyAction that is used to apply the
action to a selected set of elements."
::= { pmMib 1 }
pmPolicyEntry OBJECT-TYPE
SYNTAX PmPolicyEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry in the policy table representing one policy."
INDEX { pmPolicyAdminGroup, pmPolicyIndex }
::= { pmPolicyTable 1 }
PmPolicyEntry ::= SEQUENCE {
pmPolicyAdminGroup PmUTF8String,
pmPolicyIndex Unsigned32,
pmPolicyPrecedenceGroup PmUTF8String,
pmPolicyPrecedence Unsigned32,
pmPolicySchedule Unsigned32,
pmPolicyElementTypeFilter PmUTF8String,
pmPolicyConditionScriptIndex Unsigned32,
pmPolicyActionScriptIndex Unsigned32,
pmPolicyParameters OCTET STRING,
pmPolicyConditionMaxLatency Unsigned32,
pmPolicyActionMaxLatency Unsigned32,
pmPolicyMaxIterations Unsigned32,
pmPolicyDescription PmUTF8String,
pmPolicyMatches Gauge32,
pmPolicyAbnormalTerminations Gauge32,
pmPolicyExecutionErrors Counter32,
pmPolicyDebugging INTEGER,
pmPolicyAdminStatus INTEGER,
pmPolicyStorageType StorageType,
pmPolicyRowStatus RowStatus
}
pmPolicyAdminGroup OBJECT-TYPE
SYNTAX PmUTF8String (SIZE(0..32))
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An administratively assigned string that can be used to group
policies for convenience, for readability, or to simplify
configuration of access control.
The value of this string does not affect policy processing in
any way. If grouping is not desired or necessary, this object
may be set to a zero-length string."
::= { pmPolicyEntry 1 }
pmPolicyIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A unique index for this policy entry, unique among all
policies regardless of administrative group."
::= { pmPolicyEntry 2 }
pmPolicyPrecedenceGroup OBJECT-TYPE
SYNTAX PmUTF8String (SIZE (0..32))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"An administratively assigned string that is used to group
policies. For each element, only one policy in the same
precedence group may be active on that element. If multiple
policies would be active on an element (because their
conditions return non-zero), the execution environment will
only allow the policy with the highest value of
pmPolicyPrecedence to be active.
All values of this object must have been successfully
transformed by Stringprep RFC 3454. Management stations
must perform this translation and must only set this object to
string values that have been transformed."
::= { pmPolicyEntry 3 }
pmPolicyPrecedence OBJECT-TYPE
SYNTAX Unsigned32 (0..65535)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"If, while checking to see which policy conditions match an
element, 2 or more ready policies in the same precedence group
match the same element, the pmPolicyPrecedence object provides
the rule to arbitrate which single policy will be active on
'this element'. Of policies in the same precedence group, only
the ready and matching policy with the highest precedence
value (e.g., 2 is higher than 1) will have its policy action
periodically executed on 'this element'.
When a policy is active on an element but the condition ceases
to match the element, its action (if currently running) will
be allowed to finish and then the condition-matching ready
policy with the next-highest precedence will immediately
become active (and have its action run immediately). If the
condition of a higher-precedence ready policy suddenly begins
matching an element, the previously-active policy's action (if
currently running) will be allowed to finish and then the
higher precedence policy will immediately become active. Its
action will run immediately, and any lower-precedence matching
policy will not be active anymore.
In the case where multiple ready policies share the highest
value, it is an implementation-dependent matter as to which
single policy action will be chosen.
Note that if it is necessary to take certain actions after a
policy is no longer active on an element, these actions should
be included in a lower-precedence policy that is in the same
precedence group."
::= { pmPolicyEntry 4 }
pmPolicySchedule OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This policy will be ready if any of the associated schedule
entries are active.
If the value of this object is 0, this policy is always
ready.
If the value of this object is non-zero but doesn't
refer to a schedule group that includes an active schedule,
then the policy will not be ready, even if this is due to a
misconfiguration of this object or the pmSchedTable."
::= { pmPolicyEntry 5 }
pmPolicyElementTypeFilter OBJECT-TYPE
SYNTAX PmUTF8String (SIZE (0..128))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object specifies the element types for which this policy
can be executed.
The format of this object will be a sequence of
pmElementTypeRegOIDPrefix values, encoded in the following
BNF form:
elementTypeFilter: oid [ ';' oid ]*
oid: subid [ '.' subid ]*
subid: '0' | decimal_constant
For example, to register for the policy to be run on all
interface elements, the 'ifEntry' element type will be
registered as '1.3.6.1.2.1.2.2.1'.
If a value is included that does not represent a registered
pmElementTypeRegOIDPrefix, then that value will be ignored."
::= { pmPolicyEntry 6 }
pmPolicyConditionScriptIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A pointer to the row or rows in the pmPolicyCodeTable that
contain the condition code for this policy. When a policy
entry is created, a pmPolicyCodeIndex value unused by this
policy's adminGroup will be assigned to this object.
A policy condition is one or more PolicyScript statements
that result(s) in a boolean value that represents whether
an element is a member of a set of elements upon which an
action is to be performed. If a policy is ready and the
condition returns true for an element of a proper element
type, and if no higher-precedence policy should be active,
then the policy is active on that element.
Condition evaluation stops immediately when any run-time
exception is detected, and the policyAction is not executed.
The policyCondition is evaluated for various elements. Any
element for which the policyCondition returns any nonzero value
will match the condition and will have the associated
policyAction executed on that element unless a
higher-precedence policy in the same precedence group also
matches 'this element'.
If the condition object is empty (contains no code) or
otherwise does not return a value, the element will not be
matched.
When this condition is executed, if SNMP requests are made to
the local system and secModel/secName/secLevel aren't
specified, access to objects is under the security
credentials of the requester who most recently modified the
associated pmPolicyAdminStatus object. If SNMP requests are
made in which secModel/secName/secLevel are specified, then
the specified credentials are retrieved from the local
configuration datastore only if VACM is configured to
allow access to the requester who most recently modified the
associated pmPolicyAdminStatus object. See the Security
Considerations section for more information."
::= { pmPolicyEntry 7 }
pmPolicyActionScriptIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A pointer to the row or rows in the pmPolicyCodeTable that
contain the action code for this policy. When a policy entry
is created, a pmPolicyCodeIndex value unused by this policy's
adminGroup will be assigned to this object.
A PolicyAction is an operation performed on a
set of elements for which the policy is active.
Action evaluation stops immediately when any run-time
exception is detected.
When this condition is executed, if SNMP requests are made to
the local system and secModel/secName/secLevel aren't
specified, access to objects is under the security
credentials of the requester who most recently modified the
associated pmPolicyAdminStatus object. If SNMP requests are
made in which secModel/secName/secLevel are specified, then
the specified credentials are retrieved from the local
configuration datastore only if VACM is configured to
allow access to the requester who most recently modified the
associated pmPolicyAdminStatus object. See the Security
Considerations section for more information."
::= { pmPolicyEntry 8 }
pmPolicyParameters OBJECT-TYPE
SYNTAX OCTET STRING (SIZE (0..65535))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"From time to time, policy scripts may seek one or more
parameters (e.g., site-specific constants). These parameters
may be installed with the script in this object and are
accessible to the script via the getParameters() function. If
it is necessary for multiple parameters to be passed to the
script, the script can choose whatever encoding/delimiting
mechanism is most appropriate."
::= { pmPolicyEntry 9 }
pmPolicyConditionMaxLatency OBJECT-TYPE
SYNTAX Unsigned32 (0..2147483647)
UNITS "milliseconds"
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"Every element under the control of this agent is
re-checked periodically to see whether it is under control
of this policy by re-running the condition for this policy.
This object lets the manager control the maximum amount of
time that may pass before an element is re-checked.
In other words, in any given interval of this duration, all
elements must be re-checked. Note that how the policy agent
schedules the checking of various elements within this
interval is an implementation-dependent matter.
Implementations may wish to re-run a condition more
quickly if they note a change to the role strings for an
element."
::= { pmPolicyEntry 10 }
pmPolicyActionMaxLatency OBJECT-TYPE
SYNTAX Unsigned32 (0..2147483647)
UNITS "milliseconds"
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"Every element that matches this policy's condition and is
therefore under control of this policy will have this policy's
action executed periodically to ensure that the element
remains in the state dictated by the policy.
This object lets the manager control the maximum amount of
time that may pass before an element has the action run on
it.
In other words, in any given interval of this duration, all
elements under control of this policy must have the action run
on them. Note that how the policy agent schedules the policy
action on various elements within this interval is an
implementation-dependent matter."
::= { pmPolicyEntry 11 }
pmPolicyMaxIterations OBJECT-TYPE
SYNTAX Unsigned32
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"If a condition or action script iterates in loops too many
times in one invocation, the execution environment may
consider it in an infinite loop or otherwise not acting
as intended and may be terminated by the execution
environment. The execution environment will count the
cumulative number of times all 'for' or 'while' loops iterated
and will apply a threshold to determine when to terminate the
script. What threshold the execution environment uses is an
implementation-dependent manner, but the value of
this object SHOULD be the basis for choosing the threshold for
each script. The value of this object represents a
policy-specific threshold and can be tuned for policies of
varying workloads. If this value is zero, no
threshold will be enforced except for any
implementation-dependent maximum. Regardless of this value,
the agent is allowed to terminate any script invocation that
exceeds a local CPU or memory limitation.
Note that the condition and action invocations are tracked
separately."
::= { pmPolicyEntry 12 }
pmPolicyDescription OBJECT-TYPE
SYNTAX PmUTF8String
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"A description of this rule and its significance, typically
provided by a human."
::= { pmPolicyEntry 13 }
pmPolicyMatches OBJECT-TYPE
SYNTAX Gauge32
UNITS "elements"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The number of elements that, in their most recent execution
of the associated condition, were matched by the condition."
::= { pmPolicyEntry 14 }
pmPolicyAbnormalTerminations OBJECT-TYPE
SYNTAX Gauge32
UNITS "elements"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The number of elements that, in their most recent execution
of the associated condition or action, have experienced a
run-time exception and terminated abnormally. Note that if a
policy was experiencing a run-time exception while processing
a particular element but runs normally on a subsequent
invocation, this number can decline."
::= { pmPolicyEntry 15 }
pmPolicyExecutionErrors OBJECT-TYPE
SYNTAX Counter32
UNITS "errors"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The total number of times that execution of this policy's
condition or action has been terminated due to run-time
exceptions."
::= { pmPolicyEntry 16 }
pmPolicyDebugging OBJECT-TYPE
SYNTAX INTEGER {
off(1),
on(2)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of debugging for this policy. If this is turned
on(2), log entries will be created in the pmDebuggingTable
for each run-time exception that is experienced by this
policy."
DEFVAL { off }
::= { pmPolicyEntry 17 }
pmPolicyAdminStatus OBJECT-TYPE
SYNTAX INTEGER {
disabled(1),
enabled(2),
enabledAutoRemove(3)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The administrative status of this policy.
The policy will be valid only if the associated
pmPolicyRowStatus is set to active(1) and this object is set
to enabled(2) or enabledAutoRemove(3).
If this object is set to enabledAutoRemove(3), the next time
the associated schedule moves from the active state to the
inactive state, this policy will immediately be deleted,
including any associated entries in the pmPolicyCodeTable.
The following related objects may not be changed unless this
object is set to disabled(1):
pmPolicyPrecedenceGroup, pmPolicyPrecedence,
pmPolicySchedule, pmPolicyElementTypeFilter,
pmPolicyConditionScriptIndex, pmPolicyActionScriptIndex,
pmPolicyParameters, and any pmPolicyCodeTable row
referenced by this policy.
In order to change any of these parameters, the policy must
be moved to the disabled(1) state, changed, and then
re-enabled.
When this policy moves to either enabled state from the
disabled state, any cached values of policy condition must be
erased, and any Policy or PolicyElement scratchpad values for
this policy should be removed. Policy execution will begin by
testing the policy condition on all appropriate elements."
::= { pmPolicyEntry 18 }
pmPolicyStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines whether this policy and any associated
entries in the pmPolicyCodeTable are kept in volatile storage
and lost upon reboot or if this row is backed up by
non-volatile or permanent storage.
If the value of this object is 'permanent', the values for
the associated pmPolicyAdminStatus object must remain
writable."
::= { pmPolicyEntry 19 }
pmPolicyRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The row status of this pmPolicyEntry.
The status may not be set to active if any of the related
entries in the pmPolicyCode table do not have a status of
active or if any of the objects in this row are not set to
valid values. Only the following objects may be modified
while in the active state:
pmPolicyParameters
pmPolicyConditionMaxLatency
pmPolicyActionMaxLatency
pmPolicyDebugging
pmPolicyAdminStatus
If this row is deleted, any associated entries in the
pmPolicyCodeTable will be deleted as well."
::= { pmPolicyEntry 20 }
-- Policy Code Table
pmPolicyCodeTable OBJECT-TYPE
SYNTAX SEQUENCE OF PmPolicyCodeEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The pmPolicyCodeTable stores the code for policy conditions and
actions.
An example of the relationships between the code table and the
policy table follows:
pmPolicyTable
AdminGroup Index ConditionScriptIndex ActionScriptIndex
A '' 1 1 2
B 'oper' 1 1 2
C 'oper' 2 3 4
pmPolicyCodeTable
AdminGroup ScriptIndex Segment Note
'' 1 1 Filter for policy A
'' 2 1 Action for policy A
'oper' 1 1 Filter for policy B
'oper' 2 1 Action 1/2 for policy B
'oper' 2 2 Action 2/2 for policy B
'oper' 3 1 Filter for policy C
'oper' 4 1 Action for policy C
In this example, there are 3 policies: 1 in the '' adminGroup,
and 2 in the 'oper' adminGroup. Policy A has been assigned
script indexes 1 and 2 (these script indexes are assigned out of
a separate pool per adminGroup), with 1 code segment each for
the filter and the action. Policy B has been assigned script
indexes 1 and 2 (out of the pool for the 'oper' adminGroup).
While the filter has 1 segment, the action is longer and is
loaded into 2 segments. Finally, Policy C has been assigned
script indexes 3 and 4, with 1 code segment each for the filter
and the action."
::= { pmMib 2 }
pmPolicyCodeEntry OBJECT-TYPE
SYNTAX PmPolicyCodeEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An entry in the policy code table representing one code
segment. Entries that share a common AdminGroup/ScriptIndex
pair make up a single script. Valid values of ScriptIndex are
retrieved from pmPolicyConditionScriptIndex and
pmPolicyActionScriptIndex after a pmPolicyEntry is
created. Segments of code can then be written to this table
with the learned ScriptIndex values.
The StorageType of this entry is determined by the value of
the associated pmPolicyStorageType.
The pmPolicyAdminGroup element of the index represents the
administrative group of the policy of which this code entry is
a part."
INDEX { pmPolicyAdminGroup, pmPolicyCodeScriptIndex,
pmPolicyCodeSegment }
::= { pmPolicyCodeTable 1 }
PmPolicyCodeEntry ::= SEQUENCE {
pmPolicyCodeScriptIndex Unsigned32,
pmPolicyCodeSegment Unsigned32,
pmPolicyCodeText PmUTF8String,
pmPolicyCodeStatus RowStatus
}
pmPolicyCodeScriptIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A unique index for each policy condition or action. The code
for each such condition or action may be composed of multiple
entries in this table if the code cannot fit in one entry.
Values of pmPolicyCodeScriptIndex may not be used unless
they have previously been assigned in the
pmPolicyConditionScriptIndex or pmPolicyActionScriptIndex
objects."
::= { pmPolicyCodeEntry 1 }
pmPolicyCodeSegment OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A unique index for each segment of a policy condition or
action.
When a policy condition or action spans multiple entries in
this table, the code of that policy starts from the
lowest-numbered segment and continues with increasing segment
values until it ends with the highest-numbered segment."
::= { pmPolicyCodeEntry 2 }
pmPolicyCodeText OBJECT-TYPE
SYNTAX PmUTF8String (SIZE (1..1024))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"A segment of policy code (condition or action). Lengthy
Policy conditions or actions may be stored in multiple
segments in this table that share the same value of
pmPolicyCodeScriptIndex. When multiple segments are used, it
is recommended that each segment be as large as is practical.
Entries in this table are associated with policies by values
of the pmPolicyConditionScriptIndex and
pmPolicyActionScriptIndex objects. If the status of the
related policy is active, then this object may not be
modified."
::= { pmPolicyCodeEntry 3 }
pmPolicyCodeStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this code entry.
Entries in this table are associated with policies by values
of the pmPolicyConditionScriptIndex and
pmPolicyActionScriptIndex objects. If the status of the
related policy is active, then this object can not be
modified (i.e., deleted or set to notInService), nor may new
entries be created.
If the status of this object is active, no objects in this
row may be modified."
::= { pmPolicyCodeEntry 4 }
-- Element Type Registration Table
pmElementTypeRegTable OBJECT-TYPE
SYNTAX SEQUENCE OF PmElementTypeRegEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A registration table for element types managed by this
system.
The Element Type Registration table allows the manager to
learn what element types are being managed by the system and
to register new types, if necessary. An element type is
registered by providing the OID of an SNMP object (i.e.,
without the instance). Each SNMP instance that exists under
that object is a distinct element. The index of the element is
the index part of the discovered OID. This index will be
supplied to policy conditions and actions so that this code
can inspect and configure the element.
For example, this table might contain the following entries.
The first three are agent-installed, and the 4th was
downloaded by a management station:
OIDPrefix MaxLatency Description StorageType
ifEntry 100 mS interfaces - builtin readOnly
0.0 100 mS system element - builtin readOnly
frCircuitEntry 100 mS FR Circuits - builtin readOnly
hrSWRunEntry 60 sec Running Processes volatile
Note that agents may automatically configure elements in this
table for frequently used element types (interfaces, circuits,
etc.). In particular, it may configure elements for whom
discovery is optimized in one or both of the following ways:
1. The agent may discover elements by scanning internal data
structures as opposed to issuing local SNMP requests. It is
possible to recreate the exact semantics described in this
table even if local SNMP requests are not issued.
2. The agent may receive asynchronous notification of new
elements (for example, 'card inserted') and use that
information to instantly create elements rather than
through polling. A similar feature might be available for
the deletion of elements.
Note that the disposition of agent-installed entries is
described by the pmPolicyStorageType object."
::= { pmMib 3 }
pmElementTypeRegEntry OBJECT-TYPE
SYNTAX PmElementTypeRegEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A registration of an element type.
Note that some values of this table's index may result in an
instance name that exceeds a length of 128 sub-identifiers,
which exceeds the maximum for the SNMP protocol.
Implementations should take care to avoid such values."
INDEX { pmElementTypeRegOIDPrefix }
::= { pmElementTypeRegTable 1 }
PmElementTypeRegEntry ::= SEQUENCE {
pmElementTypeRegOIDPrefix OBJECT IDENTIFIER,
pmElementTypeRegMaxLatency Unsigned32,
pmElementTypeRegDescription PmUTF8String,
pmElementTypeRegStorageType StorageType,
pmElementTypeRegRowStatus RowStatus
}
pmElementTypeRegOIDPrefix OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"This OBJECT IDENTIFIER value identifies a table in which all
elements of this type will be found. Every row in the
referenced table will be treated as an element for the
period of time that it remains in the table. The agent will
then execute policy conditions and actions as appropriate on
each of these elements.
This object identifier value is specified down to the 'entry'
component (e.g., ifEntry) of the identifier.
The index of each discovered row will be passed to each
invocation of the policy condition and policy action.
The actual mechanism by which instances are discovered is
implementation dependent. Periodic walks of the table to
discover the rows in the table is one such mechanism. This
mechanism has the advantage that it can be performed by an
agent with no knowledge of the names, syntax, or semantics
of the MIB objects in the table. This mechanism also serves as
the reference design. Other implementation-dependent
mechanisms may be implemented that are more efficient (perhaps
because they are hard coded) or that don't require polling.
These mechanisms must discover the same elements as would the
table-walking reference design.
This object can contain a OBJECT IDENTIFIER, '0.0'.
'0.0' represents the single instance of the system
itself and provides an execution context for policies to
operate on the 'system element' and on MIB objects
modeled as scalars. For example, '0.0' gives an execution
context for policy-based selection of the operating system
code version (likely modeled as a scalar MIB object). The
element type '0.0' always exists; as a consequence, no actual
discovery will take place, and the pmElementTypeRegMaxLatency
object will have no effect for the '0.0' element
type. However, if the '0.0' element type is not registered in
the table, policies will not be executed on the '0.0' element.
When a policy is invoked on behalf of a '0.0' entry in this
table, the element name will be '0.0', and there is no index
of 'this element' (in other words, it has zero length).
As this object is used in the index for the
pmElementTypeRegTable, users of this table should be careful
not to create entries that would result in instance names with
more than 128 sub-identifiers."
::= { pmElementTypeRegEntry 2 }
pmElementTypeRegMaxLatency OBJECT-TYPE
SYNTAX Unsigned32
UNITS "milliseconds"
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The PM agent is responsible for discovering new elements of
types that are registered. This object lets the manager
control the maximum amount of time that may pass between the
time an element is created and when it is discovered.
In other words, in any given interval of this duration, all
new elements must be discovered. Note that how the policy
agent schedules the checking of various elements within this
interval is an implementation-dependent matter."
::= { pmElementTypeRegEntry 3 }
pmElementTypeRegDescription OBJECT-TYPE
SYNTAX PmUTF8String (SIZE (0..64))
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"A descriptive label for this registered type."
::= { pmElementTypeRegEntry 4 }
pmElementTypeRegStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object defines whether this row is kept
in volatile storage and lost upon reboot or
backed up by non-volatile or permanent storage.
If the value of this object is 'permanent', no values in the
associated row have to be writable."
::= { pmElementTypeRegEntry 5 }
pmElementTypeRegRowStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this registration entry.
If the value of this object is active, no objects in this row
may be modified."
::= { pmElementTypeRegEntry 6 }
-- Role Table
pmRoleTable OBJECT-TYPE
SYNTAX SEQUENCE OF PmRoleEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The pmRoleTable is a read-create table that organizes role
strings sorted by element. This table is used to create and
modify role strings and their associations, as well as to allow
a management station to learn about the existence of roles and
their associations.
It is the responsibility of the agent to keep track of any
re-indexing of the underlying SNMP elements and to continue to
associate role strings with the element with which they were
initially configured.
Policy MIB agents that have elements in multiple local SNMP
contexts have to allow some roles to be assigned to elements
in particular contexts. This is particularly true when some
elements have the same names in different contexts and the
context is required to disambiguate them. In those situations,
a value for the pmRoleContextName may be provided. When a
pmRoleContextName value is not provided, the assignment is to
the element in the default context.
Policy MIB agents that discover elements on other systems and
execute policies on their behalf need to have access to role
information for these remote elements. In such situations,
role assignments for other systems can be stored in this table
by providing values for the pmRoleContextEngineID parameters.
For example:
Example:
element role context ctxEngineID #comment
ifindex.1 gold local, default context
ifindex.2 gold local, default context
repeaterid.1 foo rptr1 local, rptr1 context
repeaterid.1 bar rptr2 local, rptr2 context
ifindex.1 gold '' A different system
ifindex.1 gold '' B different system
The agent must store role string associations in non-volatile
storage."
::= { pmMib 4 }