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 := 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 | := | | | | | | | Named | : | REAL32:PI&INT:PI_INT | | Type | | | | | | | | Anonymou | | REAL32&INT | | s Type | | | | | | | | Anonymou | := | REAL32:=3.14159&INT:=3 | | s Type | | | | Value | | | | | | | | Anonymou | = | =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:: 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 _::. 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 _.. 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 .. 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- :="; } 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. _.:: 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, . 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]