Internet Draft Policy-Based Management MIB Mar 1, 2001 Policy Based Management MIB draft-ietf-snmpconf-pm-05.txt March 1, 2001 Steve Waldbusser Jon Saperia Thippanna Hongal Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. 1. Abstract This memo defines a portion of the Management Information Base (MIB) for use with network management protocols in TCP/IP- based internets. In particular, this MIB defines objects that enable policy-based configuration management of SNMP Various Authors Expires September 1, 2001 [Page 1] Internet Draft Policy-Based Management MIB Mar 1, 2001 infrastructures. 2. The SNMP Management Framework The SNMP Management Framework presently consists of five major components: o An overall architecture, described in RFC 2571 [1]. o Mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in STD 16, RFC 1155 [2], STD 16, RFC 1212 [3] and RFC 1215 [4]. The second version, called SMIv2, is described in STD 58, RFC 2578 [5], RFC 2579 [6] and RFC 2580 [7]. o Message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in STD 15, RFC 1157 [8]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [9] and RFC 1906 [10]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [10], RFC 2572 [11] and RFC 2574 [12]. o Protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in STD 15, RFC 1157 [8]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [13]. o A set of fundamental applications described in RFC 2573 [14] and the view-based access control mechanism described in RFC 2575 [15]. A more detailed introduction to the current SNMP Management Framework can be found in RFC 2570 [18]. Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. Various Authors Expires September 1, 2001 [Page 2] Internet Draft Policy-Based Management MIB Mar 1, 2001 This memo specifies a MIB module that is compliant to the SMIv2. A MIB conforming to the SMIv1 can be produced through the appropriate translations. The resulting translated MIB must be semantically equivalent, except where objects or events are omitted because no translation is possible (use of Counter64). Some machine readable information in SMIv2 will be converted into textual descriptions in SMIv1 during the translation process. However, this loss of machine readable information is not considered to change the semantics of the MIB. Various Authors Expires September 1, 2001 [Page 3] Internet Draft Policy-Based Management MIB Mar 1, 2001 3. Overview Large IT organizations have developed management strategies to cope with the extraordinarily large scale and complexity inherent in today's networks. In particular, they try to configure the network as a whole by describing and implementing high-level business policies, rather than managing device by device, where orders of magnitude more decisions (and mistakes) may be made. Following this management practice results in the following benefits: - Reduced training needs (fewer details to learn) - Reduced documentation costs (fewer details to document) - Reduced impact of turnover (less ad-hoc knowledge goes out the door) - Greater testability (a greater percentage of fielded configurations may be tested in the lab) - Higher reliability (combination of factors above) - Lower cost of changes (changes can be simpler and operate over a wider extent) - Lower cost of corporate mergers (less knowledge to transfer; fewer policies to integrate) - Lower cost of ownership (combination of factors above) To illustrate the concept of "business policies", some examples are: - All routers will run code version 6.2 - On-site contracters will all have special security restrictions on their ports - All voice over cable ports in California must provide free local calling - Apply special forwarding to all ports whose customers have paid for premium service. Each of these policies could represent an action applied to hundreds of thousands of configuration variables. In order to automate this practice, customers need software tools that will implement business policies across their network, as well as a standard protocol that will ensure that it can be applied to all of their devices, regardless of the vendor. This practice is called Policy-Based Network Management. This document defines standard managed objects for the Simple Network Management Protocol that are used to distribute policies in a standard form throughout the network. Various Authors Expires September 1, 2001 [Page 4] Internet Draft Policy-Based Management MIB Mar 1, 2001 4. Policy-Based Management Architecture Policy-based network management is the practice of applying management operations globally on all managed elements that share certain attributes. Policies are intended to express a notion of: if (an element has certain characteristics) then (apply operation to that element) Policies take the following normal form: if (policyFilter) then (policyAction) A policyFilter is program code which results in a boolean to determine whether or not an element is a member of a set of elements upon which an action is to be performed. A policyAction is an operation performed on an element or a set of elements. These policies are most often executed on or near managed devices, where the elements live (and thus their characteristics may be easily inspected), and where operations on those elements will be performed. A management station is responsible for distributing an organization's policies to all of the managed devices in the infrastructure. The pmPolicyTable provides managed objects for sending a policy to a managed device. In this architecture, an element is a group of related MIB variables such as all the variables for interface #7. This enables policies to be expressed more efficiently and concisely. Elements can also model circuits, CPUs, queues, processes, systems, etc. The execution model for policies on a managed device is: foreach element for which policyFilter returns true execute policyAction on that element For example: If (interface is fast ethernet) then (apply full-duplex mode) If (interface is access) then (apply security filters) If (gold service paid for on circuit) then (apply special queueing) Various Authors Expires September 1, 2001 [Page 5] Internet Draft Policy-Based Management MIB Mar 1, 2001 Each unique combination of policy and element is called an execution context. Within a particular execution context, the phrase "this element" is often used to refer to the associated element, as most policy operations will be applied to "this element". The address of "this element" contains the index of the element, the context the element was discovered in, and the address of the system on which the element was discovered. In most circumstances the context and address will be implicit. PolicyFilters have the capability of performing comparison operations on SNMP variables, logical expressions, and other functions. Many device characteristics are already defined in MIBs and are easy to include in policyFilter expressions (ifType == ethernet, frCircuitCommittedBurst < 128K, etc). However, there are important characteristics that aren't currently in MIB objects, and worse, it is not current practice to store this information on managed devices. Therefore, this document defines MIB objects for this information. To meet today's needs there are three missing areas: roles, capabilities and time. Roles A role is an administratively specified characteristic of a managed element (for example, an interface). It is a selector for policies, to determine the applicability of the policy to a particular managed element. Some examples of roles are political, financial, legal, geographical, or architectural characteristics, typically not directly derivable from information stored on the managed system. For example, "paid for premium service" or "is plugged into a UPS" are examples of roles, whereas the "percent utilization of a link" would not be. Some types of information one would put into a role include: political - describes the role of a person or group of people, or of a service that a group of people use. Examples: executive, sales, outside-contracter, customer. If (attached user is executive) then (apply higher bandwidth) If (attached user is outside-contracter) then (restrict access) financial/legal - describes what financial consideration was received. Could also include contractual or legal considerations. Examples: paid, gold, free, trial, demo, lifeline Various Authors Expires September 1, 2001 [Page 6] Internet Draft Policy-Based Management MIB Mar 1, 2001 If (gold service paid for) then (apply special queueing) geographical - describes the location of an element. Examples: California, Headquarters, insecure conduit. If (interface leaves the building) then (apply special security) architectural - describes the network architects "intent" for an element. For example: backup, trunk. If (interface is backup) then (set ifAdminStatus = down) Roles in this model are human defined strings that can be referenced by policy code. Roles may be assigned to elements by the role group in this MIB as well as through implementation-dependent means. Multiple roles may be assigned to each element. Because policy code can make policy decisions based on the value of any MIB object, role strings will typically contain information not accessible in MIB objects. The roleMatch accessor function allows policy code to make decisions based on whether or not an element has a particular role assigned to it. The role group allows a management station to learn what roles exist on a managed system. The management station may choose not to install policies that depend on a role that does not exist on any elements in the system. The management station can then register for notifications of new roles. Upon receipt of a pmNewRoleNotification, it may choose to install new policies that make use of that new role. Capabilities Some actions are inappropriate for certain elements or are simply unsupported because a capability doesn't exist or because it is restricted. Policy filters must be able to be defined so that a policy can be applied only to elements that have the proper capability. The capabilities table provides MIB objects that describe the capabilities of the system. The capMatch accessor function allows policy code to make decisions based on whether or not an element has certain capabilities. The capabilities group allows a management station to learn what capabilities exist on a managed system. The management station may Various Authors Expires September 1, 2001 [Page 7] Internet Draft Policy-Based Management MIB Mar 1, 2001 choose not to install policies that depend on a capability that does not exist on any elements in the system. The management station can then register for notifications of new capabilities. Upon receipt of a pmNewCapabilityNotification, it may choose to install new policies that make use of that new capability. Time Managers may wish to define policies that are true for certain periods of time. This might mean that a policy is installed and is dormant for a period of time, becomes active, and then later becomes inactive. Sometimes these time periods will be regular (M-F 9-5) and sometimes ad-hoc. This MIB provides MIB objects that allow policies to be dependent on time. 5. Policy Based Management Execution Environment 5.1. Terminology Run-Time Exception (RTE) - A run-time exception is a fatal error caused in PolicyScript language processing or in the processing of accessor functions. If, during the invocation of a script, a run-time exception occurs, execution of that script is immediately terminated. If a filter experiences a run-time exception while processing an element, the element is not matched by the filter and the associated action will not be run on that element. A run-time exception can cause an entry to be added to the pmDebuggingTable and will be reflected in the pmTrackingPolicyToElementInfo object. The phrase run-time exception will be commonly abbreviated to RTE. There are several steps performed in order to execute policies in this environment: - Element Discovery - Element Filtering - Policy Enforcement Various Authors Expires September 1, 2001 [Page 8] Internet Draft Policy-Based Management MIB Mar 1, 2001 5.2. Element Discovery An element is a uniquely addressable entity on a managed device. Examples of elements include interfaces, circuits, queues, CPUs, and processes. Sometimes various attributes of an entity will be described through tables in several standard and proprietary MIBs - as long as the indexing is consistent between these tables, the entity can be modeled as 1 element. For example, the ifTable and the dot3Stats table both contain attributes of interfaces and share the same index (ifIndex), therefore they can be modeled in this model as one element type. The Element Type Registration table is used for 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 address of the element is the index part of the discovered OID. This address will be supplied to policy filters and actions so that this code can inspect and configure the element. For each element that is discovered, the policy filter is called with the element address as an argument to see if the element is a member of the set that the policy acts upon. 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. A special element type "0.0" exists. "0.0" represents the single instance of the system itself and provides an execution Various Authors Expires September 1, 2001 [Page 9] Internet Draft Policy-Based Management MIB Mar 1, 2001 context for policies to operate on "the system" as well as on MIB objects modelled 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). If the agent is discovering elements by polling, it should check for new elements no less frequently than pmElementTypeRegMaxLatency would dictate. When an element is first discovered all policyFilters are run immediately and policyFilters that match will have the associated policyAction run immediately. Subsequently, the policyFilter will be run regularly for the element with no more than pmPolicyFilterMaxLatency milliseconds elapsing between each invocation. Note that if an implementation has the ability to be alerted immediately when a particular type of element is created, it is urged to discover that type of element in this fashion rather than through polling, resulting in immediate configuration of the discovered element. 5.2.1. Implementation Notes Note that while the external behavior of this registration process is defined in terms of the walking of MIB tables, implementation strategies may differ. For example, commonly- used element types (like interface) may have purpose-built element discovery capability built-in and advertised to managers through an entry in the pmElementTypeRegTable. Before registering an element type, it is the responsibility of a manager to inspect the table and see if it is already registered (by the agent or another manager). Note that entries that differ only in the last OID (which specifies which object in an entry) are effectively duplicates and should be treated as such by the manager. The system which implements the Policy-Based Management MIB may not have knowledge of the format of object identifiers in other MIBs. Therefore it is inappropriate for it to check these OIDs for errors. It is the responsibility of the management station to register well-formed object-identifiers. For example, if an extra sub-identifier is supplied when registering the ifTable, no elements will be discovered. Similarly, if a sub-identifier is missing, every element will Various Authors Expires September 1, 2001 [Page 10] Internet Draft Policy-Based Management MIB Mar 1, 2001 be discovered numerous times (once per column) and none of the element addresses will be well-formed. 5.3. Element Filtering The first step in executing a policy is to see which elements match the policy filter. To evaluate a policy, the policy filter is called once for each element and runs to completion. The element address is the only state that is passed to the filter code for each invocation (in particular, except for state accessible from accessor functions, no state is remembered from the previous invocation of this element nor from the previous invocation of the policy filter). If any run-time exception occurs, the filter will terminate immediately for this element. If the filter returns non-zero, the corresponding policy action will be executed for this element. If an element matches a filter and it had not matched that filter the last time it was checked (or it is a newly- discovered element), the associated policyAction will be executed immediately. If the element had matched the filter at the last check, it will remain in the set of elements whose policyAction will be run within the policyFilterActionMaxLatency. 5.3.1. Implementation Notes It is an implementation-dependent matter as to how policy filters are scheduled. Each filter/element combination is conceptually its own process and can be scheduled sequentially or two or more could be run simultaneously. Policy filters have no side-effects except for changes to the scratchpad. 5.4. Policy Enforcement For each element that has returned non-zero from the policy filter, the corresponding policy action is called. The element Various Authors Expires September 1, 2001 [Page 11] Internet Draft Policy-Based Management MIB Mar 1, 2001 address is the only state that is passed to the policy action for each invocation (in particular, except for state accessible from accessor functions, no state is remembered from the policy filter evaluation, nor from the previous filter/action invocation of this element nor from the previous invocation of the policy filter or action on any other element). If any run-time exception occurs, the action will terminate immediately for this element. 5.4.1. Implementation Notes It is an implementation-dependent matter as to how policy actions are scheduled. Each filter/element combination is conceptually its own process and can be scheduled sequentially or two or more could be run simultaneously. Various Authors Expires September 1, 2001 [Page 12] Internet Draft Policy-Based Management MIB Mar 1, 2001 6. The PolicyScript Language Policy filters and policy actions are expressed with the PolicyScript language. The PolicyScript language is designed to be a small interpreted language that is simple to understand and implement; it is designed to be appropriate for writing small scripts that make up policy filters and actions. PolicyScript is intended to be familiar to programmers in a variety of languages, including Perl and C. PolicyScript is nominally a subset of the C language - however it was desireable to have access to C++'s operator overloading (solely to aid in documenting the language - operator overloading is not a feature of PolicyScript). Therefore, PolicyScript is defined formally as a subset of the C++ language. A subset was used to provide for easy development of low-cost interpreters of PolicyScript and to take away language constructs that are peculiar to the C/C++ languages. For example, it is expected that both C and Perl programmers will understand the constructs allowed in PolicyScript. Some examples of the features that have been removed from the C/C++ language are: function definitions, pointer variables, structures, enums, typedefs, floating point and pre-processor functions (except for comments). This language is formally defined as a subset of ISO C++ [19], but only allows those constructs that may be expressed in the Extended Backus-Naur Form (EBNF) documented here. This is done because while EBNF doesn't fully specify syntactical rules (it allows constructs that are invalid) and doesn't specify semantic rules, it can successfully be used to define the subset of the language that is required for conformance to this standard. Unless explicitly described herein, the meaning of any construct expressed in the EBNF can be found by reference to the ISO C++ standard. The use of comments and newlines are allowed and encouraged in order to promote readability of PolicyScript code. Comments begin with '/*' and end with '*/' or begin with '//' and go until the end of the line. One subset is not expressable in the EBNF syntax: all variables within a PolicyScript program are within the same scope. Various Authors Expires September 1, 2001 [Page 13] Internet Draft Policy-Based Management MIB Mar 1, 2001 PolicyScript code must be expressed in the UTF8 character set. In the EBNF used here, terminals are character set members (singly or in a sequence) that are enclosed between two single-quote characters or described as a phrase between '<' and '>' characters. Nonterminals are a sequence of letters and underscore characters. A colon (:) following a nonterminal introduces its definition, a production. In a production, a '|' character separates alternatives. The '(' and ')' symbols group the enclosed items. The '[' and ']' symbols indicate that the enclosed items are optional. The '?' symbol following an item indicates that the item is optional. The '*' symbol following an item indicates that the item is repeated zero, one, or more times. The '+' symbol following an item indicates that the item is repeated one or more times. The symbol '--' begins a comment that ends at the end of the line. 6.1. Formal Definition The PolicyScript language follows the syntax and semantics of ISO C++ [19], but is limited to that which that can be expressed in the EBNF below. The following keywords are reserved words and cannot be used in any policy script. This prevents someone from using a word that is a common keyword in other languages as an identifier in a program and thus make the meaning of the program confusing. The reserved words are: auto, case, char, const, default, do, double, enum, extern, float, goto, inline, int, long, register, short, signed, sizeof, static, struct, switch, typedef, union, unsigned, void, and volatile. Any syntax error, use of a reserved keyword, reference of an unknown identifier, improper number or type of function arguments, exceeding local limitations on string length or exceeding local limitations on the total amount of storage used by local variables will cause a RTE. PolicyScript permits comments using the comment delimiters, '/*' to '*/' or the start of comment symbol '//'. -- Lexical Grammar Various Authors Expires September 1, 2001 [Page 14] Internet Draft Policy-Based Management MIB Mar 1, 2001 letter: '_' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' digit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' non_zero: '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' oct_digit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' hex_digit: digit | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' escape_seq: '\'' | '\"' | '\?' | '\\' | '\a' | '\b' | '\f' | '\n' | '\r' | '\t' | '\v' | '\' oct_digit+ | '\x' hex_digit+ non_quote: Any character in the UTF-8 character set except single quote ('), double quote ("), backslash ('\') or newline. c_char: non_quote | '"' | escape_seq string_literal: '"' s_char* '"' s_char: non_quote | ''' | escape_seq char_constant: ''' c_char ''' decimal_constant: non_zero digit* octal_constant: '0' oct_digit* hex_constant: ( '0x' | '0X' ) hex_digit+ integer_constant: decimal_constant | octal_constant | hex_constant identifier: letter ( letter | digit )* Various Authors Expires September 1, 2001 [Page 15] Internet Draft Policy-Based Management MIB Mar 1, 2001 -- Phrase Structure Grammar -- Expressions primary_expression: identifier | integer_constant | char_constant | string_literal | '(' expression ')' postfix_expression: primary_expression | postfix_expression '(' argument_expression_list? ')' | postfix_expression '++' | postfix_expression '--' | postfix_expression '[' expression ']' argument_expression_list: assignment_expression | argument_expression_list ',' assignment_expression unary_expression: postfix_expression | unary_op unary_expression unary_op: '+' | '-' | '~' | '!' | '++' | '--' binary_expression: unary_expression | binary_expression binary_op unary_expression binary_op: '||' | '&&' | '|' | '^' | '&' | '!=' | '==' | '>=' | '<=' | '>' | '<' | '>>' | '<<' | '-' | '+' | '%' | '/' | '*' assignment_expression: binary_expression | unary_expression assignment_op assignment_expression assignment_op: '=' | '*=' | '/=' | '%=' | '+=' | '-=' | '<<=' | '>>=' | '&=' | '^=' | '|=' expression: assignment_expression | expression ',' assignment_expression -- Declarations declaration: 'var' declarator_list ';' Various Authors Expires September 1, 2001 [Page 16] Internet Draft Policy-Based Management MIB Mar 1, 2001 declarator_list: init_declarator | declarator_list ',' init_declarator init_declarator: identifier [ '=' assignment_expression ] -- Statements statement: declaration | compound_statement | expression_statement | selection_statement | iteration_statement | jump_statement compound_statement: '{' statement* '}' expression_statement: expression? ';' selection_statement: 'if' '(' expression ')' statement | 'if' '(' expression ')' statement 'else' statement iteration_statement: 'while' '(' expression ')' statement | 'for' '(' expression? ';' expression? ';' expression? ')' statement jump_statement: 'continue' ';' | 'break' ';' | 'return' expression? ';' -- Root production PolicyScript: statement* 6.2. Variables To promote shorter scripts and ease in writing scripts, PolicyScript provides a loosely-typed data class, "var", that can store both integer and string values. The native C++ types (char, int, etc.) are thus unnecessary and have not been carried into the subset that comprises this language. The semantics of the "var" type are modelled after those of ECMAScript[21]. Various Authors Expires September 1, 2001 [Page 17] Internet Draft Policy-Based Management MIB Mar 1, 2001 For example: var number = 0, name = "IETF"; This language will be executed in an environment where the following typedef is declared. (Note that this typedef will not be visible in the policyFilter or policyAction code.) typedef ... var; While this declaration is expressed here as a typedef, the 'typedef' keyword itself is not available to be used inside of PolicyScript code. 6.2.1. The var class A value is an entity that takes on one of two types: string or integer. The String type is the set of all finite ordered sequences of zero or more 8-bit unsigned integer values ("elements"). The string type can store textual data as well as binary data sequences. Each element is regarded as occupying a position within the sequence. These positions are indexed with nonnegative integers. The first element (if any) is at position 0, the next element (if any) at position 1, and so on. The length of a string is the number of elements (i.e., 8-bit values) within it. The empty string has length zero and therefore contains no elements. The integer type is the set of all integer values in the range -9223372036854775808 to 18446744073709551615, plus the value NaN. Prior to initialization, a var object has type String and a length of zero. The policy script runtime system performs automatic type conversion as needed. To clarify the semantics of certain constructs it is useful to define a set of conversion operators. These operators are not a part of the language; they are defined here to aid the specification of the semantics of the language. The conversion operators are polymorphic; that is, they can accept a value of any standard Various Authors Expires September 1, 2001 [Page 18] Internet Draft Policy-Based Management MIB Mar 1, 2001 type. ToInteger The operator ToInteger converts its argument to a value of type Integer according to the following table: Integer The result equals the input argument (no conversion). String See grammar and note below integer_constant The result equals the input argument (no conversion). string_literal See grammar and note below char_constant See grammar and note below ToInteger Applied to strings ToInteger applied to the String Type, string_literal and char_constants applies the following grammar to the input. If the grammar cannot interpret the string as an expansion of numeric_string, then the result of ToInteger is NaN. Note that a numeric_string that is empty or contains only white space is converted to 0. -- EBNF for numeric_string numeric_string : white_space* numeric white_space* white_space : | | | | | | | | | numeric : signed_decimal | hex_constant | octal_constant signed_decimal: [ '-' | '+' ] decimal_constant -- decimal_constant, hex_constant, octal_constant are defined in the -- PolicyScript EBNF described earlier ToString The operator ToString converts its argument to a value of type String according to the following table: Integer Return the string containing the decimal representation of the input argument in Various Authors Expires September 1, 2001 [Page 19] Internet Draft Policy-Based Management MIB Mar 1, 2001 the form of signed_decimal except that no leading '+' will be used. If the value is 'NaN', return the string "NaN". String Return the input argument (no conversion) integer_constant Return the string containing the decimal representation of the input argument in the form of signed_decimal except that no leading '+' will be used. If the value is 'NaN', return the string "NaN". string_literal Return the input argument (no conversion) char_constant Return the string of length one containing the value of the input argument. ToBoolean The operator ToBoolean converts its argument to a value of type Integer according to the following table: Integer The result is 0 if the argument is 0 or NaN. Otherwise the result is 1. String The results is 0 if the argument is the empty string. Otherwise the result is 1. integer_constant The result is 0 if the argument is 0. Otherwise the result is 1. string_literal The results is 0 if the argument is the empty string. Otherwise the result is 1. char_constant The result is 1. Operators A++, A--, ++A, --A: A = ToInteger(A); OP; +A: ToInteger(A); -A: -1 * ToInteger(A); ~A: ~ToInteger(A); !A: !ToBoolean(A); A * B, A - B, A & B, A ^ B , A | B, A << B, A >> B: ToInteger(A) OP ToInteger(B) A / B, A % B: if (ToInteger(B) == 0) NaN; else ToInteger(A) OP ToInteger(B) A + B: Various Authors Expires September 1, 2001 [Page 20] Internet Draft Policy-Based Management MIB Mar 1, 2001 if (Type(A) == String || Type(B) == String) ToString(A) concatenated with ToString(B) else A + B Compound Assignment (op=): Simply follow rules above. Note that type of LHS may be changed as a result. Note that for any operation above, if any operand is 'NaN' or becomes 'NaN' due to a ToInteger conversion, the result of the operation will be 'NaN'. A < B, A > B, A <= B, A >= B, A == B, A != B: if (Type(A) == String && Type(B) == String) lexically compare strings with strcmp() logic else ToInteger(A) OP ToInteger(B) A && B: if (ToBoolean(A)) ToBoolean(B); else false; A || B: if (ToBoolean(A)) true; else ToBoolean(B); A[B] as a RHS value: if (Type(A) != String || ToInteger(B) == NaN || ToInteger(B) >= strlen(A)) RTE, terminate A[ ToInteger(B) ] The contents are returned as a string of length one A[B] = C as a LHS value: if (Type(A) != String || ToInteger(B) == NaN || ToInteger(B) >= strlen(A)) RTE, terminate if (strlen(ToString(C)) == 0) RTE, terminate A[ ToInteger(B) ] = First octet of ToString(C) Various Authors Expires September 1, 2001 [Page 21] Internet Draft Policy-Based Management MIB Mar 1, 2001 Note that this is only applicable in a simple assignment. 6.3. PolicyScript QuickStart Guide PolicyScript is designed so that programmers fluent in other languages can quickly begin to write scripts. One way to become familiar with a language is to see it in action. The following nonsensical program excercizes most of the PolicyScript constructs (though it skips some usage options and many arithmetic operators). var x, index = 7, str = "Hello World", oid = "ifSpeed."; x = 0; while(x < 10){ if (str < "Goodbye") /* string comparison */ continue; else break; x++; } if (oidlen(oid) == 10) oid += "." + index; // append index to oid for(x = 0; x < 7; x++){ str += "a"; var y = 12; index = ((x * 7) + y) % 3; if (str[6] == 'W') return index; } return; A few examples that are more practical are: For a filter: // Return 1 if this is an interface and it is tagged // with the role "gold" if (insubtree(elementName(), "ifEntry") && roleMatch("gold")) return 1; // Match else return 0; Various Authors Expires September 1, 2001 [Page 22] Internet Draft Policy-Based Management MIB Mar 1, 2001 A filter/action pair: First, register the Host Resources MIB hrSWRunEntry as a new element in the pmElementTypeRegTable. This will cause the policy to run for every process on the system and $0 will be the process index. The filter: // if it's a process and it's an application and it's // consumed more than 5 minutes of CPU time if (insubtree(elementName(), "hrSWRunEntry") && getvar("hrSWRunType.$0") == 4 // app, not OS or driver && getvar("hrSWRunPerfCPU.$0") > 30000) // 300 seconds return 1; return 0; The action: // Kill it setvar("hrSWRunStatus.$0", 4, Integer); // invalid(4) kills it A more substantial action to start an RMON2 host table on interfaces that match the filter: var index, pdu; pdu = newPDU(); // setRowStatus finds an empty row and creates it if (!(index = setRowStatus("hlHostControlStatus.*", 20))) return; /* couldn't find a free row */ writeVar(pdu, 0, "hlHostControlDataSource." + index, "ifIndex." + iv(0), Oid); writeVar(pdu, 1, "hlHostControlNlMaxDesiredEntries." + index, 1000, Integer); writeVar(pdu, 2, "hlHostControlAlMaxDesiredEntries." + index, 1000, Integer); writeVar(pdu, 3, "hlHostControlOwner." + index, "policy", String); writeVar(pdu, 4, "hlHostControlStatus." + index, 1, Integer); snmpsend(pdu, 5, OP_SET); Various Authors Expires September 1, 2001 [Page 23] Internet Draft Policy-Based Management MIB Mar 1, 2001 Because PolicyScript is a least common denominator, it contains nothing that would astonish programmers familiar with C, C++, Perl, Tcl, JavaScript or Python. While a new programmer may attempt to use language constructs that aren't available in PolicyScript, they should be able to understand any existing PolicyScript and will likely know how to use anything that is valid in PolicyScript. The lists below quickly enumerate the changes of note for programmers coming some particular languages. These lists won't describe the unavailable constructs but it is easy to see from the definition above what is available. 6.3.1. Quickstart for C Programmers - Character constants (i.e. 'c') are treated as one-character strings, not integers. So operations like ('M' - 'A') or (x + 'A') will not perform as expected. - Accessor functions can change the value of arguments even though they are not pointers (or called like '&arg'). - All variables are in the same scope 6.3.2. Quickstart for Perl Programmers - Comments are '/* comment */' and '// till end of line', not '#' - No need to put a '$' in front of variables - Strings are compared with ==, <=, < etc. (Details in Sec. 6.2.1) - Strings are concatenated with '+'. (Details in Sec. 6.2.1) - No variable substitution in "" strings. '' strings are 1 char only. - Variables must be declared before use (but no type is necessary) - All variables are in the same scope 6.3.3. Quickstart for TCL Programmers - Comments are '/* comment */' and '// till end of line', not '#' - No need to put a '$' in front of variables - Function calls are func-name(arg1, arg2, ...) - Square braces [] don't interpret their contents - Double quotes "" surround a string but no substitutions are performed ("" is like { } in TCL ) - Statements are terminated by a semicolon; - Instead of "Set a b", use "b = a;" - Strings are concatenated with '+'. (Details in Sec. 6.2.1) Various Authors Expires September 1, 2001 [Page 24] Internet Draft Policy-Based Management MIB Mar 1, 2001 - All variables are in the same scope 6.3.4. Quickstart for Python Programmers - Comments are '/* comment */' and '// till end of line', not '#' - Single quotes can be used only for single-character strings ('a') - Indentation doesn't matter. Braces {} define blocks. - Variables must be declared before use (but no type is necessary) - The expression for if and while is always surrounded by parenthesis, like "if (x < 5)". - 'for' syntax is "for(expression; expression; expression)" (see EBNF). - All variables are in the same scope 6.3.5. Quickstart for JavaScript/ECMAScript/JScript Programmers - Variables must be declared before use. - Accessor functions can change the value of arguments - All variables are in the same scope 7. Address of `this element' PolicyScript code needs a convenient way to get the components of the index for "this element" so that they can perform SNMP operations on it or on related elements. Two mechanisms are provided. 1. For all oid input parameters to all SNMP Accessor Functions (but not oid utility functions), the token "$n" ('$' followed by an integer between 0 and 99) can be used in place of any decimal sub-identifier. This token is expanded by the agent at execution time to contain the n'th subid of the index for the current element. For example, if the element is interface #7, and the objectIdentifier is "1.3.6.1.2.1.2.2.1.3.$0", it will be expanded to "1.3.6.1.2.1.2.2.1.3.7". It is an RTE if a token is specified that is beyond the length of the index for the current element. 2. The ic() and iv() functions allow access to the components of the index for "this element". ic() takes no argument and returns the Various Authors Expires September 1, 2001 [Page 25] Internet Draft Policy-Based Management MIB Mar 1, 2001 number index components exist. iv() takes an integer argument specifying which component of the index (numbered starting at 0) and returns an integer containing the value of the n'th subidentifier. Refer to the accessor functions section for the complete definition of ic() and iv(). For example, if "this element" is frCircuitDLCI.5.57 (ifIndex = 5, DLCI = 57) then ic() returns 2 iv(0) returns 5 iv(1) returns 57 This is helpful when wishing to address a related element. Extending the previous example, to find the port speed of the port the circuit (above) runs over: portSpeed = getvar("ifSpeed." + iv(0)); 8. Accessor Functions Accessor functions are built-in functions available primarily to provide access to information on the local system or to more efficiently manipulate this information. A group of functions is organized into a library, the unit of conformance for function implementation. In order to claim conformance to a library, an implementation must implement all functions in a library to the specifications of the library. In order for a management station or a filter or action to understand if a certain library of functions is implemented, each library will have a registration OID that it registers in this MIB's capabilities table. Thus, conformance to a library can be tested with the capMatch library function (in the base library) or by inspecting the pmCapabilitiesType objects in the pmCapabilitiesTable. 9. Base Accessor Function Library A standard base library of accessor functions is available to all systems that implement this specification. This library is known by the capability OID of: pmBaseFunctionLibrary ::= { policyMgt pmConformance pmGroups 4 } Various Authors Expires September 1, 2001 [Page 26] Internet Draft Policy-Based Management MIB Mar 1, 2001 This library contains four types of functions: - SNMP Accessor functions - Policy Configuration Accessor functions - Utility functions - Library Functions Note that in the descriptions of these functions below, the function prototype describes the type of argument expected. Even though variables are not declared with a particular type, their contents be as appropriate for each function argument. If the type is variable, the keyword 'var' will be used. If only a string is appropriate, the keyword 'string' will be used. If only an integer is appropriate, the keyword 'integer' will be used. In the function prototype, if the '&' character precedes the identifier for an argument, that argument may be modified by the function (e.g., "integer &result, ...)"). Arguments without the '&' character cannot be modified by the function. 9.1. SNMP Accessor Functions Two sets of SNMP Accessor functions are available with different situations in mind: - Convenience SNMP Functions In an effort to keep simple things simple, these functions are easy to use and promote easy to understand code. These functions will suffice for the majority of situations where a single variable is referenced and the desired error recovery is to simply (and immediately) give up (and move to the next policy-element combination). In more complex cases, the General SNMP Functions can be used at the cost of several times the code complexity. The convenience SNMP functions are getvar, exists, setvar, setRowStatus, and searchcolumn. - General SNMP Functions The General SNMP functions allow nearly any legal SNMP Message to be generated, including those with multiple varbinds, getNext operations, notifications, and messages with explicit addressing Various Authors Expires September 1, 2001 [Page 27] Internet Draft Policy-Based Management MIB Mar 1, 2001 or security specifications. The general SNMP functions are writeVar, readVar, and snmpsend. 9.1.1. Form of SNMP Values Many of the accessor functions have input or output parameters that may be one of the many SMI data types. The actual type is not encoded in the value, but rather is specified elsewhere, possibly by nature of the context in which it is used. The exact usage for input and output is: Any Integer value (INTEGER, Integer32, Counter32, Counter64, Gauge32, Unsigned32, TimeTicks, Counter64): On input: An Integer or a String that can be successfully coerced to an Integer with the ToInteger() function. It is an RTE ifToInteger(). On output: An Integer containing the returned value. Octet String On input: Either a String or an Integer. If an Integer, it will be coerced to a String with the ToString() function. This string will be used as an unencoded representation of the octet string value. On output: A String containing the unencoded value of the octet string. Object Identifier On input and on output: A String containing a decimal ascii encoded object identifier of the following form: oid: subid [ '.' subid ]* [ '.' ] subid: '0' | decimal_constant It is an RTE if an Object Identifier argument is not in the form above. Note that a trailing '.' is acceptable and will simply be ignored. Various Authors Expires September 1, 2001 [Page 28] Internet Draft Policy-Based Management MIB Mar 1, 2001 Note that ascii descriptors (e.g. "ifIndex") are never used in these encodings "over the wire". They are never returned from accessor functions nor are they ever accepted by them. NMS user interfaces are encouraged to allow humans to view object identifiers with ascii descriptors, but they must translate those descriptors to dotted-decimal format before sending them in MIB objects to policy agents. 9.1.2. Convenience SNMP Functions 9.1.2.1. getvar() The getvar() function is used to retrieve the value of an SNMP MIB instance. string getvar(string 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"). The agent will retrieve the instance in the same SNMP context in which the element resides. Note that no actual SNMP PDU needs to be generated and parsed when the policy MIB module resides on the same system as the managed elements. It is an RTE if the queried object identifier value does not exist. This function returns a string containing the returned value, encoded according to the returned type. It is recommended that NMS user interfaces display and allow input of MIB object names by their descriptor values followed by the index in dotted-decimal form (e.g., "ifType.7"). 9.1.2.2. exists() The exists() function is used to verify the existence of an SNMP MIB instance. integer exists(string oid) Various Authors Expires September 1, 2001 [Page 29] Internet Draft Policy-Based Management MIB Mar 1, 2001 '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"). The agent will retrieve the instance in the same SNMP context in which the element resides. Note that no actual SNMP PDU needs to be generated and parsed when the policy MIB module resides on the same system as the managed elements. This function returns the value 1 if the SNMP instance exists and 0 if it doesn't exist. It is recommended that NMS user interfaces display and allow input of MIB object names by their descriptor values followed by the index in dotted-decimal form (e.g., "ifType.7"). 9.1.2.3. setvar() The setvar() function is used to set a MIB instance to a certain value. The setvar() function is only valid in policyActions. If when executing a policyFilter, the agent encounters a call to the setvar() function, it is an RTE. integer setvar(string oid, var value, integer type) '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"). 'value' is a string encoded in the format appropriate to the 'type' parameter. The agent will set the variable specified by 'oid' to the value specified by 'value'. 'type' will be the type of the 'value'' parameter and will be set to one of the values for DataType Constants. The agent will set the instance in the same SNMP context in which the element resides. Note that no actual SNMP PDU needs to be generated and parsed when the policy MIB module resides on the same system as the managed elements. If the set encounters any error, 0 is returned. If sucessful, 1 is returned. It is recommended that NMS user interfaces display and allow Various Authors Expires September 1, 2001 [Page 30] Internet Draft Policy-Based Management MIB Mar 1, 2001 input of MIB object names by their descriptor values followed by the index in dotted-decimal form (e.g., "ifType.7"). 9.1.2.4. searchcolumn() integer searchcolumn(string columnoid, string &oid, var pattern, integer mode) searchcolumn performs an SNMP walk on a portion of the MIB searching for objects with values equal to the `value' parameter. 'columnoid' constrains the search to only those variables that share the same OID prefix (i.e. are beneath it in the OID tree). A getnext packet will be sent requesting the object identifier 'oid'. If 'oid' is an empty string, the value of 'columnoid' will be sent. The value returned in each response packet will be transformed to a string representation of the value of the returned variable. The string representation of the value will be formed by putting the value in the form dictated by the "Form of SNMP Values" rules, and then performing the ToString() function on this value, forming 'SearchString'. The 'mode' value controls what type of match to perform on this value. There are 6 possibilities for mode: mode Search Action 0 Case sensitive exact match of 'pattern' and 'SearchString' 1 Case insensitive exact match of 'pattern' and 'SearchString' 2 Case sensitive substring match, finding 'pattern' in 'SearchString' 3 Case isensitive substring match, finding 'pattern' in 'SearchString' 4 Case sensitive regular expression match, searching 'SearchString' for the regular expression given in 'pattern'. 5 Case isensitive regular expression match, searching 'SearchString' for the regular expression given in 'pattern'. Various Authors Expires September 1, 2001 [Page 31] Internet Draft Policy-Based Management MIB Mar 1, 2001 searchcolumn uses the POSIX extended regular expressions defined in POSIX 1003.2. If the `case` argument is 0, the search will be case insensitive, otherwise it will be case sensitive. If a match is found, 'oid' is set to the oid of the matched value and 1 is returned. If the search traverses beyond columnoid or returns an error without finding a match, zero is returned and oid isn't modified. To find the first match, the caller should set 'oid' to the empty string. To find additional matches, subsequent calls to searchcolumn sould have 'oid' set to the oid of the last match, an operation than searchcolumn performs automatically. For example: To find an ethernet interface oid = ""; searchcolumn("ifType", oid, "6", Integer); This sends a getnext request for ifType and continues to walk the tree until a value matching 6 is found or a variable returns that is not in the 'ifType' subtree. To find the next ethernet interface, assuming interface #3 was discovered to be the first: oid = "ifType.3"; searchcolumn("ifType", oid, "6", Integer); In a loop, this looks simply like: oid = ""; while(searchcolumn("ifType", oid, "6", Integer)){ /* Do something with oid */ } Note that in the preceeding examples, "ifType" is used as a notational convenience and the actual code downloaded to the policy MIB agent must use the string "1.3.6.1.2.1.2.2.1.3" as there may be no MIB compiler (or MIB) available on the policy MIB agent. Various Authors Expires September 1, 2001 [Page 32] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.1.2.5. setRowStatus() integer setRowStatus(string oid, integer maxTries [, integer seed]) setRowStatus is used to automate the process of finding an unused row in a read-create table that uses RowStatus. 'oid' is a string containing an ASCII dotted-decimal representation of an object identifier, with one of the subids replaced with a '*' character (e.g. "1.3.6.1.3.1.99.1.2.1.9.*"). 'oid' must reference an 'instance' of the RowStatus object and the '*' must replace any integer index item that may be set to some random value. setRowStatus will come up with a number for the selected index item and will attempt to create the instance with the createAndWait state. If the attempt fails, it will retry with a different random index value. It will attempt this no more than 'maxTries' times. If the optional 'seed' argument is present, the initial index will be set to 'seed'. Otherwise it will be random. setRowStatus returns the successful integer value for the index. If unsuccessful after 'maxTries' or if more than one '*' is in oid, -1 will be returned. Various Authors Expires September 1, 2001 [Page 33] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.1.2.6. counterRate() When a policy wishes to make a decision based on the rate of a counter, it faces a couple of problems: 1. It may need to run every X minutes, but need to make decisions on rates calculated over at least Y minutes where Y > X. This would require the complexity of managing a queue of old counter values. 2. The policy script has no control over exactly when it will run The counterRate() function is designed to easily surmount these problems. integer counterRate(string oid, int minInterval [, integer 64bit]) counterRate retrieves the variable specified by oid once per invocation. It keeps track of timestamped values retrieved on previous invocations by this execution context so that it can calculate a rate over a longer period than since the last invocation. 'oid' is the object identifier that will be retrieved. A previously-saved value of the same object identifier that is older than 'minInterval' seconds old will be subtracted from the newly-retrieved value, yielding a delta. This delta will be divided by the number of seconds elapsed between the two retrievals and the integer-valued result will be returned. If there was no previously-saved retrieval older than 'minInterval' seconds, then -1 will be returned. The delta calculation will allow for 32-bit counter semantics if it encounters rollover between the two retrievals unless the the optional argument '64bit' is present and equal to 1, in which case it will allow for 64-bit counter semantics. The implementation will need to store a number of timestamped counter values. The implementation is free to throw away old values as long as it retains at least one value that is older than minInterval seconds. Various Authors Expires September 1, 2001 [Page 34] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.1.2.7. counter32Delta() If a (single) counter overflow occurs between successive retrievals of a Counter32 object, the delta can still be retrieved accurately but it has to be done consistent with 32 bit unsigned rollover semantics. This function is useful to simplify that process in an environment where all counters are 64 bits. Example: var counter, lastcounter, delta; counter = getvar("ifInOctets.$0"); if (getScratchpad(PolicyElement, "inOctets", lastcounter)){ // if returns 0, no value was stored, so punt to next iteration delta = counter32Delta(lastcounter, counter); } setScratchpad(PolicyElement, "inOctets", counter); /* * delta now contains the 32bit delta of ifInoctets since the last * iteration. */ integer counter32Delta(integer old, integer new) counter32Delta returns the delta between 'new' and 'old' compensating for the potential 32-bit unsigned rollover of the counter between the sampling of 'new' and 'old'. 9.1.3. General SNMP Functions It is desireable for a general SNMP interface have the ability to perform SNMP operations on multiple variables at once and for it to allow multiple varbind lists to exist at once. The newPdu, readVar and writeVar functions exist in order to provide these facilities in a language without pointers, arrays and memory allocators. newPDU is called to allocate a PDU and return an integer handle to it. Since PDUs are automatically freed when the script exits and because they can be reused during execution, there is no freePDU(). Various Authors Expires September 1, 2001 [Page 35] Internet Draft Policy-Based Management MIB Mar 1, 2001 readVar and writeVar access a variable length varbindlist for a PDU. The PDU handle and the index of the variable within that PDU are specified in every readVar and writeVar operation. Once a PDU has been fully specified by one or more calls to writeVar, it is passed to snmpsend (by referencing the PDU handle) and the number of varbinds to be included in the operation. When a response is returned, the contents of the response are in the same varbindlist (i.e. the same PDU handle is used) and may be read by one or more calls to readVar. Varbinds in this data store are created automatically whenever they are written by any writeVar, readVar, or snmpsend operation. It is an RTE to read a varbind that has not been previously written. For example: var pdu = newPDU(); writeVar(pdu, 0, "sysDescr.0", ...); writeVar(pdu, 1, "sysOID.0", ...); writeVar(pdu, 2, "ifNumber.0", ...); if (snmpsend(pdu, 3, Get, ...)) return; readVar(pdu, 0, iKnowItsSysDescr, iKnowItsaString, value); readVar(pdu, 1, ...) readVar(pdy, 2, ...) ... or, var pdu = newPDU(); writeVar(pdu, 0, "ifIndex", ...); writeVar(pdu, 1, "ifType", ...); while(!done){ if (snmpsend(pdu, 2, Getnext, ...)) continue; readVar(pdu, 0, oid1, ...); readVar(pdu, 1, oid2, ...); /* leave OIDs alone, now varbindlist #0 is set up for next step in table walk. */ if (oidncmp(oid1, "ifIndex", oidlen("ifIndex"))) done = 0; ... } Various Authors Expires September 1, 2001 [Page 36] Internet Draft Policy-Based Management MIB Mar 1, 2001 Note that in the preceeding examples, descriptors such as ifType and sysDescr are used in object identifiers solely as a notational convenience and the actual code downloaded to the policy MIB agent must use a dotted decimal notation only as there may be no MIB compiler (or MIB) available on the policy MIB agent. It is suggested that implementations limit the total number of PDUs per invocation to protect other script invocations from a malfunctioning script (e.g. a script that calls newPDU() in a loop). To be conformant to this specification, implementations must allow each policy script invocation to allocate at least 5 varbindlists with at least 32 varbinds per list. 9.1.3.1. newPDU() integer newPDU() newPDU will allocate a new PDU and return a handle to the PDU. If no PDU could be allocated, -1 will be returned. 9.1.3.2. writeVar() writeVar(integer pdu, integer varBindIndex, string oid, var value, integer type) writeVar will store 'oid', 'value' and 'type' in the specified varbind. 'pdu' is the handle to a PDU allocated by newPDU(). 'varbindIndex' is a non-negative integer that identifies the varbind within the specified PDU modified by this call. The first varbind is number 0. '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"). 'value' is the value to be stored, of a type appropriate to the 'type' parameter. 'type' will be the type of the value parameter and will be set Various Authors Expires September 1, 2001 [Page 37] Internet Draft Policy-Based Management MIB Mar 1, 2001 to one of the values for DataType Constants. 9.1.3.3. readVar() readVar(integer pdu, integer varBindIndex, string &oid, var &value, integer &type) readVar will retrieve the oid, the value and it's type from the specified varbind. 'pdu' is the handle to a PDU allocated by newPDU(). 'varbindIndex' is a non-negative integer that identifies the varbind within the specified PDU read by this call. The first varbind is number 0. The object identifier value of the referenced varbind will be copied into the 'oid' parameter, formatted in an ASCII dotted-decimal representation (e.g. "1.3.6.1.2.1.1.1.0"). 'value' is the value retrieved, of a type appropriate to the 'type' parameter. 'type' is the type of the value parameter and will be set to one of the values for DataType Constants. If 'pdu' doesn't reference a valid PDU or 'varBindIndex' doesn't reference a valid varbind, the function returns without modifying 'oid', 'value' or 'type'. 9.1.3.4. snmpsend() integer snmpsend(integer pdu, integer numVarbinds, integer opcode [, string context] [, string tagvalue] ) snmpsend will perform an SNMP operation using the specified varbindlist. Note that no actual SNMP PDU needs to be generated and parsed when the policy MIB module resides on the same system as the managed elements. Various Authors Expires September 1, 2001 [Page 38] Internet Draft Policy-Based Management MIB Mar 1, 2001 If the optional argument context is provided, the SNMP operation is performed on the indicated SNMP context. If the optional argument tagvalue is provided, the context argument must be provided as well. In this case, an SNMP PDU will be generated and sent to the management targets referenced by tagvalue and using the security information referenced by tagvalue. tagValue is a string in the form described by the SnmpTagValue TEXTUAL_CONVENTION in [14]. The results of the operation will be placed in the same varbindList. If an error occurred, the varbindlist will remain unmodified except for the following: 1) If the response PDU had a nonzero error-index, the varbind specified by the error-index will have its type field replaced with associated error-status constant. 2) If the response PDU contained varbinds with exceptions, the type field of those varbinds will be replaced with the appropriate exception (Nosuchobject, NosuchInstance, or Endofmibview). 3) If the error-status was zero and there were no exceptions, the varbindlist will remain unmodified. (some examples of situations where this will apply are timeout and authentication failure). This function returns zero unless an error occurs in which case it returns the proper SNMP Error Constant. 'pdu' is the handle to a PDU allocated by newPDU(). 'numVarbinds' is a integer greater than zero that specified which varbinds in the varbindList will be used in this operation. The first N varbinds in the varbindList are used. 'opcode' is the type of SNMP operation to perform and must be one of the values for SNMP Operation Constants. 9.2. Constants The following constants are defined for use in all SNMP Accessor Functions. Policy code will be executed in an environment where the following constants are declared. (Note that these constant declarations will not be visible in the Various Authors Expires September 1, 2001 [Page 39] Internet Draft Policy-Based Management MIB Mar 1, 2001 policyFilter or policyAction code.) While these declarations are expressed here as C 'const's, the 'const' construct itself is not available to be used inside of policy code. -- Datatype Constants const int Integer = 1; const int String = 2; const int Oid = 3; const int Integer32 = 4; const int Ipaddress = 5; const int Counter32 = 6; const int Gauge32 = 7; const int Unsigned32 = 8; const int Timeticks = 9; const int Opaque = 10; const int Counter64 = 11; -- SNMP Error Constants const int Nosuchobject = 21; const int Nosuchinstance = 22; const int Endofmibview = 23; const int Noerror = 24; const int Toobig = 25; const int Nosuchname = 26; const int Badvalue = 27; const int Readonly = 28; const int Generr = 29; const int Noaccess = 30; const int Wrongtype = 31; const int Wronglength = 32; const int Wrongencoding = 33; const int Wrongvalue = 34; const int Nocreation = 35; const int Inconsistentvalue = 36; const int Resourceunavailable = 37; const int Commitfailed = 38; const int Undofailed = 39; const int Authorizationerror = 40; const int Notwritable = 41; const int Badparameter = 42; Various Authors Expires September 1, 2001 [Page 40] Internet Draft Policy-Based Management MIB Mar 1, 2001 const int Toolong = 43; const int Parseerror = 44; const int Authfailure = 45; const int Timeout = 46; -- SNMP Operation Constants const int Get = 0; const int Getnext = 1; const int Set = 3; const int Trap = 4; const int Inform = 6; const int V2trap = 7; 9.3. Policy Configuration Accessor Functions Policy Configuration Accessor Functions provide access to information specifically related to the execution of policies. 9.3.1. roleMatch() The roleMatch() function is used to check to see if an element has been assigned a particular role. integer roleMatch(string roleString [, string element]) Argument 'roleString' is a string. The optional argument 'element' contains the OID address of an element, defaulting to the current element if this argument is not supplied. If roleString exactly matches (content and length) any role assigned to the specified element, the function returns 1. If no roles match, the function returns 0. 9.3.2. capMatch() The capMatch() function is used to check to see if an element has a certain capability. integer capMatch(string capOid[ , string element]) Argument 'capability' is a string containing a ASCII dotted-decimal representation of an object identifier Various Authors Expires September 1, 2001 [Page 41] Internet Draft Policy-Based Management MIB Mar 1, 2001 that describes a capability as would be found in the pmCapabilitiesTable. The optional argument 'element' contains the OID address of an element, defaulting to the current element if this argument is not supplied. If the specified element has the capability described by capString, this function returns 1, otherwise it returns 0. 9.3.3. elementName() The elementName() function is used to determine what the current element is and can be used to provide information about the type of element as well as how it is indexed. string elementName() elementName returns a string containing an ASCII dotted-decimal representation of an object identifier (e.g. 1.3.6.1.2.1.1.1.0). This object identifier identifies an instance of a MIB object that is an attribute of this element. 9.3.4. ic() The ic() and iv() functions provide convenient access to the components of the index for "this element". Typical uses will be in creating the index to other, related elements. integer ic() ic() returns an integer count of the number index subidentifiers exist in the index for "this element". 9.3.5. iv() The ic() and iv() functions provide convenient access to the components of the index for "this element". Typical uses will be in creating the index to other, related elements. integer iv(integer n) iv() returns the value of the n'th subidentifier in the index for 'this element". The first subidentifier is indexed at Various Authors Expires September 1, 2001 [Page 42] Internet Draft Policy-Based Management MIB Mar 1, 2001 0. It is an RTE if 'n' specifies a subidentifier beyond the last subidentifier. 9.3.6. setScratchpad() setScratchpad(integer scope, string varName, string value) Every maxLatency time period, every policy runs once for each element. When the setScratchpad function executes, it stores a value that can be retrieved even after this policy execution code exits. This allows sharing of data between a filter and an action, two filters executing on different elements, or even different policies altogether. The value of 'scope' controls which policy/element combinations can retrieve this 'varName'/'value' pair. The options for 'scope' are: Global The 'varName'/'value' combination will be available in the filter or action of any policy while executing on any element. Policy The 'varName'/'value' combination will be available in any future execution of the filter or action of the current policy (regardless of what element the policy is executing on). If a policy is ever deleted or its filter or action code is modified, all values in its 'Policy' scope will be deleted. PolicyElement The 'varName'/'value' combination will be available in future executions of the filter or action of the current policy but only when the policy is executing on the current element. If a policy is ever deleted or its filter or action code is modified, all values in its 'PolicyElement' scope will be deleted. 'varName' is a string used to identify the value. Subsequent retrievals of the same 'varName' in the proper scope will return the value stored. Note that the namespace for 'varName' is distinct for each scope. 'varName' is case sensitive. 'value' is a string containing the value to be stored. Various Authors Expires September 1, 2001 [Page 43] Internet Draft Policy-Based Management MIB Mar 1, 2001 ToString(value) is called on this argument to convert it to a string before storage. Note that there may be implementation-specific limits on the number of scratchpad variables that can be allocated. The limit of unique scratchpad variables may be different for each scope. Contents of the scratchpad are erased on reboot. 9.3.7. getScratchpad() integer getScratchpad(integer scope, string varName, string &value) The getScratchpad function allows the retrieval of values that were stored previously in this execution context or in other execution contexts. The value of 'scope' controls which execution contexts can pass a value to this execution context. Refer to the definition of setScratchpad to see which values of 'scope' can pass a value to which execution contexts. 'varName' is a string used to identify the value. Subsequent retrievals of the same 'varName' in the proper scope will return the value stored. Note that the namespace for varName is distinct for each scope. As a result, getScratchpad cannot force access to a variable in an inaccessible scope - it can only retrieve variables by referencing the proper scope in which they were set. 'varName' is case sensitive. On successful return, 'value' will be set to the value that was previously stored, otherwise 'value' will not be modified. This function returns 1 if a value was previously stored and 0 otherwise. Scratchpad Usage Examples Policy Element Action A ifIndex.1 setScratchpad("foo", Global, "55") A ifIndex.1 getScratchpad("foo", Global, val) == 55 A ifIndex.2 getScratchpad("foo", Global, val) == 55 B ifIndex.2 getScratchpad("foo", Global, val) == 55 B ifIndex.2 setScratchpad("foo", Global, "16") Various Authors Expires September 1, 2001 [Page 44] Internet Draft Policy-Based Management MIB Mar 1, 2001 A ifIndex.1 getScratchpad("foo", Global, val) == 16 Policy Element Action A ifIndex.1 setScratchpad("bar", Policy, "75") A ifIndex.1 getScratchpad("bar", Policy, val) == 75 A ifIndex.2 getScratchpad("bar", Policy, val) == 75 B ifIndex.1 getScratchpad("bar", Policy, val) not found B ifIndex.1 setScratchpad("bar", Policy, "20") A ifIndex.2 getScratchpad("bar", Policy, val) == 75 B ifIndex.2 getScratchpad("bar", Policy, val) == 20 Policy Element Action A ifIndex.1 setScratchpad("baz", PolicyElement, "43") A ifIndex.1 getScratchpad("baz", PolicyElement, val) == 43 A ifIndex.2 getScratchpad("baz", PolicyElement, val) not found B ifIndex.1 getScratchpad("baz", PolicyElement, val) not found A ifIndex.2 setScratchpad("baz", PolicyElement, "54") B ifIndex.1 setScratchpad("baz", PolicyElement, "65") A ifIndex.1 getScratchpad("baz", PolicyElement, val) == 43 A ifIndex.2 getScratchpad("baz", PolicyElement, val) == 54 B ifIndex.1 getScratchpad("baz", PolicyElement, val) == 65 Policy Element Action A ifIndex.1 setScratchpad("foo", PolicyElement, "11") A ifIndex.1 setScratchpad("foo", Global, "22") A ifIndex.1 getScratchpad("foo", PolicyElement, val) == 11 A ifIndex.1 getScratchpad("foo", Global, val) == 22 9.3.8. Constants The following constants are defined for use for the scratchpad functions. Policy code will be executed in an environment where the following constants are declared. (Note that these constant declarations will not be visible in the policyFilter or policyAction MIB objects.) While these declarations are expressed here as C 'const's, the 'const' construct itself is not available to be used inside of policy code. -- Scratchpad Constants const int Global = 0; const int Policy = 1; Various Authors Expires September 1, 2001 [Page 45] Internet Draft Policy-Based Management MIB Mar 1, 2001 const int PolicyElement = 2; 9.3.9. signalException() The signalException() function is used to by the script to indicate to a management station that it is experiencing abnormal behavior. signalException() turns on the filterUserSignal(3) or actionUserSignal(5) bit in the associated pmTrackingPolicyToElementInfo object (subsequent calls to signalError() have no additional effect). This bit is initially cleared at the beginning of each execution, so if upon a subsequent execution, a script no longer calls this function, the bit will be cleared. signalException() The signalException function takes no arguments and returns no value. 9.3.10. getParameters() From time to time, policy scripts may desire 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() accessor 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. string getParameters() The getParameters function takes no arguments. It returns a string containing the value of the pmPolicyParameters object for the running policy. 9.4. Utility Accessor Functions Utility Accessor Functions are provided to enable more efficient use of the other accessor functions. Various Authors Expires September 1, 2001 [Page 46] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.4.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 the `case` argument 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, the text of the first match will be copied to 'match'. If no match is found it will be unchanged. 9.4.2. regexp_replace() string regexp_replace(string pattern, string replacement, string str, integer case) regexp_replace searches 'str' for matches to the regular expression given in `pattern`, replacing the matched text with 'replacement'. regexp_replace uses the POSIX extended regular expressions defined in POSIX 1003.2. If the `case` argument is 0, the search will be case insensitive, otherwise it will be case sensitive. The modified string is returned (which could be the same as the original string if no matches were found). 9.4.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"). Various Authors Expires September 1, 2001 [Page 47] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.4.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 the first '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'. 9.4.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 is provided because this is an idiom and because it avoids evaluating 'prefix' twice if is an expression. 9.4.6. subid() integer subid(string oid, integer n) subid returns the value of the 'n'th (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. 9.4.7. subidwrite() integer subidwrite(string oid, integer n, integer subid) Various Authors Expires September 1, 2001 [Page 48] Internet Draft Policy-Based Management MIB Mar 1, 2001 subidwrite sets the value of the 'n'th (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. 9.4.8. oidsplice() string oidsplice(string oid1, integer offset, integer len, string oid2) oidsplice replaces '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'. The resulting oid is returned. 9.4.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[5]. '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 set to -1 on return. If the input index refers past the end of the oid, 'index' will be set to -1 on return. If 'type' is Integer, 'len' will not be consulted. The return value is the integer value of the next subid. Various Authors Expires September 1, 2001 [Page 49] Internet Draft Policy-Based Management MIB Mar 1, 2001 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, the 'index' argument 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 this 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, the 'index' argument 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, the 'index' argument 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 Various Authors Expires September 1, 2001 [Page 50] Internet Draft Policy-Based Management MIB Mar 1, 2001 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. 9.4.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. 9.4.11. Integer() integer Integer(var input) Integer converts 'input' into an integer by using the rules specified for ToInteger(), returning the integer-typed results. 9.4.12. String() string String(var input) String converts 'input' into a string by using the rules specified for ToString(), returning the string-typed results. 9.4.13. Type() string Type(var variable) Various Authors Expires September 1, 2001 [Page 51] Internet Draft Policy-Based Management MIB Mar 1, 2001 Type returns the type of its argument as either the string 'String' or the string 'Integer'. 9.4.14. chr() string chr(integer utf8) Returns a one-character string containing the character specified by the UTF8 code contained in 'utf8'. Note that a property of UTF8 is that 7-bit ASCII characters are represented by the same UTF8 code-points as their ascii equalivents. 9.4.15. ord() integer ord(string str) Returns the UTF8 code-point value of the first character of 'str'. This function complements chr(). Note that a property of UTF8 is that 7-bit ASCII characters are represented by the same UTF8 code-points as their ascii equalivents. 9.4.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 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 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 Various Authors Expires September 1, 2001 [Page 52] Internet Draft Policy-Based Management MIB Mar 1, 2001 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. 9.5. Library Accessor Functions The following standard library accessor functions are provided: strncmp() strncasecmp() strlen() random() sprintf() sscanf() 10. Schedule Table This table is an adapted form of the schedTable, originally published in RFC 2591 [20]. The policy schedule table allows control over when a policy will be active based on the time of day. A policy that is controlled by a schedule immediately executes its policy filter (and conditionally the policyAction) when the schedule becomes active, periodically re-executing these scripts as appropriate until the schedule becomes inactive. If a policy is associated with multiple schedules, it is considered active at any moment at least one of the schedules is active. A policy that is not controlled by a schedule will be continuously active. The policy schedule table provides for scheduling of policies periodically or at specified dates and times. Policies are activated at the beginning of each scheduled duration and remain active until the end of the duration. Schedules can be enabled or disabled by modifying the pmSchedAdminStatus object. This allows pre-configured schedules to exist which are activated or deactivated by other management functions. Various Authors Expires September 1, 2001 [Page 53] Internet Draft Policy-Based Management MIB Mar 1, 2001 The term `scheduler' is used throughout this memo to refer to the entity which implements the schedule table and which activates and deactivates policies at the specified points in time. 10.1. Periodic Schedules Periodic schedules are based on fixed time periods between the initiation of scheduled activations. Periodic schedules are defined by specifying the number of seconds between two initiations. If the duration of a schedule causes it to remain active at the next initiation, it will remain active, with no interruption, into the next scheduled duration. 10.2. Calendar Schedules Calendar schedules allow policies to be activated at specified days of the week and days of the month. Calendar schedules are therefore aware of the notion of months, days, weekdays, hours and minutes. It is possible to specify multiple values for each calendar item. This provides a mechanism for defining complex schedules. For example, a schedule could be defined which is active the entire workday each weekday. Months, days and weekdays are specified using the objects pmSchedMonth, pmSchedDay and pmSchedWeekDay of type BITS. Setting multiple bits to one 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 bit fields for pmSchedMonth, pmSchedDay and pmSchedWeekDay are combined using an AND operation. For example, setting the bits june(5) and july(6) in pmSchedMonth and combining it with the bits monday(1) and friday(5) set in pmSchedWeekDay will result in a schedule which is restricted to every Monday and Friday in the months June and July. Wildcarding of calendar items is achieved by setting all bits to one. It is possible to define calendar schedules that will never trigger cause a policy to be activated. For example, one can Various Authors Expires September 1, 2001 [Page 54] Internet Draft Policy-Based Management MIB Mar 1, 2001 define a calendar schedule which should be active on February 31st. Schedules like this will simply be ignored by the scheduler. Finally, calendar schedules are always expressed in local time. A scalar, pmSchedLocalTime is provided so that a manager can retrieve the notion of local time and the offset to GMT time. 10.3. One-shot Schedules One-shot Schedules are similar to calendar schedules. The difference between a calendar schedule and a one-shot schedule is that a one-shot schedule will automatically disable itself the first time it moves from the active state to the inactive state. Various Authors Expires September 1, 2001 [Page 55] Internet Draft Policy-Based Management MIB Mar 1, 2001 11. Definitions POLICY-MANAGEMENT-MIB DEFINITIONS ::= BEGIN IMPORTS MODULE-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE, Counter32, Integer32, Gauge32, Unsigned32, experimental FROM SNMPv2-SMI RowStatus, RowPointer, TEXTUAL-CONVENTION, DateAndTime, StorageType, TDomain, TAddress FROM SNMPv2-TC MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP FROM SNMPv2-CONF SnmpAdminString FROM SNMP-FRAMEWORK-MIB; -- Policy-Based Management MIB policyMgt MODULE-IDENTITY LAST-UPDATED "200103011500Z" -- March 1, 2001 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 JDS Consulting, Inc. 174 Chapman St. Watertown MA 02472-3063 USA Phone: +1-617-744-1079 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 Various Authors Expires September 1, 2001 [Page 56] Internet Draft Policy-Based Management MIB Mar 1, 2001 Email: hongal@riverstonenet.com" DESCRIPTION "The MIB module for rule-based configuration of SNMP infrastructures." REVISION "200103011500Z" -- March 1, 2001 DESCRIPTION "The original version of this MIB, published as RFCXXXX." ::= { experimental 107 } UTF8String ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "An octet string containing information typically in human-readable form. To facilitate internationalization, this information is represented using the ISO/IEC IS 10646-1 character set, encoded as an octet string using the UTF-8 transformation format described in [RFC2279]. Since 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 0x7fffffff. Byte sequences that do not correspond to the valid UTF-8 encoding of a code point or 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. Various Authors Expires September 1, 2001 [Page 57] Internet Draft Policy-Based Management MIB Mar 1, 2001 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 that is 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 [RFC1905]. Note that the size of an UTF8String object is measured in octets, not characters." SYNTAX OCTET STRING -- The policy group pmPolicyTable OBJECT-TYPE SYNTAX SEQUENCE OF PmPolicyEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The policy table. A policy is a pairing of a policyFilter and a policyAction which is used to apply the action to a selected set of elements." ::= { policyMgt 1 } pmPolicyEntry OBJECT-TYPE SYNTAX PmPolicyEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the policy table." INDEX { pmPolicyIndex } ::= { pmPolicyTable 1 } PmPolicyEntry ::= SEQUENCE { pmPolicyIndex Unsigned32, pmPolicyGroup UTF8String, pmPolicyPrecedence Unsigned32, pmPolicySchedule Unsigned32, Various Authors Expires September 1, 2001 [Page 58] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmPolicyFilter Unsigned32, pmPolicyAction Unsigned32, pmPolicyParameters OCTET STRING, pmPolicyFilterMaxLatency Unsigned32, pmPolicyActionMaxLatency Unsigned32, pmPolicyMaxIterations Unsigned32, pmPolicyDescription UTF8String, pmPolicyMatches Gauge32, pmPolicyAbnormalTerminations Gauge32, pmPolicyExecutionErrors Counter32, pmPolicyDebugging INTEGER, pmPolicyAdminStatus INTEGER, pmPolicyStorageType StorageType, pmPolicyRowStatus RowStatus } pmPolicyIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for this policy entry." ::= { pmPolicyEntry 1 } pmPolicyGroup OBJECT-TYPE SYNTAX UTF8String (SIZE (0..32)) MAX-ACCESS read-create STATUS current DESCRIPTION "An administratively assigned string that is used to group policies. Of all policies in the same group, only one will have its policyAction active on an element at any instance." ::= { pmPolicyEntry 2 } pmPolicyPrecedence OBJECT-TYPE SYNTAX Unsigned32 (0..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "If while checking to see which policy filters match an element, 2 or more policies in the same group match the same element, the pmPolicyPrecedence object provides the rule to arbitrate which single policy action will be executed on this element. Of policies in the same group, only the matching policy with the highest precedence value will have its policy Various Authors Expires September 1, 2001 [Page 59] Internet Draft Policy-Based Management MIB Mar 1, 2001 action periodically executed on this element. In the case where multiple policies share the highest value, it is an implementation-dependent matter as to which single policy action will be chosen." ::= { pmPolicyEntry 3 } pmPolicySchedule OBJECT-TYPE SYNTAX Unsigned32 (1..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "If this entry contains a valid pmSchedGroupIndex value, this policy will be activated as specified by the associated schedule entries. Whenever any schedule in the group is active, this policy will be active. If the value of this object is 0, this policy is always active." ::= { pmPolicyEntry 4 } pmPolicyFilter OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "A pointer to the row or rows in the pmPolicyCodeTable that contain the filter code for this policy. When a policy entry is created, an unused pmPolicyCodeIndex value will be assigned to this object. A policy filter is one or more PolicyScript statements which results in a boolean value that represents whether or not an element is a member of a set of elements upon which an action is to be performed. Filter evaluation stops immediately when any run-time exception is detected and the policyAction is not executed. The policyFilter is evaluated for various elements. Any element for which the policyFilter returns any nonzero value will match the filter and will have the associated policyAction executed on that element. If the filter object is empty (contains no code) or otherwise does not return a value, the element will not be matched. Various Authors Expires September 1, 2001 [Page 60] Internet Draft Policy-Based Management MIB Mar 1, 2001 When executing this filter, if SNMP requests are made to the local system, access to objects is under the security credentials of the the requester who modified the most recently modified pmPolicyCodeEntry associated with either the pmPolicyFilter value or pmPolicyAction value. In other words, modification of any part of a policy's filter or action will change the credentials stored for the policy. These credentials are the input parameters for isAccessAllowed from the Architecture for Describing SNMP Management Frameworks[1]." ::= { pmPolicyEntry 5 } pmPolicyAction OBJECT-TYPE SYNTAX Unsigned32 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, an unused pmPolicyCodeIndex value will be assigned to this object. A pmPolicyAction is an operation performed on a set of elements. Action evaluation stops immediately when any run-time exception is detected. When executing this action, if SNMP requests are made to the local system, access to objects is under the security credentials of the the requester who modified the most recently modified pmPolicyCodeEntry associated with either the pmPolicyFilter value or pmPolicyAction value. In other words, modification of any part of a policy's filter or action will change the credentials stored for the policy. These credentials are the input parameters for isAccessAllowed from the Architecture for Describing SNMP Management Frameworks[1]." ::= { pmPolicyEntry 6 } pmPolicyParameters OBJECT-TYPE Various Authors Expires September 1, 2001 [Page 61] Internet Draft Policy-Based Management MIB Mar 1, 2001 SYNTAX OCTET STRING MAX-ACCESS read-create STATUS current DESCRIPTION "From time to time, policy scripts may desire 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() accessor function. If it is necessary for multiple parameters to be passed to the script, the script can choose whatever encoding/deliminiting mechanism is most appropriate." ::= { pmPolicyEntry 7 } pmPolicyFilterMaxLatency OBJECT-TYPE SYNTAX Unsigned32 UNITS "milliseconds" MAX-ACCESS read-create STATUS current DESCRIPTION "Every element under the control of this agent is re-checked periodically to see if it is under control of this policy by re-running the filter 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 it is an implementation-dependent matter as to how the policy agent schedules the checking of various elements within this interval." ::= { pmPolicyEntry 8 } pmPolicyActionMaxLatency OBJECT-TYPE SYNTAX Unsigned32 UNITS "milliseconds" MAX-ACCESS read-create STATUS current DESCRIPTION "Every element that matches this policy's filter 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. Various Authors Expires September 1, 2001 [Page 62] Internet Draft Policy-Based Management MIB Mar 1, 2001 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 it is an implementation-dependent matter as to how the policy agent schedules the policy action on various elements within this interval." ::= { pmPolicyEntry 9 } pmPolicyMaxIterations OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-create STATUS current DESCRIPTION "If a filter or action script iterates in loops too many time in one invocation, it may be considered by the execution environment to be 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. It is an implementation-dependent manner as to what threshold the execution environment uses, 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. Note that the filter and action invocations are tracked separately." ::= { pmPolicyEntry 10 } pmPolicyDescription OBJECT-TYPE SYNTAX UTF8String MAX-ACCESS read-create STATUS current DESCRIPTION "A description of this rule and its significance, typically provided by a human." ::= { pmPolicyEntry 11 } pmPolicyMatches OBJECT-TYPE SYNTAX Gauge32 UNITS "elements" MAX-ACCESS read-only Various Authors Expires September 1, 2001 [Page 63] Internet Draft Policy-Based Management MIB Mar 1, 2001 STATUS current DESCRIPTION "The number of elements that, in their most recent execution of the associated filter, were matched by the filter." ::= { pmPolicyEntry 12 } 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 filter 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 on a subsequent invocation it runs normally, this number can decline." ::= { pmPolicyEntry 13 } 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 filter or action has been terminated due to run-time exceptions." ::= { pmPolicyEntry 14 } pmPolicyDebugging OBJECT-TYPE SYNTAX INTEGER { off(0), on(1) } MAX-ACCESS read-create STATUS current DESCRIPTION "The status of debugging for this policy. If this is turned on(1), log entries will be created in the pmDebuggingTable for each run-time exception that is experienced by this policy." DEFVAL { off } ::= { pmPolicyEntry 15 } Various Authors Expires September 1, 2001 [Page 64] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmPolicyAdminStatus OBJECT-TYPE SYNTAX INTEGER { inactive(0), active(1), activeAutoRemove(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "The admin status of this policy. The policy will be runnable only if the associated pmPolicyRowStatus is set to active(1) or activeAutoRemove(2) and this object is set to active(1). If this object is set to activeAutoRemove(2), 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. [Note to reader: This object exists because a row cannot sit for extended periods of time with it's rowstatus set to inactive (it is subject to garbage collection. This object allows policies to be downloaded but not run except at the convenience of the management station.]" ::= { pmPolicyEntry 16 } 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." ::= { pmPolicyEntry 17 } pmPolicyRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The row status of this pmPolicyEntry. Various Authors Expires September 1, 2001 [Page 65] Internet Draft Policy-Based Management MIB Mar 1, 2001 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 and if any of the objects in this row are not set to valid values. If this row is deleted, any associated entries in the pmPolicyCodeTable will be deleted as well." ::= { pmPolicyEntry 18 } -- Policy Code Table pmPolicyCodeTable OBJECT-TYPE SYNTAX SEQUENCE OF PmPolicyCodeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The pmPolicyCodeTable stores the code for policy filters and actions." ::= { policyMgt 2 } pmPolicyCodeEntry OBJECT-TYPE SYNTAX PmPolicyCodeEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the policy code table." INDEX { pmPolicyCodeProgramIndex, pmPolicyCodeSegment } ::= { pmPolicyCodeTable 1 } PmPolicyCodeEntry ::= SEQUENCE { pmPolicyCodeProgramIndex Unsigned32, pmPolicyCodeSegment Unsigned32, pmPolicyCodeText UTF8String, pmPolicyCodeStatus RowStatus } pmPolicyCodeProgramIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for each policy filter or action. The code for each such filter or action may be composed of multiple entries in this table if the code cannot fit in one entry. Various Authors Expires September 1, 2001 [Page 66] Internet Draft Policy-Based Management MIB Mar 1, 2001 Values of pmPolicyCodeProgramIndex may not be used unless they have previously been assigned in the pmPolicyFilterProgramIndex or pmPolicyActionProgramIndex objects." ::= { pmPolicyCodeEntry 1 } pmPolicyCodeSegment OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for each segment of a policy filter or action. When a policy filter 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 ending with the highest-numbered segment." ::= { pmPolicyCodeEntry 2 } pmPolicyCodeText OBJECT-TYPE SYNTAX UTF8String (SIZE (1..1024)) MAX-ACCESS read-create STATUS current DESCRIPTION "A segment of policy code (filter or action). Lengthy Policy filters or actions may be stored in multiple segments in this table that share the same value of pmPolicyCodeProgramIndex. When multiple segments are used, it is recommended that each segment be as large as practical. Entries in this table are associated with policies by values of the pmPolicyFilterProgramIndex and pmPolicyActionProgramIndex 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. Various Authors Expires September 1, 2001 [Page 67] Internet Draft Policy-Based Management MIB Mar 1, 2001 Entries in this table are associated with policies by values of the pmPolicyFilterProgramIndex and pmPolicyActionProgramIndex objects. If the status of the related policy is active, then entries in this table may not be created or deleted." ::= { pmPolicyCodeEntry 4 } -- Element Type Registration Table -- The Element Type Registration table is used for 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 address of the element is the index part of -- the discovered OID. This address will be supplied to policy filters -- and actions so that this code can inspect and configure the -- element. pmElementTypeRegTable OBJECT-TYPE SYNTAX SEQUENCE OF PmElementTypeRegEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A registration table for element types managed by this system. Before registering an element type, it is the responsibility of a manager to inspect the table and see if it is already registered (by the agent or another manager). Note that entries that differ only in the last OID (which specifies which object in an entry) are effectively duplicates and should be treated as such by the manager. 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 Various Authors Expires September 1, 2001 [Page 68] Internet Draft Policy-Based Management MIB Mar 1, 2001 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." ::= { policyMgt 3 } pmElementTypeRegEntry OBJECT-TYPE SYNTAX PmElementTypeRegEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A registration of an element type." INDEX { pmElementTypeRegIndex } ::= { pmElementTypeRegTable 1 } PmElementTypeRegEntry ::= SEQUENCE { pmElementTypeRegIndex Unsigned32, pmElementTypeRegOIDPrefix OBJECT IDENTIFIER, pmElementTypeRegMaxLatency Unsigned32, pmElementTypeRegName UTF8String, pmElementTypeRegStorageType StorageType, pmElementTypeRegRowStatus RowStatus } pmElementTypeRegIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for this entry." ::= { pmElementTypeRegEntry 1 } pmElementTypeRegOIDPrefix OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-create STATUS current DESCRIPTION "An OBJECT IDENTIFIER subtree under which all instances of this element type may be found. This OBJECT IDENTIFIER should be specified up to, but not including, any index objects. The agent will discover all instances in the system that are members of the specified subtree. Each instance in this subtree becomes a distinct element. The agent will then execute policy filters (and Various Authors Expires September 1, 2001 [Page 69] Internet Draft Policy-Based Management MIB Mar 1, 2001 potentially policy actions) for each instance discovered. The index of each discovered instance becomes the address of the associated element. For each element, the address of 'this element' will be passed to each invocation of the policy filter. This is derived by taking the last N sub-identifiers from the discovered instance, where N is: X = number of sub-identifiers in pmElementTypeRegOIDPrefix Y = number of sub-identifiers in discovered instance N = Y - X A special OBJECT IDENTIFIER '0.0' can be written to this object. '0.0' represents the single instance of the system itself and provides an execution context for policies to operate on 'the system' as well as on MIB objects modelled 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). 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 address of 'this element' (in other words it has zero length)." ::= { 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 it is an implementation-dependent matter as to how the policy agent schedules the checking of various elements within this interval." ::= { pmElementTypeRegEntry 3 } pmElementTypeRegName OBJECT-TYPE Various Authors Expires September 1, 2001 [Page 70] Internet Draft Policy-Based Management MIB Mar 1, 2001 SYNTAX UTF8String (SIZE (0..32)) 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 if this row is backed up by non-volatile or permanent storage." ::= { pmElementTypeRegEntry 5 } pmElementTypeRegRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this registration entry." ::= { pmElementTypeRegEntry 6 } -- Role Table -- 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 contexts -- need 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 Various Authors Expires September 1, 2001 [Page 71] Internet Draft Policy-Based Management MIB Mar 1, 2001 -- 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 -- assignements for other systems can be stored in this table by -- providing values for the pmRoleTDomain and pmRoleTAddress -- parameters. -- -- For example: -- Example: -- element role context address #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 "" 10.1.2.3 different system -- ifindex.1 gold "" 10.1.2.4 different system pmRoleTable OBJECT-TYPE SYNTAX SEQUENCE OF PmRoleEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The role string table. The agent must store role string associations in nonvolatile storage." ::= { policyMgt 4 } pmRoleEntry OBJECT-TYPE SYNTAX PmRoleEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A role string entry associates a role string with an individual element." INDEX { pmRoleElement, pmRoleString, pmRoleContextName, pmRoleTDomain, IMPLIED pmRoleTAddress } ::= { pmRoleTable 1 } PmRoleEntry ::= SEQUENCE { pmRoleElement RowPointer, pmRoleString UTF8String, pmRoleContextName SnmpAdminString, Various Authors Expires September 1, 2001 [Page 72] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmRoleTDomain TDomain, pmRoleTAddress TAddress, pmRoleStatus RowStatus } pmRoleElement OBJECT-TYPE SYNTAX RowPointer MAX-ACCESS not-accessible STATUS current DESCRIPTION "The element to which this role string is associated. If the agent assigns new indexes in the MIB table to represent the same underlying element (re-indexing), the agent will modify this value to contain the new index for the underlying element." ::= { pmRoleEntry 1 } pmRoleString OBJECT-TYPE SYNTAX UTF8String (SIZE (0..64)) MAX-ACCESS read-create STATUS current DESCRIPTION "The role string that is associated with an element through this table. A role string is an administratively specified characteristic of a managed element (for example, an interface). It is a selector for policy rules, to determine the applicability of the rule to a particular managed element." ::= { pmRoleEntry 2 } pmRoleContextName OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-create STATUS current DESCRIPTION "If the associated element is not in the default context for the target system, this object is used to identify the context. If the element is in the default context, this object is equal to the empty string." ::= { pmRoleEntry 3 } pmRoleTDomain OBJECT-TYPE SYNTAX TDomain Various Authors Expires September 1, 2001 [Page 73] Internet Draft Policy-Based Management MIB Mar 1, 2001 MAX-ACCESS read-create STATUS current DESCRIPTION "This object indicates the transport type of the address contained in the pmRoleTAddress object. If there is no address, this object will have the value '0.0'" ::= { pmRoleEntry 4 } pmRoleTAddress OBJECT-TYPE SYNTAX TAddress MAX-ACCESS read-create STATUS current DESCRIPTION "If the associated element is on a remote system, this object is used to identify the remote system. This object contains a transport address. The format of this address depends on the value of the snmpTargetAddrTDomain object. If the element is on the local system this object will be the empty string." ::= { pmRoleEntry 5 } pmRoleStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this role string." ::= { pmRoleEntry 6 } -- Capabilities table -- The pmCapabilitiesTable contains a description of -- the inherent capabilities of the system so that scripts can -- differentially apply code based on the capabilities and so that -- management stations can learn of an agent's capabilities and -- differentially install policies based on the capabilities. pmCapabilitiesTable OBJECT-TYPE SYNTAX SEQUENCE OF PmCapabilitiesEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The pmCapabilitiesTable contains a description of the inherent capabilities of the system. Note that it is not necessary to list all Various Authors Expires September 1, 2001 [Page 74] Internet Draft Policy-Based Management MIB Mar 1, 2001 OIDs that a mechanism specific MIB Module supports, just the base OID if the implementation is a fully compliant one. If the implementation is not, then additional rows will exist in the table that list the limitations or enhancements." ::= { policyMgt 6 } pmCapabilitiesEntry OBJECT-TYPE SYNTAX PmCapabilitiesEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The description of a capability or limitation of a capability of the system. An entry will exist for each domain and mechanism specific ability the system has. In the case of a domain specific capability with no mechanism specific parameters, the pmCapabilitiesSubType and all other columns may be null. Entries will exist that contain values for the pmCapabilitiesRestrictOID, pmCapabilitiesRestrictType, pmCapabilitiesRestrictValue and pmCapabilitiesRestrictString objects only when an implementation is reporting a mechanism specific restriction. Multiple entries are possible when more than one restriction for a type or subtype are needed." INDEX { pmCapabilitiesIndex } ::= { pmCapabilitiesTable 1 } PmCapabilitiesEntry ::= SEQUENCE { pmCapabilitiesIndex Unsigned32, pmCapabilitiesType OBJECT IDENTIFIER, pmCapabilitiesSubType OBJECT IDENTIFIER, pmCapabilitiesModificationOID OBJECT IDENTIFIER, pmCapabilitiesModificationType INTEGER, pmCapabilitiesModificationValue Integer32, pmCapabilitiesModificationString OCTET STRING } pmCapabilitiesIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for this entry." ::= { pmCapabilitiesEntry 1 } pmCapabilitiesType OBJECT-TYPE Various Authors Expires September 1, 2001 [Page 75] Internet Draft Policy-Based Management MIB Mar 1, 2001 SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The type of the capability represented by this entry. The IANA will publish the list of identifiers that are valid values for this object." ::= { pmCapabilitiesEntry 2 } pmCapabilitiesSubType OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The sub type of capability is a pointer to a mechanism specific set of capabilities supporting a base technology. In the case of DIFFSERV, the OID value here would be the base OID of the Differentiated Services Policy MIB Module." ::= { pmCapabilitiesEntry 3 } pmCapabilitiesModificationOID OBJECT-TYPE SYNTAX OBJECT IDENTIFIER MAX-ACCESS read-only STATUS current DESCRIPTION "The OID of the object that is either not supported, supported with one or more limitations, or expanded by an implementation specific module. If this columnar object is other than null then there must be at least an entry in pmCapabilitiesModificationType. Note that this need not be a leaf node or scalar object. If an entire table is not supported, this value can be the base OID for the table." ::= { pmCapabilitiesEntry 4 } pmCapabilitiesModificationType OBJECT-TYPE SYNTAX INTEGER { unsupported(0), restricted(1), additional(2), addvalue(3), maxlimit(4), minlimit(5) } MAX-ACCESS read-only STATUS current Various Authors Expires September 1, 2001 [Page 76] Internet Draft Policy-Based Management MIB Mar 1, 2001 DESCRIPTION "An unsupported value indicates that the OID in pmCapabilitiesModificationOID is not supported on this system. A value of 1 indicates that the OID is supported but with restricted values These constraints are described in the pmCapabilitiesModificationValue and pmCapabilitiesModificationString objects. A value of 2 indicates a vendor specific extension to a standard. The OID of the new object is pmCapabilitiesModificationOID. For some implementations, additional functions may be provided. addvalue indicates that this row of the table describes an additional value that the object can take. The specific value is in the pmCapabilitiesModificationValue. The values of 4 and 5 indicate restrictions or the removal of restrictions for the object identified." ::= { pmCapabilitiesEntry 5 } pmCapabilitiesModificationValue OBJECT-TYPE SYNTAX Integer32 (0..2147483647) MAX-ACCESS read-only STATUS current DESCRIPTION "If the value of pmCapabilitiesModificationType is 0, this object will be null since 0 indicates no support for the object at all. A value of 1 in the pmCapabilitiesModificationType will be further modified by a single integer value in this object that corresponds to enumerated integer values that are not supported by the system for the object that is identified in this row. This value can also represent the limit values in the pmCapabilitiesModificationType object." ::= { pmCapabilitiesEntry 6 } pmCapabilitiesModificationString OBJECT-TYPE SYNTAX OCTET STRING MAX-ACCESS read-only STATUS current DESCRIPTION "Any additional details or description or parameters needed." ::= { pmCapabilitiesEntry 7 } pmSchedLocalTime OBJECT-TYPE SYNTAX DateAndTime (SIZE (11)) MAX-ACCESS read-only Various Authors Expires September 1, 2001 [Page 77] Internet Draft Policy-Based Management MIB Mar 1, 2001 STATUS current DESCRIPTION "The local time used by the scheduler. Schedules which refer to calendar time will use the local time indicated by this object. An implementation MUST return all 11 bytes of the DateAndTime textual-convention so that a manager may retrieve the offset from GMT time." ::= { policyMgt 7 } -- -- The schedule table which controls the scheduler. -- pmSchedTable OBJECT-TYPE SYNTAX SEQUENCE OF PmSchedEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "This table defines schedules for policies." ::= { policyMgt 8 } pmSchedEntry OBJECT-TYPE SYNTAX PmSchedEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry describing a particular scheduled action. Unless noted otherwise, writable objects of this row can be modified independent of the current value of pmSchedRowStatus, pmSchedAdminStatus and pmSchedOperStatus. In particular, it is legal to modify pmSchedInterval, pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour, and pmSchedMinute when pmSchedRowStatus is active and pmSchedAdminStatus and pmSchedOperStatus are both enabled." INDEX { pmSchedIndex } ::= { pmSchedTable 1 } PmSchedEntry ::= SEQUENCE { pmSchedIndex Unsigned32, pmSchedGroupIndex Unsigned32, pmSchedDescr SnmpAdminString, pmSchedInterval Unsigned32, pmSchedWeekDay BITS, pmSchedMonth BITS, Various Authors Expires September 1, 2001 [Page 78] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmSchedDay BITS, pmSchedHour BITS, pmSchedMinute BITS, pmSchedDuration Unsigned32, pmSchedType INTEGER, pmSchedAdminStatus INTEGER, pmSchedOperStatus INTEGER, pmSchedStorageType StorageType, pmSchedRowStatus RowStatus } pmSchedIndex OBJECT-TYPE SYNTAX Unsigned32 (1..65535) MAX-ACCESS not-accessible STATUS current DESCRIPTION "The locally-unique, administratively assigned index for this scheduling entry." ::= { pmSchedEntry 1 } pmSchedGroupIndex OBJECT-TYPE SYNTAX Unsigned32 (1..65535) MAX-ACCESS read-create STATUS current DESCRIPTION "The locally-unique, administratively assigned index for the group that this scheduling entry belongs to. To assign multiple schedule entries to the same group, the pmSchedGroupIndex of each entry in the group will be set to the same value. This pmSchedGroupIndex value must be equal to the pmSchedIndex of one of the entries in the group. If the entry is deleted whose pmSchedIndex equals the pmSchedGroupIndex for the group, the agent will assign a new pmSchedGroupIndex to all remaining members of the group. If an entry is not a member of a group, its pmSchedGroupIndex must be assigned to the value of its pmSchedIndex. Policies that are controlled by a group of schedule entries are active when any schedule in the group is active." ::= { pmSchedEntry 2 } pmSchedDescr OBJECT-TYPE SYNTAX SnmpAdminString Various Authors Expires September 1, 2001 [Page 79] Internet Draft Policy-Based Management MIB Mar 1, 2001 MAX-ACCESS read-create STATUS current DESCRIPTION "The human readable description of the purpose of this scheduling entry." DEFVAL { ''H } ::= { pmSchedEntry 3 } pmSchedInterval OBJECT-TYPE SYNTAX Unsigned32 UNITS "seconds" MAX-ACCESS read-create STATUS current DESCRIPTION "The number of seconds between two activations of a periodic scheduler. Implementations must guarantee that activations will not occur before at least pmSchedInterval seconds have passed. The scheduler must ignore all periodic schedules that have a pmSchedInterval value of 0. A periodic schedule with a scheduling interval of 0 seconds will therefore never invoke an action. Implementations may be forced to delay invocations in the face of local constraints. A scheduled management function should therefore not rely on the accuracy provided by the scheduler implementation." DEFVAL { 0 } ::= { pmSchedEntry 4 } pmSchedWeekDay OBJECT-TYPE SYNTAX BITS { sunday(0), monday(1), tuesday(2), wednesday(3), thursday(4), friday(5), saturday(6) } MAX-ACCESS read-create STATUS current DESCRIPTION "The set of weekdays on which the schedule should Various Authors Expires September 1, 2001 [Page 80] Internet Draft Policy-Based Management MIB Mar 1, 2001 be active. Setting multiple bits will include several weekdays in the set of possible weekdays for this schedule. Setting all bits will cause the scheduler to ignore the weekday." DEFVAL { {} } ::= { pmSchedEntry 5 } pmSchedMonth OBJECT-TYPE SYNTAX BITS { january(0), february(1), march(2), april(3), may(4), june(5), july(6), august(7), september(8), october(9), november(10), december(11) } MAX-ACCESS read-create STATUS current DESCRIPTION "The set of months during which the schedule should be active. Setting multiple bits will include several months in the set of possible months for this schedule. Setting all bits will cause the scheduler to ignore the month." DEFVAL { {} } ::= { pmSchedEntry 6 } pmSchedDay OBJECT-TYPE SYNTAX BITS { d1(0), d2(1), d3(2), d4(3), d5(4), d6(5), d7(6), d8(7), d9(8), d10(9), d11(10), d12(11), d13(12), d14(13), d15(14), d16(15), d17(16), d18(17), d19(18), d20(19), d21(20), d22(21), d23(22), d24(23), d25(24), d26(25), d27(26), d28(27), d29(28), d30(29), d31(30), r1(31), r2(32), r3(33), r4(34), r5(35), r6(36), r7(37), r8(38), r9(39), r10(40), r11(41), r12(42), r13(43), r14(44), r15(45), Various Authors Expires September 1, 2001 [Page 81] Internet Draft Policy-Based Management MIB Mar 1, 2001 r16(46), r17(47), r18(48), r19(49), r20(50), r21(51), r22(52), r23(53), r24(54), r25(55), r26(56), r27(57), r28(58), r29(59), r30(60), r31(61) } MAX-ACCESS read-create STATUS current DESCRIPTION "The set of days in a month on which a schedule should be active. There are two sets of bits one can use to define the day within a month: Enumerations starting with the letter 'd' indicate a day in a month relative to the first day of a month. The first day of the month can therefore be specified by setting the bit d1(0) and d31(30) means the last day of a month with 31 days. Enumerations starting with the letter 'r' indicate a day in a month in reverse order, relative to the last day of a month. The last day in the month can therefore be specified by setting the bit r1(31), and r31(61) means the first day of a month with 31 days. Setting multiple bits will include several days in the set of possible days for this schedule. Setting all bits will cause the scheduler to ignore the day within a month. Setting all bits starting with the letter 'd' or the letter 'r' will also cause the scheduler to ignore the day within a month." DEFVAL { {} } ::= { pmSchedEntry 7 } pmSchedHour OBJECT-TYPE SYNTAX BITS { h0(0), h1(1), h2(2), h3(3), h4(4), h5(5), h6(6), h7(7), h8(8), h9(9), h10(10), h11(11), h12(12), h13(13), h14(14), h15(15), h16(16), h17(17), h18(18), h19(19), h20(20), h21(21), h22(22), h23(23) } MAX-ACCESS read-create STATUS current DESCRIPTION "The set of hours within a day during which the schedule Various Authors Expires September 1, 2001 [Page 82] Internet Draft Policy-Based Management MIB Mar 1, 2001 should be active." DEFVAL { {} } ::= { pmSchedEntry 8 } pmSchedMinute OBJECT-TYPE SYNTAX BITS { m0(0), m1(1), m2(2), m3(3), m4(4), m5(5), m6(6), m7(7), m8(8), m9(9), m10(10), m11(11), m12(12), m13(13), m14(14), m15(15), m16(16), m17(17), m18(18), m19(19), m20(20), m21(21), m22(22), m23(23), m24(24), m25(25), m26(26), m27(27), m28(28), m29(29), m30(30), m31(31), m32(32), m33(33), m34(34), m35(35), m36(36), m37(37), m38(38), m39(39), m40(40), m41(41), m42(42), m43(43), m44(44), m45(45), m46(46), m47(47), m48(48), m49(49), m50(50), m51(51), m52(52), m53(53), m54(54), m55(55), m56(56), m57(57), m58(58), m59(59) } MAX-ACCESS read-create STATUS current DESCRIPTION "The set of minutes within an hour when the schedule should be active." DEFVAL { {} } ::= { pmSchedEntry 9 } pmSchedDuration OBJECT-TYPE SYNTAX Unsigned32 UNITS "seconds" MAX-ACCESS read-create STATUS current DESCRIPTION "The number of seconds the schedule will be active after invocation." ::= { pmSchedEntry 10 } pmSchedType OBJECT-TYPE SYNTAX INTEGER { periodic(1), calendar(2), oneshot(3) } MAX-ACCESS read-create STATUS current Various Authors Expires September 1, 2001 [Page 83] Internet Draft Policy-Based Management MIB Mar 1, 2001 DESCRIPTION "The type of this schedule. The value periodic(1) indicates that this entry specifies a periodic schedule. A periodic schedule is defined by the value of pmSchedInterval. The values of pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour and pmSchedMinute are ignored. The value calendar(2) indicates that this entry describes a calendar schedule. A calendar schedule is defined by the values of pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour and pmSchedMinute. The value of pmSchedInterval is ignored. A calendar schedule will be active on all local times that satisfy the bits set in pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour and pmSchedMinute. The value oneshot(3) indicates that this entry describes a one-shot schedule. A one-shot schedule is similar to a calendar schedule with the additional feature that it disables itself by changing in the `finished' pmSchedOperStatus once the schedule becomes inactive after its first activation. Changing a schedule's type is equivalent to deleting the old-type schedule and creating a new-type one." DEFVAL { periodic } ::= { pmSchedEntry 11 } pmSchedAdminStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2) } MAX-ACCESS read-create STATUS current DESCRIPTION "The desired state of the schedule." DEFVAL { disabled } ::= { pmSchedEntry 12 } pmSchedOperStatus OBJECT-TYPE SYNTAX INTEGER { enabled(1), disabled(2), finished(3) } Various Authors Expires September 1, 2001 [Page 84] Internet Draft Policy-Based Management MIB Mar 1, 2001 MAX-ACCESS read-only STATUS current DESCRIPTION "The current operational state of this schedule. The state enabled(1) indicates this entry is active and that the scheduler will invoke actions at appropriate times. The disabled(2) state indicates that this entry is currently inactive and ignored by the scheduler. The finished(3) state indicates that the schedule has ended. Schedules in the finished(3) state are ignored by the scheduler. A one-shot schedule enters the finished(3) state when it deactivates itself." ::= { pmSchedEntry 13 } pmSchedStorageType OBJECT-TYPE SYNTAX StorageType MAX-ACCESS read-create STATUS current DESCRIPTION "This object defines whether this scheduled action is kept in volatile storage and lost upon reboot or if this row is backed up by non-volatile or permanent storage. Conceptual rows having the value `permanent' must allow write access to the columnar objects pmSchedDescr, pmSchedInterval, pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour, pmSchedMinute and pmSchedAdminStatus." DEFVAL { volatile } ::= { pmSchedEntry 14 } pmSchedRowStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this scheduled action." ::= { pmSchedEntry 15 } -- Policy Tracking pmTrackingPolicyToElementTable OBJECT-TYPE SYNTAX SEQUENCE OF PmTrackingPolicyToElementEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION Various Authors Expires September 1, 2001 [Page 85] Internet Draft Policy-Based Management MIB Mar 1, 2001 "The pmTrackingPolicyToElementTable describes what elements are under control of a policy. This table is indexed in order to optimize retrieval of the entire status for a given policy." ::= { policyMgt 9 } pmTrackingPolicyToElementEntry OBJECT-TYPE SYNTAX PmTrackingPolicyToElementEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the pmTrackingPolicyToElementTable. The pmPolicyIndex in the index specifies the policy tracked by this entry." INDEX { pmPolicyIndex, pmTrackingPolicyToElementElement } ::= { pmTrackingPolicyToElementTable 1 } PmTrackingPolicyToElementEntry ::= SEQUENCE { pmTrackingPolicyToElementElement RowPointer, pmTrackingPolicyToElementInfo BITS } pmTrackingPolicyToElementElement OBJECT-TYPE SYNTAX RowPointer MAX-ACCESS not-accessible STATUS current DESCRIPTION "The element that is configured by the associated policy." ::= { pmTrackingPolicyToElementEntry 1 } pmTrackingPolicyToElementInfo OBJECT-TYPE SYNTAX BITS { filterMatched(0), actionSkippedDueToPrecedence(1), filterRunTimeException(2), filterUserSignal(3), actionRunTimeException(4), actionUserSignal(5) } MAX-ACCESS read-only STATUS current DESCRIPTION "This object returns information about the previous policy script executions. Various Authors Expires September 1, 2001 [Page 86] Internet Draft Policy-Based Management MIB Mar 1, 2001 If the filterMatched(0) bit is set, the last execution of the associated policy filter returned TRUE. If the actionSkippedDueToPrecedence(1) bit is set, the last execution of the associated policy filter returned TRUE but the action is not active because it was trumped by a matching policy filter in the same policy group with a higher precedence value. If the filterRunTimeException(2) bit is set, the last execution of the associated policy filter encountered a run-time exception and aborted. If the filterUserSignal(3) bit is set, the last execution of the associated policy filter called the signalException() function. If the actionRunTimeException(4) bit is set, the last execution of the associated policy action encountered a run-time exception and aborted. If the actionUserSignal(5) bit is set, the last execution of the associated policy action called the signalException() function. Entries will only exist in this table of one or more bits are set. In particular, if an entry does not exist for a particular policy/element combination, it can be assumed that the policy's filter did not match this element." ::= { pmTrackingPolicyToElementEntry 2 } -- Element to Policy Table pmTrackingElementToPolicyTable OBJECT-TYPE SYNTAX SEQUENCE OF PmTrackingElementToPolicyEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The pmTrackingElementToPolicyTable describes what policies are controlling an element. This table is indexed in order to optimize retrieval of the status of all policies active for a given element." ::= { policyMgt 10 } pmTrackingElementToPolicyEntry OBJECT-TYPE Various Authors Expires September 1, 2001 [Page 87] Internet Draft Policy-Based Management MIB Mar 1, 2001 SYNTAX PmTrackingElementToPolicyEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the pmTrackingElementToPolicyTable. The pmPolicyIndex in the index specifies the policy tracked by this entry." INDEX { pmTrackingElementToPolicyElement, pmPolicyIndex } ::= { pmTrackingElementToPolicyTable 1 } PmTrackingElementToPolicyEntry ::= SEQUENCE { pmTrackingElementToPolicyElement RowPointer, pmTrackingElementToPolicyStatus INTEGER } pmTrackingElementToPolicyElement OBJECT-TYPE SYNTAX RowPointer MAX-ACCESS not-accessible STATUS current DESCRIPTION "The element configured by the associated policy." ::= { pmTrackingElementToPolicyEntry 1 } pmTrackingElementToPolicyStatus OBJECT-TYPE SYNTAX INTEGER { off(0), on(1), forceOff(2) } MAX-ACCESS read-write STATUS current DESCRIPTION "The status of this policy-element relationship. This value will be on(1) if the calendar for the policy is active and if the associated policyFilter returned 1 for this element. Entries will not exist in this table if their status would be off(0). A policy can be forcibly disabled on a particular element by setting this value to forceOff(2). The agent should then act as if the policyFilter failed for this element. The forceOff(2) state will persist (even across reboots) until this value is set to on(1) by a management request. Even if the policyFilter later fails for this element, this value Various Authors Expires September 1, 2001 [Page 88] Internet Draft Policy-Based Management MIB Mar 1, 2001 will stay in the forceOff(2) state." ::= { pmTrackingElementToPolicyEntry 2 } -- Policy Debugging Table -- Policies that have debugging turned on will generate a log entry in -- the policy debugging table for every runtine exception that occurs -- in either the filter or action code. pmDebuggingTable OBJECT-TYPE SYNTAX SEQUENCE OF PmDebuggingEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "The pmDebuggingTable logs debugging messages when policies experience run-time exceptions in either the filter or action code and the associated pmPolicyDebugging object has been turned on." ::= { policyMgt 11 } pmDebuggingEntry OBJECT-TYPE SYNTAX PmDebuggingEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the pmDebuggingTable. The pmPolicyIndex in the index specifies the policy that encountered the exception that led to this log entry." INDEX { pmPolicyIndex, pmDebuggingElement, pmDebuggingLogIndex } ::= { pmDebuggingTable 1 } PmDebuggingEntry ::= SEQUENCE { pmDebuggingElement RowPointer, pmDebuggingLogIndex Unsigned32, pmDebuggingMessage UTF8String } pmDebuggingElement OBJECT-TYPE SYNTAX RowPointer MAX-ACCESS read-only STATUS current DESCRIPTION "The element the policy was executing on when it encountered the error that led to this log entry." Various Authors Expires September 1, 2001 [Page 89] Internet Draft Policy-Based Management MIB Mar 1, 2001 ::= { pmDebuggingEntry 1 } pmDebuggingLogIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "A unique index for this log entry amongst other log entries for this policy/element combination." ::= { pmDebuggingEntry 2 } pmDebuggingMessage OBJECT-TYPE SYNTAX UTF8String (SIZE (0..128)) MAX-ACCESS read-only STATUS current DESCRIPTION "An error message generated by the policy execution environment." ::= { pmDebuggingEntry 3 } -- Notification Registration Table -- A management station may choose not to install policies to a -- system that depend on roles or capabilities that don't exist on any -- elements in the system. However, the management station must be able -- to quickly learn if new roles or capabilities are added to the -- system so that it can immediately install the policies that make -- use of that new role or capability. This table allows a management -- station to register itself so that it will receive -- pmNewRoleNotifications and pmNewCapabilityNotifications whenever a -- role or capability first appears on the system. -- -- pmNewRoleNotifications and pmNewCapabilityNotifications are sent in -- Inform PDU's so they are automatically retransmitted if they are -- not acknowledged. -- -- The procedure to guarantee accurate knowledge of roles and -- capabilities is as follows: -- -- Step 1: The NMS registers itself in the pmNotificationRegTable -- Whenever it receives a notification, it adds the new role -- or capability to its internal database for that system. -- Followed immediately by: -- Step 2: The NMS retrieves the roles and capabilities from the -- system from the pmRoleTable and the -- pmCapabilitiesTable, adding this information to its Various Authors Expires September 1, 2001 [Page 90] Internet Draft Policy-Based Management MIB Mar 1, 2001 -- internal database. -- Followed immediately by: -- Step 3: The NMS installs policies on the system, potentially -- skipping policies that depend on roles or capabilities -- that haven't been inserted into the internal database. -- Followed immediately by: -- Step 4: Whenever a notification indicates a new role or -- capability that requires new policies to be installed, -- it will immediately install such policies. The NMS will -- continue this step indefinitely. -- -- Note that using this algorithm to avoid installing "unnecessary" -- policies may result in delays in having the policy available when -- the policy becomes necessary. This delay could become extensive if -- an interruption of communications prevents the notification from -- being delivered and/or the policy from being installed, causing -- the sytem to not be in compliance with policy for a period of -- time. In particular, if the policy is enforcing security rules, -- this could open up security vulnerabilities during this period of -- time. pmNotificationRegTable OBJECT-TYPE SYNTAX SEQUENCE OF PmNotificationRegEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "A manager that wishes to receive notifications about new roles or capabilities on an agent places an entry in the notification registration table. pmNewRoleNotifications and pmNewCapabilityNotifications will then be sent to the target specified in the associated snmpTargetAddr entry. These notifications will be sent until the entry is removed from this table." ::= { policyMgt 12 } pmNotificationRegEntry OBJECT-TYPE SYNTAX PmNotificationRegEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "An entry in the pmNotificationRegTable." INDEX { pmNotificationRegIndex } ::= { pmNotificationRegTable 1 } PmNotificationRegEntry ::= SEQUENCE { Various Authors Expires September 1, 2001 [Page 91] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmNotificationRegIndex Unsigned32, pmNotificationRegSnmpTargetAddrName SnmpAdminString, pmNotificationRegStorageType StorageType, pmNotificationRegStatus RowStatus } pmNotificationRegIndex OBJECT-TYPE SYNTAX Unsigned32 MAX-ACCESS not-accessible STATUS current DESCRIPTION "A unique index for this entry." ::= { pmNotificationRegEntry 1 } pmNotificationRegSnmpTargetAddrName OBJECT-TYPE SYNTAX SnmpAdminString MAX-ACCESS read-create STATUS current DESCRIPTION "The snmpTargetAddrName of an associated snmpTargetAddrEntry. When the following conditions are true, pmNewRoleNotifications and pmNewCapabilityNotifications should be sent to the specified target: 1) The pmNotificationRegEntry is active 2) The associated snmpTargetAddr entry is fully configured and active. 3) The associated snmpTargetParams entry is fully configured and active." ::= { pmNotificationRegEntry 2 } pmNotificationRegStorageType 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 if this row is backed up by non-volatile or permanent storage." ::= { pmNotificationRegEntry 3 } pmNotificationRegStatus OBJECT-TYPE SYNTAX RowStatus MAX-ACCESS read-create STATUS current Various Authors Expires September 1, 2001 [Page 92] Internet Draft Policy-Based Management MIB Mar 1, 2001 DESCRIPTION "The status of this entry." ::= { pmNotificationRegEntry 4 } -- Notifications pmNotifications OBJECT IDENTIFIER ::= { policyMgt 13 } pmNewRoleNotification NOTIFICATION-TYPE OBJECTS { pmRoleString } STATUS current DESCRIPTION "The pmNewRoleNotification is sent when an agent is configured with its first instance of a previously unused role string (not every time a new element is given a particular role). An instance of the pmRoleString object is sent containing the new roleString. In the event that two or more elements are given the same role simultaneously, it is an implementation-dependent matter as to which pmRoleString instance will be included in the notification." ::= { pmNotifications 1 } pmNewCapabilityNotification NOTIFICATION-TYPE OBJECTS { pmCapabilitiesType } STATUS current DESCRIPTION "The pmNewCapabilityNotification is sent when an agent gains a new capability that did not previously exist in any element on the system (not every time an element gains a particular role). An instance of the pmCapabilitiesType object is sent containing the identity of the new capability. In the event that two or more elements gain the same role simultaneously, it is an implementation-dependent matter as to which pmCapabilitiesType instance will be included in the notification." ::= { pmNotifications 2 } -- Compliance Statements pmConformance OBJECT IDENTIFIER ::= { policyMgt 20 } pmCompliances OBJECT IDENTIFIER ::= { pmConformance 1 } pmGroups OBJECT IDENTIFIER ::= { pmConformance 2 } Various Authors Expires September 1, 2001 [Page 93] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "Describes the requirements for conformance to the Policy-Based Management MIB" MODULE -- this module MANDATORY-GROUPS { pmPolicyManagementGroup, pmSchedGroup, pmNotificationGroup } ::= { pmCompliances 1 } pmPolicyManagementGroup OBJECT-GROUP OBJECTS { pmPolicyGroup, pmPolicyPrecedence, pmPolicySchedule, pmPolicyFilter, pmPolicyAction, pmPolicyParameters, pmPolicyFilterMaxLatency, pmPolicyActionMaxLatency, pmPolicyMaxIterations, pmPolicyDescription, pmPolicyMatches, pmPolicyAbnormalTerminations, pmPolicyExecutionErrors, pmPolicyDebugging, pmPolicyStorageType, pmPolicyAdminStatus, pmPolicyRowStatus, pmPolicyCodeText, pmPolicyCodeStatus, pmElementTypeRegOIDPrefix, pmElementTypeRegMaxLatency, pmElementTypeRegName, pmElementTypeRegStorageType, pmElementTypeRegRowStatus, pmRoleString, pmRoleContextName, pmRoleTDomain, pmRoleTAddress, pmRoleStatus, pmCapabilitiesType, pmCapabilitiesSubType, pmCapabilitiesModificationOID, pmCapabilitiesModificationType, pmCapabilitiesModificationValue, pmCapabilitiesModificationString, pmTrackingPolicyToElementInfo, pmTrackingElementToPolicyStatus, pmDebuggingElement, pmDebuggingLogIndex, pmDebuggingMessage, pmNotificationRegSnmpTargetAddrName, pmNotificationRegStorageType, pmNotificationRegStatus } STATUS current DESCRIPTION "Objects that allow for the creation and management of configuration policies." ::= { pmGroups 1 } pmSchedGroup OBJECT-GROUP OBJECTS { pmSchedLocalTime, pmSchedGroupIndex, Various Authors Expires September 1, 2001 [Page 94] Internet Draft Policy-Based Management MIB Mar 1, 2001 pmSchedDescr, pmSchedInterval, pmSchedWeekDay, pmSchedMonth, pmSchedDay, pmSchedHour, pmSchedMinute, pmSchedDuration, pmSchedType, pmSchedAdminStatus, pmSchedOperStatus, pmSchedStorageType, pmSchedRowStatus } STATUS current DESCRIPTION "Objects that allow for the scheduling of policies." ::= { pmGroups 2 } pmNotificationGroup NOTIFICATION-GROUP NOTIFICATIONS { pmNewRoleNotification, pmNewCapabilityNotification } STATUS current DESCRIPTION "Notifications sent by an Policy MIB agent." ::= { pmGroups 3 } pmBaseFunctionLibrary OBJECT IDENTIFIER ::= { pmGroups 4 } END Various Authors Expires September 1, 2001 [Page 95] Internet Draft Policy-Based Management MIB Mar 1, 2001 12. Security Considerations There are a number of management objects defined in this MIB that have a MAX-ACCESS clause of read-write and/or read- create. Such objects may be considered sensitive or vulnerable in some network environments. The support for SET operations in a non-secure environment without proper protection can have a negative effect on network operations. SNMPv1 by itself is not a secure environment. Even if the network itself is secure (for example by using IPSec), even then, there is no control as to who on the secure network is allowed to access and GET/SET (read/change/create/delete) the objects in this MIB. It is recommended that the implementors consider the security features as provided by the SNMPv3 framework. Specifically, the use of the User-based Security Model RFC 2574 [12] and the View-based Access Control Model RFC 2575 [15] is recommended. It is then a customer/user responsibility to ensure that the SNMP entity giving access to an instance of this MIB, is properly configured to give access to the objects only to those principals (users) that have legitimate rights to indeed GET or SET (change/create/delete) them. Access control for SNMP requests made to the local system depends on the security credentials of the last entity to modify any object in the filter or action for a policy. These security credentials are the input parameters for isAccessAllowed from the Architecture for Describing SNMP Management Frameworks[1]. Some policies may be designed to ensure the security of a network. If these policies have not been installed pending the appearance of a role or capability, some delay will occur in the activation of these policies when the role or capability appears because a responsible manager must notice the change and install the policy. This delay may expose the device or the network to unacceptable security vulnerabilities during this delay. If the role or capability appears during a time of network stress or when the management station is unavailable, this delay could be extensive, further increasing the risk. It is recommended that management stations install any security- Various Authors Expires September 1, 2001 [Page 96] Internet Draft Policy-Based Management MIB Mar 1, 2001 related policy that might ever be needed on a particular managed device, even if a nonexistent role or capability suggests it isn't needed at a given time. 13. Acknowledgements The authors gratefully acknowledge the significant contributions to this work made by Jeff Case, Joel Halpern, Pablo Halpern, and David Partain. Various Authors Expires September 1, 2001 [Page 97] Internet Draft Policy-Based Management MIB Mar 1, 2001 14. References [1] Harrington, D., Presuhn, R., and B. Wijnen, "An Architecture for Describing SNMP Management Frameworks", RFC 2571, April 1999. [2] Rose, M., and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", STD 16, RFC 1155, May 1990. [3] Rose, M., and K. McCloghrie, "Concise MIB Definitions", STD 16, RFC 1212, March 1991. [4] Rose, M., "A Convention for Defining Traps for use with the SNMP", RFC 1215, March 1991. [5] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [6] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [7] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Conformance Statements for SMIv2", STD 58, RFC 2580, April 1999. [8] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol", STD 15, RFC 1157, May 1990. [9] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, January 1996. [10] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, January 1996. [11] Case, J., Harrington D., Presuhn R., and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC 2572, April 1999. Various Authors Expires September 1, 2001 [Page 98] Internet Draft Policy-Based Management MIB Mar 1, 2001 [12] Blumenthal, U., and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC 2574, April 1999. [13] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, January 1996. [14] Levi, D., Meyer, P., and B. Stewart, "SNMPv3 Applications", RFC 2573, April 1999. [15] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", RFC 2575, April 1999. [16] McCloghrie, K. and M. Rose, Editors, "Management Information Base for Network Management of TCP/IP-based internets: MIB-II", STD 17, RFC 1213, Hughes LAN Systems, Performance Systems International, March 1991. [17] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB using SMIv2", RFC 2233, Cisco Systems, FTP Software, November 1997. [18] Case, J., Mundy, R., Partain, D., and B. Stewart, "Introduction to Version 3 of the Internet-standard Network Management Framework", RFC 2570, April 1999. [19] International Standards Organization, "Information Technology - Programming Languages - C++", ISO/IEC 14882-1998 [20] Levi, D. and J. Schoenwaelder, "Definitions of Managed Objects for Scheduling Management Operations", RFC 2591, May 1999. [21] ECMA, "ECMAScript Language Specification", ECMA-262, December 1999 15. Intellectual Property The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the Various Authors Expires September 1, 2001 [Page 99] Internet Draft Policy-Based Management MIB Mar 1, 2001 technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. 16. Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET Various Authors Expires September 1, 2001 [Page 100] Internet Draft Policy-Based Management MIB Mar 1, 2001 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Various Authors Expires September 1, 2001 [Page 101] Internet Draft Policy-Based Management MIB Mar 1, 2001 Table of Contents 1 Abstract .............................................. 1 2 The SNMP Management Framework ......................... 2 3 Overview .............................................. 4 4 Policy-Based Management Architecture .................. 5 5 Policy Based Management Execution Environment ......... 8 5.1 Terminology ......................................... 8 5.2 Element Discovery ................................... 9 5.2.1 Implementation Notes .............................. 10 5.3 Element Filtering ................................... 11 5.3.1 Implementation Notes .............................. 11 5.4 Policy Enforcement .................................. 11 5.4.1 Implementation Notes .............................. 12 6 The PolicyScript Language ............................. 13 6.1 Formal Definition ................................... 14 6.2 Variables ........................................... 17 6.2.1 The var class ..................................... 18 6.3 PolicyScript QuickStart Guide ....................... 22 6.3.1 Quickstart for C Programmers ...................... 24 6.3.2 Quickstart for Perl Programmers ................... 24 6.3.3 Quickstart for TCL Programmers .................... 24 6.3.4 Quickstart for Python Programmers ................. 25 6.3.5 Quickstart for JavaScript/ECMAScript/JScript Programmers ........................................ 25 7 Address of `this element' ............................. 25 8 Accessor Functions .................................... 26 9 Base Accessor Function Library ........................ 26 9.1 SNMP Accessor Functions ............................. 27 9.1.1 Form of SNMP Values ............................... 28 9.1.2 Convenience SNMP Functions ........................ 29 9.1.2.1 getvar() ........................................ 29 9.1.2.2 exists() ........................................ 29 9.1.2.3 setvar() ........................................ 30 9.1.2.4 searchcolumn() .................................. 31 9.1.2.5 setRowStatus() .................................. 33 9.1.2.6 counterRate() ................................... 34 9.1.2.7 counter32Delta() ................................ 35 9.1.3 General SNMP Functions ............................ 35 9.1.3.1 newPDU() ........................................ 37 9.1.3.2 writeVar() ...................................... 37 9.1.3.3 readVar() ....................................... 38 9.1.3.4 snmpsend() ...................................... 38 9.2 Constants ........................................... 39 Various Authors Expires September 1, 2001 [Page 102] Internet Draft Policy-Based Management MIB Mar 1, 2001 9.3 Policy Configuration Accessor Functions ............. 41 9.3.1 roleMatch() ....................................... 41 9.3.2 capMatch() ........................................ 41 9.3.3 elementName() ..................................... 42 9.3.4 ic() .............................................. 42 9.3.5 iv() .............................................. 42 9.3.6 setScratchpad() ................................... 43 9.3.7 getScratchpad() ................................... 44 9.3.8 Constants ......................................... 45 9.3.9 signalException() ................................. 46 9.3.10 getParameters() .................................. 46 9.4 Utility Accessor Functions .......................... 46 9.4.1 regexp() .......................................... 47 9.4.2 regexp_replace() .................................. 47 9.4.3 oidlen() .......................................... 47 9.4.4 oidncmp() ......................................... 48 9.4.5 insubtree() ....................................... 48 9.4.6 subid() ........................................... 48 9.4.7 subidwrite() ...................................... 48 9.4.8 oidsplice() ....................................... 49 9.4.9 parseindex() ...................................... 49 9.4.10 stringToDotted() ................................. 51 9.4.11 Integer() ........................................ 51 9.4.12 String() ......................................... 51 9.4.13 Type() ........................................... 51 9.4.14 chr() ............................................ 52 9.4.15 ord() ............................................ 52 9.4.16 substr() ......................................... 52 9.5 Library Accessor Functions .......................... 53 10 Schedule Table ....................................... 53 10.1 Periodic Schedules ................................. 54 10.2 Calendar Schedules ................................. 54 10.3 One-shot Schedules ................................. 55 11 Definitions .......................................... 56 12 Security Considerations .............................. 96 13 Acknowledgements ..................................... 97 14 References ........................................... 98 15 Intellectual Property ................................ 99 16 Full Copyright Statement ............................. 100 Various Authors Expires September 1, 2001 [Page 103]