Policy Based Management MIB
Extracted elements (31)
A special element type '0.0' always exists and represents the single instance of the system itself, providing an execution context for policies operating on scalar MIB objects. No actual element discovery takes place for '0.0', and pmElementTypeRegMaxLatency has no effect for it.
Library conformance is advertised by registering the library name as a role characteristic of the system element ('0.0') in the default SNMP context. This lets policy conditions test library availability via roleMatch('libraryName', '0.0') without requiring a separate capability protocol.
PolicyScript is formally defined as a subset of ISO C++ rather than a new language, allowing programmers familiar with C, Perl, TCL, Python, or JavaScript to quickly write scripts. A subset was chosen to enable easy development of low-cost interpreters and to remove constructs peculiar to C/C++ (pointers, structs, enums, floating point, preprocessor).
PolicyScript uses a loosely-typed 'var' class (modeled after ECMAScript semantics) instead of native C++ types so that scripts can remain short and easy to write. The var type holds either an integer (-2^63 to 2^64-1) or a string (sequence of 8-bit values), with automatic coercion between types.
Entries in the pmElementTypeRegTable that differ only in the last subidentifier (the column selector) are effectively duplicates and should be treated as such. Adding an extra or missing sub-identifier when registering an element type will cause all elements to be discovered zero or many times, with malformed element addresses.
NMS user interfaces are encouraged to display and accept MIB object names using descriptor values (e.g., 'ifType.7'), but MUST translate those descriptors to dotted-decimal format before sending them in MIB objects to policy agents, since policy agents may have no MIB compiler or MIB file available.
Before registering an element type, a manager is REQUIRED to inspect the pmElementTypeRegTable to see whether it is already registered. The management station is responsible for registering well-formed OIDs, as the system implementing the MIB may not validate them.
If the agent is discovering elements by polling, it MUST check for new elements no less frequently than pmElementTypeRegMaxLatency dictates. When an element is first discovered, all policyConditions MUST be run immediately.
Implementations SHOULD discover newly created elements via asynchronous notification (e.g., 'card inserted') rather than polling when such capability is available, resulting in immediate configuration of the discovered element.
In order to claim conformance to a function library, an implementation MUST implement all functions in that library. A single missing function means the library cannot be claimed.
It is RECOMMENDED that role strings not duplicate information available in MIB objects; role strings should describe information not otherwise accessible in MIB objects and are generally more static than live MIB data.
PolicyScript code MUST be expressed in the ASCII character set. Any syntax error, use of a reserved keyword, reference to an unknown identifier, improper argument count, type-coercion failure, or exceeding local storage limits MUST cause an RTE.
The setVar() function is only valid in policyActions; it MUST NOT be invoked from within a policyCondition. An RTE occurs if the set encounters any error.
When NonLocalArgs are used, mPModel, tDomain, tAddress, secModel, secName, and secLevel MUST all be specified together; if one is present all must be present. contextEngineID may only be specified if all others are present.
Precedence groups allow multiple policies to be ranked so that for each element only the highest-precedence matching ready policy is active. Lower-precedence policies in the group are not executed if a higher-precedence policy matches the same element.
The createRow() and setRowStatus() functions automate row creation in read-create tables with arbitrary integer index components, encapsulating the createAndWait/createAndGo algorithm. The optional 'freeOnException' flag causes automatic row deletion (RowStatus=destroy) if the script dies with an RTE or fail() call during the same invocation.
The defer() and fail() policy library functions affect execution flow beyond their own script: fail() sets return value to zero and may set the 'defer' attribute so that a lower-precedence policy in the same precedence group may run on that element, independent of the current script's return value.
The ec() and ev(n) library functions provide programmatic access to element index components: ec() returns the count of index components, ev(n) returns the integer value of the nth sub-identifier. These allow scripts to address related elements without string manipulation.
The '$n' token (dollar sign followed by integer 0-128) in SNMP OID string arguments is expanded at execution time to the nth subidentifier of the index of the current element. The special token '$*' expands to all subidentifiers separated by dots. Using a token beyond the index length is an RTE.
The pmElementTypeRegTable allows managers to register element types by OID prefix and to discover what element types the system already manages. The OIDPrefix length determines how the agent splits discovered OIDs into base and index portions (index begins after the column subidentifier).
The pmPolicyTable provides managed objects for representing a policy on a managed device, including pmPolicyCondition (the condition script), pmPolicyAction (the action script), pmPolicySchedule (optional schedule link), pmPolicyAdminStatus, and pmPolicyStorageType which controls disposition of agent-installed entries on restart.
The pmRoleTable allows a management station to learn what roles exist on a managed system. Upon receipt of a pmNewRoleNotification, a station may install new policies that depend on the new role. Multiple roles may be assigned to each element.
The pmSchedTable provides schedule entries that control when a policy is 'ready'. If pmPolicySchedule is zero, no schedule is defined and the policy is always ready. If non-zero, the policy is ready only if the referenced schedule group contains at least one valid entry active at the current time.
The pmTrackingTables and pmDebuggingTable provide policy monitoring. Run-time exceptions may cause an entry to be added to pmDebuggingTable and are reflected in the pmTrackingPEInfo object.
The searchColumn() function performs an SNMP walk searching for column values matching a pattern using one of six match modes: ExactMatch, ExactCaseMatch, SubstringMatch, SubstringCaseMatch, RegexpMatch, RegexpCaseMatch (POSIX 1003.2 extended regular expressions). Caller controls search start/continuation via the 'oid' in-out parameter.
The MIB module defined in this document (PM-MIB) is assigned an object identifier under the mib-2 subtree by IANA. Section 14 (IANA Considerations) records this assignment. The module defines tables pmPolicyTable, pmElementTypeRegTable, pmSchedTable, pmRoleTable, pmCapabilitiesTable, pmTrackingTable, and pmDebuggingTable.
The Security Considerations section (Section 13) notes that PolicyScript running on a managed device can perform arbitrary SNMP reads and writes, including to remote systems. Operators must carefully restrict who can write to the pmPolicyTable and pmElementTypeRegTable, as an attacker with write access could install policies that exfiltrate or modify configuration across the entire managed infrastructure.
When a policy script performs SNMP operations on a remote system using NonLocalArgs, the agent MUST use security credentials from the local configuration datastore on behalf of the principal identified as the last entity to modify pmPolicyAdminStatus for that policy. VACM must be configured so that the installing user has access to the relevant credentials (e.g., usmUserTable entries for the target system).
Policy lifecycle has four states: Valid (fully configured and enabled), Ready (valid and either unscheduled or linked to an active schedule), Active Execution Context (ready policy paired with an element that matches condition and, if in a precedence group, no higher-precedence policy also matches). A Run-Time Exception (RTE) terminates script execution immediately and prevents the associated action from running for that element.
SNMP Object Identifiers are encoded in policy scripts and library functions as ASCII dotted-decimal strings of the form 'subid[.subid]*' where each subid is '0' or a decimal constant. ASCII descriptors (e.g., 'ifIndex') are never used in these encodings and must be translated to dotted-decimal before being placed in MIB objects.
The contextEngineID NonLocalArg is encoded as a pair of hex digits (upper- or lowercase) per octet of the contextEngineID value when passed to SNMP library functions.