RFC 1024
HEMS variable definitions
Part 1 of 11 🎀
RFC 1024: HEMS Variable Definitions 💖
okay bestie, let's start with the title block ✨ This is RFC 1024, titled "HEMS VARIABLE DEFINITIONS". It's from the Network Working Group and was written by C. Partridge (BBN/NNSC) and G. Trewitt (Stanford), dated October 1987. The title block doesn't say anything about what it obsoletes or updates, and it doesn't list a category. The memo's own status section describes its status instead 🫶
STATUS OF THIS MEMO 📜
okay so this memo assigns instruction codes, and defines object formats and object semantics, for use with the High-Level Monitoring and Control Language. That language is defined in RFC-1023 🧚
this memo is provisional, which means the definitions can change 👀 readers should check that they have the most recent version of the memo. no cap, this matters 💅
the authors assume you already know the ISO data encoding standard, ASN.1, and you have a general understanding of the IP protocol suite 🌸
distribution of this memo is unlimited 🦋
INTRODUCTION 🌈
in other memos [RFC-1021, RFC-1022] the authors described a general system for monitoring and controlling network entities. this system is called the High-Level Entity Management System (HEMS) 👑 it lets applications read and write values in remote entities that run a simple query processor. iconic 😭
in this memo we standardize three things for the language: the instruction codes, the objects that can be read or written, and the meanings of any constants stored in those objects. this standardization has three parts 💅
- assigning an ASN.1 tag to each value
- defining the external representation of the value (for example, INTEGER, OCTETSTRING, etc.)
- defining the meaning, or semantics, of a value (for example, what types of packets a particular packet counter actually tracks) ✨
this definition is provisional. the authors hope it gets expanded and improved as the community gets more experienced with HEMS 🍓 if you have ideas for new object definitions, or better ones, the authors really want to hear from you 🫶
MESSAGE FORMATS 💌
all HEMS values are passed between applications and entities using the High-Level Entity Management Protocol (HEMP), which is specified in RFC-1022 🦋 every value in this memo goes in the data sections of HEMP messages. for every message type, the data section is a SEQUENCE of objects. for requests, those objects are operations and their operands. replies hold a sequence of objects that a request retrieved. events start with an initial event object, followed by an optional number of objects related to the event 🎀
messages that follow this memo should set the link field in the HEMP CommonHeader to 1, which means 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 that the query processor must be able to perform 👑 these operations and their operands are ASN.1 objects, sent to the query processor over a network connection. they're sent in postfix form, so the operation comes after its operands. operands get pushed onto a stack, and they're processed when the operation shows up 🌸
so that operations are easy to spot in the input stream, they're all encoded in a single application-specific type. here it is 👇
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 hits an Operation object, it checks the value to figure out which operation to run (for example, GET) 🔥
GENERAL COMMENTS ON OBJECTS STORED IN ENTITIES 🌈
the High-Level Monitoring and Control Language needs the object space to have a tree-shaped type space. to find a particular object, you have to identify the section of the tree where that object lives. (there's a more detailed explanation of the scheme in RFC-1023 🧚)
this memo defines a universal type space. a subset of it is expected to be a suitable type space for any entity, like a gateway or a multi-user host. the type space is split into required and optional portions. implementors should implement the required portion, plus whichever part of the optional type space fits their particular entity 💅
here's the tricky part: some interesting objects aren't universal at all. they're very machine specific, like status registers on specialized hardware 🙈 so that implementors can still retrieve those implementation-specific objects through HEMS, a special APPLICATION type is reserved for non-standard values ✨
putting objects into ASN.1 form means being able to map to and from ASN.1 format. one design goal here was to minimize how much ASN.1 compilation the query processor has to do, to keep the cost of processing queries at entities low. (that does mean the applications querying entities have to be more powerful 💪) most of the complex mapping happens when objects are read, since most writable objects have a simple format, like an INTEGER or an OCTETSTRING. because of this, the design leans heavily on the ASN.1 SET type, which lets values show up in any order. applications that need particular fields in an object can use the template structure to ask for those fields, but the query processor can still return them in whatever order is easiest for it 🫶
to make the ASN.1 compilation problem easier, query processors are not required to reduce an INTEGER to the minimum number of octets that ASN.1 specifies. applications should be ready to receive INTEGERs with leading octets that are all zeros or all ones 🌸
more generally, a big HEMS design goal was to limit the data processing done at the entity, and put the burden of data reduction on the querying application. so the objects here are usually counters, or values the entity already has to compute 🍓 object definitions that make the entity do data reduction aren't supported, though making them optionally available might be considered 👀
last but definitely not least, HEMS has to support access by multiple network management centers or applications. this brings some big consequences 😭 first, the SET operation can't be applied to any Counter, since changing a Counter's value could mess up data acquisition for other centers. beyond that, there are questions about competing or clashing SET requests from management centers. right now HEMS doesn't provide any way to protect against those requests. if that kind of protection becomes necessary, the authors picture enhancing the object definitions to include the idea of "owned" objects 💜
📖 Reading the Object Definitions 🎀
okay bestie, so most of the rest of this memo is basically one giant list of every object the query processor manages ✨ A lot of them are dictionaries, which are objects that point at other objects, so when you define one you have to say what class of objects it references 💅
The important stuff, like packet counts, lives at the leaves of the object data tree 🌸 Those leaves need super careful definitions so their meaning stays consistent across every HEMS implementation 🔥 Each one gets written up in this 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 make sure their instance of the object fulfills this definition, because a big feature of HEMS is that objects mean the same thing on every machine. It's better not to implement an object than to abuse its definition 🙈
Notes: An OPTIONAL section of the definition, used to talk about issues that aren't covered in the other sections of this specification.
Object Status: An OPTIONAL section that says whether the object is required of all HEMS implementations, encouraged, or just considered useful. There are currently four levels:
- 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 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. Lots of operations have the same effect on almost every value, so some default definitions are listed here. If there's no 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 REQUIRED for implementation-specific objects. Any descriptions of objects listed in this memo SHOULD cite this memo. GET-ATTRIBUTES MUST be supported on all entity-specific values. GET-ATTRIBUTES returns an Attributes object, which is defined in the well-known types section below.
- 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 if it 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 🦋 They do this with the GET-ATTRIBUTES operator, which makes an Attributes object get 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,
}Here's what each attribute means 🌈
- tagASN1: The ASN.1 tag for this object. This attribute is REQUIRED.
- 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 🧚
Every vendor or implementation specific value MUST be contained within a VendorSpecific object 💅 The format of the VendorSpecific object is shown below.
Type: VendorSpecific
VendorSpecific ::= [APPLICATION 3] IMPLICIT SET of ANYIf you want the full story on why this type exists, check out RFC 1023 🫶
WELL-KNOWN TYPES ✨
okay so there are some generally useful types that are defined across the whole system, and they're considered well-known 🌸 they back up abstract ideas that keep showing up in other definitions, so they're basically the foundation 🫶
TYPE: Error
Error ::= [APPLICATION 0] IMPLICIT SEQUENCE {
errorCode INTEGER,
errorOffset INTEGER
errorDescription IA5String,
}the Error type gets sent back inside reply messages whenever an error is countered 😭 errorCode is a number that tells you the general class of error, and errorOffset is the octet in the query where the error was discovered. the query starts at the first octet (octet 0) of the HEMP data section, so count from there 🧚 errorDescription is a text message explaining what went wrong. ngl this is basically the same as the HEMP protocol error structure, except for where the offset starts. the error codes were picked so the code spaces stay distinct, which makes error messages way easier to process 💅 the defined errorCodes are:
100 -- Any error not listed below.
101 -- System error. The query processor has failed
in some way.
102 -- Format error. An error has been detected in
the input stream.
103 -- Stack error. A stack overflow or underflow has
occurred.
104 -- Instruction error. The instruction is either
unknown, or not supported on the object to which
it has been applied.
105 -- Operand error. The wrong number of operands or
inappropriate operands have been given to an
instruction.TYPE: Counter
Counter ::= [APPLICATION 4] IMPLICIT INTEGERthe Counter type is an unsigned integer that rolls over to 0 once it's incremented past a certain value 🦋 (you can find the roll-over point by looking at the attributes for that particular counter.) counter sizes should be chosen so the counters won't roll over more than once every 24 hours ⏰ that's the vibe, bestie.
TYPE: InstructionGroup
InstructionGroup ::= [APPLICATION 5] IMPLICIT SEQUENCE
of ANYan InstructionGroup is an encapsulated sequence of operands and operations 🎀 it lets applications encode queries as objects. literally so cool.
TYPE: Histogram
Histogram ::= SET of HistEntry
HistEntry ::= SEQUENCE {
histValue INTEGER,
histCount Counter
}a Histogram links a count (histCount) to a numeric value (histValue) 📊 this definition doesn't put any meaning on the count or the value. each HistEntry can be a simple map (like histCount instances of histValue), or something more complex, like a count of all values between this histValue and the next lowest histValue in the Histogram 🌈 the meaning of the particular Histogram is given in the object definition, so check there!
TYPE: TrafficMatrix
TrafficMatrix ::= SET of TrafficEntry
TrafficEntry ::= SEQUENCE {
src IpAddress,
dst IpAddress,
count Counter
}a TrafficMatrix measures traffic observed between two IP addresses 🍓 typically it's used to count packets flowing through a gateway. main character energy for gateways, honestly 👑
TYPE: IpAddress
IpAddress ::= OCTETSTRINGthis is the 4 octet IP address. if the string is less than 4 octets long, the missing octets are wildcarded 🌟 a zero length string is a default address (for example, for indicating default routes). iconic 💅
TYPE: Fraction
Fraction ::= INTEGERa Fraction is an integer way of representing a fractional value 🫧 it holds the numerator of a value expressed over 256. so if you divide the Fraction by 256, you get the fractional value. the math is giving clean 🧮
TYPE: BootClock
BootClock ::= INTEGERthe time in milliseconds since the machine was last booted or reset ⏳ this value is always defined. no excuses 💖
TYPE: localClock
LocalClock ::= INTEGERthe local system clock, measured in milliseconds since 00:00 1 January 1900 UTC 🕰️ it's assumed to be only a local estimate of the time, so don't treat it like gospel. the value 0 is reserved for an uninitialized clock (for example, an uninitialized time-of-day chip) 🙈
TYPE: NetClock
NetClock ::= INTEGERa network synchronized clock, which is assumed to be synchronized across some part of a network 🌐 the clock value is measured in milliseconds since 00:00 1 January 1900 UTC. specific info about the synchronization protocol is in the system variable dictionary. the value 0 is used to indicate an uninitialized clock 🫶
TYPE: TimeStamp
TimeStamp ::= CHOICE {
[0] BootClock
[1] localClock
[2] NetClock
}a TimeStamp can be taken from the boot clock, the system clock, or the synchronized clock ⭐ in general, a time of day is preferred over time since boot, and a synchronized clock is preferred over an unsynchronized one. it's way more useful to know an event happened at a particular time than that it happened so many milliseconds after the machine booted 🥹
OBJECT DEFINITIONS 💜
The Root Dictionary
okay so in HEMS, all data is stored in dictionaries 🗂️ a dictionary is basically a conceptual grouping of values. the top-level one is the root dictionary. the form of the root dictionary for is shown below.
RootDictionary ::= [APPLICATION 32] IMPLICIT SET {
SystemVariables,
EventControls OPTIONAL,
Interfaces,
IpNetworkLayer,
IpRoutingTable,
IpTransportLayer,
IpApplications OPTIONAL
}the root dictionary is split into seven general dictionaries 🌸
SystemVariablesstores general system values like the system clock, machine memory, and system up/down status ⏰EventControlsstores all the objects needed to observe and control the event generating mechanism in entities that support events 🔔interfacesholds all the info on all the network interfaces and the IP to physical address maps (ARP tables, X.25 Standard mappings, etc) 🔌IpNetworkLayerhas info about how the IP layer works. that includes stuff like routing tables, general packet counts, and host-traffic matrices 📦IpRoutingTablehas info on how the machine routes packets. it turned out to be more useful to segregate routing info than to keep it stored with the network layer data 🛣️IpTransportLayerstores info on the transport protocols the entity supports 🚚IpApplicationsmay store info about various internet applications, like the domain system. this section is not required of HEMS entities 🧚
the next several sections define the values stored in the five dictionaries 💖
The SystemVariables Dictionary 💖
okay so the SystemVariables dictionary is the grab bag 🧺 for stuff that isn't tied to any one protocol, network, or app. Think machine load, clocks, and processor status. Here's the shape of it:
SystemVariables ::= [APPLICATION 33] IMPLICIT SET {
referenceClock [0] IMPLICIT TimeStamp,
netClockInfo [1] IMPLICIT SET OPTIONAL,
processorLoad [2] IMPLICIT INTEGER,
entityState [3] IMPLICIT INTEGER,
kernelMemory [4] IMPLICIT OCTETSTRING OPTIONAL,
pktBuffers [5] IMPLICIT INTEGER OPTIONAL,
pktOctets [6] IMPLICIT INTEGER OPTIONAL,
pktBuffersFree [7] IMPLICIT INTEGER OPTIONAL,
pktOctetsFree [8] IMPLICIT INTEGER OPTIONAL
systemID [9] IMPLICIT IA5STRING,
}OBJECT: SystemVariables Type: SET Definition: see above
The objects in the dictionary are defined below. 🌸
OBJECT: referenceClock 🕰️
Type: TimeStamp
Definition: This is the system clock used to stamp information with times. Using a NetClock is encouraged. ✨
Operations on Object: Defaults.
Notes: Adjusting clocks across networks is best handled by a proper time synchronization protocol, not by using SET. 🙅♀️
OBJECT: netClockInfo 🧾
Type: SET
Definition: Detailed info about the referenceClock, but only if the referenceClock is a NetClock. The format is shown below.
netClockInfo ::= [1] IMPLICIT SET {
estError INTEGER,
refClockType INTEGER {
unspecified(0), primary-reference(1),
ntp-secondary-reference(2), secondary-reference(3),
wristwatch(4)
}
}So estError is the estimated error, measured in milliseconds. ⏱️ refClockType says what kind of reference clock was consulted for network time. The values come straight from the Network Time Protocol specification, RFC-958. 🧠
Object Status: Required if the referenceClock is a NetClock. 🔒
OBJECT: processorLoad 🔥
Type: Fraction
Definition: This is a Fraction showing how busy the entity's processing is right now. A value of 256 (which is 1.0) means running at capacity. ngl this is an imprecise definition, because capacity can be measured a bunch of different ways. A multiprocessor might have loads of room even when one processor is maxed out. Or it might be "at capacity" just because that one processor is the master and handles all the context switching. 🙃 The goal is that remote apps can get a vibe check on the entity's current workload. ✨
The time scale should be small. A load measure averaged over the past 10 seconds is fine, but one averaged over the past 10 minutes is not. Implementors should choose some mapping between system load and this scale so that 256 means a machine under severe strain. 😵 (This also means values above 256 might show up in rare cases.)
OBJECT: entityState 👑
Type: INTEGER
Definition: This object tells you the system state. There are several defined values. Some are read-only, meaning you can only read them from the object. Others are write-only and will never be read back from the object. Over values are write-only and will never be read from the object. Over values are write-only and will never be read from the object.The values are:
The read-only values are:
(0)-- reserved.(1)-- running. The entity is up and running. 🟢(2)-- testing. The entity is running some sort of diagnostics which may affect its network operation. 🧪
The write-only values are:
(0)-- reserved.(1)-- reset the entity. 🔄(2)-- reboot the entity. This value is assumed to cause a more aggressive recycling of the system than reset, though this need not be the case. 💥(3)-- halt the entity. This value stops the entity. It is assumed to prevent the entity from operating until it is manually restarted. (I.e. the halt takes the machine off the network.) 🛑
Note: Being able to change an entity's state requires very strong access controls. 🚨🔐
Operations on Object: The defaults except as noted below.
- SET: Optionally writes the value into the object. The message requesting the SET must be authenticated. 🪪
- SET-MATCH: Optionally writes the value into the object if the current value is matched. 🎯
OBJECT: kernelMemory 🧠
Type: OCTETSTRING
Definition: A sequence of octets that represents the image of the kernel software running on the entity. This exists so you can do remote network debugging. 🐛
By kernel software, we mean the software that controls operations and access to the hardware. The kernel is expected to contain all network software up through the IP layer. 🧱
Implementations that use lightweight processes or segmented images should consider providing some way to map their internal representation into a single contiguous stream of octets. 🧩
Note: Access control is required to read this object. 🙈🔒
Object Status: Useful. 💅
Operations on Object: The defaults except as noted below.
- GET-RANGE: Emits the section of memory specified.
- GET: Emits all of memory, but note that a GET on the system dictionary should not emit this object. 🚫
OBJECT: pktBuffers 📦
Type: INTEGER
Definition: The total number of packet buffers in the entity. 🧺
Object Status: Required if the entity has a maximum number of buffers. Note that most entities do have a limit (even if it's for practical purposes, near infinite) and should return that limit. ♾️
OBJECT: pktOctets 🔢
Type: INTEGER
Definition: The maximum number of octets that can be buffered in the entity at any one time. 📊
Object Status: Required if the entity has a maximum number of octets it can buffer. Note that most entities do have a limit and should return that limit. 🧮
OBJECT: pktBuffersFree 🆓
Type: INTEGER
Definition: The number of packet buffers currently available. Subtracting pktBuffersFree from pktBuffers should give the number of buffers in use. ➖
Object Status: Required if there is a limit on the number of buffers. 🚧
OBJECT: pktOctetsFree 🫧
Type: INTEGER
Definition: The number of octets currently available, including those not used in allocated buffers. Subtracting this value from pktOctets should give the number of octets in use. 🧠
This object can be used to track how well the entity buffers its data. 🕵️♀️
Object Status: Required if there is a limit on the number of octets that can be buffered. 🚧
OBJECT: systemID 🏷️
Type: IA5STRING
Definition: The text identification of the entity. This value should include the full name of the vendor, the type of system, and the version number of the hardware and software running on the entity. 🪪✨
The EventControls Dictionary 🦋
The EventControls dictionary holds objects for controlling and monitoring how event messages get delivered to operations centers. 📬 Here's the format:
EventControls ::= [APPLICATION 34] IMPLICIT SET OPTIONAL {
lastEvent [0] IMPLICIT OCTETSTRING OPTIONAL,
eventMessageID [1] IMPLICIT Counter,
eventCenters [2] IMPLICIT SET of IpAddress,
eventList [3] IMPLICIT SET of eventEntry,
}OBJECT: eventControls 🎛️
Type: SET
Definition: See above.
Object Status: This object will be required in entities that support events, once the event definitions have been properly specified. See the discussion of the event formats at the end of this memo. 🔜
A description of the fields in this dictionary is given below. 📝
OBJECT: lastEvent ⏮️
Type: OCTETSTRING
Definition: The last event message sent. 💌
Object Status: Implementing this object is encouraged if the transport protocol used for events is unreliable (e.g., UDP). 🌪️
OBJECT: eventMessageID 🔖
Type: Counter
Definition: The HEMP MessageId to be used in the next event message. This equals the number of events sent. 🔢
OBJECT: eventCenters 📍
Type: SET of IpAddress
Definition: The list of IP addresses that events get sent to. This list receives all events. For more selective monitoring, centers should list themselves under the particular events they're interested in. 🎯
Note: If the SET operator is defined, then some form of access control is recommended. 🔐
Operations on Object: The defaults except as listed below.
- CREATE: Adds an address to the list. The new address may not be a broadcast address (it may be a multicast address). 📣
- DELETE: Deletes an address from the list. 🗑️
- SET-MATCH: Defined on the IP address. Replaces the address with a new value. 🔁
- EMIT-MATCH: Defined on the IP address. 📤
OBJECT: eventList 📋
Type: SET of eventEntry
Definition: An array of entries containing objects that let management centers control how and when events are sent. (The contents of the eventEntry structure are explained below.) 🧩
The eventControls Dictionary: eventList/eventEntry ✨
Okay so the eventEntry is basically the control panel for each event 🎛️ It gives you the control objects that decide how a particular event gets sent. Here's the format:
eventEntry ::= [0] IMPLICIT SET {
eventID [0] IMPLICIT INTEGER,
eventMode [1] IMPLICIT INTEGER,
eventCount [2] IMPLICIT Counter,
threshold [3] IMPLICIT Counter,
thresholdIncr [4] IMPLICIT INTEGER,
eventExecution [5] IMPLICIT InstructionGroup OPTIONAL,
eventCenters [6] IMPLICIT SET of IpAddress
}eventEntry 💖
Type: SET
Definition: See Above.
eventID 🦋
Type: INTEGER
Definition: The particular event ID.
eventMode 🌸
Type: INTEGER
Definition: This is the control object that decides how and whether this event is sent. The three modes are:
0 -- unused.
1 -- off. The event is not sent.
2 -- on. The event is sent every time it occurs.
3 -- threshold. The event is sent every time the
event count reaches the threshold.eventCount 🔢
Type: Counter
Definition: The number of times this event has occurred.
threshold 🎯
Type: Counter
Definition: The event threshold. If the eventMode is "threshold", then an event is sent every time the eventCount equals this value.
Operations on Object: The defaults, except as noted below.
SET: Changes the threshold.
thresholdIncr 📈
Type: INTEGER
Definition: The threshold increment. Every time an event threshold is reached, the threshold value is incremented by this value (modulo the precision of the Counter) to find the new threshold.
Operations on Object: The defaults, except as noted below.
SET: Changes the increment.
eventExecution 🧚
Type: InstructionGroup
Definition: A query to be executed whenever the event is actually sent. Any data retrieved by this query is appended to the event message.
Object Status: Encouraged.
Operations on Object: The defaults, except as noted below.
SET: Changes the buffer.
eventCenters 👑
Type: SET
Definition: The IP addresses of the monitoring centers that want to listen to this particular event. Note that events should be sent to both these centers and the global list of event centers.
Operations on Object: The defaults, except as noted below.
CREATE: Adds an address to the list of centers.DELETE: Deletes an address from the list.SET-MATCH: Defined on the IP address. Replaces the entry with a new value.EMIT-MATCH: Defined on the IP address.
The Interfaces Dictionary 🌈
Okay, the Interfaces dictionary is a list of per-interface objects. One of the big goals of HEMS is to use generic interfaces across differing hardware, so every hardware interface gets described by the same data structure: the InterfaceData. 🫶
Interfaces ::= [APPLICATION 35] IMPLICIT SET OF InterfaceDataInterfaces ✨
Type: SET
Definition: See above.
The Interfaces Dictionary: The InterfaceData structure 💅
The InterfaceData structure holds all the information on one particular interface. Here's the shape of it:
InterfaceData ::= [0] IMPLICIT SET {
addresses [0] IMPLICIT SET of IpAddress,
mtu [1] IMPLICIT INTEGER,
netMask [2] IMPLICIT IpAddress,
pktsIn [3] IMPLICIT Counter,
pktsOut [4] IMPLICIT Counter,
inputPktsDropped [5] IMPLICIT Counter,
outputPktsDropped [6] IMPLICIT Counter,
bcastPktsIn [7] IMPLICIT Counter OPTIONAL,
bcastPktsOut [8] IMPLICIT Counter OPTIONAL,
mcastPktsIn [9] IMPLICIT Counter OPTIONAL,
mcastPktsOut [10] IMPLICIT Counter OPTIONAL,
inputErrors [11] IMPLICIT Counter,
outputErrors [12] IMPLICIT Counter,
outputQLen [13] IMPLICIT INTEGER,
name [14] IMPLICIT IA5String,
status [15] IMPLICIT INTEGER,
ifType [16] IMPLICIT INTEGER,
mediaErrors [17] IMPLICIT Counter OPTIONAL,
upTime [18] IMPLICIT TimeStamp,
broadcast [19] IMPLICIT BITSTRING
multicast [20] IMPLICIT SET of BITSTRING,
addressList [21] IMPLICIT SET OPTIONAL,
}InterfaceData 🎀
Type: SET
Definition: See above.
Operations on Object: The defaults, except as noted below.
SET-MATCH: This operation is optionally defined on the address field of the structure. Only certain fields in this structure may be changed. The fields that may be SET are indicated in the descriptions below.GET-MATCH: Defined to emit information on the interface that matches the address given.
The fields in the structure are defined below. 🍓
addresses 🏠
Type: SET of IpAddress
Definition: The IP addresses that the interface accepts. Note that additional information on multicast addresses may be found in the IgmpValues dictionary.
mtu 📦
Type: INTEGER
Definition: The maximum transmission unit of the device.
netMask 🎭
Type: IpAddress
Definition: The subnet mask, which is an address with all the network bits set to 1 and all the hosts bits set to 0. Used to identify subnets.
pktsIn 📥
Type: Counter
Definition: The total number of packets received on this interface, including those in error.
pktsOut 📤
Type: Counter
Definition: The total number of packets that higher levels have attempted to send, including those that were not sent.
inputPktsDropped 🫠
Type: Counter
Definition: The number of good inbound packets dropped (presumably to free up buffer space).
outputPktsDropped 🫠
Type: Counter
Definition: The number of good outbound packets dropped (presumably to free up buffer space).
bcastPktsIn 📡
Type: Counter
Definition: The number of broadcast packets received, including those in error.
Object Status: Encouraged on interfaces that support broadcast.
bcastPktsOut 📡
Type: Counter
Definition: The number of broadcast packets that higher levels attempted to send, including those that were not sent.
Object Status: Encouraged on interfaces that support broadcast.
mcastPktsIn 🎶
Type: Counter
Definition: The number of multicast packets received, including those in error.
Object Status: Encouraged on interfaces that support multicast.
mcastPktsOut 🎶
Type: Counter
Definition: The number of multicast packets sent, including those that were not sent.
Object Status: Encouraged on interfaces that support multicast.
inputErrors 🚨
Type: Counter
Definition: The number of inbound packets that could not be delivered. The number of inbound packets delivered should equal inputPkts less this value and inputPktsDropped.
outputErrors 🚨
Type: Counter
Definition: The number of outbound packets that could not be transmitted because of errors. The number of outbound packets placed on the network should equal outputPkts less this value and outputPktsDropped.
outputQLen 🪣
Type: INTEGER
Definition: The length of the output packet queue (in packets).
name 🏷️
Type: IA5String
Definition: A text string that completely identifies the interface. This string should include the name of the manufacturer, the product name, and the version of the hardware.
status 🚦
Type: INTEGER
Definition: The status of the object. The status values are:
0 -- reserved
1 -- testing (the interface is in some test mode)
2 -- down (the interface is down)
3 -- up (the interface is up ready to pass packets)Note: If set operations are defined, access control is required.
Operations on Object: The defaults, except as noted below.
SET: Optionally defined to change the state of the interface.
ifType 🔌
Type: INTEGER
Definition: A flag that indicates the type of interface in use. The currently defined types are:
0 -- reserved
1 -- 1822 HDH
2 -- 1822
3 -- FDDI
4 -- DDN X.25
5 -- RFC-877 X.25
6 -- StarLan
7 -- Proteon 10Mbit
8 -- Proteon 80Mbit
9 -- Ethernet
10 -- 802.3 Ethernet
11 -- 802.4 Token Bus
12 -- 802.5 Token Ring
13 -- Point-to-Point SerialmediaErrors 🌧️
Type: Counter
Definition: A counter of media errors, such as collisions on Ethernets, token regeneration on token-passing rings, or lost RFNMs on PSNs.
Object Status: Encouraged for interfaces to media that have such errors.
upTime ⏰
Type: TimeStamp
Definition: When the interface was put in its current state.
broadcast 📣
Type: BITSTRING
Definition: Whether this interface has a physical broadcast address.
Object Status: Required if the interface has a broadcast address.
multicast 🎧
Type: SET of BITSTRING
Definition: The set of hardware multicast addresses currently enabled on the device.
Object Status: Encouraged in interfaces that support multicast.
addressList 🗺️
Definition: SET of addressMap
addressMap ::= [0] IMPLICIT SET {
ipAddr [0] IMPLICIT IpAddress
physAddr [1] IMPLICIT BITSTRING
}Definition: Most interfaces maintain tables that map physical network addresses to IP addresses. An example is an ARP table. This table stores that map as a series of entries, each of which maps IP addresses to the physical address. 🧭
Object Status: Required if the interface has to map IP addresses to physical addresses.
The IpNetworkLayer Dictionary 🌐
okay bestie, this one is the IP Layer dictionary and it holds all the info about the IP layer 💅 here's the format:
IpNetworkLayer ::= [APPLICATION 36] IMPLICIT SET {
gateway [0] IMPLICIT BOOLEAN,
inputPkts [1] IMPLICIT Counter,
inputErrors [2] IMPLICIT Counter,
inputPktsDropped [3] IMPLICIT Counter,
inputQLen [4] IMPLICIT INTEGER OPTIONAL,
outputPkts [5] IMPLICIT Counter,
outputErrors [6] IMPLICIT Counter,
outputPktsDropped [7] IMPLICIT Counter,
outputQLen [8] IMPLICIT INTEGER OPTIONAL,
ipID [9] IMPLICIT Counter,
fragCreated [10] IMPLICIT Counter OPTIONAL,
fragRcvd [11] IMPLICIT Counter OPTIONAL,
fragDropped [12] IMPLICIT Counter OPTIONAL,
pktsReassembled [13] IMPLICIT Counter OPTIONAL,
pktsFragmented [14] IMPLICIT Counter OPTIONAL,
htm [15] IMPLICIT TrafficMatrix OPTIONAL,
itm [16] IMPLICIT TrafficMatrix OPTIONAL
}OBJECT: IpNetworkLayer ✨
Type: SET
Definition: see above.
The fields of the dictionary are defined below 🎀
gateway
Type: BOOLEAN
Definition: this is true if the entity gateways packets 🚪
inputPkts
Type: Counter
Definition: the total number of input packets received, including the ones that came in with errors 📥
inputErrors
Type: Counter
Definition: the number of input packets thrown out because of errors (unknown protocols, format errors, etc) 💀
inputPktsDropped
Type: Counter
Definition: the number of input packets dropped because there wasn't enough buffer space 😭
inputQLen
Type: INTEGER
Definition: the number of inbound packets currently waiting to be processed by the IP layer ⏳
Object Status: Encouraged.
outputPkts
Type: Counter
Definition: the total number of outbound packets, counting both the ones higher layers handed to the IP layer and the packets that get gatewayed 🦋
outputErrors
Type: Counter
Definition: the number of output packets discarded because of errors (unable to route, format errors, etc) 🙈
outputPktsDropped
Type: Counter
Definition: the number of output packets dropped for lack of buffer space 🫠
outputQLen
Type: INTEGER
Definition: the number of outbound packets waiting to be processed by the IP layer 📦
Object Status: Encouraged.
ipID
Type: Counter
Definition: the next IP packet ID identifier to be used 🆔. note that in some implementations the transport layer may set the IP identifier. if that happens, this value is used only when the transport layer hasn't set the IP identifier.
fragCreated
Type: Counter
Definition: the number of IP fragments created at this entity. for example, if an IP datagram gets split into three fragments here, this counter goes up by three ✂️
Object Status: Encouraged.
fragRcvd
Type: Counter
Definition: the number of IP fragments received at this entity 📩
Object Status: Encouraged.
fragDropped
Type: Counter
Definition: the number of IP fragments discarded at this entity for whatever reason (timed out, errors, etc) 🗑️
Object Status: Encouraged.
pktsReassembled
Type: Counter
Definition: the number of IP datagrams that have been reassembled at this entity 🧩
Object Status: Encouraged
pktsFragmented
Type: Counter
Definition: the number of IP datagrams that have been fragmented at this entity 🍰
Object Status: Encouraged.
htm
Type: TrafficMatrix
Definition: a host traffic matrix, mapping all traffic switched between any pair of sources and destinations. the count in each trafficEntry routeDst is expressed in packets. source routed IP packets should be logged as being between their source and the destination (i.e., they should not be treated as destined for this entity). 🗺️
Notes: this info may be considered sensitive 🔒
Object Status: Encouraged in gateways.
itm
Type: TrafficMatrix
Definition: an interface traffic matrix showing traffic switched between interfaces in an entity. the source and destinations fields are the IP addresses of the interfaces between which the packet was switched. the count in each trafficEntry is expressed in packets. 🌈
Object Status: Useful.
The IpRoutingTable Dictionary 🛣️
the IpRoutingTable dictionary holds all the routing info 🗺️ quick note: info about any routing protocols used to maintain the routing table lives under the entry for that routing protocol. here's the format:
IpRoutingTable ::= [APPLICATION 37] IMPLICIT SET {
routingProtocols [0] IMPLICIT OCTETSTRING,
coreRouter [1] IMPLICIT BOOLEAN,
autoSys [2] IMPLICIT INTEGER,
metricUsed [3] IMPLICIT OCTET,
[4] RoutingEntries,
}OBJECT: IpRoutingTable ✨
Type: SET
Definition: see above.
the objects inside this dictionary are described below 👇
routingProtocols
Type: OCTETSTRING
Definition: a sparse list of the routing protocols used to update the routing table (e.g., EGP and ICMP). each octet contains one of the following values:
0 -- anything not specified below.
1 -- local (non-protocol) information. (E.g.
routing tables can be changed by hand).
2 -- HEMS (was changed/set by a HEMS operation)
3 -- Internet Control Message Protocols, (i.e.
ICMP redirects).
4 -- Exterior Gateway Protocol (EGP).
5 -- Gateway-to-Gateway Protocol (GGP).
6 -- Dissimilar Gateway Protocol (DGP).
7 -- HELO
8 -- RIP
9 -- Proprietary IGPcoreRouter
Type: BOOLEAN
Definition: this is set to true if this entity is a reference router for any other router (i.e., if it distributes any of its routes to other machines) 📡
autoSys
Type: INTEGER
Definition: the autonomous system number of the autonomous system this entity lives in 🏠
metricUsed
Type: OCTET
Definition: classifies the routing metric used in the routing table entries. the value should be picked from the list of values for routingProtocols above, and it indicates which metric definition is used (e.g., this entity uses an EGP metric internally) 📏
RoutingEntries
Type: SET of RoutingEntry
Definition: the set of all routing entries. the RoutingEntry is defined below 👇
The IpRoutingTable Dictionary: The RoutingEntry 🧭
the RoutingEntry holds all the info on one particular route 🛤️ here's the structure:
RoutingEntry ::= [0] IMPLICIT SET {
routeMetric [0] IMPLICIT INTEGER,
routeDst [1] IMPLICIT IpAddress,
nextHop [2] IMPLICIT IpAddress,
routeAuthor [3] IMPLICIT IpAddress OPTIONAL,
routeproto [4] IMPLICIT Octet OPTIONAL,
routeTime [5] TimeStamp,
routeTOS [6] IMPLICIT INTEGER OPTIONAL,
valid [7] IMPLICIT BOOLEAN
}OBJECT: RoutingEntry
Type: SET
Definition: see above.
Operations on Object: defaults, except as specified below 🎀
- CREATE: adds a new routing entry. it should be confirmed that the entry is new 🆕
- DELETE: deletes a routing entry 🗑️
- GET-MATCH: the match operator is defined on the
routeDstfield. a match on anIpAddressis defined as a search to find the route or routes that would be used to reach thatIpAddress. more than one route may apply, in which case all possible routes should be returned 🔍 - SET-MATCH: is optionally defined on the object. a SET on an entire
RoutingEntryreplaces the whole entry with a new value. certain fields (indicated below) can also be changed using a SET-MATCH.
The match operator is defined on the routeDst and routeTOS fields. to SET a value, the match must be exact on the IP address (this is different from the search definition for GET-MATCH).
Note that support of the operator on an entity which uses a dynamic routing protocol such as GGP or EGP will require close coordination with the routing protocol to keep the data consistent. (Arguably, this facility should not be supported on such machines.) ⚠️
the definitions of the fields in the RoutingEntry are given below 💖
routeMetric
Type: INTEGER
Definition: the routing metric on this route. the type of metric is defined in the metricUsed field of the IpRoutingTable dictionary 📊
routeDst
Type: IpAddress
Definition: the final destination that can be reached via this route 🎯
nextHop
Type: IpAddress
Definition: the next hop on the way to the final destination 👣
routeAuthor
Type: IpAddress
Definition: the IP address of the entity from which this route was first received. that is, the first entity which stated that the destination was reachable via nextHop. the default IpAddress should be used to indicate routes which originated on the entity itself ✍️
Object Status: Encouraged.
routeProto
Type: Octet
Definition: the routing protocol this route was learned from. the value is taken from the list of values for routingProtocols above 📚
Object Status: Encouraged.
routeTime
Type: TimeStamp
Definition: when this route was first received ⏰
Object Status: Encouraged.
routeTOS
Type: INTEGER
Definition: the IP Type of Service this routing entry serves 🚦
Object Status: Required if type of service routing is supported.
valid
Type: BOOLEAN
Definition: whether the route is active. (some machines keep routes that are no longer valid, for various reasons 🙃)
The IpTransportLayer Dictionary 🎀
okay so the IpTransportLayer Dictionary is where we keep all the info about transport protocols that run on top of IP 💅 For easy lookup, the ASN.1 tag of each transport protocol's dictionary is the same as its assigned IP Protocol number 🦋 Heads up that a lot of protocols don't have their dictionaries defined yet 🙈
IpTransportLayer ::= [APPLICATION 38] IMPLICIT SET {
[0] IMPLICIT ProtocolsSupported,
[1] IMPLICIT IcmpValues,
[2] IMPLICIT IgmpValues OPTIONAL,
[3] IMPLICIT GgpValues OPTIONAL,
[7] IMPLICIT TcpValues OPTIONAL,
[8] IMPLICIT EgpValues OPTIONAL,
[17] IMPLICIT UdpValues OPTIONAL,
[20] IMPLICIT HmpValues OPTIONAL,
[27] IMPLICIT RdpValues OPTIONAL,
[30] IMPLICIT NetbltValues OPTIONAL,
}OBJECT: IpTransportLayer 💖
Type: SET
Definition: see above ✨
The objects in this dictionary are defined below 🌸
The IpTransportLayer Dictionary: ProtocolsSupported 🧚
OBJECT: protocolsSupported
Type: OCTETSTRING
Definition: This is a sparse list of the transport protocols that are supported 💜 Each octet in the OCTETSTRING holds the IP protocol number of one supported protocol. For this definition, an entity counts as supporting a protocol only if it has BOTH the software that makes it possible for the protocol to be used in communications with the entity, and it keeps the required values (if any) that this memo defines for that protocol 👑
The IpTransportLayer Dictionary: IcmpValues 🦋
The IcmpValues dictionary is a subdictionary of the IpTransportLayer dictionary, and it keeps track of how the Internet Control Message Protocol is doing, which is defined in RFC-792 🌈 Here's the form it takes:
IcmpValues ::= SET {
inputPktCount [0] IMPLICIT Counter,
inputPktErrors [1] IMPLICIT Counter,
inputPktDeliver [2] IMPLICIT Counter,
inputPktTypes [3] IMPLICIT Histogram OPTIONAL,
outputPktCount [4] IMPLICIT Counter,
outputPktErrors [5] IMPLICIT Counter,
outputPktTypes [6] IMPLICIT Histogram OPTIONAL,
icmpTraffic [7] IMPLICIT TrafficMatrix OPTIONAL,
ipID [8] IMPLICIT Counter OPTIONAL
}OBJECT: IcmpValues 💅
Type: SET
Definition: see above ✨
The objects in this dictionary are defined below 🎀
OBJECT: inputPktCount 🔥
Type: Counter
Definition: This is the total number of ICMP packets received, errors included 💖
OBJECT: inputPktErrors 🙈
Type: Counter
Definition: This counts the ICMP packets received that turned out to have errors, like bad checksums, bad lengths, and so on. If you subtract this value from inputPktCount, you should get the number of valid ICMP packets received 🫶
OBJECT: inputPktDeliver 🌸
Type: Counter
Definition: This is the number of valid ICMP packets that were successfully processed, for example delivered up to the higher protocol ✨
OBJECT: inputPktTypes 🌈
Type: Histogram
Definition: This is a histogram of the ICMP message types and codes received, leaving out any messages that turned out to contain errors. The histogram's histValue field holds a 16-bit value, which is (ICMP type * 256) + ICMP code, and the histCount field holds how many valid messages with that type/code pair have been received 🦋
The message type and code values are the ones defined in RFC-792. For example, the Time Exceeded Message with a code of "fragment reassembly time exceeded" is (11 * 256) + 1 = 2817 💜
Object Status: Useful ✨
Operations on Object: The defaults apply, except as listed below 👑
- GET-MATCH: Matching is defined on the value of the
histValuefield 💅
OBJECT: outputPktCount 🧚
Type: Counter
Definition: This is the total number of ICMP packets the entity tried to send. That includes the ones that failed because of things like running out of buffers, a missing route, or other temporary transmission problems 🎀
OBJECT: outputPktErrors 🙈
Type: Counter
Definition: This is the number of ICMP packets the entity couldn't send because of transmission problems, such as running out of buffers, a missing route, or other temporary transmission problems. This value isn't required to include errors that the ICMP layer couldn't reasonably be expected to detect, like damage to the packet while it was in transit 💖 If you subtract this value from the PktCount field, you should get the number of ICMP packets the entity believes it successfully sent 🫶
OBJECT: outputPktTypes 🌸
Type: Histogram
Definition: This is a histogram of the ICMP message types and codes sent, including messages that later failed to be transmitted. The histogram's histValue field holds a 16-bit value, which is (ICMP type * 256) + ICMP code, and the histCount field holds how many valid messages with that type/code pair have been sent 🌈
The message type and code values are the ones defined in RFC-792. For example, the Time Exceeded Message with a code of "fragment reassembly time exceeded" is (11 * 256) + 1 = 2817 ✨
Object Status: Useful 🦋
Operations on Object: The defaults apply, except as listed below 👑
- GET-MATCH: Matching is defined on the value of the
histValuefield 💅
OBJECT: icmpTraffic 🔥
Type: TrafficMatrix
Definition: This covers all ICMP traffic that originated on this machine. The source address in the traffic matrix should be the interface the packet was sent from. The destination is the address the packet is ultimately going to be delivered to, not an intermediate hop 🧚
Object Status: Useful 💜
OBJECT: ipID 💖
Type: Counter
Definition: This is the next IP packet ID identifier to be used by the ICMP code 🎀
Object Status: Required if the ICMP code generates its own IP identifiers 🌸
The IpTransportLayer Dictionary: IgmpValues 🌈
IgmpValues ::= SET {
conformance [0] IMPLICIT INTEGER,
inputPktCount [1] IMPLICIT Counter,
inputPktErrors [2] IMPLICIT Counter,
inputPktTypes [3] IMPLICIT Histogram OPTIONAL,
outputPktCount [4] IMPLICIT Counter,
outputPktErrors [5] IMPLICIT Counter,
outputPktTypes [6] IMPLICIT Histogram OPTIONAL,
igmpTraffic [7] IMPLICIT TrafficMatrix OPTIONAL
igmpGroups [8] IMPLICIT SET of IgmpGroupEntry,
ipID [9] IMPLICIT Counter OPTIONAL,
}OBJECT: IgmpValues ✨
Type: SET
Definition: This is the dictionary of info on the Internet Group Management Protocol, which is defined in RFC-988 🦋
Object Status: Required in hosts which support IGMP 💅
The objects stored in this dictionary are defined below 💜
OBJECT: conformance 👑
Type: INTEGER
Definition: This is the level of conformance with RFC-988 🫶 The conformance levels are:
0-- Level 0. No support for IP multicasting 🙈1-- Level 1. Support for sending but not receiving multicast datagrams 🌸2-- Level 2. Full support for IP multicasting 🔥
These values are taken directly from RFC-988 ✨
OBJECT: inputPktCount 🧚
Type: Counter
Definition: This is the number of IGMP packets received, including the ones that turned out to be in error 💖
OBJECT: inputPktErrors 🎀
Type: Counter
Definition: This is the number of IGMP packets received that turned out to be in error. If you subtract this value from inputPktCount, you should get the number of valid IGMP packets received 🌈
OBJECT: inputPktTypes 🦋
Type: Histogram
Definition: This is a histogram of the IGMP message types and codes sent, including messages that later failed to be transmitted. The histogram's histValue field holds a 16-bit value, which is (IGMP type * 256) + IGMP code, and the histCount field holds how many valid messages with that type/code pair have been sent 💜
The type and code values are taken from RFC-988 ✨
OBJECT: outputPktCount 💅
Type: Counter
Definition: This is the total number of IGMP packets the entity tried to send. That includes the ones that failed because of things like running out of buffers, a missing route, or other temporary transmission problems 👑
OBJECT: outputPktErrors 🙈
Type: Counter
Definition: This is the number of IGMP packets the entity couldn't send because of transmission problems, such as running out of buffers, a missing route, or other temporary transmission problems. This value isn't required to include errors that the IGMP layer couldn't reasonably be expected to detect, like damage to the packet in transit 🫶 If you subtract this value from the outputPktCount field, you should get the number of IGMP packets the entity believes it successfully sent 🌸
OBJECT: outputPktTypes 🔥
Type: Histogram
Definition: This is a histogram of the IGMP message types and codes sent, including messages that later failed to be transmitted. The histogram's histValue field holds a 16-bit value, which is (IGMP type * 256) + IGMP code, and the histCount field holds how many valid messages with that type/code pair have been sent 🧚
The type and code values are taken from RFC-988 💖
OBJECT: igmpTraffic 🎀
Type: TrafficMatrix
Definition: This covers all IGMP traffic that originated on this machine. The source address in the traffic matrix should be the interface the packet was sent from. The destination is the address the packet is ultimately going to be delivered to, not an intermediate hop 🌈
Object Status: Useful 🦋
OBJECT: igmpGroups 💜
Type: SET
Definition: These are the various igmpGroups this host is aware of. They're stored as a set of IgmpGroupEntry, and the format of an IgmpGroupEntry is shown below 👑
IgmpGroupEntry ::= [0] SET {
groupAddress [0] IMPLICIT IpAddress,
groupAccessKey [1] IMPLICIT OCTETSTRING,
groupAgent [2] IMPLICIT BOOLEAN,
}The groupAddress is the multicast IP address. The groupAccessKey is the 8 octet key, and this key may be confidential, so it should only be available to authorized querying entities 💅 The groupAgent field is true if this entity is an agent for the multicast group 🫶
OBJECT: ipID 🌸
Type: Counter
Definition: This is the next IP packet ID identifier to be used by the IGMP code 🌈
Object Status: Required if the IGMP code generates its own IP identifiers ✨
The IpTransportLayer Dictionary: GgpValues 🧚
The definition of the GgpValues dictionary is left for further study 🎀
The IpTransportLayer Dictionary: TcpValues ✨
okay so the TcpValues dictionary is the subdictionary of IpTransportLayer that keeps track of how TCP is doing (that's the Transmission Control Protocol, defined in RFC-793 💅). a bunch of the objects in here point back to definitions in RFC-793, so keep that in your back pocket. here's the shape:
TcpValues ::= SET {
[0] IMPLICIT TcpParam
[1] IMPLICIT TcpStats OPTIONAL,
tcpConnData [2] IMPLICIT SET of TcpConn,
}OBJECT: TcpValues
Type: IMPLICIT SET
Definition: see above.
Object Status: Required if the entity supports TCP.
the objects inside are covered in the next few sections 🧚
The IpTransportLayer Dictionary: TcpValues/TcpParam 🎀
the TcpParam dictionary holds info about certain parameters, like the round-trip timer estimation constants, that get managed on a per-machine basis. obsessed with how it's laid out:
TcpParam ::= SET {
tcpRtoA [0] IMPLICIT IA5String,
tcpRtoParam [1] IMPLICIT SET of RtoParam,
ipID [2] IMPLICIT Counter,
tcpRtoMin [3] IMPLICIT INTEGER OPTIONAL,
tcpRtoMax [4] IMPLICIT INTEGER OPTIONAL,
tcpMaxSegSiz [5] IMPLICIT INTEGER,
tcpMaxConn [6] IMPLICIT INTEGER OPTIONAL,
tcpMaxWindow [7] IMPLICIT INTEGER OPTIONAL,
}OBJECT: tcpParam
Type: SET
Definition: see above.
the definitions for each object in the tcpParam dictionary are below 💖
tcpRtoA 🦋
Type: IA5String
Definition: this is the TCP retransmission timeout algorithm. it's written as one or more equations that generate a target value, RTO[N], which is the retransmission timeout for packet N. okay the formatting rules are a vibe:
- expressions use well-understood symbols like
*for multiplication and/for division, plus parentheses for precedence - variables start with an uppercase character
- multiple equations are separated by semicolons
- comments go in braces, like
{} - constants start with a lowercase character
on top of RTO[N], the symbol S[N] means the round-trip sample for packet N. written this way, the algorithm in RFC-793 looks like:
RTO[N] = SRTT[N] * beta ;
SRTT[N] = ( S[N-1] * alpha) + (SRTT[N-1] * (1 - alpha))Note: the syntax probably needs refining so a program can parse and interpret it. that's left for future study 🥺
tcpRtoParam 🌸
Type: SET of RtoParam
Definition: the list of values for the constants the retransmission timeout algorithm uses. the RtoParam structure looks like this:
RtoParam ::= SEQUENCE {
name IA5String,
value Fraction
}the name is the name of the constant as it shows up in tcpRtoA, like "beta".
ipID 🍓
Type: Counter
Definition: the next IP packet ID identifier that the TCP code is going to use.
Object Status: Required if the TCP code generates its own IP identifiers.
tcpRtoMin ✨
Type: INTEGER
Definition: the minimum value the TCP implementation allows for the retransmission timeout (RTO), in milliseconds.
Note: if the SET operation is optionally defined, access control must be exercised 🔒
Object Status: Required if the implementation uses the suggested algorithm in RFC-793, or if it sets any limits on the minimum RTO.
Operations on Object: the defaults, except as listed below:
- SET: optionally defined to change the value. implementations should confirm that the new value is less than
tcpRtoMax.
tcpRtoMax 👑
Type: INTEGER
Definition: the maximum value the TCP implementation allows for the retransmission timeout (RTO), in milliseconds.
Note: if the SET operation is optionally defined, access control must be exercised 🔒
Object Status: Required if the implementation uses the suggested algorithm in RFC-793, or if it sets any limits on the maximum RTO.
Operations on Object: the defaults, except as listed below:
- SET: optionally defined to change the value. implementations should confirm that the new value is greater than
tcpRtoMax, and that the value is large (i.e., several seconds).
tcpMaxSegSiz 🎀
Type: INTEGER
Definition: the maximum segment size this implementation uses.
Object Status: Required if the entity sets an upper limit on the MTU. (some implementations have no constraints, but choose an MTU based on external constraints, like the maximum MTU of the network interface in use.)
tcpMaxConn 🧚
Type: INTEGER
Definition: an optional value, which must be present if the entity has a limit on the total number of TCP connections it can support.
Object Status: Required if the entity sets limits.
Note: if the SET operation is defined, access control must be exercised 🔒
Operations on Object: the defaults, except as listed below:
- SET: optionally defined to change the value. if the new value is less than the number of currently open connections, implementations are not required to close existing connections, but they may not open any additional ones.
tcpMaxWindow 💜
Type: INTEGER
Definition: an optional value, which must be present if the entity places a fixed upper limit on the size of any connection's TCP window (i.e., if the maximum window size is not configurable per connection).
Object Status: Required if the entity sets limits.
Note: if the SET operation is defined, access control must be exercised 🔒
Operations on Object: the defaults, except as listed below:
- SET: optionally defined to change the value. the new value must be at least the size of one maximum TCP segment.
The IpTransportLayer Dictionary: TcpValues/TcpStats 📊
the TcpStats dictionary stores general info about how the TCP layer is working. the form is:
TcpStats ::= SET {
connAttempts [0] IMPLICIT Counter OPTIONAL,
connOpened [1] IMPLICIT Counter OPTIONAL,
connAccepted [2] IMPLICIT Counter OPTIONAL,
connClosed [3] IMPLICIT Counter OPTIONAL,
connAborted [4] IMPLICIT Counter OPTIONAL,
connAbortedInfo [5] IMPLICIT Histogram OPTIONAL,
octetsIn [6] IMPLICIT Counter OPTIONAL,
octetsOut [7] IMPLICIT Counter OPTIONAL,
octetsInDup [8] IMPLICIT Counter OPTIONAL,
octetsRetrans [9] IMPLICIT Counter OPTIONAL,
inputPkts [10] IMPLICIT Counter OPTIONAL,
retransPkts [11] IMPLICIT Counter OPTIONAL,
outputPkts [12] IMPLICIT Counter OPTIONAL,
dupPkts [13] IMPLICIT Counter OPTIONAL,
}OBJECT: TcpStats
Type: SET
Definition: see above.
Object Status: Encouraged.
the fields in the dictionary are defined below ✨
connAttempts 🌈
Type: Counter
Definition: the number of connection attempts made from this host. this includes pending attempts.
Object Status: Encouraged.
connOpened 🦋
Type: Counter
Definition: the number of connection attempts from this host that successfully produced an open connection. this includes currently open connections.
Object Status: Encouraged.
connAccepted 🫶
Type: Counter
Definition: the number of connections accepted by listening peers on this entity. this includes currently open connections.
Object Status: Encouraged.
connClosed 🌸
Type: Counter
Definition: the number of connections that were properly closed.
Object Status: Encouraged.
connAborted 💀
Type: Counter
Definition: the number of connections that were aborted. if implementations trace how the connection was aborted, they're encouraged to use the connAbortedInfo histogram.
Object Status: Encouraged.
connAbortedInfo 🔥
Type: Histogram
Definition: the number of connections aborted, sorted by type of abort. the histValue is one of the codes below, and the histCount is the number of connections aborted for that reason. the histValue codes are:
0 -- an abort condition not specified below
1 -- remote abort
2 -- local application abort
3 -- local protocol level abortObject Status: Useful
octetsIn 🍓
Type: Counter
Definition: the total number of TCP octets (not counting duplicates) received at this entity.
Object Status: Required if TcpStats is implemented.
octetsOut 💖
Type: Counter
Definition: the total number of TCP octets (not counting retransmissions) sent from this entity.
Object Status: Required if TcpStats is implemented.
octetsInDup 🙈
Type: Counter
Definition: the total number of TCP octets received that were duplicates.
Object Status: Required if TcpStats is implemented.
octetsReTrans 🔁
Type: Counter
Definition: the total number of TCP octets that have been retransmitted.
Object Status: Required if TcpStats is implemented.
inputPkts 📥
Type: Counter
Definition: the total number of valid packets received, including those on current connections.
Object Status: Useful.
retransPkts 🔄
Type: Counter
Definition: the total number of packets retransmitted.
Object Status: Useful.
outputPkts 📤
Type: Counter
Definition: the total number of packets sent.
Object Status: Useful.
dupPkts 👯
Type: Counter
Definition: the number of packets received that contained only data already received.
Object Status: Useful.
The IpTransportLayer Dictionary: TcpValues/TcpConn ✨
okay so the tcpConnData field in the TcpValues dictionary is a set of TcpConn 🧚, and each TcpConn holds info on one particular TCP connection. literally the little diary entry for every connection 💖 here's the shape:
TcpConn ::= SET {
localPort [0] IMPLICIT INTEGER,
localAddress [1] IMPLICIT IpAddress,
foreignPort [2] IMPLICIT INTEGER,
foreignAddress [3] IMPLICIT IpAddress,
state [4] IMPLICIT INTEGER,
snduna [5] IMPLICIT INTEGER,
sndnxt [6] IMPLICIT INTEGER,
sndwnd [7] IMPLICIT INTEGER,
congwnd [8] IMPLICIT INTEGER,
rcvnxt [9] IMPLICIT INTEGER,
rcvwnd [10] IMPLICIT INTEGER,
srtt [11] IMPLICIT INTEGER OPTIONAL,
lastrtt [12] IMPLICIT INTEGER OPTIONAL,
maxSegSize [13] IMPLICIT INTEGER,
octetsSent [14] IMPLICIT Counter OPTIONAL,
octetsRXmit [15] IMPLICIT Counter OPTIONAL,
octetsRcvd [16] IMPLICIT Counter OPTIONAL,
octetDups [17] IMPLICIT Counter OPTIONAL,
octetPastWin [18] IMPLICIT Counter OPTIONAL,
segSizes [19] IMPLICIT Histogram OPTIONAL,
}the set of TCP connections can be searched a bunch of ways using the local and foreign addresses (port number included) 🔍 but you can't grab the individual values of a connection without doing a search first. no shortcuts bestie 🙈
OBJECT: TcpConn
Type: SET
Definition: the per TCP connection data 🎀
Operations on Object: the defaults, except for this one:
- GET-MATCH: works on any combo of localAddress, localPort, foreignAddress and foreignPort 💅 it hands back every connection that matches the template. (ex: GET-MATCH on one particular foreignAddress gives you every connection to that address 🦋)
the fields of the tcpConn structure are explained below, so let's go 🌸
OBJECT: localPort
Type: INTEGER
Definition: the local port number of this connection 🍓
Operations on Object: defaults. MATCH operators can be applied to this object to find info on one specific TCP connection ✨
OBJECT: localAddress
Type: IpAddress
Definition: the local IP address of this connection. this can be the default IP address defined above 🫶 but this value might not be valid in certain states 💀
Operations on Object: defaults. MATCH operators can be applied to this object too, to locate info on one specific TCP connection 💜
OBJECT: foreignPort
Type: INTEGER
Definition: the foreign port number of this connection. it can be meaningless if the local peer is in certain states (like LISTEN) 👑
Operations on Object: defaults. MATCH operators can be applied to this object to locate info on one specific TCP connection 🧚
OBJECT: foreignAddress
Type: IpAddress
Definition: the foreign IP address of this connection. same deal as foreignPort: it can be meaningless if the local peer is in certain states (like LISTEN) 🌈
Operations on Object: defaults. MATCH operators can be applied to this object to locate info on one specific TCP connection 🔥
OBJECT: state
Type: INTEGER
Definition: the current state of the local peer 😭 the values for the different states are: close(0), listen(1), syn-sent(2), syn-received(3), established(4), close-wait(5), fin-wait-1(6), closing(7), last-ack(8), fin-wait-2(9), time-wait(10). implementations have to map their internal state representations onto these values, so everyone's speaking the same language 🫶
OBJECT: snduna
Type: INTEGER
Definition: the SND.UNA value as defined in RFC-793 🌸
OBJECT: sndnxt
Type: INTEGER
Definition: the SND.NXT value as defined in RFC-793 🌸
OBJECT: sndwnd
Type: INTEGER
Definition: the SND.WND value as defined in RFC-793 🌸
OBJECT: congwnd
Type: INTEGER
Definition: the congestion window. this is less than or equal to sndwnd. if it's less than sndwnd, congestion control is in effect and congwnd is the reduced send window size in use 🦋
OBJECT: rcvnxt
Type: INTEGER
Definition: the RCV.NXT value as defined in RFC-793 🌸
OBJECT: rcvwnd
Type: INTEGER
Definition: the RCV.WND value as defined in RFC-793 🌸
OBJECT: srtt
Type: INTEGER
Definition: the smoothed round-trip time in milliseconds ⏱️
Object Status: Required if the implementation maintains a smoothed round-trip time 🔥
OBJECT: lastrtt
Type: INTEGER
Definition: the last round-trip time sample taken, in milliseconds ⭐
Object Status: Encouraged 💖
OBJECT: maxSegSize
Type: INTEGER
Definition: the maximum segment size that can be used on this connection 🍓
OBJECT: octetsSent
Type: Counter
Definition: the total number of octets transmitted since the connection was opened, not counting retransmissions. you can also think of it as the current length of the stream 🌊
Object Status: Encouraged 💖
OBJECT: octetsRXmit
Type: Counter
Definition: the total number of octets retransmitted since the connection was opened. this plus octetsSent should give you the total number of octets sent 🧮
Object Status: Encouraged 💖
OBJECT: octetsRcvd
Type: Counter
Definition: the number of octets received since the connection was opened, not counting duplicates received. it's the receiver's version of octetsSent 📬
Object Status: Encouraged 💖
OBJECT: octetDups
Type: Counter
Definition: the total number of octets received since the connection was opened that were redundant (aka, they'd already been received before) 👯
Object Status: Encouraged 💖
OBJECT: octetPastWin
Type: Counter
Definition: the number of segments that contained data beyond the upper edge of the receive window 🚧
Object Status: Encouraged 💖
OBJECT: segSizes
Type: Histogram
Definition: a histogram of the sizes of the packets sent on the connection. it's useful for catching cases of silly-window syndrome 🕵️♀️ this is a range histogram, so it counts the segments whose size fell into a given range. the histValue field holds a segment size, and the histCount field holds the number of segments between this size and the next largest size 📊
Object Status: Useful 🎀
The IpTransportLayer Dictionary: EgpValues ✨
the EgpValues dictionary keeps info on how the Exterior Gateway Protocol is doing, which is defined in RFC-904 🌐 here's the format:
EgpValues ::= SET {
egpState [0] IMPLICIT INTEGER,
[1] IMPLICIT EgpParam,
[2] IMPLICIT EgpStats OPTIONAL,
egpPeerData [3] IMPLICIT SET of EgpPeer
}OBJECT: EgpValues
Type: SET
Definition: see above 👀
Object Status: Required in entities which support EGP 💜
the subdictionaries of this dictionary are explained below 💅
OBJECT: egpState
Type: INTEGER
Definition: the state of the EGP system. the state values are:
0 -- Idle
1 -- Acquisition
2 -- Down
3 -- Up
4 -- Ceasethese values are taken directly from RFC-904 📖
The IpTransportLayer Dictionary: EgpValues/EgpParam ✨
the EgpParam dictionary stores all the various EGP parameters 🎀 here's the format:
EgpParam ::= SET {
p1 [0] IMPLICIT INTEGER,
p2 [1] IMPLICIT INTEGER,
p3 [2] IMPLICIT INTEGER,
p4 [3] IMPLICIT INTEGER,
p5 [4] IMPLICIT INTEGER,
ipID [5] IMPLICIT Counter OPTIONAL
}OBJECT: EgpParam
Type: SET
Definition: see above 👀
the fields of the dictionary are explained below. all the definitions come from RFC-904 📚
OBJECT: p1
Type: INTEGER
Definition: the minimum interval acceptable between successive Hello commands received ⏰
Operations on Object: the defaults, except as noted below.
- SET: the set command is optionally defined on this object 🧁
OBJECT: p2
Type: INTEGER
Definition: the minimum interval acceptable between successive Poll commands received ⏰
Operations on Object: the defaults, except as noted below.
- SET: the set command is optionally defined on this object 🧁
OBJECT: p3
Type: INTEGER
Definition: the interval between Request or Cease command retransmissions 🔁
Operations on Object: the defaults, except as noted below.
- SET: the set command is optionally defined on this object 🧁
OBJECT: p4
Type: INTEGER
Definition: the interval during which state variables are maintained in the absence of commands or response in the Down and Up states 🫧
Operations on Object: the defaults, except as noted below.
- SET: the set command is optionally defined on this object 🧁
OBJECT: p5
Type: INTEGER
Definition: the interval during which state variables are maintained in the absence of commands or response in the Acquisition and Cease states 🫧
Operations on Object: the defaults, except as noted below.
- SET: the set command is optionally defined on this object 🧁
OBJECT: ipID
Type: Counter
Definition: the next IP packet ID identifier to be used by the EGP code 🆔
Object Status: Required if the EGP code generates its own IP identifiers 🫶
The IpTransportLayer Dictionary: EgpValues/EgpStats ✨
Okay bestie, the EgpStats dictionary is where the entity keeps its stats on how it's been using EGP 📊. It's a SET, and it looks like this 💅:
EgpStats ::= SET {
inputPktCount [1] IMPLICIT Counter,
inputPktErrors [2] IMPLICIT Counter,
inputPktTypes [3] IMPLICIT Histogram OPTIONAL,
outputPktCount [4] IMPLICIT Counter,
outputPktErrors [5] IMPLICIT Counter,
outputPktTypes [6] IMPLICIT Histogram OPTIONAL,
egpTraffic [7] IMPLICIT TrafficMatrix OPTIONAL
}EgpStats 🎀
Type: SET
Definition: see above, it's the whole thing 🙈
Now let's look at each object inside 👀
inputPktCount 📥
Type: Counter
Definition: the number of EGP packets received, including the ones that turned out to be broken ❌
inputPktErrors 🚫
Type: Counter
Definition: the number of EGP packets received that turned out to be broken. If you take this number away from inputPktCount, you get the number of valid EGP packets received ✨
inputPktTypes 📊
Type: Histogram
Definition: a histogram of the types of valid EGP messages received. The histValue field holds the message type number, and the histCount field holds how many messages of that type were received 🧁
Object Status: Useful.
outputPktCount 📤
Type: Counter
Definition: the total number of EGP packets the entity tried to send. That includes the ones that failed because of things like no buffers, a missing route, or other temporary transmission problems 💫
outputPktErrors 💔
Type: Counter
Definition: the number of EGP packets the entity couldn't send because of transmission problems, like no buffers, a missing route, or other temporary issues. This doesn't have to include errors the EGP layer couldn't reasonably be expected to catch, like a packet getting damaged in transit 🚚. If you subtract this from outputPktCount, you get the number of EGP packets the entity thinks it successfully sent 🎉
outputPktTypes 📦
Type: Histogram
Definition: a histogram of the EGP message types sent, including the ones that later failed to go out. The histValue field holds the message type number, and the histCount field holds how many messages of that type were sent 🍓
Object Status: Useful.
egpTraffic 🌍
Type: TrafficMatrix
Definition: all EGP traffic that started on this machine. In the traffic matrix, the source address should be the interface the packet was sent from. The destination is the address the packet is finally delivered to, not an intermediate hop 🛤️
Object Status: Useful.
The IpTransportLayer Dictionary: EgpValues/EgpPeer 🦋
The egpPeerData field of the EgpValues dictionary is a set of EgpPeer structures. Each one holds the state variables for one particular EGP neighbor 🤝. Here's the EgpPeer structure 💖:
EgpPeer ::= SET {
r [0] IMPLICIT Counter,
s [1] IMPLICIT Counter,
t1 [2] IMPLICIT INTEGER,
t2 [3] IMPLICIT INTEGER,
t3 [4] IMPLICIT INTEGER,
m [5] IMPLICIT BOOLEAN,
timer1 [6] IMPLICIT INTEGER,
timer2 [7] IMPLICIT INTEGER,
timer3 [8] IMPLICIT INTEGER,
addr [9] IMPLICIT IpAddress
}EgpPeer 🌸
Type: SET
Definition: the state info for a given EGP neighbor 👯
Here's what each field means 👇
r 🔢
Type: Counter
Definition: the receive sequence number, as defined in RFC-904.
s 🔢
Type: Counter
Definition: the send sequence number, as defined in RFC-904.
t1 ⏱️
Type: INTEGER
Definition: the interval between Hello command retransmissions, as defined in RFC-904.
t2 ⏱️
Type: INTEGER
Definition: the interval between Poll command retransmissions, as defined in RFC-904.
t3 ⏱️
Type: INTEGER
Definition: the interval during which neighbor-reachability indications are counted, as defined in RFC-904.
m 🔀
Type: BOOLEAN
Definition: the Hello Polling mode. It's true when in active mode and false when in passive mode.
Operations on Object: the defaults, except as noted below.
- SET: optionally defined, so you can change the Hello Polling mode 🎛️
timer1 ⏲️
Type: INTEGER
Definition: the value of timer 1, as defined in RFC-904.
timer2 ⏲️
Type: INTEGER
Definition: the value of timer 2, as defined in RFC-904.
timer3 ⏲️
Type: INTEGER
Definition: the value of timer 3, as defined in RFC-904.
addr 📍
Type: IpAddress
Definition: the IP address of the neighbor.
The IpTransportLayer Dictionary: UdpValues 🌷
The UdpValues dictionary stores all the info on the User Datagram Protocol, which is defined in RFC-768 📮. Here's the format 💅:
UdpValues ::= [17] IMPLICIT SET OPTIONAL {
ipID [0] IMPLICIT Counter OPTIONAL,
[1] IMPLICIT UdpStats,
udpPortData [2] IMPLICIT SET of udpPort
}UdpValues 🌼
Type: SET
Definition: see above.
Object Status: implementation of this dictionary is required if the entity supports UDP.
Here are the fields 👀
ipID 🆔
Type: Counter
Definition: the next IP packet ID identifier to be used by the UDP code.
Object Status: required if the UDP code generates its own IP identifiers.
The IpTransportLayer Dictionary: UdpValues/UdpStats 🎀
The UdpStats dictionary holds general info about how UDP is behaving on the entity 📈. Here's the format ✨:
UdpStats ::= SET {
inputPkts [0] IMPLICIT Counter,
inputPktErrors [1] IMPLICIT Counter,
outputPkts [2] IMPLICIT Counter,
}UdpStats 💜
Type: SET
Definition: see above.
Object Status: encouraged.
Here's what's inside 🫶
inputPkts 📥
Type: Counter
Definition: the total number of UDP packets received at this entity, including any errors.
Object Status: required if the UdpStats dictionary is implemented.
inputPktsErrors 🚫
Type: Counter
Definition: the number of UDP packets that couldn't be delivered because of format errors, data corruption, or because there was no application at the destination port 💔
Object Status: required if the UdpStats dictionary is implemented.
outputPkts 📤
Type: Counter
Definition: the total number of UDP segments sent from this entity.
Object Status: required if the UdpStats dictionary is implemented.
The IpTransportLayer Dictionary: UdpValues/udpPortData 🧚
The udpPortData structure stores info about individual UDP applications 🎪. It's a set of records called udpPorts, and each one tracks how one port is behaving. Both structures look like this 👑:
udpPortData [1] IMPLICIT SET of UdpPort
UdpPort ::= [0] IMPLICIT SET {
localAddress [0] IMPLICIT IpAddress,
localPort [1] IMPLICIT INTEGER,
foreignAddress [2] IMPLICIT IpAddress OPTIONAL,
foreignPort [3] IMPLICIT INTEGER OPTIONAL,
maxPktSize [4] IMPLICIT INTEGER,
pktsRcvd [5] IMPLICIT Counter,
octetRcvd [6] IMPLICIT Counter OPTIONAL,
pktsSent [7] IMPLICIT Counter,
octetSent [8] IMPLICIT Counter OPTIONAL,
}udpPortData 🌈
Type: SET of udpPort
Definition: see above.
UdpPort 🦋
Type: SET
Definition: see above.
Operations on Object: the defaults, except as noted below.
- GET-MATCH: defined on any combination of the values of localAddress, localPort, foreignAddress, and foreignPort. It returns all ports that match the template 🔍
Now the meaning of each field in the udpPort record 💕
localAddress 🏠
Type: IpAddress
Definition: the local IP address of the port. It may be the default IP address if records are accepted from any interface.
localPort 🚪
Type: INTEGER
Definition: the local port number.
foreignAddress 🌐
Type: IpAddress
Definition: some UDP implementations let applications specify the remote address that packets will be accepted from. In those implementations, this field can be used to return the remote IP address. If it's set to the default IP address, packets from any host are accepted. The default IP address means the application hasn't specified a remote address, but it could if it wanted to 🤷♀️
Object Status: required in entities that let applications specify the remote address.
foreignPort 🔌
Type: INTEGER
Definition: some UDP implementations let applications specify the remote address that packets will be accepted from. In those implementations, this field can be used to return the remote port. If it's set to 0, packets from any remote port are accepted.
Object Status: required in entities that let applications specify the remote port.
maxPktSize 📏
Type: INTEGER
Definition: the maximum UDP packet size, if any, that this host supports.
Object Status: required if there's a limit on the UDP packet size.
pktsRcvd 📬
Type: Counter
Definition: the total number of packets received on this port during the lifetime of this application, meaning the application that opened this port.
octetsRcvd 🔢
Type: Counter
Definition: the total number of octets received at this port.
pktsSent 📨
Type: Counter
Definition: the total number of packets sent on this port during the lifetime of this application, meaning the application that opened this port.
octetsSent 🔢
Type: Counter
Definition: the total number of octets sent on this port during the lifetime of this application, meaning the application that opened this port.
The IpTransportLayer Dictionary: HmpValues 🍓
The HmpValues dictionary would store all the info on the Host Monitoring Protocol, which is defined in RFC-869. But HEMS is designed to replace HMP, so defining this dictionary has been put off until there's a clear need for it 🫠
The IpTransportLayer Dictionary: RdpValues 💜
The RdpValues dictionary would store all the info on the Reliable Data Protocol (RDP). RDP is still being tested and revised, so defining this dictionary is left for further study 🧪
The IpTransportLayer Dictionary: NetbltValues 🦋
okay so the NetbltValues dictionary is where all the info on the Network Block Transfer protocol (Netblt) lives 📦. but Netblt is still being tested and revised rn, so the definition of this dictionary is left for further study 🙈 no cap, it's a "we'll get back to you" situation.
The IpApplications Dictionary 🌸
the IpApplications dictionary stores info about networking apps whose operations might affect how the network runs properly 🧚. examples? domain nameservers or distributed routing agents (like gated or routed) bestie 💅. the definition of this dictionary is also left for further study ✨.
NOTES ON RETRIEVAL OF OBJECTS 💜
this part is lowkey important. the vibe is that the query processor is only one of many processes running at once on an entity, and the other processes can change the values of the objects the query processor manages 🌀. so the query processor is not required to keep values frozen while a query runs. which means related values can change mid-query! applications should be ready for that 🙈
also, a few places specify mathematical relations between objects, like object X minus object Y should give some well-defined value 🔢. in lots of cases X and Y are roll-over counters, so those relations are only valid modulo the precision of the counter. that's acceptable fr 💅. the relationships are only intended to clarify the association between objects.
EVENTS 🔥
in the rest of this memo we present the format and definition of event messages, which are unsolicited updates sent from entities to management centers 📨.
this section needs much more work. the authors included it to show how the trap mechanism works, but way more research is needed on what events should be reported and what info they must carry before it can be finished. the authors welcome any advice from the community on this 🫶
Format of Event Messages 🎀
Event messages have the same format as replies: they are a sequence of objects. the only difference between an event message and a regular reply to a query is that the event message is labelled as an event in the HEMP message header, and the first object is a special event leader describing the event. all objects after the event leader are standard objects stored by the entity that might be useful to a monitoring center in understanding the machine state which caused the event 🧠. each event has a certain number of objects that it must return. additional objects may be returned by loading instructions into the eventExecution buffer of the relevant eventEntry ✨.
The format of the event leader is shown below:
EventLeader ::= [APPLICATION 1024] IMPLICIT SEQUENCE {
eventCode INTEGER,
eventIndex INTEGER,
eventThreshold INTEGER,
eventTime TimeStamp,
eventDescr IA5STRING
}- eventCode: a number which indicates the type of event. the eventCodes are defined below.
- eventIndex: an implementation specific value. it is considered good practice to make sure that a particular event is only generated in one place. it may be the case that certain HEMS generic events (for example, "no buffer space") may be generated by more than one place in an entity's code. to allow implementors and network managers to determine where the event is actually being generated, implementors should make sure that a distinct eventIndex is assigned to each location in the code that generates a particular event 🔍.
- eventThreshold: the value of the event threshold when the event was sent.
- eventTime: indicates when the trap was generated ⏰.
- eventDescr: a text string which describes the event. this description should explain the general problem (e.g., "no buffer space") and may also, optionally, include additional information about why this particular event was generated (e.g., "could not send ICMP redirect") 💌.
Event Definitions 📖
the remainder of this memo presents a few generic events, which are presented for illustration only. implementors interested in supporting events should contact the authors to help work out a more comprehensive set of definitions 🌟.
the format of the event definitions is:
- EVENT CODE: the event code number.
- Definition: defines the event.
- Related Objects: the list of related objects which must be returned following the event header. all objects should be returned as fully qualified objects (with ASN.1 codes tracing a complete path from the root object dictionary). if no objects are specified, then no related objects are required.
- Event Status: events are either required of all conforming implementations, required if the entity supports a particular feature (e.g., TCP events), or optional.
- Notes: any additional notes about the event.
List of Events 🌈
the next few event codes are for system (as opposed to more network oriented) events 💻.
EVENT CODE: 0
- Definition: Unused
EVENT CODE: 1
- Definition: The entity has rebooted.
- Related Objects: An INTEGER which is the highest HEMP messageID reached by the trap system before the system crashed. 💀
EVENT CODE: 2
- Definition: The entity is about to go into test mode.
EVENT CODE: 3
- Definition: The entity is about to reset.
EVENT CODE: 4
- Definition: The entity is about to reboot.
EVENT CODE: 5
- Definition: The entity is about to halt.
EVENT CODE: 6
- Definition: The system is close to depleting its packet buffer space.
- Event Status: optional
EVENT CODE: 7
- Definition: The system has depleted its packet buffer space.
EVENT CODE: 8
- Definition: The system has depleted a non-packet buffer space.
- Note: The two trap codes above do not deal neatly with systems which have multiple buffer pools, each of which may be depleted separately, with very different effects on the entity 🙃.
the next set of event codes applies to events related to network interfaces 🌐.
EVENT CODE: 1024
- Definition: The given interface has just come up.
- Related Objects: The InterfaceData structure for the interface.
EVENT CODE: 1025
- Definition: The given interface has just been taken down.
- Related Objects: The InterfaceData structure for the interface.
EVENT CODE: 1026
- Definition: The given interface has just gone into test mode.
- Related Objects: The InterfaceData structure for the interface.
the next set of event codes is used to report IP-level errors 🚨.
EVENT CODE: 2048
- Definition: Unable to route IP packet.
EVENT CODE: 2049
- Definition: Bad IP checksum.
EVENT CODE: 2050
- Definition: An IP packet with a bad header was received (for example, with a broadcast or multicast IP address as the source, or the wrong IP version number, or a header length which is too short).
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2051
- Definition: Packet for unsupported IP transport protocol.
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2052
- Definition: A stunted IP packet was received (smaller than the IP length says it should be).
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2053
- Definition: An oversize IP packet was received (larger than the IP length says it should be).
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2054
- Definition: A good IP packet was discarded (usually to free up buffer space).
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2055
- Definition: An IP packet's time-to-live as expired.
- Related Objects: Should return the IP header of the packet. Note that an IP header type has not yet been defined.
EVENT CODE: 2056
- Definition: This IP fragment has timed out.
- Related Objects: Should return the header of the fragment. Note that an IP header type has not yet been defined.
AREAS FOR FURTHER STUDY 🧠
there are several parts of this document that could use additional study, so comments from readers are super welcome 💖.
the whole event system needs a thorough examination 👀. it's not clear that the event control mechanism strikes the proper balance between enough flexibility for monitoring centers to customize their event stream and keeping the basic mechanism simple. further, defining generic events for all entities is an immense task 😭. finally, the system of appending required values after traps, followed by optional values read from the data tree, feels a bit cumbersome. it would be nice if all values were in the same data space 🫠.
several readers have suggested it might make more sense to keep TCP connection parameters on a per-connection basis rather than globally 🦋.
the method for specifying the TCP round-trip time algorithm needs to be refined. the expression syntax should be sufficiently general that all round-trip-time-related algorithms (e.g., those for time or routing protocols) can be expressed in it 🔥.
much more research could be done into what information needs to be gathered to effectively monitor a network 🌸✨
📦 where this page comes from
- ietf: rfc1024 1987-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms