As per Relevance of the word monitoring, we have this rfc below:
Network Working Group G.
Request for Comments: 1076 Stanford
Obsoletes: RFC 1023 C.
BBN/
November 1988
HEMS Monitoring and Control
TABLE OF
1. Status of This Memo 1
Introduction 2
2. Overview and Scope 2
3. Overview of Query Processor Operation 4
4. Encoding of Queries and Responses 5
4.1 Notation Used in This Proposal 5
5. Data Organization 6
5.1 Example Data Tree 7
5.2 Arrays 8
6. Components of a Query 9
7. Reply to a Query 10
8. Query Language 12
8.1 Moving Around in the Data Tree 14
8.2 Retrieving Data 15
8.3 Data Attributes 16
8.4 Examining Memory 18
8.5 Control Operations: Modifying the Data Tree 19
8.6 Associative Data Access: Filters 21
8.7 Terminating a Query 26
9. Extending the Set of Values 27
10. Authorization 27
11. Errors 28
I. ASN.1 Descriptions of Query Language Components 29
I.1 Operation Codes 30
I.2 Error Returns 31
I.3 Filters 33
I.4 Attributes 34
I.5 VendorSpecific 36
II. Implementation Hints 36
III. Obtaining a Copy of the ASN.1 Specification 42
1. STATUS OF THIS
This RFC specifies a query language for monitoring and control
network entities. This RFC supercedes RFC-1023, extending the
language and providing more discussion of the underlying issues
Trewitt & Partridge [Page 1]
RFC 1076 HEMS Monitoring and Control Language November 1988
This language is a component of the High-Level Entity
System (HEMS) described in RFC-1021 and RFC-1022. Readers may
to consult these RFCs when reading this memo. RFC-1024
detailed assignments of numbers and structures used in this system
Portions of RFC-1024 that define query language structures
superceded by definitions in this memo. This memo assumes
knowledge of the ISO data encoding standard, ASN.1.
Distribution of this memo is unlimited
This RFC specifies the design of a general-purpose, yet efficient
monitoring and control language for managing network entities.
data in the entity is modeled as a hierarchy and specific items
named by giving the path from the root of the tree. Most items
read-only, but some can be "set" in order to perform
operations. Both requests and responses are represented using
ISO ASN.1 data encoding rules
2. OVERVIEW AND
The basic model of monitoring and control used in this memo is that
query is sent to a monitored entity and the entity sends back
response. The term query is used in the database sense -- it
request information, modify data, or both. We will use gateway
oriented examples, but it should be understood that this query
response mechanism is applicable to any IP entity
In particular, there is no notion of an interactive "conversation"
in SMTP [RFC-821] or FTP [RFC-959]. A query is a complete
that stands on its own and elicits a complete response
In order to design the query language, we had to define a model
the data to be retrieved by the queries, which required
understanding of and assumptions to be made about the data. We
up with a fairly flexible data model, which places few limits on
type or size of the data
Wherever possible, we give motivations for the design decisions
assumptions that led to particular features or definitions. Some
the important global considerations and assumptions are
- The query processor should place as little
burden on the monitored entity as possible
- It should not be necessary for a monitored entity to
the complete query. Nothing in the query language
Trewitt & Partridge [Page 2]
RFC 1076 HEMS Monitoring and Control Language November 1988
preclude an implementation from being able to process
query on the fly, producing portions of the response
the query is still being read and parsed. There may
other constraints that require large amounts of data to
buffered, but the query language design must not be one
- It is assumed that there is some mechanism to transport
sequence of octets to a query processor within
monitored entity and that there is some mechanism to
a sequence of octets to the entity making the query.
HEMS, this is provided by HEMP and its underlying
layer. The query language design is independent of
details, however, and could be grafted onto some
protocol
- The data model must provide organization for the data,
that it can be conveniently named
- Much of the data to be monitored will be contained
tables. Some tables may contain other tables. The
language should be able to deal with such tables
- We don't provide capabilities for data reduction in
query language. We will provide for data selection,
example, only retrieving certain table entries, but we
not provide general facilities for processing data, such
computing averages
- Because one monitoring center may be querying
(possibly hetrogenous) hosts, it must be possible to
generic queries that can be sent to all hosts, and have
query elicit as much information as is available from
host. i.e., queries must not be aborted just because
requested non-existent data
There were some assumptions that we specifically did not make
- It is up to the implementation to choose what degree
concurrency will be allowed when processing queries.
locking only portions of the database, it should
possible to achieve good concurrency while still
deadlock
- This specification makes no statement about the use of
"definite" and "indefinite" length forms in ASN.1.
is currently some debate about this usage in the
community; implementors should note the recommendations
the ASN.1 specification
Trewitt & Partridge [Page 3]
RFC 1076 HEMS Monitoring and Control Language November 1988
Other RFCs associated with HEMS are
RFC-1021 Overview
RFC-1022 Transport protocol and message encapsulation
RFC-1024 Precise data definitions
The rest of this report is organized as follows
Section 3 Gives a brief overview of the data model and
operation of the query processor
Section 4 Describes the encoding used for queries
responses, and the notation used to represent
in this report
Section 5 Describes how the data is organized in
monitored entity, and the view provided of it
the query processor
Section 6 Describes the basic data types that may be
to the query processor as input
Section 7 Describes how a reply to a query is organized
Section 8 Describes the operations available in the
language
Section 9 Describes how the set of data in the tree may
extended
Section 10 Describes how authorization issues affect
execution of a query
Section 11 Describes how errors are reported, and
effect on the processing of the query
Appendix I Gives precise ASN.1 definitions of the data
used by the query processor
Appendix II Gives extensive implementation hints for the
of the query processor
3. OVERVIEW OF QUERY PROCESSOR
In this section, we give an overview of the operation of the
processor, to provide a framework for the later sections
The query language models the manageable data as a tree, with
Trewitt & Partridge [Page 4]
RFC 1076 HEMS Monitoring and Control Language November 1988
branch representing a different aspect of the entity, such
different layers of protocols. Subtrees are further divided
provide additional structure to the data. The leaves of the
contain the actual data
Given this data representation, the task of the query processor is
traverse this tree and retrieve (or modify) data specified in
query. A query consists of instructions to move around in the
and to retrieve (or modify) named data. The result of a query is
exact image of the parts of the tree that the query
visited
The query processor is very simple -- it only understands
commands, most of which share the same structure. It is helpful
think of the query processor as an automaton that walks around in
tree, directed by commands in the query. As it moves around,
copies the tree structure it traverses to the query result.
that is requested by the query is copied into the result as well
Data that is changed by a query is copied into the result after
modification is made
4. ENCODING OF QUERIES AND
Both queries and responses are encoded using the
defined in ISO Standard ASN.1 (Abstract Syntax Notation 1). ASN.1
represents data as sequences of contents> triples
are encoded as a stream of octets. The data tuples may
recursively nested to represent structured data such as arrays
records. For a full description, see the ISO standards IS 8824
IS 8825. See appendix for information about obtaining
documents
4.1 Notation Used in This
The notation used in this memo is similar to that used in ASN.1,
less formal, smaller, and (hopefully) easier to read. We will
to a contents> tuple as a "data object". In this RFC,
will not be concerned with the details of the object lengths.
exist in the actual ASN.1 encoding, but will be omitted in
examples here
Data objects that have no internal ASN.1 structure such as integer
octet string are referred to as "simple types" or "simple objects".
Objects which are constructed out of other ASN.1 data objects will
referred to as "composite types" or "composite objects".
Trewitt & Partridge [Page 5]
RFC 1076 HEMS Monitoring and Control Language November 1988
The
ID(value
represents a simple object whose tag is "ID" with the given value.
composite object is represented
ID{ ... contents ... }
where contents is a sequence of data objects. The contents
include both simple and structured types, so the structure is
recursive
The difference between simple and composite types is close to
meaning of the "constructor" bit in ASN.1. For the uses here,
distinction is made based upon the semantics of the data, not
representation. Therefore, even though an OctetString can
represented in ASN.1 using either constructed or non-
forms, it is conceptually a simple type, with no internal structure
and will always be written
ID("some arbitrary string")
in this RFC
There are situations where it is necessary to specify a type but
no value, such as when referring to the name of the data. In
situation, the same notation is used, but with the value omitted
ID or ID() or ID{}
Such objects have zero length and no contents. The latter two
are used when a distinction is being made between simple
composite data, but the difference is just notation --
representation is the same
ASN.1 distinguishes between four "classes" of tags: universal
application-specific, context-dependent, and reserved. HEMS and
query language use the first three. Universal tags are assigned
the ASN.1 standard and its addendums for common types, and
understood by any application using ASN.1. Application-specific
are limited in scope to a particular application. These are used
"well-known" identifiers that must be recognizable in any context
such as derived data types. Finally, context-dependent tags are
for objects whose meaning is dependent upon where they
encountered. Most tags that identify data are context-dependent
5. DATA
Data in a monitored entity is modeled as a hierarchy
Implementations are not required to organize the data internally as
hierarchy, but they must provide this view of the data through
query language. A hierarchy offers useful structure for
following operations
Trewitt & Partridge [Page 6]
RFC 1076 HEMS Monitoring and Control Language November 1988
Organization A hierarchy allows related data to be
together in a natural way
Naming The name of a piece of data is just the path from
root to the data of interest
Mapping onto ASN.1
ASN.1 can easily represent a hierarchy by using
"constructor" type as an envelope for an
subtree
Efficient
Hierarchical structures are compact and can
traversed quickly
Safe Locking If it is necessary to lock part of the hierarchy (
example, when doing an update), locking an
subtree can be done efficiently and safely, with
danger of deadlock
We will use the term "data tree" to refer to this entire structure
Note that this internal model is completely independent of
external ASN.1 representation -- any other suitable
would do. For the sake of efficiency, we do make a one-to-
mapping between ASN.1 tags and the (internal) names of the nodes
The same could be done for any other external representation
Each node in the hierarchy must have names for its component parts
Although we would normally think of names as being ASCII strings
as "input errors", the actual name is just an ASN.1 tag. Such
are small integers (typically, less than 30) and so can easily
mapped by the monitored entity onto its internal representation
We use the term "dictionary" to mean an internal node in
hierarchy. Leaf nodes contain the actual data. A dictionary
contain both leaf nodes and other dictionaries
5.1 Example Data
Here is a possible organization of the hierarchy in an entity
has several network interfaces and does IP routing. The
organization of data in entities is specified in RFC-1024.
skeletal data tree will be used throughout this RFC in
examples
System {
name -- host
clock-msec -- msec since
Trewitt & Partridge [Page 7]
RFC 1076 HEMS Monitoring and Control Language November 1988
interfaces -- # of
}
Interfaces { -- one per
InterfaceData{ address, mtu, netMask, ARP{...}, ... }
InterfaceData{ address, mtu, netMask, ARP{...}, ... }
:
}
IPRouting {
Entry{ ip-addr, interface, cost, ... }
Entry{ ip-addr, interface, cost, ... }
:
}
There are three top-level dictionaries in this hierarchy (System
Interfaces, and IPRouting) and three other dictionary
(InterfaceData, Entry, and ARP), each with multiple instances
The "name" of the clock in this entity would be
system{ clock-msec }
and the name of a routing table entry's IP address would be
IPRouting{ Entry{ ip-addr } }.
More than one piece of data can be named by a single ASN.1 object
The entire collection of system information is named by
and the name of a routing table's IP address and cost would be
IPRouting{ Entry{ ip-addr, cost } }.
5.2
There is one sub-type of a dictionary that is used as the basis
tables of objects with identical types. We call these
arrays. In the example above, the dictionaries for interfaces
routing tables, and ARP tables are all arrays
In the examples above, the "ip-addr" and "cost" fields are named.
fact, these names refer to the field values for ALL of the
table entries -- the name doesn't (and can't) specify which
table entry is intended. This ambiguity is a problem wherever
is organized in tables. If there was a meaningful index for
tables (e.g., "routing table entry #1"), there would be no problem
Unfortunately, there usually isn't such an index. The solution
this problem requires that the data be accessed on the basis of
of its content. Filters, discussed in section 8.6, provide
mechanism
The primary difference between arrays and plain dictionaries is
Trewitt & Partridge [Page 8]
RFC 1076 HEMS Monitoring and Control Language November 1988
arrays may contain only one type of item, while dictionaries,
general, will contain many different types of items. For example
the dictionary IPRouting (which is an array) will contain only
of type Entry
The fact that these objects are viewed externally as arrays or
does not mean that they are represented in an implementation
linear lists of objects. Any collection of same-typed objects
viewed as an array, even though it might be stored internally in
other format, for example, as a hash table
6. COMPONENTS OF A
A HEMS query consists of a sequence of ASN.1 objects, interpreted
a simple stack-based interpreter. [Although we define the
language in terms of the operations of a stack machine, the
does not require an implementation to use a stack machine. This is
well-understood model, and is easy to implement.] One ASN.1 tag
reserved for operation codes; all other tags indicate data that
eventually be used by an operation. These objects are pushed
the stack when received. Opcodes are immediately executed and
remove or add items to the stack. Because ASN.1 itself
tags, very little needs to be done to the incoming ASN.1 objects
make them suitable for use by the query interpreter
Each ASN.1 object in a query will fit into one of the
categories
Opcode An opcode tells the query interpreter to perform an action
They are described in detail in section 8. Opcodes
represented by an application-specific type whose
determines the operation
Template These are objects that name one or more items in the
tree. Named items may be either simple items (leaf nodes
or entire dictionaries, in which case the entire
"underneath" the dictionary is understood. Templates
used to select specific data to be retrieved from the
tree. A template may be either simple or structured
depending upon what it is naming. A template only
the data -- there are no values contained in it.
the leaf objects in a template will all have a length
zero
Examples of very simple templates are
name() or System{}
Each of these is just one ASN.1 data object, with
length. The first names a single data item in the "System
Trewitt & Partridge [Page 9]
RFC 1076 HEMS Monitoring and Control Language November 1988
dictionary (and must appear in that context), and
second names the entire "System" dictionary. A
complex template such as
Interfaces{ InterfaceData{ address, netMask, ARP } }
names two simple data items and a dictionary, iterated
all occurrences of "InterfaceData" within the
array
Path A path is a special case of a template that names only
single node in the tree. It specifies a path down into
dictionary tree and names exactly one node in
dictionary tree
Value These are used to give data values when needed in a query
for example, when changing a value in the data tree.
value can be thought of as either a filled-in template
as the ASN.1 representation some part of the data tree
Filter A boolean expression that can be executed in the context
a particular dictionary that is used to select or
select items in the dictionary. The expressions consist
the primitives "equal", "greater-or-equal",
"less-or-equal", and "present" possibly joined by "and",
"or", and "not". (See section 8.6.)
Values, Paths, and Templates usually have names in the context
dependent class, except for a few special cases, which are in
application-specific class
7. REPLY TO A
The data returned to the monitoring entity is a sequence of ASN.1
data items. Conceptually, the reply is a subset of the data tree
where the query selects which portions are to be included. This
exactly true for data retrieval requests, and essentially true
data modification requests -- the reply contains the data after
has been modified. The key point is that the data in a
represents the state of the data tree immediately after the query
executed
The sequence of the data is determined by the sequence of
language operations and the order of data items within Templates
Values given as input to these operations. If a query requests
from two of the top-level dictionaries in the data tree, by
two templates such as
System{ name, interfaces }
Interfaces
Trewitt & Partridge [Page 10]
RFC 1076 HEMS Monitoring and Control Language November 1988
InterfaceData { address, netMask, mtu }
}
then the response will consist of two ASN.1 data objects, as follows
System {
name("system name"),
interfaces(2)
}
Interfaces {
InterfaceData { address(36.8.0.1),
netMask(FFFF0000),
mtu(1500)
}
InterfaceData { address(10.1.0.1),
mtu(1008),
netMask(FF000000)
}
}
With few exceptions, each of the data items in the hierarchy is
in the context-specific ASN.1 type space. Because of this,
returned objects must be fully qualified. For example, the name
the entity must always be returned encapsulated inside an ASN.1
object for "System". If it were not, there would be no way to
if the object that was returned was "name" inside the "System
dictionary or "address" inside the "interfaces" dictionary (
in this case that "name" and "address" were assigned the same
as their ASN.1 tags).
Having fully-qualified data simplifies decoding of the data at
receiving end and allows the tags to be locally chosen.
for tags within routing tables won't conflict with definitions
tags within interfaces. Therefore, the people doing the
assignments are less constrained. In addition, most of
identifiers will be fairly small integers, which is an
because ASN.1 can fit tag numbers up to 30 in a one-octet tag field
Larger numbers require a second octet
If data is requested that doesn't exist, either because the tag
not defined, or because an implementation doesn't provide that
(such as when the data is optional), the response will contain
ASN.1 object that is empty. The tag will be the same as in
query, and the object will have a length of zero
The same response is given if the requested data does exist, but
invoker of the query does not have authorization to access it.
section 10 for more discussion of authorization mechanisms
Trewitt & Partridge [Page 11]
RFC 1076 HEMS Monitoring and Control Language November 1988
This allows completely generic queries to be composed without
to whether the data is defined or implemented at all of the
that will receive the query. All of the available data will
returned, without generating errors that might otherwise
the processing of the query
8. QUERY
The query language is designed to be expressive enough to
useful queries with, yet simple enough to be easy to implement.
query processor should be as simple and fast as possible, in order
avoid placing a burden on the monitored entity, which may be
critical node such as a gateway
Although queries are formed in a flexible way using what we term
"language", this is not a programming language. There are
that operate on data, but most other features of
languages are not present. In particular
- Programs are not stored in the query processor
- The only form of temporary storage is a stack, of
depth
- There are no subroutines
- There are no explicit control structures defined in
language
The central element of the language is the stack. It may
templates, (and therefore paths), values, and filters taken from
query. In addition, it can contain dictionaries (and
arrays) from the data tree. At the beginning of a query, it
one item, the root dictionary
The overall operation consists of reading ASN.1 objects from
input stream. All objects that aren't opcodes are pushed onto
stack as soon as they are read. Each opcode is executed
and may remove items from the stack, may generate ASN.1 objects
send them to the output stream, and may leave items on the stack
Because each input object is dealt with immediately, portions of
response may be generated while the query is still being received
In the descriptions below, operator names are in capital letters
preceded by the arguments used from the stack and followed by
left on the stack. For example
Trewitt & Partridge [Page 12]
RFC 1076 HEMS Monitoring and Control Language November 1988
OP a b OP a
means that the OP operator takes and off of
stack and leaves on the stack. Most of the
in the query language leave the first operand ( in
example) on the stack for future use
If both and were received as part of the query (as opposed
being calculated by previous operations), then this part of the
would have consisted of the sequence
So, like other stack-based languages, the arguments and
must be presented in postfix order, with an operator following
operands
Here is a summary of all of the operators defined in the
language. Most of the operators can take several different sets
operands and behave differently based upon the operand types
Details and examples are given later
BEGIN dict1 path BEGIN dict1
array path filter BEGIN array
Move down in the data tree, establishing a context
future operations
END dict END --
Undo the most recent BEGIN
GET dict GET
dict template GET
array template filter GET
Retrieve data from the data tree
GET-
dict GET-ATTRIBUTES
dict template GET-ATTRIBUTES
array template filter GET-ATTRIBUTES
Retrieve attribute information about data in the data tree
GET-RANGE dict path start length GET-RANGE
Retrieve a subrange of an OctetString. Used for
memory
SET dict value SET
array value filter SET
Change values in the data tree, possibly performing
functions
Trewitt & Partridge [Page 13]
RFC 1076 HEMS Monitoring and Control Language November 1988
CREATE array value CREATE
Create new table entries
DELETE array filter DELETE
Delete table entries
These operators are defined so that it is impossible to generate
invalid query response. Since a response is supposed to be
snapshot of a portion (or portions) of the data tree, it is
that only data that is actually in the tree be put in the response
Two features of the language help guarantee this
- Data is put in the response directly from the tree (
GET-*). Data does not go from the tree to the stack
then into the response
- Dictionaries on the stack are all derived from the initial
root dictionary. The operations that
dictionaries (BEGIN and END) also update the response
the new location in the tree
8.1 Moving Around in the Data
The initial point of reference in the data tree is the root.
is, operators name data starting at the root of the tree. It
useful to be able to move to some other dictionary in the tree
then name data from that point. The BEGIN operator moves down in
tree and END undoes the last unmatched BEGIN
BEGIN is used for two purposes
- By moving to a dictionary closer to the data of interest
the name of the data can be shorter than if the full
(from the root) were given
- It is used to establish a context for filtered
to operate in. Filters are discussed in section 8.6.
BEGIN dict1 path BEGIN dict1
Follow down the dictionary starting from .
Push the final dictionary named by onto the stack
must name a dictionary (not a leaf node). At
same time, produce the beginning octets of an ASN.1
corresponding to the new dictionary. It is up to
implementation to choose between using the "
length" representation or the "definite length" form
going back and filling the length in later
Trewitt & Partridge [Page 14]
RFC 1076 HEMS Monitoring and Control Language November 1988
END dict END --
Pop off of the stack and terminate the open ASN.1
object(s) started by the matching BEGIN. Must be
with a BEGIN. If an END operation pops the root
off of the stack, the query is terminated
must point to a regular dictionary. If any part of it
to a non-existent node, if it points to a leaf node, or if it
to a node inside an array-type dictionary, then it is in error,
the query is terminated immediately
An additional form of BEGIN, which takes a filter argument,
described later
8.2 Retrieving
The basic model that all of the data retrieval operations follow
that they take a template and fill in the leaf nodes of the
with the appropriate data values
GET dict template GET
Emit an ASN.1 object with the same "shape" as the
template, except with values filled in for each node.
first ASN.1 tag of <template> should refer to an object
. If a dictionary tag is supplied anywhere
<template>, the entire dictionary contents are emitted
the response. Any items in the template that are not
<dictionary> (or its components) are represented as
with a length of zero
dict GET
If there is no template, get all of the items in
dictionary. This is equivalent to providing a
that lists all of the items in the dictionary
An additional form of GET, which takes a filter argument,
described later
Here is an example of using the BEGIN operator to move down the
tree to the TCP dictionary and then using the GET operator
retrieve 5 data values from the TCP Stats dictionary
IPTransport{ TCP }
Stats{ octetsIn, octetsOut, inputPkts, outputPkts, badtag }
Trewitt & Partridge [Page 15]
RFC 1076 HEMS Monitoring and Control Language November 1988
This might return
IPTransport{
Stats{ octetsIn(13255), octetsOut(82323),
inputPkts(9213), outputPkts(12425), badtag() }
}
"badtag" is a tag value that is undefined. No value is returned
it, indicating that there is no data value associated with it
8.3 Data
Although ASN.1 "self-describes" the structure and syntax of the data
it gives no information about what the data means. For example,
looking at the raw data, it is possible to tell that an item is
type [context 5] and is 4 octets long. That does not tell how
interpret the data (is this an integer, an IP address, or a 4-
character string?) or what the data means (IP address of what?).
Even if the data were "tagged", in ASN.1 parlance, that would
give the base type (e.g., IP-address or counter) and not the meaning
Most of the time, this information will come from RFC-1024,
defines the ASN.1 tags and their precise meaning. When
have been made, it may not be possible to get documentation on
extensions. (Extensions are discussed in section 9.)
The GET-ATTRIBUTES operator is similar to the GET operator,
returns a set of attributes describing the data rather than the
itself. This information is intended to be sufficient to let a
understand the meaning of the data and to let a
application treat the data appropriately. Such an application
use the attribute information to format the data on a display
decide whether it is appropriate to subtract one sample from another
Some of the attributes are textual descriptions to help a
understand the nature of the data and provide meaningful labels
it. Extensive descriptions of standard data are optional, since
are defined in RFC-1024. Complete descriptions of extensions must
available, even if they are documented in a user's manual.
firefighters may not have a current manual handy when the network
broken
The format of the attributes is not as simple as the format of
data itself. It isn't possible to use the data's tag, since
would look exactly like the data itself. The format is
Attributes ::= [APPLICATION 3] IMPLICIT SEQUENCE {
tagASN1 [0] IMPLICIT INTEGER
Trewitt & Partridge [Page 16]
RFC 1076 HEMS Monitoring and Control Language November 1988
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
valueSet [7] IMPLICIT SET OF valueDesc
}
The GET-ATTRIBUTES operator is similar to the GET operator.
major difference is that dictionaries named in the template do
elicit data for the entire subtree
GET-
dict template GET-ATTRIBUTES
Emit a single ASN.1 Attributes object for each of
objects named in <template>. For each of these,
tagASN1 field will be set to the corresponding tag from
template. The rest of the fields are set as
for the data object. Any items in the template that
not in <dictionary> (or its components) elicit
Attributes object with a valueFormat of NULL, and no
descriptive information
dict GET-ATTRIBUTES
If there is no template, emit Attribute objects for all
the items in the dictionary. This is equivalent
providing a template that lists all of the items in
dictionary. This allows a complete list of a dictionary'
contents to be obtained
An additional form of GET-ATTRIBUTES, which takes a filter argument
is described later
Here is an example of using the GET-ATTRIBUTES operator to
attributes for three objects in the System dictionary
System{ name, badtag, clock-msec } GET-
"badtag" is some unknown tag. The result might be
System
Attributes
tagASN1(name),
valueFormat(IA5String),
longDesc("The primary hostname."),
Trewitt & Partridge [Page 17]
RFC 1076 HEMS Monitoring and Control Language November 1988
shortDesc("hostname")
},
Attributes
tagASN1(badtag), valueFormat(NULL
}
Attributes
tagASN1(clock-msec),
valueFormat(Integer),
longDesc("milliseconds since boot"),
shortDesc("uptime"), unitsDesc("ms")
precision(4294967296),
properties(1)
}
Note that in this example "name" and "clock-msec" are integer
for the ASN.1 tags for the two data items. "badtag" is an
value that has no corresponding name in this context
There will always be exactly as many Attributes items in the
as there are objects in the template. Attributes objects for
which do not exist in the entity will have a valueFormat of NULL
none of the optional elements will appear
[ A much cleaner method would be to store the attributes
sub-components of the data item of interest. For example
System{ clock-msec }
would normally just get the value of the data. Asking for
additional layer down the tree would now get its attributes
System{ clock-msec{ shortDesc, unitsDesc }
would get the named attributes. (The attributes would
named with application-specific tags.) Unfortunately, ASN.1
doesn't provide a notation to describe this type
organization. So, we're stuck with the GET-
operator. However, if a cleaner organization were possible
this decision would have been made differently. ]
8.4 Examining
Even with the ability to symbolically access all of this
in an entity, there will still be times when it is necessary to
to very low levels and examine memory, as in remote
operations. The building blocks outlined so far can easily
extended to allow memory to be examined
Memory is modeled as an ordinary object in the data tree, with
ASN.1 representation of OctetString. Because of the variety
addressing architectures in existence, the conversion from
Trewitt & Partridge [Page 18]
RFC 1076 HEMS Monitoring and Control Language November 1988
internal memory model to OctetString is very machine-dependent.
only simple case is for byte-addressed machines with 8 bits per byte
Each address space in an entity is represented by one "memory"
item. In a one-address-space situation, this dictionary
probably be in "System" dictionary. If each process has its
address space, then one "memory" item might exist for each process
Again, this is very machine-dependent
Although the GET-RANGE operator is provided primarily for the
of retrieving the contents of memory, it can be used on any
whose base type is OctetString
GET-RANGE dict path start length GET-RANGE
Get elements of the OctetString, starting
. and are both ASN.1 INTEGER type
, starting from , must specify a
representing memory, or some other OctetString
The returned data may not be octets long, since it may
more than one octet to represent one memory location
Memory items in the data tree are special in that they will
automatically be returned when the entire contents of a
are requested. e.g., If memory is part of the "System" dictionary
then the
System
will emit the entire contents of the System dictionary, but not
memory item
8.5 Control Operations: Modifying the Data
All of the operators defined so far only allow data in an entity
be retrieved. By replacing the template argument used in the
operators with a value, data in the entity can be changed. Very
items in the data tree can be changed; those that can are noted
RFC-1024.
Values in the data tree can modified in order to change
parameters, patch routing tables, etc. Control functions, such
bringing an interface "down" or "up", do not usually map directly
changing a value. In such cases, an item in the tree can be
to have arbitrary side-effects when a value is assigned to it
Control operations then consist of "setting" this item to
appropriate command code. Reading the value of such an item
return the current status. Again, details of such data tree
are given in RFC-1024.
Trewitt & Partridge [Page 19]
RFC 1076 HEMS Monitoring and Control Language November 1988
This "virtual command-and-status register" model is very powerful
and can be extended by an implementation to provide whatever
are needed. It has the advantage that the control function
associated with the controlled object in the data tree. In addition
no additional language features are required to support
functions, and the same operations used to locate data for
are used to describe what is being controlled
For all of the control and data modification operations, the fill
in-the-blank model used for data retrieval is extended: the
to an operation is the affected part of the data tree, after
operation has been executed. Therefore, for normal execution,
and CREATE will return the object given as an argument, and
will return nothing (because the affected portion was deleted).
SET dict value SET
Set the value(s) of data in the entity to the value(s
given in . The result will be the value of the
after the SET. Attempting to set a non-settable item
not produce an error, but will yield a result in the
different from what was sent
CREATE array value CREATE
Insert a new entry into . Depending upon
context, there may be severe restrictions about
constitutes a valid . The result will be the
item added to the . Note that only one item can
added per CREATE operation
DELETE array filter DELETE
Delete the entry(s) in that match .
Filters are described later in this document. Normally,
data items will be produced in the response, but if any
the items that matched the filter could not be deleted
they will be returned in the response
An additional form of SET, which takes a filter argument,
described later
Here is an example of attempting to use SET to change the number
interfaces in an entity
System{ interfaces(5) }
Since that is not a settable parameter, the result would be
System{ interfaces(2) }
giving the old value
Here is an example of how CREATE would be used to add a routing
entry for net for 128.89.0.0.
Trewitt & Partridge [Page 20]
RFC 1076 HEMS Monitoring and Control Language November 1988
IPRouting BEGIN -- get
Entries{ DestAddr(128.89.0.0), ... } -- entry to
END -- finished with
The result would be what was added
IPRouting{ Entries{ DestAddr(128.89.0.0), ... } }
The results in the response of these operators is consistent of
global model of the response: it contains a subset of the data
the tree immediately after the query is executed
Note that CREATE and DELETE only operate on arrays, and then only
arrays that are specifically intended for it. For example, it
quite reasonable to add and remove entries from routing tables or
tables, both of which are arrays. However, it doesn't make sense
add or remove entries in the "Interfaces" dictionary, since
contents of that array is dictated by the hardware. For each
in the data tree, RFC-1024 indicates whether CREATE and DELETE
valid
CREATE and DELETE are always invalid in non-array contexts.
DELETE were allowed on monitored data, then the deleted data
become unmonitorable to the entire world. Conversely, if it
possible to CREATE arbitrary dictionary entries, there would be
way to give such entries any meaning. Even with the data in place
there is nothing that would couple the data to the operation of
monitored entity. [Creation and deletion would also add
complication to an implementation, because without them, all of
data structures that represent the data tree are essentially static
with the exception of dynamic tables such as the ones mentioned
which already have mechanisms in place for adding and
entries.]
8.6 Associative Data Access:
One problem that has not been dealt with was alluded to earlier:
dealing with array data, how do you specify one or more entries
upon some value in the array entries? Consider the situation
there are several interfaces. The data might be organized as
Interfaces { -- one per
InterfaceData { address, mtu, netMask, ARP{...}, ... }
InterfaceData { address, mtu, netMask, ARP{...}, ... }
:
}
If you only want information about one interface (perhaps
Trewitt & Partridge [Page 21]
RFC 1076 HEMS Monitoring and Control Language November 1988
there is an enormous amount of data about each), then you have
have some way to name it. One possibility would be to just
the interfaces and refer to the desired interface
InterfaceData(3)
for the third one
But this is not sufficient, because interface numbers may change
time, perhaps from one reboot to the next. It is even worse
dealing with arrays with many elements, such as routing tables,
connections, etc. Large, changing arrays are probably the
common case, in fact. Because of the lack of utility of indexing
this context, there is no general mechanism provided in the
for indexing
A better scheme is to select objects based upon some value
in them, such as the IP address. The query language uses filters
select specific table entries that an operator will operate on.
operators BEGIN, GET, GET-ATTRIBUTES, SET, and DELETE can take
filter argument that restricts their operation to entries that
the filter
A filter is a boolean expression that is executed for each element
an array. If an array entry "matches" the filter (i.e., if the
produces a "true" result), then it is used by the operation.
filter expression is very restricted: it can only compare
contained in the array element and the comparisons are only
constants. Comparisons may be connected by AND, OR and
operators
The ASN.1 definition of a filter is
Filter ::= [APPLICATION 2] CHOICE {
present [0] DataPath
equal [1] DataValue
greaterOrEqual [2] DataValue
lessOrEqual [3] DataValue
and [4] SEQUENCE OF Filter
or [5] SEQUENCE OF Filter
not [6]
}
DataPath ::= ANY -- Path with no
DataValue ::= ANY -- Single data
This definition is similar to the filters used in the ISO
protocol (CMIP) and was derived from that specification
Trewitt & Partridge [Page 22]
RFC 1076 HEMS Monitoring and Control Language November 1988
"DataPath" is the name of a single data item; "DataValue" is
value of a single data item. The three comparisons are all of
form "data OP constant", where "data" is the value from the tree
"constant" is the value from the filter expression, and "OP" is
of equal, greater-than-or-equal, or less-than-or-equal. The
operation, "present", tests to see if the named item exists in
data tree. By its nature, it requires no value, so only a path
to be given
Here is an example of a filter that matches an Interface whose
address is 10.1.0.1:
Filter{ equal{ address(10.0.0.51) } }
Note that the name of the data to be compared is relative to
"InterfaceData" dictionary
Each operator, when given a filter argument, takes an
(dictionary containing only one type of item) as its first argument
In the current example, this would be "Interfaces". The items in
are all of type "InterfaceData". This tag is referred to as
"iteration tag".
Before a filtered operation is used, BEGIN must be used to put
array (dictionary) on top of the stack, to establish it as
context that the filter iterates over. The general operation of
filtered operation is then
1. Iterate over the items in the array
2. For each element in the array, execute the filter
3. If the filter succeeds, do the requested
(GET/SET/etc.) on the matched element, using
template/value/path as input to the operation. At
point, the execution of the operation is the same as
the non-filtered case
This is a model of operation; actual implementations may
advantage of whatever lookup techniques are available for
particular table (array) involved
Therefore, there are three inputs to a filtered operation
1. The "current dictionary" on the stack. This is
array-type dictionary to be searched, set by an
BEGIN
2. A filter, to test each item in the array. Each path
value mentioned in the filter must be named in the
Trewitt & Partridge [Page 23]
RFC 1076 HEMS Monitoring and Control Language November 1988
of an item in the array, as if it was the
dictionary. For example, in the case where a
operation iterates over the set of "InterfaceData"
in the "Interfaces" array, each value or path in
filter should name an item in the "InterfaceData
dictionary, such as "address".
3. A template, path, or value associated with the
to be performed. The leading ASN.1 tag in this must
the iteration tag. In the current example where
filter is searching the "Interfaces" dictionary, the
tag in the template/tag/value must be "InterfaceData".
The operators which take filters as arguments are
BEGIN array path filter BEGIN array
Find a dictionary in that matches .
that as the starting point for and push
dictionary corresponding to onto the stack. If
than one dictionary matches , then any of
matches may be used. This specification does not state
the choice is made. At least one dictionary must match;
is an error if there are no matches. (Perhaps it should
an error for there to be multiple matches;
experience is needed to decide.)
GET array template filter GET
For each item in that matches , fill in
template with values from the data tree and emit
result. The first tag of <template> must be equal to
iteration tag. Selected parts of matched items are
based upon <template>, just as in a non-filtered
operation
GET-
array template filter GET-ATTRIBUTES
Same as GET, except emit attributes rather than
values
SET array value filter SET
Same as GET, except set the values in rather
retrieving values. Several values in the data tree will
changed if the filter matches more than one item in
array
DELETE array filter DELETE
Delete the entry(s) in that match .
Trewitt & Partridge [Page 24]
RFC 1076 HEMS Monitoring and Control Language November 1988
Notes about filter execution
- Expressions are executed by inorder tree traversal
- Since the filter operations are all GETs and comparisons
there are no side-effects to filter execution, so
implementation is free to execute only as much of
filter as required to produce a result (e.g., don't
the rest of an AND if the first comparison turns out to
false).
- It is not an error for a filter to test a data item
isn't in the data tree. In this situation, the
just fails (is false). This means that filters don't
to test for the existence of optional data
attempting to compare it
Here is an example of how filtering would be used to obtain the
and output packet counts for the interface with IP address 10.0.0.51.
Interfaces BEGIN --
InterfaceData{ pktsIn, pktsOut } --
Filter{ equal{ address(10.0.0.51) } }
END -- finished with
The returned value would be something like
Interfaces{ --
InterfaceData{ pktsIn(1345134), pktsOut(1023729) }
--
} --
The annotations indicate which part of the response is generated
the different operators in the query
Here is an example of accessing a table contained within some
table. Suppose we want to get at the ARP table for the
with IP address 36.8.0.1 and retrieve the entire ARP entry for
host with IP address 36.8.0.23. In order to retrieve a single
in the ARP table (using a filtered GET), a BEGIN must be used to
down to the ARP table. Since the ARP table is contained within
Interfaces dictionary (an array), a filtered BEGIN must be used
Interfaces BEGIN --
InterfaceData{ ARP } --
Filter{ equal{ address(36.8.0.1) } } --
BEGIN -- filtered
Trewitt & Partridge [Page 25]
RFC 1076 HEMS Monitoring and Control Language November 1988
-- Now in ARP table for 38.0.0.1; get entry for 38.8.0.23.
addrMap -- whole
Filter{ equal{ ipAddr(36.8.0.23) } } --
GET -- filtered
The result would be
Interfaces{ -- first
InterfaceData{ ARP{ -- second
addrMap{ ipAddr(36.8.0.23), physAddr(..) } -- from
} } -- first
} -- second
Note which parts of the output are generated by different parts
the query
Here is an example of how the SET operator would be used to shut
the interface with ip-address 10.0.0.51 by changing its status
"down".
Interfaces BEGIN -- get
Interface{ Status(down) } -- value to
Filter{ equal{ IP-addr(10.0.0.51) } }
If the SET is successful, the result would be
Interfaces{ --
Interface{ Status(down) } -- from
} --
8.7 Terminating a
A query is implicitly terminated when there are no more ASN.1
to be processed by the interpreter. For a perfectly-formed query
the interpreter would be back in the state it was when it started
the stack would have only the root dictionary on it, and all of
ASN.1 objects in the result would be terminated
If there are still "open" ASN.1 objects in the result (caused
leaving ENDs off of the query), then these are closed, as if
sufficient number of ENDs were provided. This condition would
indicated by the existence of dictionaries other than the
dictionary on the stack
Trewitt & Partridge [Page 26]
RFC 1076 HEMS Monitoring and Control Language November 1988
If an extra END is received that would pop the root dictionary off
the stack, the query is terminated immediately. No error
generated
9. EXTENDING THE SET OF
There are two ways to extend the set of values understood by
query language. The first is to register the data and its
and get an ASN.1 tag assigned for it. This is the preferred
because it makes that data specification available for everyone
use
The second method is to use the VendorSpecific application type
"wrap" the vendor-specific data. Wherever an implementation
data that is not in RFC-1024, the "VendorSpecific" tag should be
to label a dictionary containing the vendor-specific data.
example, if a vendor had some data associated with interfaces
was too strange to get standard numbers assigned for, they could
instead represent the data like this
interfaces {
interface {
in-pkts, out-pkts, ...
VendorSpecific { ephemeris, declination }
}
}
In this case, ephemeris and declination correspond to two context
dependent tags assigned by the vendor for their non-standard data
If the vendor-specific method is chosen, the private data MUST
descriptions available through the GET-ATTRIBUTES operator.
with this descriptive ability, the preferred method is to
standard numbers assigned if possible
10.
This specification does not state what type of authorization
is used, if any. Different systems may have needs for
mechanisms (authorization levels, capability sets, etc.), and
systems may not care about authorization at all. The only
that an authorization system has on a query is to restrict what
items in the tree may be retrieved or modified
Therefore, there are no explicit query language features that
with protection. Instead, protection mechanisms are implicit and
make some of the data invisible (for GET) or non-writable (for SET):
Trewitt & Partridge [Page 27]
RFC 1076 HEMS Monitoring and Control Language November 1988
- Each query runs with some level of authorization or set
capabilities, determined by its environment (HEMS and
HEMP header).
- Associated with each data item in the data tree is
sort of test to determine if a query's authorization
grant it access to the item
Authorization tests are only applied to query language
that retrieve information (GET, GET-ATTRIBUTES, and GET-RANGE)
modify it (SET, CREATE, DELETE). An authorization system must
affect the operation of BEGIN and END. In particular,
authorization must not hide entire dictionaries, because that
make a BEGIN on such a dictionary fail, terminating the entire query
11.
If some particular information is requested but is not available,
will be returned as "no-value" by giving the ASN.1 length as 0.
When there is any other kind of error, such as having
arguments on the top of the stack or trying to execute BEGIN when
path doesn't refer to a dictionary, an ERROR object is emitted
The contents of this object identify the exact nature of the error
Error ::= [APPLICATION 0] IMPLICIT SEQUENCE {
errorCode INTEGER
errorInstance INTEGER
errorOffset
errorDescription IA5String
errorOp INTEGER
}
errorCode identifies what the error was, and errorInstance is
implementation-dependent code that gives a more precise indication
where the error occured. errorOffset is the location within
query where the error occurred. If an operation was being executed
errorOp contains its operation code, otherwise zero
errorDescription is a text string that can be printed that gives
description of the error. It will at least describe the errorCode
but may also give details implied by errorInstance.
definitions of all of the fields are given in appendix I.2.
Since there may be several unterminated ASN.1 objects in progress
the time the error occurs, each one must be terminated.
unterminated object will be closed with a copy of the ERROR object
Depending upon the type of length encoding used for this object,
Trewitt & Partridge [Page 28]
RFC 1076 HEMS Monitoring and Control Language November 1988
will involve filling the value for the length (definite length form
or emitting two zero octets (indefinite length form). After
objects are terminated, a final copy of the ERROR object will
emitted. This structure guarantees that the error will be noticed
every level of interpretation on the receiving end
In summary, if there was an error before any ASN.1 objects
generated, then the result would simply be
error{...}
If a couple of ASN.1 objects were unterminated when the
occurred, the result might look like
interfaces
interface { name(...) type(...) error{...} }
error{...}
}
error{...}
It would be possible to define a "WARNING" object that has a
(or same) format as ERROR, but that would be used to
responses when a non-fatal "error" occurs, such as attempting
SET/CREATE/DELETE and the operation is denied. This would be
additional complication, and we left it out in the interests
simplicity
I. ASN.1 DESCRIPTIONS OF QUERY LANGUAGE
A query consists of a sequence of ASN.1 objects, as follows
Query := IMPLICIT SEQUENCE of QueryElement
QueryElement ::= CHOICE {
Operation
Filter
Template
Path
}
Operation and Filter are defined below. The others are
Template ::=
Path ::=
InputValue ::=
These three are all similar, but have different restrictions on
structure
Trewitt & Partridge [Page 29]
RFC 1076 HEMS Monitoring and Control Language November 1988
Template Specifies a portion of the tree, naming one or
values, but not containing any values
Path Specifies a single path from one point in the tree
another, naming exactly one value, but not
a value
InputValue Gives a value to be used by a query
operator
A query response consists of a sequence of ASN.1 objects, as follows
Response := IMPLICIT SEQUENCE of ResponseElement
ResponseElement ::= CHOICE {
ResultValue
}
Error is defined below. The others are
ResultValue ::=
ResultValue is similar to Template, above
ResultValue Specifies a portion of the tree, naming
containing one or more values
The distinctions between these are elaborated in section 6.
I.1 Operation
