Network Working Group C.Partridge Request For Comment: 1024 BBN/NNSC G. Trewitt Stanford October 1987 HEMS VARIABLE DEFINITIONS STATUS OF THIS MEMO This memo assigns instruction codes, defines object formats and object semantics for use with the High-Level Monitoring and Control Language, defined in RFC-1023. This memo is provisional and the definitions are subject to change. Readers should confirm that they have the most recent version of the memo. The authors assume a working knowledge of the ISO data encoding standard, ASN.1, and a general understanding of the IP protocol suite. Distribution of this memo is unlimited. INTRODUCTION In other memos [RFC-1021, RFC-1022] the authors have described a general system for monitoring and controlling network entities; this system is called the High-Level Entity Management System (HEMS). This system permits applications to read and write values in remote entities which support a simple query processor. In this memo we standardize the language instruction codes, the objects which can be read or written, and the meanings of any constants stored in the objects. There are three parts to this standardization: (1) the assignment of an ASN.1 tag to each value, (2) the definition of the external representation of the value (e.g., INTEGER, OCTETSTRING, etc.), and (3) the definition of the meaning, or semantics of a value (e.g., what types of packets a particular packet counter actually tracks). This definition is provisional, and the authors hope that it will be expanded and improved as the community becomes more experienced with HEMS. Readers with suggestions for additional object definitions, or improved definitions are encouraged to contact the authors. Partridge & Trewitt [Page 1] RFC 1024 HEMS Definitions October 1987 MESSAGE FORMATS All HEMS values are conveyed between applications and entities using the High-Level Entity Management Protocol (HEMP) specified in RFC- 1022. All values specified in this memo are passed in the data sections of HEMP messages. For all message types, the data section is a SEQUENCE of objects. For requests, these objects are operations and their operands. Replies contain a sequence of objects retrieved by a request. Events contain an initial event object followed by an optional number of objects related to the event. Messages conforming to this memo should set the link field in the HEMP CommonHeader to 1, to indicate version 1 of HEMS. The resourceId field should be set to NULL. CONTROL LANGUAGE INSTRUCTIONS The HEMS Monitoring and Control Language defines a suite of operations which the query processor must be able to perform. These operations and their operands are ASN.1 objects which are passed to the query processor over a network connection. The operations and operands are sent in postfix form (the operation follows the operands). Operands are pushed onto a stack and are processed when the operation is encountered. To ensure that operations are easily recognized in the input stream, they are all encoded in a single application-specific type. This type is shown below. Operation ::= [APPLICATION 1] IMPLICIT INTEGER { reserved(0), get(1) begin(2), end(3), get-match(4), get-attributes(5), get-attributes-match(6), get-range(7), set(8), set-match(9) } When the query processor encounters an Operation object it consults the value to determine which operation is to be done (e.g., GET). GENERAL COMMENTS ON OBJECTS STORED IN ENTITIES The High-Level Monitoring and Control Language requires the object space to have a tree-shaped type space. Locating a particular object requires identifying that section of the tree in which the object resides. (A more detailed explanation of the scheme is given in RFC-1023). Partridge & Trewitt [Page 2] RFC 1024 HEMS Definitions October 1987 This memo defines a universal type space. A subset of this type space is expected to be an appropriate type space for any entity (e.g., a gateway or a multi-user host). The type space is divided into required and optional portions. Implementors should implement the required portion of the type space plus that part of the optional type space which is appropriate for their particular entity. One problem with defining a universal type space is that certain interesting objects are not universal, but are instead very machine specific (for example, status registers on specialized hardware). To allow implementors to retrieve such implementation-specific objects using the HEMS system, a special APPLICATION type is reserved for non-standard values. Putting objects in ASN.1 form implies an ability to map to and from ASN.1 format. One of the design goals of this system has been to minimize the amount of ASN.1 compilation required by the query processor to reduce the expense of processing queries at entities. (This implies a certain willingness to force the applications querying entities to be more powerful). We expect that most of the complex mapping will be done when objects are read; most writable objects have a simple format (e.g., an INTEGER, or OCTETSTRING). As a result, we have made a heavy use of the ASN.1 SET type, which allows values to be presented in any order. Applications which require particular fields in an object may use the template structure to specify particular fields to be retrieved, but this still permits the query processor to return the fields in whatever order is convenient. In addition to ease the problems of ASN.1 compilation, query processors are not required to reduce an INTEGER to the minimum number of octets as specified in ASN.1. Applications should be prepared to receive INTEGERs which have leading octets with all zeros or ones. More generally, a design goal of HEMS was to try to limit the data processing done at the entity, and to place the burden of data reduction on the querying application. As a result, the objects presented here are typically counters, or values which the entity has to compute already. Object definitions which require the entity to do data reduction are not supported, although consideration might be given to making them optionally available. Finally, HEMS is required to support access by multiple network management centers or applications. This constraint has some important consequences. First, the SET operation cannot be applied to any Counter, since changing the value of a Counter may impair data acquisition by other centers. More generally, there are questions Partridge & Trewitt [Page 3] RFC 1024 HEMS Definitions October 1987 about competing or clashing SET requests from management centers. Currently HEMS does not provide any facilities for protecting against such requests. If such facilities become necessary, the authors envision the enhancement of the object definitions to incorporate the idea of "owned" objects. READING THE OBJECT DEFINITIONS Most of the rest of this memo is devoted to ennumerating the objects managed by the query processor. Many of these objects are dictionaries, objects which reference other objects. Defining dictionaries requires that we specify the class of objects they reference. Most significant objects, such as packet counts, reside at the leaves of the object data tree. They need to be carefully defined to ensure that their meaning is consistent across all HEMS implementations. These values are defined using the following format: OBJECT: This is the name of the object. Type: This is the ASN.1 type of the object. Definition: The meaning of the data the object contains. Implementations should ensure that their instance of the object fulfills this definition since an important feature of HEMS is that objects have consistent meaning across all machines. It is better not to implement an object than to abuse its definition. Notes: An optional section of the definition which is used to discuss issues not covered in other sections of this specification. Object Status: An optional section of the definition which is used to indicate whether the object is required of all HEMS implementations, encouraged of HEMS implementations or simply considered useful. Currently, there are four levels of status: Required: The object is felt to provide critical information and must be included in a fully conforming HEMS implementation. Required On Condition: The object is felt to provide critical information about an optional Partridge & Trewitt [Page 4] RFC 1024 HEMS Definitions October 1987 feature of an IP entity (for example, support of the Transmission Control Protocol). The object is required if the feature is implemented in the entity. Encouraged: The object is felt to provide very useful management information and implementors are encouraged to implement it. Defined: The object may be useful and has been defined so that all implementations of the object are consistent. If the object status is not specified, the object should be considered required. If the parent dictionary is optional, then the object should be considered required if the parent dictionary is supported. Operations on Object: The definition of how each monitoring and control operation acts on the object. Many operations have the same effect on almost all values, so some default definitions are presented here. In the absence of an operation specification, implementors should use the default operations defined here. BEGIN: The default is for BEGIN to be defined for dictionaries, and an error if performed on leaf objects in the tree. CREATE: The default is that CREATE is undefined. DELETE: The default is that DELETE is undefined. END: END is a stack operation and is defined for all objects. Note that END may fail if there is no object on the stack. GET-ATTRIBUTES: The default is that GET-ATTRIBUTES is defined on the contents of all dictionaries specified in this memo. The text description attributes are optional for values defined in this memo, but are required for implementation-specific objects. Any descriptions of object listed in this memo should cite this memo. GET-ATTRIBUTES must be supported on all entity-specific values. GET-ATTRIBUTES returns a Attributes object, which is defined in the well-known types section below. Partridge & Trewitt [Page 5] RFC 1024 HEMS Definitions October 1987 GET-ATTRIBUTES-MATCH: The default is that GET-ATTRIBUTES-MATCH is optionally defined on any object which supports GET-MATCH, and is an error otherwise. The rules for attributes returned by GET-ATTRIBUTES-MATCH are the same as those for GET-ATTRIBUTES. GET: The default definition of GET is to emit the operand specified is a leaf object, and if the operand is a dictionary, to recursively GET the entire dictionary and its subdictionaries. GET-MATCH: Unless otherwise specified, GET-MATCH is not supported on an object. GET-RANGE: Unless otherwise specified, GET-RANGE is not supported on an object. SET: Unless otherwise specified, SET is not supported on an object. SET-MATCH: Unless otherwise specified, SET-MATCH is not supported on an object. ATTRIBUTES HEMS requires that remote applications be able to discover the meaning of an object by querying the entity in which the object is stored. This is done through use of the GET-ATTRIBUTES operator, which causes an Attributes object to be returned to the application. The Attributes object is described below. Attributes ::= [APPLICATION 2] IMPLICIT SEQUENCE { tagASN1 [0] IMPLICIT INTEGER, valueFormat [1] IMPLICIT INTEGER, longDesc [2] IMPLICIT IA5String OPTIONAL, shortDesc [3] IMPLICIT IA5String OPTIONAL, unitsDesc [4] IMPLICIT IA5String OPTIONAL, precision [5] IMPLICIT INTEGER OPTIONAL, properties [6] IMPLICIT BITSTRING OPTIONAL, } The meanings of the various attributes are given below. tagASN1: The ASN.1 tag for this object. This attribute is required. Partridge & Trewitt [Page 6] RFC 1024 HEMS Definitions October 1987 valueFormat: The underlying ASN.1 type of the object (e.g., SEQUENCE, or OCTETSTRING). This attribute is required. longDesc: A potentially lengthy text description which fully defines the object. This attribute is optional for objects defined in this memo and required for entity-specific objects. shortDesc: A short mnemonic string of less than 15 octets which is suitable for labelling the value on a display. This attribute is optional. unitsDesc: A short string used for integer values to indicate the units in which the value is measured (e.g. "ms", "sec", "packets", etc). This attribute is optional. precision: For Counter objects, the value at which the Counter will roll-over. Required for all Counter objects. properties: A bitstring of boolean properties of the object. If the bit is on, it has the given property. This attribute is optional. The bits currently defined are: 0 -- If true, the difference between two values of this object is significant. For example, the changes in a packet count is always significant, it always conveys information. In this case, the 0 bit would be set. On the other hand, the difference between two readings of a queue length may be meaningless. IMPLEMENTATION SPECIFIC TYPES Each vendor or implementation specific value must be contained within an VendorSpecific object. The format of the VendorSpecific object is shown below. Type: VendorSpecific