Delay-Tolerant Networking E. Birrane
Internet-Draft E. DiPietro
Intended status: Informational D. Linko
Expires: May 3, 2018 Johns Hopkins Applied Physics Laboratory
October 30, 2017
AMA Application Data Modeling
draft-birrane-dtn-adm-00
Abstract
This document defines a data model suitable for managing applications
in asynchronously managed networks. This includes a description of
the data structures and type definitions that comprise the data model
as well as a template for publishing standardized representations of
static elements of the model. A YANG representation of the data
model and the template are also provided.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 3, 2018.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Birrane, et al. Expires May 3, 2018 [Page 1]
Internet-Draft ADM October 2017
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Data Modeling Concept of Operations . . . . . . . . . . . . . 5
5. Type Definitions . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Primitive Types . . . . . . . . . . . . . . . . . . . . . 6
5.2. Derived Types . . . . . . . . . . . . . . . . . . . . . . 7
5.2.1. Hex String . . . . . . . . . . . . . . . . . . . . . 7
5.2.2. Timestamp (TS) . . . . . . . . . . . . . . . . . . . 8
5.2.3. Type-Name-Value Collection . . . . . . . . . . . . . 8
6. Identification . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Asynchronous Resource Namespace (ARNs) . . . . . . . . . 10
6.2. Managed Identifiers . . . . . . . . . . . . . . . . . . . 10
6.2.1. MID Semantic Information . . . . . . . . . . . . . . 10
6.2.2. MID Value . . . . . . . . . . . . . . . . . . . . . . 11
6.2.3. MID Parameters . . . . . . . . . . . . . . . . . . . 12
6.2.4. MID References . . . . . . . . . . . . . . . . . . . 15
7. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1. MID Collection (MC) . . . . . . . . . . . . . . . . . . . 15
7.2. Expression (EXPR) . . . . . . . . . . . . . . . . . . . . 16
7.3. Predicate (PRED) . . . . . . . . . . . . . . . . . . . . 16
8. ADM Structures . . . . . . . . . . . . . . . . . . . . . . . 16
8.1. AMA Overview . . . . . . . . . . . . . . . . . . . . . . 16
8.2. Externally Defined Data (EDD) . . . . . . . . . . . . . . 18
8.3. Variables (VAR) . . . . . . . . . . . . . . . . . . . . . 19
8.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.4.1. Table Template (TBLT) . . . . . . . . . . . . . . . . 20
8.4.2. Table (TBL) . . . . . . . . . . . . . . . . . . . . . 21
8.5. Reports . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.5.1. Report Template (RPTT) . . . . . . . . . . . . . . . 22
8.5.2. Report (RPT) . . . . . . . . . . . . . . . . . . . . 23
8.6. Control (CTRL) . . . . . . . . . . . . . . . . . . . . . 24
8.7. Time-Based Rule (TRL) . . . . . . . . . . . . . . . . . . 25
8.8. State-Based Rule (SRL) . . . . . . . . . . . . . . . . . 27
8.9. Macro (MAC) . . . . . . . . . . . . . . . . . . . . . . . 28
8.10. Constant (CONST) . . . . . . . . . . . . . . . . . . . . 29
8.11. Operator (OP) . . . . . . . . . . . . . . . . . . . . . . 30
9. Data Type IDs and Enumerations . . . . . . . . . . . . . . . 32
9.1. Numeric Promotions . . . . . . . . . . . . . . . . . . . 33
9.2. Numeric Conversions . . . . . . . . . . . . . . . . . . . 34
10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 34
Birrane, et al. Expires May 3, 2018 [Page 2]
Internet-Draft ADM October 2017
10.1. ADM Types and Structures . . . . . . . . . . . . . . . . 34
10.2. Application Data Template . . . . . . . . . . . . . . . 47
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49
12. Security Considerations . . . . . . . . . . . . . . . . . . . 50
13. Informative References . . . . . . . . . . . . . . . . . . . 50
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50
1. Introduction
This document defines a data model suitable for managing applications
in asynchronously managed networks.
1.1. Purpose
The Asynchronous Management Architecture [I-D.birrane-dtn-ama]
documents a concept for open-loop control of applications and
protocols for situations where timely, highly-available connections
cannot exist amongst managing and and managed nodes in a network.
While the AMA describes a logical data model, it does not include the
detailed information necessary to produce interoperable physical
models.
This document provides a normative physical model, called an
Application Data Model (ADM), that is compliant with the AMA logical
data model and can be used to manage individual applications (or
protocols). An ADM is comprised of both predefined and dynamic
information. Predefined information is represented in an Application
Data Definition (ADD) document populated in conformance with an an
Application Data Template (ADT). Dynamic information is created on-
the-fly by operators in the context of individual network deployments
and management scenarios.
1.2. Scope
The ADM presented in this document is a data model. In order to
communicate this model between agents and managers in a network, the
model must be encoded for transmission. Any such encoding scheme is
outside of the scope of this document. Generally, encoding of the
model is a separate concern from the specification of data within the
model.
Since different networks may use different encodings for data,
mandating an encoding format would require incompatible networks to
encapsulate data in ways that could introduce inefficiency and
obfuscation. It is envisioned that different networks would be able
to encode ADMs in their native encodings such that translating ADM
data from one encoding to the next could be a mechanical action taken
at network borders. For this reason, the ADM model must provide
Birrane, et al. Expires May 3, 2018 [Page 3]
Internet-Draft ADM October 2017
information necessary to allow for the coherent translation of of
different encodings.
Since the specification does not mandate an encoding format, the data
model itself must provide enough information to make encoding (and
translating from one encoding to another) an unambiguous process.
Therefore, where necessary, this document provides identification,
enumeration and other schemes that ensure ADMs provide enough
information to prevent ambiguities caused by different encoding
schemes.
2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
3. Terminology
Note: The terms "Actor", "Agent", "Application Data Model", "Atomic
Data", "Computed Data", "Control", "Literal", "Macro", "Manager",
"Report Template", "Report Entry", and "Rule" are used without
modification from the definitions provided in [AMA].
Additional terms critical to understanding the ADMT are as follows.
o Application - A software implementation running on an Agent and
being managed by a manager. This includes software that
implements protocol processing on an Agent.
o Application Data Definitions (ADD) - The set of predefined data
items for an ADM, captured in the format of the ADT.
o Application Data Model (ADM) - The full set of data items
necessary to manage an application (or set of applications)
asynchronously. This includes both predefined and dynamically-
constructed data items.
o Application Data Template (ADT) - A standard format for expressing
predefined data items for an application.
o Managed Item Definition (MID) - A parameterized structure used to
uniquely identify all ADM objects.
o Report (RPT) - An ordered collection of report entries gathered by
an Agent and provided to one or more Managers. Reports represent
the fundamental unit of data exchange from an Agent to a Manager.
Birrane, et al. Expires May 3, 2018 [Page 4]
Internet-Draft ADM October 2017
o State-Based Rule (SRL) - A rule whose action is performed if a
defined predicate evaluates to true. SRLs are defined in
Section 8.8.
o Time-Based Rule (TRL) - A rule whose action is performed at
regular intervals. SRLs are defined in Section 8.7.
4. Data Modeling Concept of Operations
When a new application is to be asynchronously managed in accordance
with the [I-D.birrane-dtn-ama], the series of control and data
information specific to that application must be captured in a data
model. Portions of that data model will be predefined and common to
all instances of the application and portions of the data model will
be ad-hoc in the context of specific network deployments and
operational conditions.
The conceptual set of all information necessary to manage an
application is defined as the data model for that application and
termed the Application Data Model (ADM). The portions of the ADM
that are predefined can be published as a common set of management
information that is otherwise agnostic of any specific network
deployment. That set of predefined information is termed the
Application Data Definitions (ADD).
To aid in the exchange of data model information, a common
identification scheme and data format should be used to capture
information. This is defined in this document as a template that can
be filled out for each application and is terms the Application Data
Template (ADT).
The relationship of the ADM, ADD, and ADT are illustrated in
Figure 1.
Birrane, et al. Expires May 3, 2018 [Page 5]
Internet-Draft ADM October 2017
Data Model Relationship
+---------+
| ADT |
+----+----+
|
V
+---------+ +-----------+
| Ad-Hoc | | Published |
| Info | | ADD |
+----+----+ +-----+-----+
| |
V V
+-----------------------------+
| ADM |
+-----------------------------+
Figure 1
5. Type Definitions
This section describes custom type definitions used by the ADM.
Specifying basic type definitions is important as it forms the basis
for interchangeable encodings of the model.
5.1. Primitive Types
ADMs support a series of primitive types such as bytes, (un)signed
integers, floating point values, and others as outlined in Table 1.
Birrane, et al. Expires May 3, 2018 [Page 6]
Internet-Draft ADM October 2017
+--------------------+----------------------------------------------+
| Type | Description |
+--------------------+----------------------------------------------+
| BYTE | unsigned byte value |
| | |
| INT | 32-bit signed integer in 2's complement |
| | |
| UINT | 32-bit unsigned integer in 2's complement |
| | |
| VAST | 64-bit signed integer in 2's complement |
| | |
| UVAST | 64-bit unsigned integer in 2's complement |
| | |
| REAL32 | Single-precision, 32-bit floating point |
| | value in IEEE-754 format. |
| | |
| REAL64 | Double-precision, 64-bit floating point |
| | value in IEEE-754 format. |
| | |
| STRING | NULL-terminated series of characters in |
| | UTF-8 format. |
| | |
| BOOL | A Boolean value of FALSE (whose integer |
| | interpretation is 0) or TRUE (which is any |
| | integer interpretation that is not FALSE). |
+--------------------+----------------------------------------------+
Table 1: Primitive Types
5.2. Derived Types
A derived typed is a primitive type that is interpreted with special
semantics. The ADM supports the following derived types.
5.2.1. Hex String
A Hex String is a special type of STRING.
A Hex String contents a written representation of a hexadecimal
value, without prefix. In this scheme, byte values are separated by
colons (:). While either upper or lower case characters are
acceptable, by convention lower-case characters should be used for
increased readability.
For example, given the hexadecimal value 0x12AB the resultant Hex
String would be "12:ab".
Birrane, et al. Expires May 3, 2018 [Page 7]
Internet-Draft ADM October 2017
Hex Strings follow the format of the hex-string derived type as
defined in RFC6991.
5.2.2. Timestamp (TS)
A Timestamp is a special type of UVAST.
There are two "types" of timestamp within an ADM: a relative
timestamp and an absolute timestamp. A relative timestamp is defined
as the number of seconds between two events (such as the receipt of a
control by an agent and the execution of that control). An absolute
timestamp is defined as UTC time since the Unix/POSIX Epoch.
Rather than define two separate data types (one for relative
timestamps and one for absolute timestamps) or adding an extra field
(e.g., a timestamp type identifier) the type of timestamp can be
simply and unambiguously inferred from a single timestamp value. The
ADMT defines a Relative Timestamp Epoch. Timestamp values less than
the RTE will be interpreted as relative timestamps. Timestamp values
greater than or equal to the RTE will be interpreted as absolute
timestamps. The RTE is defined as September 9th, 2012 (UTC time
1347148800).
For example, a timestamp value of "10" refers to 10 seconds in the
future. A timestamp value of "1508554859" refers to Saturday,
October 21, 2017 3:00:59 AM.
It should be noted that absolute and relative times are
interchangeable. An absolute time can be converted into a relative
time by subtracting the current time from the absolute time. A
relative time can be converted into an absolute time by adding to the
relative time the current time. A pseudo-code example of this
conversion is as follows.
IF (timestamp < 1347148800) THEN
absolute_time = current_time + timestamp
ELSE
absolute_time = timestamp
5.2.3. Type-Name-Value Collection
A Type-Name-Value Collection (TNV) is a special type of STRING.
A TNV describes a list of ADM items with each item described as the
three-tuple of {type, name, value} or certain permitted subsets of
that three-tuple. The general form of the string is
Birrane, et al. Expires May 3, 2018 [Page 8]
Internet-Draft ADM October 2017
<type>:<name>=<value> with each item in the collection separated by
"&".
Type refers to the string representation of the ADM item type as
defined in Section 9. Name refers to the name of the ADM item.
Value refers to the string (or hex string) value of the ADM item.
For each item in a TNV, there are three acceptable formulations that
can be used to represent the item, as illustrated in the following
table. For the examples in this table, consider the REAL32 value of
PI as 3.14159.
+----------+---------------------+----------------------------------+
| Desc | Format | Example |
+----------+---------------------+----------------------------------+
| Full | <type>:<name>=<valu | REAL32:PI=3.14159&INT:PI_INT=3 |
| | e> | |
| | | |
| Named | <type>:<name> | REAL32:PI&INT:PI_INT |
| Type | | |
| | | |
| Anonymou | <type> | REAL32&INT |
| s Type | | |
| | | |
| Anonymou | <type>:=<value> | REAL32:=3.14159&INT:=3 |
| s Type | | |
| Value | | |
| | | |
| Anonymou | =<value> | =3.14159&=3 |
| s Value | | |
| | | |
| Mixed | Varies | REAL32:PI=3.14159&INT:PI_INT&INT |
| | | &=3 |
+----------+---------------------+----------------------------------+
Table 2: TNV Formulations
In ADMs, TNVs are used to capture parameterized items and describe
the contents of reports.
6. Identification
The primary responsibility of an ADM is to uniquely identify the
components necessary to asynchronously manage the application. This
section describes the two mechanisms used to identify every item
within every ADM: Asynchronous Resource Names (ARNs) and Managed
Identifiers (MIDs).
Birrane, et al. Expires May 3, 2018 [Page 9]
Internet-Draft ADM October 2017
6.1. Asynchronous Resource Namespace (ARNs)
Every ADM must identify itself by an asynchronous resource namespace
(ARN). This is separate from the YANG namespace and provides a
moderated, formatted way of identifying the ADM in the context of
other ADMs. Such a naming provides important semantic information
necessary for encodings of ADM contents. The format of an ARN is a
colon-separated set of moderated scoping keywords, as follows.
arn:<Broadest-Scoped Keyword>:<Narrowest-Scoped Keyword>
For example, the DTN community publishes the Bundle Protocol and the
ADM for the Bundle Protocol could be assigned the namespace
arn:Dtn:BundleProtocol. Another ADM published specifically for
management of a particular implementation of a Bundle Protocol Agent
(for example, the Interplanetary Overlay network (ION)) could have
the separate namespace arn:DTN:ION:BundleProtocolAdmin.
ARN keywords will be moderated to create a known keyword list and
associated ontology that provides some semantic structure to ADM
names beyond the associations that may or may not be present to allow
groupings in the YANG format.
6.2. Managed Identifiers
Every item codified in a published ADM (or generated in operational
use) must be uniquely identifiable. The Managed Identifier (MID)
accomplishes this by providing a variable-length, flexible structure
with optional fields to capture special identifier-related
circumstances.
A MID in an ADM consists of three types of information: (1) human-
readable semantic information, (2) the identifier value, and (3)
parameters, if necessary.
6.2.1. MID Semantic Information
A MID can have an optional name and description associated with it.
These help provide documentation of the ADM item identified by the
MID.
The MID Name is a string that should uniquely identify the ADM item
within the context of the ADM. It is recommended that this name be a
human-readable and user-friendly alternative to the numeric ID
portion of the MID.
The MID Description is a string that captures important information
describing the purpose of usage of the ADM item. The description
Birrane, et al. Expires May 3, 2018 [Page 10]
Internet-Draft ADM October 2017
should also be human-readable and user-friendly. The MID description
is not considered part of the uniquely identifying part of the MID
and may be duplicated across multiple MIDs in an ADM. No part of the
MID description should be used to interpret the uniqueness of any ADM
item.
6.2.2. MID Value
There are two categories of information that can be identified by a
MID in an ADM: named and literal items. A named item is an item in
an ADM whose value should not be used as its identifier. This can be
because the value is not unique to the item, or the value is of such
length or complexity as to make its use as an identifier impractical.
A literal item is one that can be uniquely and succinctly identified
by its value.
6.2.2.1. Named Item
The identification of a named item consists of four parts: (1) The
type of item being identified, (2) a unique identifying value for the
item, (3) an optional issuer field, and (4) an optional tag field.
These four items are represented as a string with the format
<Type>_<enumeration>:<issuer>:<tag>. The description of each of
these types is as follows.
Item Type
The type of the ADM item being identified is the string
representation of the type, as defined in Section 9.
Unique Identifier
The identifier may be any uniquely identifying information, such as
the name of the MID, or a numeric enumeration of the order of the MID
in the ADM.
Issuer
The issuer field is any string (or hex string) representing some
identification of the organization defining this item. This value
may come from a global registry of organizations, an issuing node
address, a signed known value, or some other network-unique marking.
When an item is defined in the context of an ADM, the issuer tag MUST
NOT be present. ADD-defined items are defined relative to their ARN
and need no additional information to determine their issuer.
Therefore, the issuer tag is only present in ADM items created on-
the-fly as part of an operational network.
Tag
The tag field is any string (including a hex string) used to
disambiguate or otherwise validate a MID created by an issuer.
Birrane, et al. Expires May 3, 2018 [Page 11]
Internet-Draft ADM October 2017
Similar to the issuer field, the tag field MUST NOT be present in a
MID identified in an ADM. Since a tag field has meaning only in the
context of its issuer it MUST NOT be present in a MID that is lacking
an issuer field. The contents of the tag field is left to the
discretion of the issuer. Examples of envisioned tag values include
an issuer-known version number or a signed or unsigned hashing of the
data associated with the MID.
6.2.2.2. Literal Item
The identification of a literal item consists of three parts: (1) The
type of item being identified, (2) the data type of the value, and
(3) the value of the item. These two items are represented as a
string in the ADM with the format <Type>_<value type>.<value>. The
description of each of these types is as follows.
Item Type
The type of a literal item MUST be LIT.
Value Type
The type of the literal value. This MUST be one of the primitive
types as described in Table 1.
Value
The value is simply the value of the item.
For example, here are some ways of identifying the literal value "9"
in an ADM.
+---------------------------+----------------+
| Description | Example |
+---------------------------+----------------+
| As a signed integer | LIT_INT.9 |
| | |
| As an unsigned integer | LIT_UINT.9 |
| | |
| As a floating point value | LIT_REAL32.9.0 |
| | |
| As a string | LIT_STR.Nine |
+---------------------------+----------------+
Sample Literal MIDs
6.2.3. MID Parameters
Certain ADM items can be parameterized to support a cleaner and less-
chatty interface between agents and managers. When a MID is
parameterized, a parameter specification is appended to the end of
Birrane, et al. Expires May 3, 2018 [Page 12]
Internet-Draft ADM October 2017
the string representation of the MID. This specification may capture
"formal parameters" or "actual parameters". The ADM also supports
the specification of optional parameters.
6.2.3.1. Formal Parameters
A "formal parameter" defines the type, name, and order of the
variables that should be provided to the MID. Formal parameters are
defined in the context of an ADM using static, strong typing. This
approach is similar to how parameters are defined in a function
definition, such as "foo(int a, float b)". In this example, the
function foo is defined as accepting two variables: an integer named
"a" and a floating point value named "b".
Formal parameters MUST include TYPE and NAME information and MAY
include an optional default VALUE. If specified, a default value
will be used whenever a set of Actual Parameters fails to provide a
value for this Formal Parameter.
Formal parameters are represented in a MID using a TNV Collection.
The TNV for the example above could be represented as
"INT:a&REAL32:b". Also, if parameter a had a default value of 7, the
Formal Parameter list could have been represented as
"INT:a=7&REAL32:b".
6.2.3.2. Actual Parameters
An "actual parameter" defines the type, name, and value of a set of
variables that serve as arguments for a previously-defined formal
parameter set. Actual parameters are used when a particular instance
of a parameterized ADM item is generated by an Agent or a Manager and
the MID of that instance must contain values that match, in type and
number, the formal parameters of the ADM item. Using the "foo"
example above, an actual parameter list would be represented in the
call "foo(3, 3.14)".
An Actual Parameter MAY have any combination of TYPE or VALUE
information. If the Formal Parameter list defined a default value,
then the associated Actual Parameter MAY also be empty. If a TYPE is
provided in an Actual Parameter then the type MUST match the type
provided by the Formal Parameter. An Actual Parameter MUST NOT
include NAME information.
Actual parameters are represented in a MID using a TNV string. The
TNV for the example above could be represented as
"INT:a=3&REAL32:b=3.14". If parameter a had a default value defined,
then another possible Actual Parameter list for the above example
could be represented as "INT:=&b=3.14" or simply "&b=3.14".
Birrane, et al. Expires May 3, 2018 [Page 13]
Internet-Draft ADM October 2017
6.2.3.3. Optional Parameters
When parameterizing an ADM item, some parameters may be optional with
default values defined if parameters are omitted. The use of
optional parameters helps keep MID values small when using default
values for parameters is a common case, rather than forcing all
parameters to be provided all the time.
Consider the following TNV string capturing a set of formal
parameters: "INT:a&REAL32:b&UINT:c=0&INT:d=-1". The following table
shows the values of formal parameters c and d given a variety of TNV
strings representing actual parameters.
+-------------------------------------+----------+------------------+
| Actual Parameter | C Value | D Value |
+-------------------------------------+----------+------------------+
| INT:=3&REAL32:=3.14 | 0 | -1 |
| | | |
| INT:=3&REAL32:=3.14&UINT:=1 | 1 | -1 |
| | | |
| INT:=3&REAL32:=3.14&UINT:=1&INT:=-2 | 1 | -2 |
| | | |
| INT:=3&REAL32:=3.14&&INT:=-2 | 0 | -2 |
+-------------------------------------+----------+------------------+
Table 3: TNV Formulations
6.2.3.4. Parameter Evaluation
Actual Parameters in a MID may be represented in one of two ways: the
parameter itself (parameter by value), or an expression used to
determine the parameter (parameter by evaluation).
6.2.3.4.1. Parameter By Value
When specifying a parameter using a value, the type of the Actual
Parameter MUST be present and MUST match the expected Formal
Parameter type. The Actual Parameter value will be used as the value
of the parameter.
For example, consider a Formal Parameter list that takes 1 parameter,
an unsigned integer (UINT). When populating this parameter by value,
the type of the Actual Parameter MUST be UINT and the parameter value
MUST be the desired unsigned integer.
Birrane, et al. Expires May 3, 2018 [Page 14]
Internet-Draft ADM October 2017
6.2.3.4.2. Parameter By Evaluation
When the value of a Actual Parameter is likely to change, an
Expression (EXPR) may be substituted for the Actual Parameter value.
The Expression can then be evaluated to calculate the value.
An Actual Parameter defined by evaluation MUST be of type EXPR, and
the type of the EXPR must be equal to the expected type. Expressions
and Expression types are discussed in Section 3.6.2.
NOTE: If the type of the Formal Parameter is already EXPR, and an
Actual Parameter of type EXPR is provided, then the Actual Parameter
MUST be processed in the same way as Parameter By Value. The ADM
does not support an EXPR which references another EXPR as doing so
leads to significant confusion in implementations and the possibility
of circular reference.
6.2.3.4.3. Identifying Parameter Approach
The determination of whether an Actual Parameter should be
interpreted by value or by evaluation is made by comparing the given
type of the Actual Parameter to the expected type of the Formal
Parameter.
If the types match, then the Actual Parameter MUST be considered by
value. If the Actual Parameter type is an EXPR and the EXPR type
matches the Formal Parameter type, then the Actual Parameter MUST be
considered by evaluation of the EXPR. In any other case, the Actual
Parameter MUST be considered invalid as being from a type mismatch.
6.2.4. MID References
There are several times when a MID must be referenced within the
contents of an ADM document and a useful shorthand is defined to
allow for this expression. Since a MID name is required to be unique
for a given data type, the combination of MID type and MID name may
be used as a reference.
Specifically, a MID reference is a string with the form
<type>.<name>.
7. Collections
7.1. MID Collection (MC)
Often, in either an ADM or an ADD, it is necessary to discuss
collections of items that are provided as parameters to other items.
For example, a Control that is used to generate a series of Report
Birrane, et al. Expires May 3, 2018 [Page 15]
Internet-Draft ADM October 2017
Entries may accept, as a parameter, a list of the MIDs defining the
Report Templates to be generated.
A MC may be represented as a string that contains zero or more MID
representations separated by whitespace. A MID within a MC MAY be
either a MID Reference or a MID Identifier.
A MC may alternatively be represented as an array with zero or more
elements, with each element being a MID representation (either a MID
reference or a MID identifier).
7.2. Expression (EXPR)
Expression apply mathematical operations to values to generate new
values, typically on computers fulfilling the Agent role within the
AMA. Since the variables, operators, and literals that comprise
these operations are all formal ADM items, they are all identified by
MIDs. Because they are all identified by MIDs, the expression may be
represented by a MC.
An expression (EXPR) is a MC in which a series of items are ordered
so as to produce a valid post-fix mathematical expression. For
example, the infix expression A * (B * C) is represented as the
sequence A B C * *.
7.3. Predicate (PRED)
Predicates are Expressions whose values are interpreted as a Boolean.
The value of zero MUST be considered "false" and all other values
MUST be considered "true".
8. ADM Structures
This section identifies the ADM structures that implement the AMA
logical data model.
8.1. AMA Overview
The AMA defines a series of logical components that should be
included as part of an ADM. These components are summarized from the
AMA in the following table. The ADM implements these logical
components in largely a one-to-one fashion with a few exceptions.
Birrane, et al. Expires May 3, 2018 [Page 16]
Internet-Draft ADM October 2017
+-----------+-----------------------------------+-------------------+
| AMA | Summary Description | ADM Structure |
| Component | | |
+-----------+-----------------------------------+-------------------+
| Atomic | A typed, measured value whose | Externally |
| Data | definition and value | Defined Data |
| | determination occurs externally | |
| | from the network management | |
| | system. | |
| | | |
| Computed | A typed, computed value whose | Variable |
| Data | definition and value | |
| | determination occurs within the | |
| | network management system. | |
| | | |
| Report | Collections of Atomic and/or | Table Definition, |
| Entry | Computed data and/or other | Table, Report |
| | Reports. | Definition, |
| | | Report |
| | | |
| Control | Parameterized opcode for any | Control |
| | action that can be taken by an | |
| | Agent. | |
| | | |
| Rule | A pre-configured response to a | State-Based Rule, |
| | predefined time or state on an | Time-Based Rule |
| | Agent. | |
| | | |
| Macro | An ordered collection of | Macro |
| | Controls. | |
| | | |
| Literal | A constant used when evaluating | Literal, Constant |
| | Rules or determining the value of | |
| | Computed Data. | |
| | | |
| Operator | An opcode representing a | Operator |
| | mathematical function known to an | |
| | Agent. | |
+-----------+-----------------------------------+-------------------+
AMA Logical Components
The remainder of this section describes the format of these
structures in the context of the aforementioned ADM data types.
Birrane, et al. Expires May 3, 2018 [Page 17]
Internet-Draft ADM October 2017
8.2. Externally Defined Data (EDD)
Externally defined data (EDD) are predefined components of an ADM for
various applications and protocols. These represent values that are
calculated outside of the context of Agents and Managers, such as
those values measured by firmware. As such, their value is defined
external to the ADM system.
8.2.1. Definition
An EDD consists of a MID, type, and a description, as follows.
MID
EDDs are defined solely in the context of an ADD. Since they
are sampled external to the management system, changes or
additions to EDDs require changes to how the network
management system interfaces with other components on an
Agent.
Because an EDD is defined in the context of an ADD, it MUST
NOT contain an Issuer or Tag field and the type of the MID
MUST be the EDD type.
Type
This represents the data type of the value associated with
the EDD.
Description
This represents the human-readable description of the EDD, as
a string.
8.2.2. Processing
Managers
o Store the MID for each known EDD definition.
o Associate a data type to each known EDD definition.
o Encode EDD MIDs in Controls to Agents, as appropriate.
Agents
o Store the MID for each known EDD definition.
o Associate a data type to each known EDD definition.
o Calculate the value of an EDD definition when required, such as
when generating a Report Entry or evaluating an Expression.
Birrane, et al. Expires May 3, 2018 [Page 18]
Internet-Draft ADM October 2017
8.3. Variables (VAR)
Variables (VAR) may be predefined in an ADD or dynamically in a
network deployment. VARs differ from EDDs in that they are
completely described by other known data in the system (either other
VARs or other EDDs). For example, letting E# be a EDD item and V# be
a VAR item, the following are examples of VAR definitions.
V1 = E1 * E2
V2 = V1 + E3
8.3.1. Definition
VARs are defined by a MID, a type, an initializing expression, and a
description, as follows.
MID
The type of this MID MUST be type VAR, and the MID MUST NOT
contain parameters.
Type
This is the type of the VAR, and acts as a static cast for
the result of the initializing EXPR. This type MUST be one
of the data types defined in Table 1. Note, it is possible
to specify a type different than the resultant type of the
initializing EXPR. For example, if an EXPR adds two single-
precision floating point numbers, the VAR MAY have an integer
type associated with it.
Initializer
The initial value of the VAR is given by an initializing
EXPR. In the case where the type of the VAR itself is EXPR
the initializer is used as the value of the VAR. In the case
where the type of the VAR is anything other than EXPR, then
the initializer EXPR will be evaluated and the resultant
value will be used as the initial value of the VAR.
Description
This represents the human-readable description of the VAR, as
a string.
8.3.2. Processing
Managers
o Store the MID for each ADD-defined VAR definition.
Birrane, et al. Expires May 3, 2018 [Page 19]
Internet-Draft ADM October 2017
o Send requests to Agents to add, list, describe, and remove VAR
definitions.
o Remember custom VAR definitions.
o Encode VAR MIDs in Controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined VAR definition.
o Calculate the value of VARs when required, such as during Rule
evaluation, calculating other VAR values, and generating Reports.
o Add, remove, list, and describe custom VAR definitions.
8.4. Tables
A Table is a named, typed, collection of tabular data. Columns
within a table are named and typed. Rows within a table capture
individual data sets with one value in each row corresponding to one
column in the table.
Tables are represented in two ways in the ADM: Table Definitions and
Table Instances. A Table Definition appears in an ADD and describes
the general format of a table. A Table Instance is a set of data
populated according to the structure of a Table Definition.
8.4.1. Table Template (TBLT)
Table definitions are predefined items of an ADM and, as such, MUST
appear in the ADD for an application.
8.4.1.1. Definition
TBLTs are defined by a MID, a set of column descriptions, and a
description, as follows.
MID
The type of this MID MUST be type TBLT, and the MID MUST NOT
contain parameters. Since Table Template definitions only
appear in an ADD document, this MID MUST NOT contain an
Issuer or a Tag field.
Columns
A Table is completely defined by its ordered set of columns
descriptions. Each column description is a name and a type.
Birrane, et al. Expires May 3, 2018 [Page 20]
Internet-Draft ADM October 2017
The type of each column MUST be one of the primitive types
defined in Table 1.
A column description is represented as a TNV string that MUST
contain TYPE and NAME information and MUST NOT contain VALUE
information. For example, a table with three columns could
be represented by the TNV string
"REAL32:col1&INT:col2&UINT:col3".
Description
This represents the human-readable description of the TABLE
template, as a string.
8.4.2. Table (TBL)
Tables are collections of data that MUST be constructed in accordance
with an associated Table Template. Tables MUST NOT appear in the ADD
for an application; they are only instantiated dynamically as part of
the operation of a network.
8.4.2.1. Definition
TBLs are defined by their Table Template, the number of rows in the
table, and the associated set of data values for each row.
Template MID
This is the MID of the Table Template holding the column
definitions for this table. This MID MUST match a known
Table Template defined in an ADD.
Number of Rows
This is the number of rows in the table. A Table MAY have
zero rows.
Rows Information
Each row in a TBL is represented as the number of data
elements in the row, followed by the data elements
themselves.
The number of data values for each row MUST be equal to the
number of columns defined for the Table Template.
The data values for each row are represented by a TNV that
optionally contains TYPE information and MUST contain value
information. Type information MAY be included when necessary
to verify that elements entered into a table match the type
expected by a column in the table.
For example, given the above Table Template example, a valid
row could be represented as "=3.14&=3&=3" or as
"REAL32:=3.14&INT:=3&UINT:=3".
Birrane, et al. Expires May 3, 2018 [Page 21]
Internet-Draft ADM October 2017
8.4.3. Processing
Managers
o Store the MID for each ADD-defined Table Template definition.
o Request that Agents populate tables according to this template.
Agents
o Store the MID for each ADD-defined Table Template definition.
o Produce Tables in accordance with Table Template definitions when
required.
8.5. Reports
A Report is a set of non-tabular, potentially nested data items that
may be predefined in the context of an ADD, or defined dynamically in
the context of a deployed network.
Reports are represented in two ways in the ADM: Report Templates and
Reports. A Report Template defines the type of information to be
included in a report, and a Report contains that information.
8.5.1. Report Template (RPTT)
A Report Template (RPTT) is the ordered set of data descriptions that
describe how values will be represented in a corresponding Report.
RPTTs can be viewed as a schema that describes how to interpret a
Report; they contain no values and are either defined in an ADM or
configured between Managers and Agents during network operations.
8.5.1.1. Definition
RPTTs are defined by a MID, the set of information comprising the
report, and a description, as follows.
MID
The type of this MID MUST be type RPTT. If the RPTT is
defined in an ADD it MUST NOT contain an Issuer or Tag field.
If the RPTT is defined outside of an ADD it MUST contain an
Issuer field and MAY contain a Tag field.
An RPTT MID MAY be parameterized. If the RPTT MID is
parameterized, the parameters MUST be used (in the same
number and order) to customize any parameterized data in any
Report generated using this template.
Birrane, et al. Expires May 3, 2018 [Page 22]
Internet-Draft ADM October 2017
Entries
The list of ordered data items to be included in the report
is represented by the list of identifiers for those items.
Since every structure in the ADM can be identified by a MID,
this value is represented by a MC.
NOTE: Since a RPTT is identified by a MID, it is possible
that a RPTT contains the MID of another RPTT. This signifies
that a report has, as one of its entries, another report.
This is allowed in the system, but MUST NOT lead to circular
references.
Description
This represents the human-readable description of the Report
template, as a string.
8.5.2. Report (RPT)
A Report (RPT) is a set of data values populated in conformance to a
given RPTT. Each data value in a report is termed a Report Entry
(RPTE).
8.5.2.1. Definition
RPTs are defined by their associated report template and the report
entries themselves, as follows.
RPTT MID
This is the identifier associated with the structure used to
help interpret the Report. A Report may be generated in
accordance with a predefined Report Template, in which case
the MID MUST be the MID of the RPTT. However, a Report MAY
be generated without an RPTT (called an anonymous report) in
which case this MID MUST be the MID of the Control that
caused the report to be generated.
Report Entries)
This is the collect of data that comprise the report. These
entires MUST consist of a series of data values and MAY
additionally contain type information for each entry.
RPTEs are represented by a TNV collection. This TNV MUST
contain VALUEs and MAY contain NAMES. If the RPTT MID
associated with this Report is of type CTRL (in which case
this is an anonymous Report) then the TNV MUST contain TYPE
information as well. Otherwise, the TNV MAY contain TYPE
information.
Birrane, et al. Expires May 3, 2018 [Page 23]
Internet-Draft ADM October 2017
8.5.3. Processing
Managers
o Store the MID for each ADD-defined Report Template.
o Send requests to Agents to add, list, describe, and remove custom
Report Templates.
o Remember custom Report Templates when processing Report Entries
received by Agents.
o Encode Report Template MIDs in Controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined Report Template.
o Populate Report Entries for transmission to Managers when required
by a Control.
o Add, remove, list, and describe custom Report Templates.
8.6. Control (CTRL)
A Control represents a predefined (possibly parameterized) opcode
that can be run on an Agent. Controls in the ADM are always defined
in the context of an ADD as there is no concept of an operator-
defined Control. Since Controls are pre-configured in Agents and
Managers as part of ADM support, their representation is simply the
MID that identifies them, similar to EDDs.
8.6.1. Definition
Controls are identified by their MID and their description, as
follows.
MID
This is the MID identifying the Control. The MID MUST be of
type CTRL. Since Controls are only defined in ADDs, this MID
MUST NOT have an Issuer field and MUST NOT have a Tag field.
The MID MAY have parameters.
When defined in the context of an ADD, the Control MID MUST
match the definition of a Formal Parameter list (e.g., there
are no VALUES). This is because the ADD defines the Controls
that can be invoked, but does not define any particular
invocation of a Control.
Birrane, et al. Expires May 3, 2018 [Page 24]
Internet-Draft ADM October 2017
When used as part of network operations, a Control MID MUST
match the definition of an Actual Parameter list (e.g., there
are VALUES). This is because when used operationally, a
parameterized Control required parameters to be run.
In cases where a Control takes no parameters, the definition
in the ADD document MUST be considered the definition of the
Control and the presence of the same MID in the context of an
operational system MUST be seen as an invocation of that
Control.
Description
This represents the human-readable description of the
Control, as a string.
8.6.2. Processing
Managers
o Store the MID for each ADD-defined Control definition.
o Store the number of parameters and each parameter type for
parameterized Controls.
o Encode Control MIDs in other Controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined Control definition.
o Implement Controls in firmware and run Controls with appropriate
parameters when necessary in the context of Manager direction and
Rule execution.
o Communicate "return" values from Controls back to Managers as
Report Entries where appropriate.
8.7. Time-Based Rule (TRL)
A Time-Based Rule (TRL) specifies that a particular action should be
taken by an Agent based on some time interval. A TRL specifies that
starting at a particular START time, and for every PERIOD seconds
thereafter, an ACTION should be run by the Agent until the ACTION has
been run for COUNT times. When the TRL is no longer valid it MAY BE
discarded by the Agent.
Examples of TRLs include:
Birrane, et al. Expires May 3, 2018 [Page 25]
Internet-Draft ADM October 2017
Starting 2 hours from receipt, produce a Report Entry for Report
Template R1 every 10 hours ending after 20 times.
Starting at the given absolute time, run Macro M1 every 24 hours
ending after 365 times.
8.7.1. Definition
MID
This is the MID identifying the TRL. When a TRL is defined
in an ADD this MID MUST NOT have an Issuer field and MUST NOT
have a Tag field. When the TRL is defined outside of an ADD,
the MID MUST have an Issuer field and MAY have a Tag field.
This MID MUST NOT be parameterized.
START
The time at which the TRL should start to be evaluated. This
will mark the first running of the action associated with the
TRL.
PERIOD
The number of seconds to wait between running the action
associated with the TRL.
COUNT
The number of times the TRL action may be run. The special
value of 0 indicates the TRL should continue running the
action indefinitely.
ACTION
The collection of Controls and/or Macros to run by the TRL.
This is captured as a MC with the constraint that every MID
within the MC represent a Control or Macro.
Description
This represents the human-readable description of the TRL, as
a string.
8.7.2. Processing
Managers
o Send requests to Agents to add, list, describe, and remove custom
TRL definitions.
o Remember custom TRL definitions when processing Reports received
by Agents.
Birrane, et al. Expires May 3, 2018 [Page 26]
Internet-Draft ADM October 2017
o Send requests to Agents to suspend/resume the evaluation of TRLs.
o Encode TRL MIDs in Controls to Agents, as appropriate.
Agents
o Run the actions associated with TRLs in accordance with their
start time and period.
o Add, remove, list, and describe custom TRL definitions.
o Suspend and resume the evaluation of a TRL when directed by a
Manager or another Rule.
o Report on the status of TRLs.
8.8. State-Based Rule (SRL)
A State-Based Rule (SRL) specifies that a particular action should be
taken by an Agent based on some evaluation of the internal state of
the Agent. A SRL specifies that starting at a particular START time
an ACTION should be run by the agent if some CONDITION evaluates to
true, until the ACTION has been run COUNT times. When the SRL is no
longer valid it MAY be discarded by the agent.
Examples of SRLs include:
Starting 2 hours from receipt, whenever V1 > 10, produce a Report
Entry for Report Template R1 no more than 20 times.
Starting at some future absolute time, whenever V2 != V4, run
Macro M1 no more than 36 times.
8.8.1. Definition
MID
This is the MID identifying the SRL. When a report is
defined in an ADM this MID MUST NOT have an Issuer field and
MUST NOT have a Tag field. When the SRL is defined outside
of an ADM, the MID MUST have an Issuer field and MAY have a
Tag field. This MID MUST NOT be parameterized.
START
The time at which the SRL condition should start to be
evaluated. This will mark the first evaluation of the
condition associated with the SRL.
CONDITION
Birrane, et al. Expires May 3, 2018 [Page 27]
Internet-Draft ADM October 2017
The Predicate which, if true, results in the SRL running the
associated action.
COUNT
The number of times the SRL action can be run. The special
value of 0 indicates there is no limit on how many times the
action can be run.
ACTION
The collection of Controls and/or Macros to run as part of
the action. This is captured as a MC data type with the
constraint that every MID within the MC represent a Control
or Macro.
Description
This represents the human-readable description of the SRL, as
a string.
8.8.2. Processing
Managers
o Send requests to Agents to add, list, describe, suspend, resume,
and remove custom SRL definitions.
o Remember custom SRL definitions when processing Report Entries
received by Agents.
o Encode SRL MIDs in Controls to Agents, as appropriate.
Agents
o Run the actions associated with SRLs in accordance with their
start time and evaluation of their predicate.
o Add, remove, list, and describe custom SRL definitions.
o Suspend and resume SRL evaluation when commanded by a Manager or
another Rule.
8.9. Macro (MAC)
Macros are ordered collections of MIDs (an MC) that contain Controls
or other Macros. When run by an Agent, each MID in the MC is run in
order.
Birrane, et al. Expires May 3, 2018 [Page 28]
Internet-Draft ADM October 2017
8.9.1. Definition
A Macro is defined by a MID, a set of Controls, and a description, as
follows.
MID
This is the MID identifying the Macro. When a Macro is
defined in an ADD this MID MUST NOT have an Issuer field and
MUST NOT have a Tag field. When the Macro is defined outside
of an ADD, the MID MUST have an Issuer field and MAY have a
Tag field. This MID MUST NOT be parameterized.
Definition
This is the ordered collection of MIDs that identify the
Controls and other Macros that should be run as part of
running this Macro. This is represented by a MC.
Description
This represents the human-readable description of the MACRO,
as a string.
8.9.2. Processing
Managers
o Store the MID for each ADD-defined Macro definition.
o Send requests to Agents to add, list, describe, and remove custom
Macro definitions.
o Encode macro MIDs in Controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined Macro definition.
o Remember custom Macro definitions and run Macros when appropriate,
such as when responding to a run-Macro Control or when executing
the action of a TRL or SRL.
o Add, remove, list, and describe custom Macro definitions.
8.10. Constant (CONST)
Constants represent named basic values. Examples include common
mathematical values such as PI or well-known Epochs such as the UNIX
Epoch. Constants are defined solely within the context of ADDs.
Birrane, et al. Expires May 3, 2018 [Page 29]
Internet-Draft ADM October 2017
8.10.1. Definition
A CONST is defined by its MID, value, and description, as follows.
MID
The MID MUST have type CONST and MUST NOT have an Issuer
field and MUST NOT have a Tag field. MIDs for CONST
structures MUST NOT be parameterized.
Typed Value
The value of a constant is the immutable value that should be
used in lieu of the Constant MID when evaluating Expressions
and Predicates.
The typed value of a CONST is represented by a TNV collection
that MUST have 1 element and MUST contain a TYPE and a VALUE
and MUST NOT contain a NAME. An example of a typed value for
a CONST would be ""REAL32:=3.14".
Description
This represents the human-readable description of the CONST,
as a string.
8.10.2. Processing
Managers
o Store the MID for each ADD-defined Constant definition.
o Encode Constant MIDs in controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined Constant definition.
o Calculate the value of Constants where appropriate, such as when
generating a Report Entry or when evaluating an Expression.
8.11. Operator (OP)
Operators represent user-defined mathematical functions implemented
in the firmware of an Agent for the purpose of aiding the evaluation
of Expressions and Predicates. The ADM separates the concepts of
Operators and Controls to prevent side-effects in Expression and
Predicate evaluation (e.g. to avoid constructs such as A = B +
GenerateReport()) which is why Operators are given their own
structure type and Controls do not support a return value.
Birrane, et al. Expires May 3, 2018 [Page 30]
Internet-Draft ADM October 2017
Because Operators represent custom firmware implemented on the Agent,
they are not defined dynamically as part of network operations.
Therefore, they may only be defined in the ADD for an application.
8.11.1. Definition
An Operator is defined by its MID, its resultant type, the number of
operands, the type of operands, and a description, as follows.
MID
The MID MUST have type OP and MUST NOT have an Issuer or Tag
field. The MID MUST NOT be parameterized.
Out Type
This is the return value of the Operator and MAY be different
than the operand types accepted by the Operator.
Num Operands
This is the number of operands accepted by the operator. For
example, the unary NOT Operator ("!") would accept one
parameter. The binary PLUS Operator ("+") would accept two
parameters. A custom function to calculate the average of
the last 10 samples of a data item would accept 10
parameters.
In Types
This is the TYPE information for each operand accepted by the
Operator. This is represented as a TNV Collection that MUST
contain TYPE information, MAY contain NAME information and
MUST NOT contain VALUE information. There MUST be exactly
the same number of elements in the TNV collection as the Num
Operands specified for the Operator.
Description
This represents the human-readable description of the
Operator, as a string.
8.11.2. Processing
Managers
o Store the MID for each ADD-defined Operator definition.
o Encode Operator MIDs in Controls to Agents, as appropriate.
Agents
o Store the MID for each ADD-defined Operator definition.
Birrane, et al. Expires May 3, 2018 [Page 31]
Internet-Draft ADM October 2017
o Store the number of parameters expected for each Operator.
o Calculate the value of applying an Operator to a given set of
parameters, such as when evaluating an Expression.
9. Data Type IDs and Enumerations
This section defines identifiers and enumeration values for objects
defined in the ADM. Identifiers are the text abbreviations used in
ADMs to identify data types. Enumerations associate data types with
a numeric value. These enumerations MUST be used whenever a data
type is represented as a numerical representation.
IDs and enumerations are grouped by the kind of data they represent,
as follows. ADM structure identifiers occupy enumerations 0 - 9 and
represent data structures that are formally identified by a MID.
Basic data types occupy enumerations 10-18 and represent primitive
data types. Special types occupy the remaining enumeration space.
While the ADM does not specify any encoding of data model elements, a
common set of enumerations help to ensure that various encoding
standards can interoperate.
Structure ID Enumeration Numeric
------------------------------- -------------- ----------- ----------
Externally Defined Data EDD 0 No
Variable VAR 1 No
Table Template TBLT 2 No
Report Template RPTT 3 No
Control CTRL 4 No
Time-Based Rule TRL 5 No
State-Based Rule SRL 6 No
Macro MACRO 7 No
Constant CONST 8 No
Operator OP 9 No
Birrane, et al. Expires May 3, 2018 [Page 32]
Internet-Draft ADM October 2017
Basic Data Type ID Enumeration Numeric
------------------------------- -------------- ----------- ----------
BYTE BYTE 10 No
Signed 32-bit Integer INT 11 Yes
Unsigned 32-bit Integer UINT 12 Yes
Signed 64-bit Integer VAST 13 Yes
Unsigned 64-bit Integer UVAST 14 Yes
Single-Precision Floating Point REAL32 15 Yes
Double-Precision Floating Point REAL64 16 Yes
Character String STR 17 No
Boolean BOOL 18 No
Compound/Special Data Type ID Enumeration Numeric
------------------------------- -------------- ----------- ----------
Hex String TS 19 No
Timestamp TS 20 No
Type-Name-Value Collection TNV 21 No
Asynchronous Resource Namespace ARN 22 No
Managed Identifier MID 23 No
MID Collection MC 24 No
Expression EXPR 25 No
Predicate EXPR 26 No
9.1. Numeric Promotions
When attempting to evaluate operators of different types, wherever
possible, an Agent MAY need to promote operands until they are of the
correct type. For example, if an Operator is given both an INT and a
REAL32, the INT SHOULD be promoted to a REAL32 before the Operator is
applied.
Listing legal promotion rules is mandatory for ensuring that behavior
is similar across multiple implementations of Agents and Managers.
Birrane, et al. Expires May 3, 2018 [Page 33]
Internet-Draft ADM October 2017
The listing of legal promotions in the ADM are listed in Figure 2.
In this Figure, operands are listed across the top row and down the
first column. The resultant type of the promotion is listed in the
table at their intersection.
INT UINT VAST UVAST REAL32 REAL64
+--------+--------+--------+--------+--------+--------+
INT | INT | INT | VAST | UNK | REAL32 | REAL64 |
UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 |
VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 |
UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 |
REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |
REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |
+--------+--------+--------+--------+--------+--------+
Figure 2: Numeric Promotions
ADMs do not permit promotions between non-numeric types, and numeric
promotions not listed in this section are not allowed. Any attempt
to perform an illegal promotion SHOULD result in an error.
9.2. Numeric Conversions
Variables, Expressions, and Predicates are typed values. When
attempting to assign a value of a different type, a numeric
conversion must be performed. Any numeric type may be converted to
any other numeric type in accordance with the C rules for arithmetic
type conversions.
10. YANG Modules
This section contains three sets of YANG modules which capture the
ADM and ADT concepts.
10.1. ADM Types and Structures
There are two YANG modules that capture all elements of the ADM:
basic structures and complex structures, as follows.
module basic-structures{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:basic-structures";
prefix basic;
Birrane, et al. Expires May 3, 2018 [Page 34]
Internet-Draft ADM October 2017
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
"This YANG module models the basic structures and collections that make up the complex structures in asynchronous systems.";
typedef type-enum{
type enumeration{
enum EDD{description "external defined data";}
enum VAR{description "variable";}
enum RPT{description "report";}
enum CTRL{description "control";}
enum SRL{description "state-based rule";}
enum TRL{description "time-based rule";}
enum MACRO{description "macro";}
enum CONST{description "constant";}
enum OP{description "operator";}
enum TBL{description "table";}//moved to capture in a nibble
enum LIT{description "literal";}
enum BYTE{description "unsigned byte value";}
enum INT{description "32bit signed integer";}
enum UINT{description "32bit unsigned integer";}
enum VAST{description "64bit signed integer";}
enum UVAST{description "64bit unsigned integer";}
enum REAL32{description "32bit floating point";}
enum REAL64{description "64bit floating point";}
enum BOOL{description "boolean";}
enum SDNV{description "self-delimiting numeric value";}
enum TS{description "timestamp";}
enum STR{description "string";}
enum BLOB{description "binary large object";}
enum MID{description "managed identifier";}
enum MC{description "MID collection";}
enum EXPR{description "expression";}
enum DC{description "data-collection";}
enum TC{description "type-collection";}
enum TDC{description "type-data-collection";}
}
description "This is the enumeration for the various basic data types.";
}
typedef hex-string{
Birrane, et al. Expires May 3, 2018 [Page 35]
Internet-Draft ADM October 2017
type string{
pattern
'[0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*';
}
description
"This defines a hexadecimal string with octets represented as hex digits
separated by colons. The canonical representation uses
lowercase characters.";
reference
"RFC 6991:Common YANG Data Types";
}
typedef mid-ref{
type string{
pattern
'^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL).\w+$';
}
description
"A mid reference uses the MID's type and it's unique name to quickly identify it.
They are used in MID collections to avoid restating already defined MIDs, helping to reduce space.";
}
typedef ts{
type uint64;
description
"A timestamp value can represent either a relative or absolute time.
A relative time is defined as the number of seconds between two events.
An absolute time is defined as UTC time using the UNIX/POSIX Epoch.";
}
typedef type-name-value-collection{
type string{
pattern
'^((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*)(&((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*))*$';
}
description
"A TNV collection describes a list of ADM items where each item is described as a three tuple of {type, name, value}
or certain permitted subsets of that three-tuple.
GENERAL FORMAT- <type>:<name>=<value>";
}
grouping mid{
description
"A managed identifier(MID) is used to provide unique naming for structures.
There is a general MID format for everything except for Literals.
Literal MIDs are interpreted in a different way to express numeric values without the need to store numbers as full MIDs.
Birrane, et al. Expires May 3, 2018 [Page 36]
Internet-Draft ADM October 2017
Regular expressions are used to show a general human readable organization of a MID.";
leaf name{
type string;
description
"The human readable name identifying the MID. Should act as the key in the structure containing the MIDs.";
}
choice mid{
case reg-mid{
leaf id{
type string{
pattern
'^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL)_(\w+)(\.\w+)?(:\w+(:\w+)?)?$';
}
mandatory true;
description
"This pattern organizes the needed information for a MID.
<TYPE>_<ID>.<opt nicknamed>:<opt issuer>:<opt tag>
The type and ID field is mandatory. Everything else is optional and can be left as an empty section.
The type gives the type of the identifed object. The ID is the unique ID of the object.
The optional but encouraged nickname helps to reduce the total space of the MID.
The optional issuer represents a predetermined issuer name.
The optional tag is used to disambiguate multiple MIDs with the same OID/Issuer combination. MIDs can't have a tag without an issuer.
ex.) VAR_01.14 => MID for a for a non-parameterized compressed variable with nickname 14 and id 01";
}
choice params{
case proto{
leaf paramspec-proto{
type type-name-value-collection;
description
"In a proto-mid, parameters represents a prototype with parameters being a type collection.";
}
}
case full{
leaf paramspec{
type type-name-value-collection;
description
"This parameter specification can represent a function call with the parameters being a typed data collection.";
}
}
description
"Depending on if the MID's parameters have values or not, a type-collection or a type-data-collection could be used.";
}
Birrane, et al. Expires May 3, 2018 [Page 37]
Internet-Draft ADM October 2017
}
case LIT-mid{
leaf num-id{
type string{
pattern
'^LIT_(INT|UINT|VAST|UVAST|REAL32|REAL64)\.(\d+(\.\d+))?$';
}
mandatory true;
description
"Literals are specialized MIDs.
Since Literals are not stored and evaluated when needed, there is no 'name field' associated with them.
Literals only contain type value information.
ex.) LIT_INT.9 is how the integer value 9 would be expressed";
}
}
mandatory true;
description
"You can use either a standard MID or a specialized literal MID to represent numbers.";
}
}
grouping mid-collection{
description
"A mid collection(MC) is a collection of MIDs. The ideal way to show a MC is to list the MIDs using a mid-ref or nickname id pair,
and use the full-MIDs only when that MID is being defined for the first time.";
choice mc-type{
case string{
leaf string-mc{
type string;
description
"The MID collection is represented using a string to list all the mids.
If it contains MIDs that have already been defined, then it should use the mid-ref format previously stated.
MIDs are separated by spaces.";
}
}
case array{
leaf-list array-mc{
type string;
description
"The MID collection is represented using an array to list all the MIDs.
If it contains MIDs that have already been defined then it should use the mid-ref format previously stated.";
}
}
mandatory true;
description
Birrane, et al. Expires May 3, 2018 [Page 38]
Internet-Draft ADM October 2017
"A MID collection can be modeled as a string, where MIDs are separated by spaces, or by an array of MIDs.";
}
}
grouping expr{
description
"Expressions apply operations to values to generate new values.";
leaf type{
type type-enum;
mandatory true;
description
"This is the enumeration representing the type of the result of the evaluated expression";
}
uses mid-collection{
description
'An expression is represented as a MID collection,
where each MID in the ordered collection represents the data, constants
and/or operations that comprise the expression. The expression must use the following pattern:
EDD/VAR/CONST/NUM.name OP.name EDD/VAR/CONST/NUM.name.....
(((EDD)|(VAR)|(CONST)|(NUM)).(\w+)_?)+op.\S)+
Uses post fix format.';
}
}
}
module complex-structures{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:complex-structures";
prefix complex;
import basic-structures{
prefix basic;
}
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
"This module models complex structures for asynchronous systems.";
Birrane, et al. Expires May 3, 2018 [Page 39]
Internet-Draft ADM October 2017
grouping externally-defined-data {
description
"Externally defined data (EDD) represents values that are calculated outside of the context of Agents and Managers
such as values that are measured by firmware.";
uses basic:mid;
leaf type {
type basic:type-enum;
mandatory true;
description
"This is the type of the stored data.";
}
leaf description{
type string;
description
"This gives a human readable description of the EDD.";
}
}
grouping variable{
description
"Variables are values that are completely described by other known data in the system such as other variables or other EDDs.";
uses basic:mid{
description
"This is the MID for the variable.";
}
leaf type{
type basic:type-enum;
mandatory true;
description
"This is the type of the variable. It acts as a static cast for the result of the initializing expression.";
}
container initializer{
uses basic:expr;
presence
"This is the initializer represented by an expression";
description
"An expression is used as the initializer for the variable.";
}
leaf description{
type string;
description
Birrane, et al. Expires May 3, 2018 [Page 40]
Internet-Draft ADM October 2017
"This is the human readable description of the variable.";
}
}
grouping table-template {
description
"This is the template for prototyping tables.";
uses basic:mid{
description
"This is the MID for the table-template.";
}
leaf columns{
type basic:type-name-value-collection;
mandatory true;
description
"A TNV collection is used to store the type and names of the columns in the table-template.";
}
leaf description{
type string;
description
"This is the human readable description of the table.";
}
}
grouping table {
description
"A table is a names, typed, collection of tabular data with each row represented as a data collection
and each column defined by both a column name and a column type.";
uses basic:mid{
description
"This is the MID for the table.";
}
leaf columns{
type basic:type-name-value-collection;
mandatory true;
description
"A TNV collection is used to store the type and names of the columns in the table.";
}
leaf num-rows{
type uint64;
mandatory true;
description
Birrane, et al. Expires May 3, 2018 [Page 41]
Internet-Draft ADM October 2017
"This is the number of rows in the TBL.";
}
list rows{
key "num";
leaf num{
type uint64;
description "This is the number of data values in the row.";
}
leaf data{
type basic:type-name-value-collection;
description
"A TNV collection is used since col-types gives the types.";
}
description
"These are the rows of the table.";
}
leaf description{
type string;
description "This is the human readable description of the table.";
}
}
grouping report{
description
"A report is a typed data collection that is identified by a mid and generated to capture the return value of a control.";
uses basic:mid{
description
"This contains the MID for the report entry.";
}
leaf values{
type basic:type-name-value-collection;
description
"This TNV collection contains the values for the report entry.";
}
leaf description{
type string;
description
"This is the human readable description of the report-entry.";
}
}
Birrane, et al. Expires May 3, 2018 [Page 42]
Internet-Draft ADM October 2017
grouping report-template{
description
"A report template is the ordered set of data descriptions which describe
how values will be represented in a corresponding report entry.";
uses basic:mid{
description
"This contains the MID for the report entry.";
}
uses basic:mid-collection;
leaf description{
type string;
description
"This is the human readable description of the report-template.";
}
}
grouping control{
description
"A control represents a pre-defined opcode that can be run on an agent.";
uses basic:mid{
description
"This is the MID identifying the control. It must NOT have an issuer field nor a tag field.";
}
leaf description{
type string;
description
"This is the human readable description of the control.";
}
}
grouping time-based-rule{
description
"A time based rule specifies that a particular action should be taken by an agent
based on some time interval.";
uses basic:mid{
description
"This is the MID identifying the time-based rule.";
}
leaf start{
type basic:ts;
mandatory true;
description
Birrane, et al. Expires May 3, 2018 [Page 43]
Internet-Draft ADM October 2017
"This is the time at which the TRL should start.";
}
leaf period{
type uint64;
default 1;
description
"This is the length of time to wait in between running the action associated with the TRL.";
}
leaf count{
type uint64;
mandatory true;
description
"This is the number of times that action is performed. 0 = inf";
}
container action{
uses basic:mid-collection;
presence
"The action is a mid-collection;";
description
"This is the collection of controls and/or macros to be run by the TRL.";
}
leaf description{
type string;
description
"This is the human readable description of the time-based-rule.";
}
}
grouping state-based-rule{
description
"A state based rule(SRL) specifies that a particular action should be taken by an agent
based on some evaluation of the internal state of the agent.";
uses basic:mid{
description
"This is the MID identifying the SRL.";
}
leaf start{
type basic:ts;
mandatory true;
description
"This is the time at which the SRL should start to be evaluated.";
}
Birrane, et al. Expires May 3, 2018 [Page 44]
Internet-Draft ADM October 2017
container condition{
uses basic:expr;
presence
"The condition is represented by an expression.";
description
"This contains the boolean expression, which, if true, results in the SRL running the associated action.";
}
leaf count{
type uint64;
mandatory true;
description
"This is the number of times the action is run. 0 = inf";
}
container action{
uses basic:mid-collection;
presence
"The action is a mid-collection.";
description
"This is the collection of controls and/or macros to be run as part of the action.";
}
leaf description{
type string;
description
"This is the human readable description of the state-based-rule.";
}
}
grouping macro{
description
"This is the ordered collections of MIDs that contain controls or other macros. When run by an agent, each MID in the mid-collection
is run in order.";
uses basic:mid{
description
"This is the MID identifying the Macro.";
}
container definition{
uses basic:mid-collection;
presence
"The definition is represented by a mid collection.";
description
"This is the ordered collections of MIDs which identify the controls and
other macros that should be run as part of the running macro.";
}
Birrane, et al. Expires May 3, 2018 [Page 45]
Internet-Draft ADM October 2017
leaf description{
type string;
description
"This is the human readable description of the macro.";
}
}
grouping constant{
description
"Constants represent named values defined in an ADM.";
uses basic:mid{
description
"This is the MID that corresponds to the constant.";
}
leaf typed-value{
type basic:type-name-value-collection{
pattern
}
mandatory true;
description
"This is the type and value of the constant.";
}
leaf description{
type string;
description
"This is the human readable description of the constant.";
}
}
grouping operator{
description
"Operators are always defined in the context of an ADM. They represent functions
implemented by the firmware of the agent.";
uses basic:mid{
description
"Since Operators are always defined soley in the context of an ADM,
the issuer and tag field should not be used.";
}
leaf out-type{
type basic:type-enum;
description
"This is the type of the return value of the operator.";
}
Birrane, et al. Expires May 3, 2018 [Page 46]
Internet-Draft ADM October 2017
leaf in-type{
type basic:type-name-value-collection{
pattern
}
description
"This is the type(s) of the inputs of the operator.";
}
leaf num-operands{
type uint32;
mandatory true;
description
"This is the number of operands needed to utilize the operator.";
}
leaf description{
type string;
description
"This is the human readable description of the operator.";
}
}
}
10.2. Application Data Template
The ADT lists the set of predefined information necessary to capture
the non-dynamic parts of an application data model, as follows.
module adm{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:adm";
prefix adm;
import complex-structures{
prefix complex;
}
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
Birrane, et al. Expires May 3, 2018 [Page 47]
Internet-Draft ADM October 2017
"This YANG module is used for modeling Application Data Models (ADMs). All keys in the list of the information uses the associated with the data's MIDs.";
list metadata{
key "name";
uses complex:constant;
description
"This is the metadata for the ADM. Should contain Name, Version, Namespace, and Issuing organization of the adm";
}
list externally-defined-data{
key "name";
uses complex:externally-defined-data{
description
"These are the EDD definitions that are defined by the ADM and its firmware";
}
description
"This is the listing of all the EDDs that are defined in the ADM.";
}
list tables{
key "name";
uses complex:table-template;
description
"This is the list of all the table/table-templates in the ADM.";
}
list variables{
key "name";
uses complex:variable{
description "These are the variables created and defined by the ADM.";
}
description
"Variable definitions are expressions used to calculate data values, on the fly,
from a set of other variable definitions, EDDs, constants, or numerics using any
of the operators defined.";
}
list report-templates{
key "name";
uses complex:report-template;
description
Birrane, et al. Expires May 3, 2018 [Page 48]
Internet-Draft ADM October 2017
"This is the collection of report templates, which is the ordered set of data descriptions that
describe how values will be represented in a corresponding Report Entry.";
}
list controls{
key "name";
uses complex:control;
description
"This is the collection of controls which represent well-known command opcodes
that can be run by the Agent in response to direct request by an AMP manager or
in response to time- or state-based rules on the agent itself.";
}
list constants{
key "name";
uses complex:constant;
description
"These are the constants made available in the ADM.";
}
list macros{
key "name";
uses complex:macro;
description
"Macro definitions are ordered collections of controls that can be sequentially run.";
}
list operators{
key "name";
uses complex:operator;
description
"This is the set of operators that are made available in the ADM";
}
}
11. IANA Considerations
TBD.
Birrane, et al. Expires May 3, 2018 [Page 49]
Internet-Draft ADM October 2017
12. Security Considerations
TBD
13. Informative References
[I-D.birrane-dtn-ama]
Birrane, E., "Asynchronous Management Architecture",
draft-birrane-dtn-ama-05 (work in progress), March 2017.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
Authors' Addresses
Edward J. Birrane
Johns Hopkins Applied Physics Laboratory
Email: Edward.Birrane@jhuapl.edu
Evana DiPietro
Johns Hopkins Applied Physics Laboratory
Email: Evana.DiPietro@jhuapl.edu
David Linko
Johns Hopkins Applied Physics Laboratory
Email: David.Linko@jhuapl.edu
Birrane, et al. Expires May 3, 2018 [Page 50]