| Internet-Draft | DTNMA AMM/ADM | January 2024 |
| Birrane, et al. | Expires 6 July 2024 | [Page] |
This document defines a data model that captures the information necessary to asynchronously manage applications within the Delay-Tolerant Networking Management Architecture (DTNMA). This model provides a set of common type definitions, data structures, and a template for publishing standardized representations of model elements.¶
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 6 July 2024.¶
Copyright (c) 2024 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Delay-Tolerant Networking Management Architecture (DTNMA) [I-D.ietf-dtn-dtnma] defines a concept for the open-loop control of applications (and protocols) in situations where timely, highly-available connections cannot exist among managing and managed nodes in a network. While the DTNMA provides a conceptual information model, it does not include details necessary to produce interoperable data models.¶
This document defines a two-level data model suitable for managing applications in accordance with the DTNMA. The two levels of model are:¶
This document also defines a text representation of an ADM using the types and structures defined by the AMM combined with the syntax and processing semantics of YANG modules [RFC7950], while using AMM-specific extensions for object and data modeling. With this representation, individual applications can capture their static management information in module files.¶
Although this document defines a representation for the ADM, it does not define a representation for the objects and literal values modeled by the ADM/ODM. In order to communicate values between DTNMA 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, the encoding of the model is a separate concern from the specification of data within the model.¶
Because 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 values in their native encodings such that the translation of ADM data from one encoding to another can be completed using mechanical action taken at network borders.¶
Since the specification does not mandate an encoding format, the AMM and ADM 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 contain enough information to prevent ambiguities caused by different encoding schemes.¶
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].¶
The terms "Actor", "Agent", "Externally Defined Data", "Variable", "Constant", Control", "Literal", "Macro", "Manager", "Operator", "Report", "Report Template", "Rule", "State-Based Rule", "Table", "Table Template", and "Time-Based Rule" are used without modification from the definitions provided in [I-D.ietf-dtn-dtnma].¶
Additional terms defined in this document are as follows.¶
In order to asynchronously manage an application in accordance with the [I-D.ietf-dtn-dtnma], an application-specific data model must be created containing static structure for that application. This model is termed the Application Data Model (ADM) and forms the core set of information for that application in whichever network it is deployed. ADM structure and base ADMs are discussed in detail in Section 4.¶
The objects codified in the ADM represents static configurations and definitions that apply to any deployment of the application, regardless of the network in which it is operating. Within any given network, Managers supplement the information provided by ADMs with dynamic objects. Each namespace of dynamic objects is termed an Operational Data Model (ODM) and is discussed in detail in Section 5.¶
Both the ADMs and ODMs rely on a common meta-model, the Application Management Model of Section 3, which defines the basic structure of what kinds of types and objects are available to use within the DTNMA. The relationships among the AMM, ADM, and ODM are illustrated in Figure 1. Together, the set of objects in the union of all supported ADMs with dynamic ODM objects forms the data model used to manage an Agent.¶
+---------------+
| AMM |
| (object types)|
+-------^-------+
|
+-------+-------+
| |
+-----+-----+ +-----+-----+
| ADM | | ODM |
|(instances)| |(instances)|
+-----------+ +-----------+
The AMM defines a strict separation between long-lived object instances and ephemeral value instances. While an Agent hosts the object instances, each manager must contain the corresponding ADM and ODM definitions in order to identify and interact with those objects. Those interactions are performed using Application Resource Identifiers (ARIs) as depicted in Figure 2.¶
+-------------+ +-------------+
| AMM Value | | AMM Object |
| (in ARI) | | (in model) |
+------^------+ +-------------+
| ^
| subtypes |
+-------+-------+ |
| | | referenced
+-----+-----+ +-----+-----+ | object
| Literal | | Object |-----------+
| | | Reference |
+-----------+ +-----------+
While an agent hosts the actual object instances, each manager must contain the corresponding ADM and ODM definitions in order to identify and interact with those objects. Those interactions are performed using Application Resource Identifiers (ARIs) as depicted in Figure 3.¶
+------------------------------------------+
| |
| +-------+ +-------+ +-------+ |
| | ADM 1 | | ADM 2 | | ODM 1 | |
| | def'n | | def'n | | def'n | |'
| +-------+ +-------+ +-------+ |
| ... ... |
| +-------+ +-------+ |
| | ADM N | | ODM M | |
| | def'n | | def'n | |
| +-------+ +-------+ |
| Manager instance |
+------------------------------------------+
^^
||
ARI values
||
vv
+------------------------------------------+
| |
| +-------+ +-------+ +-------+ |
| | ADM 1 | | ADM 2 | | ODM 1 | |
| | objs | | objs | | objs | |
| +-------+ +-------+ +-------+ |
| ... ... |
| +-------+ +-------+ |
| | ADM N | | ODM M | |
| | objs | | objs | |
| +-------+ +-------+ |
| Agent instance |
+------------------------------------------+
The ARI of [I-D.birrane-dtn-ari] is used as the basis for the values used internally for Agent Processing activities and for the basis of Agent-Manager Messaging contents.¶
Of the value-producing object types discussed in Section 3.4 and Section 6.5, the functions of these objects are summarized and compared with literals in Table 1 and the following list. In that table, "internal" means values are managed by the Agent itself and "external" means the source of values is outside the Agent.¶
ARI literals are, by definition, immutable and fully self-contained values.¶
For example, the number 4 is a literal value. The name "4" and the value 4 represent the same thing and are inseparable. Literal values cannot change ("4" could not be used to mean 5) and they are defined external to the autonomy model (the autonomy model is not expected to redefine what 4 means).¶
These objects are named values which are defined in specific revisions of an ADM and produced directly by the Agent implementing the ADM. Both the name and the value of the constant are fixed and cannot be changed (within a revision).¶
An example of a constant would be defining the numerical value pi to some predetermined precision.¶
These objects are named value storage entities which are defined in ADMs or ODMs and managed by the Agent implementing the ADM or ODM. While the name is constant the value can change over time due to controls acting upon the Agent. One standard interface is an ADM-defined initial state expression with a control available to reset to that initial state (which can itself reference other value producing objects and operators). Another standard interface is a control to set a variable to a specific value.¶
An example of a variable using just its initial expression would be an accumulator summing together a list of counter values produced by other objects. An example of a manager-controlled variable would be a threshold value used to compare against a sensor value in a rule predicate.¶
These objects are named entities which are defined in an ADM but produce values based on data provided to an Agent from its environment. These values are the foundation of state-based autonomy as they capture the state of the managed device. The autonomy model treats these values as read-only state. It is an implementation matter to determine how external data is transformed into values of the specific type specified for an EDD.¶
Examples of externally defined values include temperature sensor readings and the instantaneous data rate from a modem or radio.¶
| Immutable | Mutable | |
|---|---|---|
| Internal | CONST | VAR |
| External | Literal | EDD |
Based on the reasoning described in [I-D.ietf-dtn-dtnma], much of the closed-loop processing of the state of the DTNMA Agent is performed on the Agent itself using rule objects. The different types of processing performed on the Agent are separated into Execution, Evaluation, and Reporting with corresponding AMM object types related to each of these as indicated in Table 2 (e.g., execution relates to CTRL objects but not OPER objects). Some of the objects defined in the Agent ADM (Section 4.3) combine the use of these processing activities, but they are still independent of each other. There is no mixing of activities such as executing a control within an expression; although the execution of a control can result in an expression being evaluated they are independent activities.¶
Within the runtime of an Agent any input, output, and intermediate values can use the concept of a semantic type (Section 3.3) to do things like restrict the valid numeric range of a value or allow a union of disjoint types to be present (e.g., a certain value can be a boolean or an unsigned integer). This is combined with the literal types available from the ARI to allow complex type information to be present in an ADM or ODM without requiring additional over-the-wire encoding size. A Type Conversion activity is defined for when implicit or explicit type conversion is needed.¶
| Activity | Objects | Values |
|---|---|---|
| Execution | CTRL | MAC |
| Evaluation | OPER, TYPEDEF | EXPR |
| Reporting | N/A | RPTT |
| Value Production | CONST, EDD, VAR | N/A |
| Type Casting | TYPEDEF | N/A |
| Rule Autonomy | SBR, TBR | N/A |
This document does not define a messaging protocol between agents and managers but full functioning of this data model behavior does rely on the following types of messages being available. Because each message is based on ARI value types, they can be implemented in Agent and Manager by encoding the associated ARI according to a network-specific transport profile. The choice of encoding form, framing, or transport are implementation matters outside of this specific document.¶
The contents of these messages, individual fields, are representable by ARI values so require only small additional message-type identifying and framing overhead to bind to whatever transport is being used (e.g. the Bundle Protocol).¶
This section describes the Application Management Model, which is the meta-model used to implement the DTNMA. This section also provides additional information necessary to work with this model, such as: literal value types, object structure, naming conventions, and processing semantics.¶
The overall AMM is decomposed into two categories:¶
Values within the AMM have two top-level classes: literal values, and object reference values. Each of these is discussed more detail in the following subsections. Both classes of AMM values are related to what can be represented externally as an ARI, as described in Section 3.1.3.¶
As defined in the DTNMA, Literal values are those whose value and identifier are equivalent. These are the most simple values in the AMM. For example, the literal "4" serves as both an identifier and a value.¶
Because the value of a Literal object serves as its identifier, there is no concept of a parent namespace or parameters. A literal can be completely identified by its data type and data value.¶
Literals have two layers of typing:¶
BOOL has two possible values, while an INT has a large domain of integers).
There are a small number of literal types and they are managed with an IANA registry defined in Section 9.3 of [I-D.birrane-dtn-ari].¶
All literal values have a concrete and stand-alone representation independent of any ADM or ODM behavior in the form of an ARI (Section 3.1.3), but when represented as an ARI a value loses its semantic type.¶
Every object in the AMM is uniquely identifiable, regardless of whether the item is defined statically in an ADM or dynamically in an ODM. Object reference values are composed of four parts: a namespace, an object type, an object name, and object-specific optional parameters.¶
AMM objects are identified within unique namespaces to prevent conflicting names within network deployments, particularly in cases where network operators are allowed to define their own object names. In this capacity, namespaces exists to eliminate the chance of a conflicting object name. They MUST NOT be used as a security mechanism. An Agent or Manager MUST NOT infer security information or access control based solely on namespace information.¶
Two categories of namespaces available within the object reference value and the ARI syntax:¶
Object types, each with a text-name and enumeration, are defined in an IANA registry by Section 9.3 of [I-D.birrane-dtn-ari].¶
Object names are text strings and enumerations whose value is determined by the creator of the object. For those objects defined in an ADM, the structure of the object name is given in Section 3.4.1.¶
Parameterization is used in the AMM to enable expressive autonomous function and reduce the amount of traffic communicated between Managers and Agents. In the AMM, most objects can be parameterized and the meaning of parameterization for each object type is defined in Section 3.4 with behaviors related to parameters defined in Section 6.¶
There are three notions of parameters defined in the AMM, which take their name from computer programming vernacular used for discussing function declarations and function calls, those are: formal parameters, given parameters, and actual parameters. Formal parameters are discussed in Section 3.4.1 while given and actual parameters are discussed here in relation to the object reference.¶
Given parameters represent the data values passed to a parameterized AMM Object at runtime. They "fulfill" the parameter requirements defined by the formal parameters for that object. Each object type can have a slightly different notion of how its parameters affect its processing activities.¶
A given parameter MUST include a value and MAY include a type. If a type is provided it MUST be consistent with the type provided by the corresponding formal parameter.¶
There are two ways in which the value of an given parameter can be used:¶
LABEL of some other processing-context-specific value and substituting, at runtime, that named value as the value of this parameter.
This method is useful when a parameterized AMM Object produces a value that references a parameter of the producing object.
The produced value's given parameter can be given as the LABEL of the producing object's formal parameter.
In this way, a value-producing object's parameters can "flow down" to all of the values that it produces.¶
In cases where a formal parameter contains a default value, the associated given parameter may be omitted. Default values in formal parameters (and, thus, optional given parameters) are encouraged as they reduce the size of data items communicated between Managers and Agents in a network.¶
Finally, actual parameters are the result of applying the Parameter Handling procedure to normalize a set of given parameters based on a set of formal parameters from a processing context.¶
The Application Resource Identifier (ARI) is used to represent AMM values outside of an Agent or Manager (i.e. in messaging between them) and is defined in [I-D.birrane-dtn-ari]. Another function of the ARI is for diagnostic or configuration purposes within either Managers or Agents. It is important to make the distinction that within an AMM entity (Agent or Manager) the semantic type of a value is kept, but when exchanged via ARI the semantic type is lost. The AMM defines type compression and reconstruction rules in Section 6.12 to handle this.¶
This section describes the literal type definitions used by the AMM. By definition, literal values are self-contained and literal types restrict the form and function of those values.¶
All literal types within the AMM exit within a flat namespace, but some types have complex relationships with other types beyond the "is a" concept of type inheritance. Types are defined within an IANA registry by Section 9.3 of [I-D.birrane-dtn-ari] and explained in this section. The following subsections divide the types into groups to simplify their explanation, not because of an intrinsic relationship within each group.¶
Simple types are those which cannot be subdivided and represent an "atomic" value within the AMM type system. They correspond roughly with the CBOR primitive types Section 3.3 of [RFC8610]. The simple types are summarized in Table 3.¶
| Type | Description |
|---|---|
NULL
|
The singleton null value. |
BOOL
|
A native boolean true or false value. |
BYTE
|
An 8-bit unsigned integer. |
INT
|
A 32-bit signed integer. |
UINT
|
A 32-bit unsigned integer. |
VAST
|
A 64-bit signed integer. |
UVAST
|
A 64-bit unsigned integer. |
REAL32
|
A 32-bit [IEEE.754-2019] floating point number. |
REAL64
|
A 64-bit [IEEE.754-2019] floating point number. |
TEXTSTR
|
A text string composed of (unicode) characters. |
BYTESTR
|
A byte string composed of 8-bit values. |
TP
|
An absolute time point (TP). |
TD
|
A relative time difference (TD) with a sign. |
LABEL
|
A text label of a parent object parameter. This is only valid in a nested parameterized ARI. |
CBOR
|
A byte string containing an encoded CBOR item. The structure is opaque to the Agent but guaranteed well-formed for the ADM using it. |
LITTYPE
|
An integer value representing one of the code points in this Literal Types table. |
The following subsections discuss nuances in sub-groups of these simple types.¶
The NULL and BOOL types are used to limit to specific discrete values.
Because there are CBOR primitive types corresponding exactly with these AMM types, generators of ARIs with these types can always be compressed by eliding the literal type as defined in Section 6.12.¶
The NULL type has only a single value, null, which is not useful for expressions or type casting but is useful for defining union types which have "optional value" semantics where the null value is used to indicate the absence of a normal value.¶
The BOOL type is useful for type casting (Section 6.11.1) where an arbitrary value is treated as "truthy" or "falsey" in a context such as a State-Based Rule (SBR) condition.¶
All of the numeric types (BYTE, UINT, INT, UVAST, VAST, REAL32, and REAL64) exist within a domain where values can be converted between types (Section 6.11.2).
Some cases of implicit casting is done for type promotion as necessary for arithmetic operations.¶
The TP type represents an instant in time in the UTC datum.
When in text form it is formatted in accordance with the date-time symbol of Appendix A of [RFC3339] and always in the "Z" time-offset.¶
The TD type represents an offset in time from a relative epoch instant, either later than (a positive offset) or earlier than (a negative offset).
When in text form it is formatted in accordance with the duration symbol of Appendix A of [RFC3339] with a positive or negative sign prefix.
The epoch instant of a relative time MUST be unambiguously defined in the context using the time value.¶
AMM objects, or parameters associated with those objects, often need to represent groups of related data or more complex nesting of data. These are the literal types for AMM value containers, which can only be present in a typed-literal ARI form.¶
The AMM defines three collection literal types (AC, AM, and TBL) and allows ADMs to combine these literal types with a complex pattern syntax to create semantic types constraining their contents (e.g., for macros and expressions in Section 4.2.3).¶
An ARI Collection (AC) is an ordered list of ARI elements. The contents of an AC can be restricted in size and type by the use of a semantic type (Section 3.3).¶
An AC is used when there is a need to refer to multiple AMM values as a single unit. For example, when defining a Report Template, the definition has an AC that defines the ordered ARIs whose values constitute that report.¶
An ARI Map (AM) is a mapping from a set of "key" ARIs to arbitrary-typed "value" ARIs. As defined in [I-D.birrane-dtn-ari] the AM keys are limited to untyped literals, while the AM values can be any type. The contents of an AM can be restricted in size and type by the use of a semantic type (Section 3.3).¶
An AM is used when there is a need to define data structures with complex, optionally present attributes. For example, as control parameters used to define new objects in an ODM.¶
An ARI Table (TBL) is a collection of values which are logically structured as a two dimensional table of rows and columns, with each cell of the table containing an AMM value.¶
Although the contents of a TBL can be handled independently of any data model, the meaning of a TBL can only be interpreted within the context of a Table Template (TBLT) defined within an ADM. The TBLT takes the form of a structured type definition on a value-producing object which defines the columns of the table, including each of their column names and types and optional constraints on the number of and uniqueness of rows in the TBL.¶
A TBL is used when an EDD represents a set or list of complex items as rows in a table. For example, the Agent ADM reports its own set of supported ADMs and features as a TBL (see the "capability" object).¶
An Execution-Set (EXECSET) is a collection of values used as targets for the Execution activity. Each message can reference multiple execution sources (CTRL and MAC) and, unlike the MAC execution itself, can be handled by executing multiple items in parallel.¶
The contents of an EXECSET value are as follows:¶
NONCE (Section 4.2.2) type.¶
exec-tgt (Section 4.2.6) type.¶
A Reporting-Set (RPTSET) is a collection of report containers, where each report container consists of a timestamp and an ordered list of data values populated in conformance to a source object being reported on. Reporting-Set values and reports themselves do not have individual identifiers, rather they are identified by their source and the timestamp at which their data values were collected.¶
The contents of an RPTSET value are as follows:¶
NONCE type (Section 4.2.2).¶
TP built-in type.
It is used as an storage optimization when a large number of reports are generated around the same time.¶
The contents of each report within a RPTSET are as follows:¶
VALUE-OBJ (Section 4.2.2), or CTRL. If the source was parameterized, this ARI SHALL contain the actual parameters used at the time of reporting.¶
TD built-in type.¶
null value if the report is not associated with an execution activity.
The value is limited to match the NONCE type (Section 4.2.2).¶
A list of values corresponding to the source object, with cardinality according to the following:¶
VALUE-OBJ source the item list SHALL be the result of reporting (Section 6.8.2) on that object.¶
CTRL-REF source there SHALL be a single value representing the Result of the execution. A result of undefined indicates a failure executing the CTRL.¶
When an application requires a more complex or specialized literal type than one already available the preferred design procedure is as follows:¶
CBOR type with interface documentation to explain the syntax of the encoded CBOR item.¶
Implementing a custom literal type requires implementation effort on both an Agent and its associated Manager(s) as well as being more opaque to diagnostic tools and middleboxes.¶
While literal types control the basic syntax and domain of AMM values, the concept of semantic type is to provide a means to augment literal types by expanding (via union), narrowing (via constraints), and adding human-friendly attributes (such as references to defining documents, or explanations of purpose).¶
Semantic types can be defined in two ways: a named Semantic Type Definition (TYPEDEF) or an anonymous type defined at the point of use (e.g., within an AMM object definition). The specific syntax used to define semantic types within an ADM are defined and explained in Section 7.2.2.¶
When a "type" is needed for an AMM value in an object definition it SHALL be either one of the built-in types, a namespace-qualified semantic type, or an anonymous semantic type just for that value.¶
This section identifies the types of objects that make up the AMM and which are instantiated within each ADM and ODM. Each object type is defined by its logical structure and its behavior in Value Production, Execution, or Evaluation contexts within Agents. Each type can allow or disallow parameters within objects and, due to processing behaviors, can either allow or disallow use within an ADM or ODM.¶
The names for the types of objects defined in this section can be used in two different and separate contexts: as a name for the type of the object itself (written as plain text within this document) when in the context of the AMM object model, or as the name of an object reference (Section 3.1.2) type (written in typewriter text within this document) when used in the context of the AMM value model.¶
Unless explicitly specified in the object type subsection, an object SHALL NOT be parameterized.¶
Every object type in the AMM includes a set of fields providing annotative or otherwise user-friendly descriptive information for the object. This information may be used as documentation (for example, only present in ADMs and on operator consoles) and/or encoded and transmitted over the wire as part of a management protocol.¶
The metadata supported by the AMM for all objects is as follows:¶
id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari].
Within each namespace and object type, the name of an object SHALL be unique.¶
Formal parameters define a method to customize an AMM object. When used by an object definition, it's formal Parameters SHALL be an ordered list of individual formal parameter definitions. Each formal parameter SHALL include type and name. Each formal parameter MAY include an optional default value. The application of default parameters and relationship of actual parameters (Section 3.1.2.1) to formal parameters is defined in Section 6.4.¶
An ADM can define a semantic type definition (TYPEDEF) to give a name to a semantic type (Section 3.3). This TYPEDEF name can then be used as a type anywhere else in the same ADM or another one which imports it.¶
The definition of a TYPEDEF consists of the following:¶
As defined in this document, TYPEDEFs and semantic types can only be defined within an ADM. Future capability could allow the use of TYPEDEFs within ODMs.¶
Externally defined data (EDD) objects, as defined in the DTNMA, represent data values that are produced based on a source external to the Agent itself. The Value Production occurs at the moment the value is needed, by either an Evaluation or a Reporting. The actual value could come from outside of the Agent proper, or be derived from data outside of the Agent.¶
The value production of an EDD SHOULD be nilpotent and have no side-effects in the processor. This property is not enforced by the Agent but requires consideration of the ADM designers, see Section 8.¶
For values managed entirely within the Agent use a Variable (VAR) or for constant-values use a Constant (CONST). For complex tabular data, use an EDD with a type which produces an ARI Table (TBL).¶
The definition of an EDD consists of the following:¶
As defined in this document, EDDs can only be defined within an ADM. Future capability could allow the use of EDDs within ODMs.¶
A Constant (CONST) represents a named literal value, but unlike an Externally Defined Data (EDD) or Variable (VAR) a CONST always produces the same value. Examples include common mathematical values such as PI or well-known time epochs such as the UNIX Epoch. A CONST typed to produce a simple value can be used within an expression (see Section 6.7), where the object is used to produce a value at the moment of evaluation. A CONST can also be typed to produce an EXPR value to evaluate, or MAC value to execute.¶
The definition of a CONST consists of the following:¶
As defined in this document, CONSTs can only be defined within an ADM. Allowing network operators to define constants dynamically means that a Constant could be defined, removed, and then re-defined at a later time with a different value, which defeats the purpose of having Constants. When adding new "fixed" values to an ODM, a Variable (VAR) MUST be used instead of a Constant.¶
A Control (CTRL) represents a predefined function that can be executed on an Agent. Controls are not able to be defined as part of dynamic network configuration since their execution is typically part of the firmware or other implementation outside of the Agent proper.¶
The execution of a CTRL SHOULD be idempotent and have no effect if executed multiple times in sequence. This property is not enforced by the Agent but requires consideration of the ADM designers, see Section 8.¶
Controls can be executed in a "one shot" manner as part of messaging from a Manager to an Agent. Network operators that wish to autonomously execute functions on an Agent may use a State-Based Rule (SBR) or Time-Based Rule (TBR). When an execution involves the ordered sequence of controls, a Macro (MAC) SHOULD be used instead of a more fragile use of CTRL directly.¶
The definition of a CTRL consists of the following:¶
A CTRL definition MAY include ARI parameters to be used when the CTRL is executed. Parameterized objects are discussed in Section 8.¶
As defined in this document, CTRLs can only be defined within an ADM. Future capability could allow the use of CTRLs within ODMs if there was some mechanism to bind a CTRL definition to some platform-specific execution specification (e.g., a command line sequence).¶
An Operator (OPER) represents a user-defined, typically mathematical, function that operates within the evaluation of an Expression (EXPR). It is expected that operators are implemented in the firmware of an Agent.¶
The AMM separates the concepts of Operators and Controls to prevent side-effects in Expression evaluation (e.g. to avoid constructs such as A = B + GenerateReport()).
For this reason, Operators are given their own object type and Controls do not interact with operators.¶
The definition of an OPER consists of the following:¶
As defined in this document, OPERs can only be defined within an ADM. Future capability could allow the use of OPERs within ODMs if there was some mechanism to bind an OPER definition to some platform-specific evaluation specification.¶
A State-Based Rule (SBR) is a form of autonomy in which the Agent performs an action upon the change of state to meet a specific condition. The execution model of the SBR is to evaluate the Condition (as often as necessary to handle changes in its expression evaluation) and when it evaluates to a truthy (Section 6.11.1) value and it has been no shorter than the Minimum Interval since the last execution, the Action is executed. When the Maximum Count of executions is reached the TBR is disabled. The execution occurs concurrently with any time processing and may take longer than the Minimum Interval, so it is possible that multiple executions are requested to overlap in time.¶
Each SBR has an enabled state to allow rules to be retained in an ADM or ODM but not enabled during Manager-controlled time periods or under certain Manager-desired conditions. See Section 4.3 for details about what SBR-related controls are in the Agent ADM.¶
The definition of an SBR consists of the following:¶
BOOL value after evaluation and used to determine when to execute the action of the SBR.¶
TD value.
The interval MAY be zero to indicate that there is no minimum.
This is not a limit on the interval of evaluations of the condition.
This value can be used to limit potentially high processing loads on an Agent.¶
UVAST value.
The count sentinel value zero SHALL be interpreted as having no maximum.
This is not a limit on the number of evaluations of the condition.¶
true.¶
A Time-Based Rule (TBR) is a form of autonomy in which the Agent performs an action at even intervals of time. The execution model of the TBR is to start a timer at the Start Time of the TBR ticking at an even Period; each time the timer expires the Action is executed. When the Maximum Count of executions is reached the TBR is disabled. The execution occurs concurrently with any time processing and may take longer than the TBR Period, so it is possible that multiple executions are requested to overlap in time.¶
Each TBR has an enabled state to allow rules to be retained in an ADM or ODM but not enabled during Manager-controlled time periods or under certain Manager-desired conditions. See Section 4.3 for details about what TBR-related controls are in the Base ADM.¶
The definition of a TBR consists of the following:¶
TIME (Section 4.2.2) value.
A relative start time SHALL be interpreted relative to the absolute time at which the Agent is initialized (for ADM rules) or the rule is created (for ODM rules).
The start time MAY be the relative time zero to indicate that the TBR is always active.
This is not a limit on the interval of evaluations of the condition.¶
TD value.
The period SHALL NOT be zero but any non-zero small period is valid.¶
UVAST value.
The count sentinel value zero SHALL be interpreted as having no maximum.
This is not a limit on the number of evaluations of the condition.¶
true.¶
A Variable (VAR) is a stateful store of a value in an Agent. The evaluation of a VAR is similar to an EDD except that all the behavior of a VAR is entirely within an Agent, while the ultimate source of an EDD value is outside of the Agent. The evaluation of a VAR into a value SHALL be nilpotent and have no side-effects in the processor.¶
A VAR has an initializer, which is used at Agent initialization and to reset the VAR, but the VAR is otherwise stateful and will retain its last value between any actions which edit it.¶
The definition of a VAR consists of the following:¶
LABEL value.¶
An ADM is a logical entity for defining static AMM object instances, which are discussed in detail in Section 3.4. Each ADM exists as a separate namespace for its contained objects, but allows importing object names from other ADMs to reuse them. Each Agent can support any number of ADMs at one time (subject to implementation limitations) and each Manager can operate with ADMs of different revisions to support diverse Agents.¶
The following subsections define what is present in an ADM generally and what objects necessary to operate a DTNMA Agent are present in two base ADMs.¶
An ADM is "static" in the sense that it is revision-controlled and a released revision of an ADM does not change. Besides AMM object definitions there are metadata and handling rules for the ADM itself, which are discussed in this section.¶
This section explains the purposes of the metadata fields of an ADM, while the profile of Section 7 defines a syntax for how these fields fit into an ADM module.¶
id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari].¶
id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari].¶
Following in the pattern of YANG features Section 5.6.2 of [RFC7950] and SMIv2 conformance groups [RFC2580], the AMM has the concept of ADM features and Agent conformance to those features. Each feature is a simple qualified name and each object in an ADM can be conditional on the conformance to a set of features.¶
The base DTNMA ADM is a necessary part of the AMM typing, execution, and evaluation models. Rather than having some Agent logic defined purely by specification, this document uses a base ADM to define semantic types and controls needed for normal Agent operations. The needed types are still set by specification and are unchanging within an ADM revision, but this avoids having a separate, intermediate typing system between the AMM-defined semantic types and the ARI-defined literal types. This is also in-line with how the SMIv2 [RFC2578] and NETCONF/YANG [RFC6991] both rely on base modules for some core behavior.¶
The most basic use of a semantic type is to provide additional meaning to simple types. None of these types associates a unit with the value, which it is expected that a derived type or an anonymous type (at the point of use) would add for additional clarity.¶
These are summarized below:¶
counter32 and counter64:gauge32 and gauge64:timestamp:All of the literal types defined in [I-D.birrane-dtn-ari] have a flat structure, with some types sharing the same CBOR primitive encoding but having the concept of a derived "base" of another type. In order to allow types to fit into a more logical taxonomy, the base ADM defines some specific semantic typedefs to group literal types. These groups are not a strict logical hierarchy and are intended only to simplify the effort of an ADM designer when choosing type signatures.¶
These are summarized below:¶
TYPE-REF:ARITYPE and TYPEDEF types.¶
INTEGER:BYTE, UINT, INT, UVAST, and VAST types.¶
FLOAT:REAL32 and REAL64 types.¶
NUMERIC:INTEGER and FLOAT types.¶
PRIMITIVE:NULL, BOOL, NUMERIC, TEXTSTR, and BYTESTR types.¶
TIME:TP and TD types.¶
SIMPLE:PRIMITIVE, and TIME types.¶
LITERAL:SIMPLE, LITTYPE, LABEL, CBOR, AC, and AM types. This matches all values that can be in a literal value ARI.¶
VALUE-OBJ:CONST-REF, EDD-REF, and VAR-REF reference types. This matches any reference to an object that can produce a value (Section 6.5).¶
NONCE:BYTESTR, UINT64, and NULL types. This is used to correlate Agent-Manager messages.¶
An Expression (EXPR) is an ordered collection of references to Operators or operands. An EXPR takes the form of a semantic typedef refining an AC to be a list of ARIs referencing OPERs, ARIs referencing evaluate-able objects (see Section 6.7), or literal value ARIs (with Simple Types). These operands and operators form a mathematical expression that is used to compute a resulting value.¶
The evaluation procedure of an EXPR is defined in Section 6.7. Expressions are used within an ADM for defining the initializer of a Variable (VAR) and for defining the condition of a State-Based Rule (SBR).¶
Since the Expression is an AC, there are no annotative constructs such as parenthesis to enforce certain orders of operation. To preserve an unambiguous calculation of values, the ARIs that form an Expression MUST be represented in postfix order. Postfix notation requires no additional symbols to enforce precedence, always results in a more efficient encoding, and post-fix engines can be implemented efficiently in embedded systems.¶
For example, the infix expression A * (B * C) is represented as the postfix A B C * *.¶
A Macro (MAC) is an ordered collection of references to Controls or other Macros. A Macro takes the form of a semantic typedef refining an AC to be a list of ARIs referencing Controls or objects which produce other Macros.¶
The execution procedure of an MAC is defined in Section 6.6. Macros are used within an ADM for defining the action of a State-Based Rule (SBR) or Time-Based Rule (TBR).¶
In cases where a Macro references another Macro, Agent implementations MUST implement some mechanism for preventing infinite recursions, such as defining maximum nesting levels, performing Macro inspection, and/or enforcing maximum execution times.¶
A Report Template (RPTT) is an ordered list of object references or expression values used as a source for generating items for report (Section 3.2.2.5) containers.
A RPTT takes the form of a semantic typedef refining an AC to be a list of references to value-producing objects (VALUE-OBJ (Section 4.2.2)) or expressions (EXPR (Section 4.2.3)).
An object which produces an RPTT can itself be parameterized so that the object flows down parameters as described in Section 3.1.2.1.¶
A RPTT can be viewed as a schema that defines how to generate and interpret a Report; they contain no direct values. RPTT values either defined in an ADM or configured between Managers and Agents in an ODM. Reports themselves are ephemeral and represented as ARI built-in type, not as part of the AMM object model. The procedure for reporting on a RPTT is defined in Section 6.8.1.¶
RPTT values SHOULD be used within a CONST where possible. RPTT values MAY be used within a VAR where necessary. This makes correlating a RPT value with its associated RPTT easier over time. Rather than having a VAR object's RPTT value changing over time, it is RECOMMENDED to deprecate earlier RPTT-producing CONST objects and create new objects.¶
A convenience typedef exec-tgt is defined to codify the type of values allowed to be used as input for an Execution (or within an Execution-Set (EXECSET) value) or produced by objects referenced as execution targets.
The execution target type is defined to be either a direct CTRL reference, a direct MAC value, or a reference to a value-producing object which itself is typed as exec-tgt.¶
A convenience typedef eval-tgt is defined to codify the type of values allowed to be used as input for an Evaluation activity or produced by objects referenced as evaluation targets.
The execution target type is defined to be either a direct SIMPLE value, a direct EXPR value, or a reference to a value-producing object which itself is typed as eval-tgt.¶
While the DTNMA ADM described in Section 4.2 contains definitions of static aspects of the AMM, the DTNMA Agent ADM is needed to include necessary dynamic aspects of the operation of an Agent. This separation is also helpful in order to allow the dynamic behaviors of an Agent to be modified over time while the AMM definitions stay stable and unchanging.¶
The Agent ADM contains the following EDD objects used to introspect the Agent's state, all of which can change over time.¶
feature set, the contained objects in each ADM can be derived.
Because of this, the ADM-contained objects do not require additional introspection.¶
TBD defining boolean, bitwise, and numeric operators¶
An ODM is a logical entity for containing AMM objects, similar to an ADM (Section 4) but in an ODM the objects are not static. An ODM's objects can be added, removed, and (with some restrictions) modified during the runtime of an Agent. Like an ADM, each ODM exists as a separate namespace for its contained objects and an Agent can contain any number of ODMs.¶
Some object types, those which require implementation outside of the Agent proper, are not available to be created in an ODM. These include the CTRL, EDD, and OPER.¶
The actions for inspecting and manipulating the contents of an ODM are available through EDDs and CTRLs of the Agent ADM (Section 4.3.1).¶
This section discusses logic and requirements for processing of AMM objects and values. Each subsection is a separate class of processing that is performed by an Agent.¶
A Manager (or any other entity) MAY perform some of the same processing, e.g. evaluating an expression, in order to validate values or configurations before sending them to an Agent. That kind of behavior is effectively creating a "digital twin" of the managed Agent to ensure that the processing will behave as expected before it is sent. For this reason, the subject noun used in all of these activities is the "processor".¶
The initialization of the Agent state can be associated with a power-on event or, due to the use of volatile memory, can be an explicit activity initiated from outside the Agent runtime. If volatile memory is used the contents of the ODMs on an Agent will be present for the initialization procedure; otherwise the ODMs will be considered empty or absent.¶
The procedure to initialize an Agent is as follows:¶
All ADM-defined VAR objects SHALL have their value set to one of the following:¶
undefined.¶
Any ODM-defined VAR objects MAY retain their state.¶
Within an ADM, ARIs present in the various fields of object definitions are URI References, which can take the form of Relative URIs (see Section 4.2 of [RFC3986]). Any ARIs within an ADM definition SHALL be handled as URI References and resolved in accordance with the procedure of Section 5 of [RFC3986] with the following used as a Base URI:¶
ari:/ SHALL be the Base URI.
This means that all ARIs within an ADM do not require a URI scheme part.¶
An Object Reference Values contains an identity and a parameter part.
Dereferencing an OBJECT value uses the identity to look up a specific defined object available to the agent.¶
The process of dereferencing a value is as follows:¶
OBJECT value namespace (whether text or enumeration) is used to search for a defined ADM or ODM namespace.
A text form namespace SHALL be compared within the UTF-8 character set in accordance with [RFC3629].
An integer namespace SHALL be compared numerically.
If no corresponding namespace is available, this procedure stops and is considered failed.¶
An Object Reference Values contains an identity and a parameter part.
The parameter part of an OBJECT value represents the given parameters (Section 3.1.2.1) being used.
The given parameters are present either as a (possibly empty) ARI list or an ARI map.
Due to nuances of the AMM value system, the given parameters are not themselves either AC or AM values but similar to untyped ARI values.¶
The process to validate and normalize given parameters against an object's formal parameters to produce actual parameters is as follows.¶
For each formal parameter, the processor performs the following:¶
If the given parameters are a list, the formal parameter is correlated to the list by its position in the formal parameters list.
If the given parameters list does not contain a corresponding position the given parameter is treated as the undefined value.¶
If the given parameters are a map, the formal parameter is correlated to a map key by either its position (as an integer) or its name (as a text string) but not both.
If both integer and name are present in the given parameters map the procedure stops and is considered failed.
If the given parameters map does not contain a corresponding key the given parameter is treated as the undefined value.¶
For each correlated pair of formal parameter and given parameter, the processor performs the following:¶
If the given parameter is undefined and the formal parameter defines a default value, that default is used as the actual parameter value.
If there is no default value, the actual parameter is left as the undefined value.¶
TYPEDEF and the object reference itself has a parameter, the given parameter is treated as the result of a type conversion (Section 6.11.3) to the TYPEDEF.
If the conversion fails this procedure stops and is considered failed.
Is this step strictly necessary? Would the formal parameter conversion not be sufficient?¶
The actual parameters resulting from this procedure are intended to be able to be looked up by an implementation either by ordinal position in the formal parameters list or by unique name of the formal parameter. It is an implementation matter whether or not to provide both accessing methods and the specifics of how, for example, and EDD or CTRL runtime accesses actual parameter values.¶
An implementation MAY perform deferred "lazy" processing of any of the above steps, causing a failure when the actual parameter value is needed. One caveat about deferred processing is that it will not fail if the parameter is unused, which is not necessarily a problem but could mask other issues in whatever provided the given parameters.¶
Value production can be thought of as a common behavior used for Execution, Evaluation, and Reporting activities. Within the AMM the following entities have a value production procedure: CONST, EDD, and VAR object references.¶
This activity relies on an object reference value to have been dereferenced in accordance with Section 6.3 and its parameters handled in accordance with Section 6.4. After that, each of the object types is treated differently as defined in the following subsections.¶
Both CONST and VAR objects act as a store of a single literal value within the Agent.
Formal parameters on either CONST or VAR objects are applicable only when the objects store a value which itself contains parameters with at least one LABEL type.¶
The value production for these objects takes the stored value from the object and augments it by label substitution based on the following:¶
LABEL type within the stored value, descending into container (Section 3.2.2) contents and object reference parameter contents as necessary.¶
LABEL text is not present in the formal parameters of the value-producing object then this procedure stops and is considered failed.¶
LABEL value the corresponding actual parameter is not the undefined value, the LABEL value is replaced by the actual parameter.¶
This augmentation has no effect on the stored value, it occurs only in the produced value.
It is valid both for an actual parameter to have no substitution occur with its value and for an undefined actual value not be sued in substitution.¶
For EDD objects, the actual parameters are used by the underlying implementation to produce the value in an arbitrary way.
The produced value is typically either a SIMPLE (Section 4.2.2) value or an ARI Table (Section 3.2.2.3).¶
The value production for these objects occurs outside of the Agent proper within an implementation of the EDD being produced from.¶
The context given to the implementation is the following:¶
EDD value which was dereferenced during the production.¶
The initial state of the Result Storage is the undefined value.
It is an implementation matter and author consideration (Section 8) to enforce that the produced value is consistent with the type of the object.¶
Within the AMM only two entities can be the target of an execution procedure: controls and macros.
Controls are executed by reference, while macros are executed both by value and by reference.
This means the execution target value SHALL match the exec-tgt (Section 4.2.6) semantic type.¶
The procedure for executing is divided into phases to ensure that it does not fail due to invalid references or produced values after some controls have already been executed. The phases are processed as follows:¶
In the expansion phase the target value is processed to dereference all references, handle all parameters, and expand any produced values.¶
If the target is a literal value, the following is performed:¶
MAC (Section 4.2.4) semantic type.
If it does not match, this procedure stops and is considered failed.¶
If the target is an object reference, the following is performed:¶
LABEL parameters within the value.¶
After expansion the target is either a dereferenced CTRL object, or a (possibly nested) macro expanded to contain only dereferenced CTRL objects.¶
The execution of an Macro (MAC) value after expansion is as follows:¶
The processor iterates through all items of the expanded MAC in order and performs the following:¶
If the item is an CTRL-REF it is executed in accordance with Section 6.6.2.
If the execution fails, this procedure stops and is considered failed.¶
Otherwise the item is an expanded sub-macro and it is executed in accordance with this procedure.¶
An effect of this procedure is that if any referenced CTRL fails during execution the processing fails immediately and subsequent CTRLs or MACs are not executed.¶
This activity relies on an object reference value to have been dereferenced in accordance with Section 6.3 and its parameters handled in accordance with Section 6.4.¶
The execution of a Control (CTRL) object occurs outside of the Agent proper within an implementation of the CTRL behavior.¶
The context given to the implementation is the following:¶
CTRL value which was dereferenced during the execution.¶
The initial state of the Result Storage is the null value.¶
If the execution fails, the result value SHALL be treated as the undefined value for the purposes of any subsequent reporting.¶
Within the AMM the following entities can be the target of an evaluation procedure: references to value-producing objects, OPERs, and TYPEDEFs and EXPR or SIMPLE literal values.¶
The procedure for evaluation is divided into phases to ensure that it does not fail due to invalid references or produced values after some expressions have already been evaluated. The phases are processed as follows:¶
In the expansion phase the target value is processed to dereference all references, handle all parameters, and expand any produced values.¶
If the target is a literal value, the following is performed:¶
SIMPLE (Section 4.2.2) or EXPR (Section 4.2.4) semantic type.
If it does not match, this procedure stops and is considered failed.¶
If the target is an object reference, the following is performed:¶
LABEL parameters within the value.¶
After expansion the target is either a SIMPLE value, or a (possibly nested) expression expanded to contain only SIMPLE or ARITYPE values, or dereferenced OPER or TYPEDEF objects.¶
If the expanded evaluation target is already a SIMPLE value, then that is the result of the evaluation.
Otherwise, the expanded expression is evaluated in accordance with Section 6.7.1.¶
The reduction of an Expression (EXPR) value after expansion is as follows:¶
SIMPLE or ARITYPEvalues, the result value of sub-expression reduction, or dereferenced OPER or TYPEDEF objects.¶
The expression is treated as a Reverse Polish Notation (RPN) sequence, where the following is performed on each item in the AC in sequence:¶
If the item is an ARITYPE value or dereferenced OPER or TYPEDEF object it is evaluated in accordance with Section 6.7.4, Section 6.7.2 or Section 6.7.3 respectively.
If the evaluation fails, this procedure stops and is considered failed.¶
Otherwise, the item is pushed onto the stack.¶
One effect of this procedure is that if any referenced values cannot be produced the procedure fails before any OPER is evaluated.
Another effect of this procedure is that if any referenced OPER fails during evaluation or any value production fails the EXPR processing fails immediately and subsequent OPER values, EXPR values, or VALUE-OBJ references are not evaluated.¶
This procedure applies only during the evaluation of a containing expression (Section 6.7.1); an OPER cannot be evaluated in isolation.¶
The evaluation of an OBJECT value referencing a Operator (OPER) is as follows:¶
The processor passes the evaluation on to the underlying implementation of the OPER being evaluated.¶
The context available to the implementation is the following:¶
If the evaluation procedure fails, the failure SHALL propagate up to any expression evaluation.¶
This procedure applies only during the evaluation of a containing expanded expression; a TYPEDEF object cannot be evaluated in isolation. The evaluation of a TYPEDEF is handled similarly to a unary OPER but it occurs entirely within the Agent and does not rely on an object-specific implementation.¶
The evaluation of a TYPEDEF object is as follows:¶
TYPEDEF value itself has no parameters, the input value is popped from the stack.
If the TYPEDEF value itself has one parameter, the input value is that parameter.
If the TYPEDEF value itself has more than parameter, this procedure stops and is considered failed.¶
This procedure applies only during the evaluation of a containing expanded expression; an ARITYPE value cannot be evaluated in isolation. The evaluation of an ARITYPE is handled similarly to a TYPEDEF but with no possibility of a parameterized conversion.¶
The evaluation of an ARITYPE value is as follows:¶
Within the AMM the following entities have a reporting context: RPTT and EXPR values and CONST, EDD, and VAR objects. The value-producing objects are reported-on by reference, while RPTT are reported-on both by value and by reference.¶
The reporting on a Report Template (RPTT) value, which is structured as an AC, is as follows:¶
The processor iterates through all items of the AC, performing the following:¶
If the item is an EXPR value it is replaced by the result of evaluation in accordance with Section 6.7.
If the evaluation fails the undefined value is used as a substitute.¶
Otherwise, if the item is a VALUE-OBJ it is replaced by the value produced in accordance with Section 6.5.
If the production fails the undefined value is used as a substitute.¶
Otherwise, the result of the production is the value appended to the item list.¶
Because this procedure acts on an RPTT value and not an object reference, the report itself cannot be assembled within this context.
One effect of this procedure is that if any item of the RPTT cannot be reported on, the undefined value is used as a sentinel and the other report items are still generated.¶
This activity relies on an object reference value to have been dereferenced in accordance with Section 6.3 and its parameters handled in accordance with Section 6.4.¶
The reporting on an object producing a value of any type is as follows:¶
LABEL parameters within the value.¶
If the value is an RPTT (Section 4.2.5) type, this value is used to generate an AC containing report items in accordance with Section 6.8.1.
Should this be allowed? What is the end structure of sub-reports?¶
Otherwise, the produced value is used as the single RPT item.¶
Managers SHOULD aggregate multiple Execution-Set (EXECSET) values associated with the same Agent and Correlator Nonce into a single Execution-Set. The aggregation MAY be based on a size limit (e.g., number of targets), time limit, or an event (e.g., network availability). This avoids the overhead of transport and processing multiple executions on the same Agent, and due to the requirements in Section 6.9.2 makes no difference to (lack of) guarantees in execution order.¶
An Agent SHALL process an Execution-Set through the independent Execution of each item in the target list. Execution order is not guaranteed and failures on one target do not affect other target, so targets MAY be executed in any order or concurrently. This is not the same behavior as the execution of a macro, where execution of items is ordered and a failure of any execution causes subsequent items to not be executed.¶
Agents SHOULD aggregate multiple Reporting-Set (RPTSET) values associated with the same Manager and Correlator Nonce into a single Reporting-Set. The aggregation MAY be based on a size limit (e.g., number of reports or number of total report items), time limit, or an event (e.g., network availability or power-saving wake-up). This avoids the overhead of transport and processing multiple messages on a Manager and improves timestamp compression in the reports, but it does require that all of the items are associated with the same manager and nonce.¶
A Manager SHALL process each report within a Reporting-Set independently. Failures in processing any one report do not affect other reports, so reports MAY be processed in any order or concurrently. After using a Report Template to correlate report items with source objects, a Manager SHALL treat each (timestamp, object, item value) tuple independently from its containing Reporting-Set or Report.¶
Definition TBD, type matching does not affect the AMM value.¶
The type system of the AMM allows conversions of values between different literal and semantic types in a way which is supposed to preserve the "meaning" of the value.¶
In some cases, type conversion is performed implicitly by the Agent while other cases the conversion is explicitly part of an expression. One example of implicit casting is during Parameter Handling to ensure each processed parameter meets the formal parameter type signature. Another example of implicit conversion is for numeric operators in the Agent ADM (Section 4.3.2).¶
The AMM has the concepts of "truthy" and "falsey" as being the result of casting to BOOL type.
Similar to the ToBoolean() function from [ECMA-262], the AMM casting treats the following as falsey and every other value as truthy:¶
undefined¶
null value of NULL¶
false value of BOOL¶
BYTE, UINT, INT, UVAST, and VAST¶
REAL32 and REAL64¶
TEXTSTR and BYTESTR¶
When casting a value to BOOL type, the processor SHALL use the result value false if the original value is falsey and true otherwise.¶
The casting of a value to a NUMERIC type is intended to easily allow mixed-type expressions while keeping the number of operators and parameter unions small.¶
When casting a value to an INTEGER type from any other NUMERIC type, the processor SHALL perform the following:¶
FLOAT types and is not finite, the conversion is considered failed.¶
FLOAT types, the value is truncated to an integer by rounding toward zero.¶
When casting a value to an FLOAT type from any other NUMERIC type, the processor SHALL perform the following:¶
While the earlier discussion of numeric type casting is about converting from an input type to an output type, the concept of a type promotion is about finding a "least compatible type" which can accommodate most, if not all, of the input type range. Converting to a promoted type is called an "up" conversion, and from a promoted type a "down" conversion.¶
The promotion order for NUMERIC types is as follows:¶
This promotion logic does not guarantee that an up-conversion will always succeed (e.g. some large UVAST values will not fit within a VAST or REAL32) but does provide a strict ordering for finding a compatible type between two NUMERIC values.
The "least compatible type" between two types SHALL be defined as the smallest up-conversion that will accommodate the input types, as indicated in Table 4.
This is almost a strict ordering except for the conversion of INT and UVAST to VAST to accommodate both the signed-ness and the size of the inputs.¶
| BYTE | UINT | INT | UVAST | VAST | REAL32 | REAL64 | |
|---|---|---|---|---|---|---|---|
| BYTE | BYTE | UINT | INT | UVAST | VAST | REAL32 | REAL64 |
| UINT | UINT | INT | UVAST | VAST | REAL32 | REAL64 | |
| INT | INT | VAST | VAST | REAL32 | REAL64 | ||
| UVAST | UVAST | VAST | REAL32 | REAL64 | |||
| VAST | VAST | REAL32 | REAL64 | ||||
| REAL32 | REAL32 | REAL64 | |||||
| REAL64 | REAL64 |
Unlike literal type casting, which has the potential to change the form of the value itself, casting to a semantic type is meant to either affirm or add an association between an AMM value and a TYPEDEF object. All of this processing is performed independently of any literal-type-specific handling, so none of it needs to be specialized to specific TYPEDEF objects.¶
The conversion of an input value to a TYPEDEF is as follows:¶
NOTE: These procedures need to be validated by a trial implementation.¶
The procedures in this section allow AMM values, which can have a semantic type (Section 3.3), to be translated into and out of the ARI syntax (Section 3.1.3), which has no semantic type information. They also describe a way to use type-less literal values to give further compression of values in certain circumstances.¶
The compression of removing type information is possible only when the context in which the value is being used has a specific semantic or literal type associated with it. For example, when a formal object parameter or a report item is typed to either a literal type or a semantic type that doesn't represent a type union then a value being used for the parameter or item can only have that specific type; any other value type will be mismatched and invalid. Another way of looking at this compression is when the value has the same type as its context requires, then the value's type is redundant and can be elided without loss of information.¶
In addition to compression by eliding semantic type within a context, there are also some literal types which have values which only exist in that type.
For example, the BOOL value true exists only within that type while the UINT value 5 is also within the domain of INT and several others.¶
For the procedures below, the contexts which provide type information SHALL be: all formal parameters, VALUE-OBJ values, report template items, tabular columns.¶
When translating from an AMM value into an ARI, the processor performs the following:¶
When translating from an ARI into an AMM value, the processor performs the following:¶
This section provides an ADM syntax in the form of a YANG module conforming to a profile of [RFC7950] with AMM-specific extensions.¶
It is not required that this encoding be used for transmission of ADM information over the wire in the context of a network deployment. Since the AMM is designed to allow for multiple encodings, the expression of ADMs in YANG syntax is intended to support translation to other encodings without loss of information.¶
Some aspects of this ADM module profile restrict the allowable definitions to conform with Section 3.4 and by doing so make YANG modules defining ADMs incompatible with YANG modules intended for NETCONF, RESTCONF, or other applications. Because of this, YANG modules defining ADMs SHALL be managed separately from the "YANG Module Names" sub-registry of [IANA-YANG]. See the ADM sub-registry defined in Section 9.3 of [I-D.birrane-dtn-ari] for registration of ADM modules. For the remainder of this section, a YANG module defining an ADM will be referred to as an "ADM module" and a YANG module for any other purpose will be referred to as a "Legacy module" to differentiate it.¶
After explanation of extensions in Section 7.3, the following minimal ADM module will be expanded upon for further examples.¶
<CODE BEGINS> file "example-adm.yang"
module example-adm {
yang-version 1.1;
namespace "ari:/example-adm";
prefix example-adm;
import ietf-amm {
prefix amm;
}
organization "Example Org.";
description "Example module.";
amm:enum "4294967296";
}
<CODE ENDS>¶
The benefit of using the pre-existing YANG syntax is to take advantage of both tools that process YANG modules as well as some of the syntax and module-level semantics provided by YANG.¶
The following statements and behaviors of YANG are usable within an ADM with no modification:¶
ari:/example-adm which is valid YANG.¶
VALUE-OBJ definitions, and table columns.¶
Because of the different interpretation of data definitions for an ADM module, the following restrictions are used to limit pre-existing valid YANG syntax within an ADM module:¶
NULL type to indicate optional values and AMM values can use the null value to represent that state.
In the case of formal parameters, the use of a "default" statement is used to indicate behavior when an actual parameter is undefined.
In any case, the AMM value is always present when defined in the structure of an AMM object.
An ADM module SHALL NOT contain any "mandatory" statements.¶
As discussed in Section 7.1.2, the YANG type and node models are fundamentally different from the AMM value model of Section 3.1. While YANG modules have been used to model data for XML representation for NETCONF (or equivalent representations for equivalent protocols), AMM values do not have explicit identifiers.¶
The built-in types of the AMM are present in the "Literal Types" and "Managed Object Types" sub-registries of [IANA-DTNMA]. These lists of type names are not fixed in any single specification, but do require standards action to add to and update URI processors to handle them, so it is expected that this list will be relatively static (compared to the expected rate of addition or changes to ADMs).¶
Similar to how YANG treats built-in types, the AMM literal and object type names are used without any namespace context. Differently to YANG, the AMM type names are handled and compared in a case-insensitive manner.¶
There are a number of extensions defined in Section 7.3 related to how AMM value types and type definitions are used by object definitions. These include the following purposes.¶
A type definition is a way for an ADM to apply a name and descriptive metadata to a specific type use (see Section 7.2.2). The type definition (TYPEDEF) is also a top-level ADM object, as explained in Section 3.4.2 with a syntax in Section 7.3.4.¶
An imported module "prefix" and object name of a TYPEDEF can be used wherever a type name is needed by one of the type uses. The syntax for this is the same as for YANG types and uses, where the prefix and typedef name are joined by a colon (":"). For example, importing a module with a prefix of "mod" containing a typedef "mytype" is used by the type name:¶
mod:mytype¶
Except for the case of a simple "type" with no restrictions or annotations, where one of the type uses occurs in an object definition can be considered as an "anonymous" TYPEDEF. The behavior in those cases is identical to a TYPEDEF just without a name associated with the type use.¶
In order to provide syntax necessary for AMM Object Types definitions this document defines, via the DTNMA ADM (Appendix A), the following extensions for ADM modules.¶
amm:enum Statement
This statement is used to apply an integer enumeration to an ADM module or object, which enables the compressed form of ARI discussed in Section 3.1 of [I-D.birrane-dtn-ari].
The argument to this statement is an integer in the YANG range 0..2^31-1 to fit within the ARI syntax.
There are no substatements defined in this profile.¶
The statements within this section enable the various type uses as explained in Section 7.2.2. They are all used as substatements within one of the AMM object definition statements, sometimes directly (e.g., for CONST or EDD typing) and sometimes indirectly (e.g., for parameter or operand typing), but always as a choice between the need for one of the type use statements.¶
amm:type Statement
This statement creates a simple type use by its parent statement. The argument to this statement is the name of the type being used, which can either be a built-in type or a qualified typedef name.¶
The substatements under this are restrictions on the type being used.¶
| Substatement | Cardinality | Valid for These Types |
|---|---|---|
| reference | 0..1 | |
| description | 0..1 | |
| units | 0..1 | Any NUMERIC
|
| range | 0..1 | Any INTEGER or FLOAT with appropriate quantized values |
| length | 0..1 |
TEXTSTR as number of characters, or BYTESTR as number of bytes |
| pattern | 0..1 |
TEXTSTR only |
| int-labels | 0..1 | Any INTEGER type |
Examples of the "type" statement are below, some as simple use and some as restriction.¶
amm:type uint {
description "unconstrained";
}
amm:type uint {
range "3..10";
units "meter";
description "constrained";
}
amm:type textstr {
length "10..100";
}
¶
amm:ulist Statement
This statement defines the structure of and constraints on ARI Collection (AC) values where a single type is used for each of its elements. There is no argument to this statement.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| min-elements | 0..1 |
| max-elements | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
Examples of the "ulist" statement are below, some as simple use and some as restriction.¶
amm:ulist {
amm:type uint;
}
amm:ulist {
amm:type uint {
range "3..10";
units "meter";
}
min-elements 2;
max-elements 10;
}
¶
amm:dlist Statement
This statement defines the structure of and constraints on ARI Collection (AC) values where diverse types are used among each of its elements. There is no argument to this statement.¶
Each of the type use substatements defines a single element within the AC, except for the amm:seq which defines a sequence of type-matching elements within the AC (rather than as a sub-AC).¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| One or more of the type uses: | |
| amm:type | 0..n |
| amm:ulist | 0..n |
| amm:dlist | 0..n |
| amm:umap | 0..n |
| amm:union | 0..n |
| amm:seq | 0..n |
Examples of the "dlist" statement are below, one as simple structure and the other as a complex sequence.¶
amm:dlist {
// each "type" substatement is one element of the AC
amm:type uint;
amm:type uint;
}
amm:dlist {
// first AC element is text
amm:type textstr;
// remaining 2-10 element are int
amm:seq {
amm:type int;
min-elements 2;
max-elements 10;
}
}
¶
amm:umap Statement
This statement defines the structure of and constraints on ARI Map (AM) values where a single type is used for each of its keys and values respectively. There is no argument to this statement.¶
When present, each of the amm:keys and amm:values substatements constrains the associated aspect of all map items to the specific type; when absent the aspect is left unconstrained.
Keep in mind that AM keys are always constrained to untyped literal values and the use of amm:keys can only narrow this constraint.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| amm:keys | 0..1 |
| amm:values | 0..1 |
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
Examples of the "umap" statement are below, some as simple use and some as restriction.¶
amm:umap {
amm:keys {
amm:type uint;
}
description "restrict only keys";
}
amm:umap {
amm:keys {
amm:type uint;
}
amm:values {
amm:type textstr;
}
}
¶
amm:tblt Statement
This statement defines the structure of and constraints on ARI Table (TBL) values. There is no argument to this statement.¶
The substatements are a combination of "amm:column" statements defining table structure and "amm:key", "amm:unique", "min-elements", "max-elements" statements defining constraints on the table rows.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| min-elements | 0..1 |
| max-elements | 0..1 |
| amm:column | 0..n |
| amm:key | 0..1 |
| amm:unique | 0..n |
Examples of the "tblt" statement are below.¶
amm:tblt {
amm:column first {
amm:type uint;
}
amm:column second {
amm:type textstr;
}
amm:key first;
}
¶
amm:column Statement
This statement defines the name and type of each column of a table. The argument to this statement is an identifier for the column. All columns SHALL have unique names within the same parent table.¶
The substatements under this are one of the type use statements (Section 7.3.2) which defines the type for values in this column. The type of a column SHALL NOT itself use a "tblt" or a union which contains a "tblt".¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
amm:union Statement
This statement defines a choice from a list of other type uses. There is no argument to this statement.¶
Each of the substatements defines one of the possible choices of the union. The order of the list of choices is significant, especially when converting ARI values, because the first choice which matches or converts will be used regardless of any other choices.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| amm:type | 0..n |
| amm:ulist | 0..n |
| amm:dlist | 0..n |
| amm:tblt | 0..n |
| amm:umap | 0..n |
Examples of the "union" statement are below, some as simple use and some as restriction.¶
amm:union {
amm:type int;
amm:type null;
description "an optional int";
}
amm:union {
amm:type uint {
range "3..10";
units "meter";
}
amm:type textstr;
}
¶
amm:seq Statement
This statement creates a sequence within an AC with identical type use in each of its elements. There is no argument to this statement.¶
This statement is distinct from the "amm:ulist" statement, which types the AC container itself, while the "amm:seq" types a portion of elements within an AC. The "amm:seq" is not present as a top-level value type except for the special case of a greedy capturing parameter type.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| min-elements | 0..1 |
| max-elements | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
Examples of the "seq" statement are below.¶
amm:dlist {
amm:type textstr;
amm:seq {
amm:type uint;
min-elements 1;
}
}
¶
amm:parameter Statement
This statement is used to define one formal parameter that apply to the parent object. The argument to this statement is an identifier for the parameter. All parameters SHALL have unique names within the same parent object.¶
The substatements under this are one of the type use statements (Section 7.3.2) which defines the type of the parameter. When the "amm:seq" statement is used to type a formal parameter, it SHALL be the last parameter in the list and represents a greedy matching of that an all subsequent given parameters.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| amm:default | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
| amm:seq | 0..1 |
An example of the "parameter" statement is below, where there are three defined parameters two of which have default values.¶
amm:parameter first {
amm:type uint {
range "3..10";
}
}
amm:parameter second {
amm:type textstr;
amm:default "\"value\"";
}
amm:parameter third {
amm:ulist {
amm:type uint;
}
amm:default "/AC/(3,5,8)"
}
¶
amm:default Statement
This statement is used to define default parameter as an AMM value. The argument to this statement is the text form of the ARI encoding the expression.¶
The default value is used in the Parameter Handling procedure to normalize given parameters into actual parameters.¶
amm:typedef Statement
This statement is used to define a Semantic Type Definition (TYPEDEF) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are a choice of the type use (see Section 7.2.2) being named by the typedef.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
Examples of the "typedef" statement are below, some as restriction and some as union.¶
amm:typedef restricted-uint {
amm:type uint {
range "3..10";
}
description "Example restriction";
}
amm:typedef annotated-uint {
amm:type uint {
units "meter";
}
description "Example units annotation";
}
amm:typedef structured-ac {
amm:ulist {
amm:type real32;
amm:units "meter";
min-elements 3;
max-elements 10;
}
description "Example units annotation";
}
¶
amm:const Statement
This statement is used to define a Constant (CONST) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, optional formal parameters, and one of the type use statements (Section 7.3.2) that represents the produced value of the CONST. The "const" statement SHALL contain a an "init-value", which is the constant represented by this object.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| amm:parameter | 0..n |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| amm:init-value | 1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
An example of a simple-typed CONST is below.¶
amm:const pi32 {
amm:type real32;
amm:init-value "3.14159";
description "A truncated value of Pi.";
}
¶
Another example of a semantic-typed MAC-valued (Section 4.2.4) CONST is below.¶
amm:const do_thing {
amm:type amm:MAC;
amm:init-value "/AC/(../CTRL/first,../CTRL/second(2))";
description "Execute two controls in sequence.";
}
¶
amm:ctrl Statement
This statement is used to define a Control (CTRL) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, optional formal parameters, and an optional execution result.
If the amm:result substatement is present it SHALL contain an "init-value" substatement, used to initialize the Result Storage for the execution procedure (Section 6.6.2).
If the amm:result substatement is omitted the assumed result type SHALL be NULL with a default value of null.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| amm:parameter | 0..n |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| amm:result | 0..1 |
An example of a single-parameter CTRL is below.¶
amm:ctrl reset_count {
amm:parameter src {
type textstr;
description "The name of the source.";
}
amm:result previous {
type UVAST;
description "The value just before reset.";
}
description "This control resets counts for the given source.";
}
¶
amm:result Statement
The result statement contains one of the type use statements (Section 7.3.2) which represents the result expected from executing a CTRL or evaluating an OPER. The argument to this statement is an identifier for the result.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
amm:edd Statement
This statement is used to define a Externally Defined Data (EDD) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, optional formal parameters, and one of the type use statements (Section 7.3.2) that represents the produced value of the EDD.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| amm:parameter | 0..n |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
An example of a simple-typed EDD is below.¶
amm:edd tx_count {
amm:type amm:counter64 {
units "frames";
}
description "The count of the number of frames sent.";
}
¶
amm:oper Statement
This statement is used to define a Operator (OPER) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, optional formal parameters, an operands list, and an evaluation result.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| amm:parameter | 0..n |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| operands | 1 |
| result | 1 |
An example of an arithmetic OPER is below.¶
amm:oper add {
amm:operand val_a {
amm:type amm:NUMERIC;
}
amm:operand val_b {
amm:type amm:NUMERIC;
}
amm:result sum {
amm:type amm:NUMERIC;
}
description "Sum together the two operands.";
}
¶
A more complex "variadic" OPER with parameters is below. Also note the anonymous semantic type used to restrict the parameter.¶
amm:oper sum {
parameter count {
amm:type amm:UINT {
range "1..max";
}
description "The number of operands to pop."
}
operand value {
amm:type amm:NUMERIC;
description
"This is not within a container, so does not represent an AC;
it is multiple operands.";
}
result sum {
type amm:NUMERIC;
}
description "Sum together a sequence from the stack.";
}
¶
amm:operand Statement
This statement is used to define one operand that applies to the parent object. The argument to this statement is an identifier for the operand. All operands SHALL have unique names within the same parent object.¶
| Substatement | Cardinality |
|---|---|
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
amm:sbr Statement
This statement is used to define a State-Based Rule (SBR) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| amm:action | 1 |
| amm:condition | 1 |
| amm:min-interval | 0..1 |
| amm:max-count | 0..1 |
| amm:init-enabled | 0..1 |
An example of an SBR with some default fields is below.¶
amm:sbr enable_safe_mode {
amm:action "TBD";
amm:condition "/AC/(./EDD/sensor,./VAR/min_threshold,/ietf-amm/OPER/lessthan)";
description "Enable safe mode below threshold.";
}
¶
amm:min-interval Statement
This statement is used to define the Minimum Interval field of State-Based Rule (SBR) objects.
The argument to this statement is the text form of a TD value.
If not present, the default value of zero (meaning no minimum) is used.¶
amm:max-count Statement
This statement is used to define the Maximum Count field of State-Based Rule (SBR) and Time-Based Rule (TBR) objects.
The argument to this statement is the text form of a UVAST value.
If not present, the default value of zero (meaning no limit) is used.¶
amm:init-enabled Statement
This statement is used to define the Initial Enabled state of State-Based Rule (SBR) and Time-Based Rule (TBR) objects.
The argument to this statement is the text form of a BOOL value.
If not present, the default value of true is used.¶
amm:tbr Statement
This statement is used to define a Time-Based Rule (TBR) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| amm:action | 1 |
| amm:start | 1 |
| amm:period | 0..1 |
| amm:max-count | 0..1 |
| amm:init-enabled | 0..1 |
An example of an TBR with some default fields is below.¶
amm:tbr tlm_rule {
amm:action "/AC/(./CTRL/first,/adm2/CTRL/other)";
amm:period "/TD/PT30s";
description "Generate telemetry reports.";
}
¶
amm:start Statement
This statement is used to define the Start field of Time-Based Rule (TBR) objects.
The argument to this statement is the text form of a TIME (Section 4.2.2) value.
If not present, the default value of zero (meaning start immediately) is used.¶
amm:var Statement
This statement is used to define a Variable (VAR) object. The argument to this statement is the name of the AMM object.¶
The substatements under this are the common object metadata, optional formal parameters, one of the type use statements (Section 7.3.2) that represents the stored-and-produced value of the VAR, and an optional initializer expression.¶
| Substatement | Cardinality |
|---|---|
| if-feature | 0..1 |
| amm:enum | 0..1 |
| amm:parameter | 0..n |
| status | 0..1 |
| reference | 0..1 |
| description | 0..1 |
| One of the type uses: | |
| amm:type | 0..1 |
| amm:ulist | 0..1 |
| amm:dlist | 0..1 |
| amm:tblt | 0..1 |
| amm:umap | 0..1 |
| amm:union | 0..1 |
| An optional initializer: | |
| amm:init-value | 0..1 |
| amm:init-expr | 0..1 |
An example of a simple-typed VAR with an initializer value is below.¶
amm:var min_threshold {
amm:type real32 {
units "meter";
}
amm:init-value "1e4";
description "The lower threshold to enable safe mode.";
}
¶
amm:init-value Statement
This statement is used to define CONST values and VAR initial state as an AMM value. The argument to this statement is the text form of the ARI encoding the expression.¶
The initializer is used as part of the Agent Initialization procedure, and when new VAR objects are defined in an ODM.¶
amm:init-expr Statement
This statement is used to define an initial VAR state as an AMM value or an Expression (EXPR). The argument to this statement is the text form of the ARI encoding the expression.¶
The initializer is used as part of the Agent Initialization procedure and when new VAR objects are defined in an ODM.¶
An ADM module is identified, as defined in Section 7.1.1, by the module "namespace" having an "ari" scheme. Within an ADM module, this profile makes restrictions in Section 7.1.2 which are formalized in the following table of allowed module substatements. This table is adapted from Section 7.1. of [RFC7950].¶
The "yang-version" of all ADM modules conforming to this document SHALL be "1.1". Later versions of YANG syntax could introduce incompatible changes and will need to be examined for consistency with the ADM module use.¶
| Substatement | Cardinality |
|---|---|
| yang-version | 1 |
| namespace | 1 |
| prefix | 1 |
| include | 0..n |
| import | 0..n |
| status | 0..1 |
| reference | 0..1 |
| organization | 0..1 |
| description | 0..1 |
| revision | 0..n |
| extension | 0..n |
| feature | 0..n |
| deviation | 0..n |
| amm:enum | 1 |
| amm:typedef | 0..n |
| amm:const | 0..n |
| amm:ctrl | 0..n |
| amm:edd | 0..n |
| amm:oper | 0..n |
| amm:sbr | 0..n |
| amm:tbr | 0..n |
| amm:var | 0..n |
The AMM model provides multiple ways to represent certain types of data. This section provides informative guidance on how to express application management constructs efficiently when authoring an ADM document.¶
Parameters incur bandwidth and processing costs (such as type checking) and should only be used where necessary. If an EDD object can be parameterized, but the set of parameters is known and unchanging it may be more efficient to define multiple non-parameterized EDD objects instead. For example, consider a single parameterized EDD object reporting the number of bytes of data received for a specific, known set of priorities and a request to report on those bytes for the "low", "med", and "high" priorities. Below are two ways to represent these data: using parameters and not using parameters.¶
+------------------------+------------------------+ | Parameterized EDDs | Non-Parameterized EDDs | +------------------------+------------------------+ | num_bytes_by_pri(low) | num_bytes_by_low_pri | | num_bytes_by_pri(med) | num_bytes_by_med_pri | | num_bytes_by_pri(high) | num_bytes_by_high_pri | +------------------------+------------------------+
The use of parameters in this case only incurs the overhead of type checking, parameter encoding/decoding, and associative lookup. This situation should be avoided when deciding when to parameterize AMM objects.¶
This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of schema and namespaces related to core ADMs, in accordance with BCP 26 [RFC1155].¶
This document relies on existing ARI-defined sub-registries defined in [IANA-DTNMA] by Section 9.3 of [I-D.birrane-dtn-ari].¶
This document registers the following entries within the "Application Data Models" sub-registry of the "DTN Management Architecture Parameters" registry [IANA-DTNMA].¶
| Enumeration | Name | Reference | Notes |
|---|---|---|---|
| 1 | ietf-dtnma-agent | [This document] |
This document does not describe any on-the-wire encoding or other messaging syntax. It is assumed that the exchange of AMM objects between Agents and Managers occurs within the context of an appropriate network environment.¶
The Access Control Lists (ACLs) functionality presented in this document would be implemented separately from network security mechanisms.¶
ACL groups are expected to be associated with Managers. However, the form of Manager identification must be provided by separate transport-specific ADMs. The AMM provides no general purpose identifier, such as peer name and address, that would be required to uniquely describe each Manager.¶
The following is the ADM module implementing the entities described in Section 4.2:¶
<CODE BEGINS> file "ietf-amm.yang"
module ietf-amm {
yang-version 1.1;
namespace "ari:/ietf-amm/";
prefix amm;
amm:enum "0";
organization
"IETF Delay Tolerant Networking (DTN) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/dtn/>
WG List: <mailto:dtn@ietf.org>
Author: Brian Sipos
<mailto:brian.sipos+ietf@gmail.com>";
description
"This module implements the DTN Management Architecture (DTNMA)
Application Management Model (AMM) extensions within YANG";
reference
"draft-birrane-dtn-adm";
revision 2023-06-08 {
description
"Updated for latest AMM contents.";
reference
"draft-birrane-dtn-adm";
}
revision 2016-04-01 {
description
"Updated to fix typos.";
reference
"draft-bsipos-dtn-amp-yang";
}
revision 2016-03-14 {
description
"Initial draft release.";
reference
"draft-bsipos-dtn-amp-yang";
}
/****
* This section contains extension for AMM object definitions
****/
// This group of extensions are for common behavior for AMM objects
extension enum {
argument value;
description
"An enumeration identifies an object within a namespace.
The argument to this statement is the integer value.";
}
extension parameter {
argument name;
description
"The schema for a formal parameter of an object.
Order of parameters is significant within this statement.";
}
extension default {
argument value;
description
"The literal value default for a parameter or result.
The argument is the text form of the ARI";
}
extension init-value {
argument value;
description
"The literal value of a CONST object,
initial state for a VAR object.
The argument is the text form of the ARI";
}
extension init-expr {
argument expr;
description
"An expression evaluated to initialize a VAR object.
The argument is the text form of the EXPR AC";
}
// This group are AMM object keywords and their parameters
extension typedef {
argument name;
description
"Definition of a TYPEDEF within an ADM.
The argument to this statement is the object name.
One of the type use substatements must be present.";
}
extension ident {
argument name;
description
"Definition of an IDENT within an ADM.
The argument to this statement is the object name.
An 'base' substatement must be present.";
}
extension base {
argument name;
description
"The argument is the base of an IDENT object.";
}
extension const {
argument name;
description
"Definition of a CONST within an ADM.
The argument to this statement is the object name.
An 'init-value' substatement must be present.";
}
extension ctrl {
argument name;
description
"Definition of a CTRL within an ADM.
The argument to this statement is the object name.";
}
extension result {
argument name;
description
"A result value reported as a response to a control.
The substatement is the result type.
Each CTRL can have a single optional result.";
}
extension edd {
argument name;
description
"Definition of an EDD within an ADM.
The argument to this statement is the object name.";
}
extension oper {
argument name;
description
"Definition of an OPER within an ADM.
The argument to this statement is the object name.";
}
extension operand {
argument name;
description
"An individual operand taken from the expression stack
during evaluation of the OPER.
Each substatement is an operand as a leaf (ARI).
Order of operands is significant within an object definition.";
}
extension var {
argument name;
description
"Definition of a VAR within an ADM.
The argument to this statement is the object name.";
}
/****
* This section contains ARI (literal and object-reference) value types.
****/
extension type {
argument name;
description
"A reference to a built-in type or prefix-qualified typedef.";
}
extension int-labels {
description
"Type narrowing for an INTEGER to label enum values or bit positions.";
}
extension cddl {
argument text;
description
"Type narrowing for a CBOR item in the form of CDDL syntax.
The argument to this statement is the actual CDDL text.";
}
extension ulist {
description
"Type for an AC containing a list of uniform-typed values.";
}
extension dlist {
description
"Type for an AC containing a list of diverse-typed sequences.";
}
extension seq {
description
"A sequence of uniform-typed values within a 'dlist'.";
}
extension umap {
description
"Type for an AM containing a set of uniform-typed key-value pairs.";
}
extension keys {
description
"The type restriction for 'umap' keys.";
}
extension values {
description
"The type restriction for 'umap' values.";
}
extension tblt {
description
"Type for a table of values with a column schema.";
}
extension column {
argument name;
description
"Type for a table of values with a column schema.";
}
extension key {
argument columns;
description
"Names of columns composing the row key.";
}
extension unique {
argument columns;
description
"Names of columns composing a uniqueness constraint.";
}
extension union {
description
"Type for a union of other types.";
}
// Named type unions for literals
amm:typedef TYPE-REF {
amm:union {
amm:type ARITYPE;
amm:type TYPEDEF;
}
description
"Reference to either a literal type or a typedef.";
}
amm:typedef INTEGER {
amm:union {
amm:type BYTE;
amm:type UINT;
amm:type INT;
amm:type UVAST;
amm:type VAST;
}
description
"Any type which represents a discrete integer.";
}
amm:typedef FLOAT {
amm:union {
amm:type REAL32;
amm:type REAL64;
}
description
"Any type which represents a floating point number.";
}
amm:typedef NUMERIC {
amm:union {
amm:type INTEGER;
amm:type FLOAT;
}
description
"Any type which can be used with numeric expressions.";
}
amm:typedef TIME {
amm:union {
amm:type TP;
amm:type TD;
}
description
"Any type which can be used with time expressions.";
}
amm:typedef SIMPLE {
amm:union {
amm:type NULL;
amm:type BOOL;
amm:type NUMERIC;
amm:type TEXTSTR;
amm:type BYTESTR;
amm:type TIME;
amm:type LABEL;
amm:type CBOR;
}
description
"Any type which contains a single literal value (not complex).";
}
amm:typedef COMPLEX {
amm:union {
amm:type AC;
amm:type AM;
}
description
"A literal type which is not SIMPLE.";
}
amm:typedef ANY {
// These type names are built-in
amm:union {
amm:type LITERAL;
amm:type OBJECT;
}
description
"Any value representable by an ARI.";
}
amm:typedef VALUE-OBJ {
amm:union {
amm:type CONST;
amm:type EDD;
amm:type VAR;
}
description
"A reference to an object which can produce a value.";
}
// operational semantic types
amm:typedef counter32 {
amm:type UINT;
description
"A 32-bit counter with an arbitrary initial value that only increments.
When the value reaches the upper range it wraps around to zero.
At least two samples of this value need to be compared over time.";
}
amm:typedef counter64 {
amm:type UVAST;
description
"A 64-bit counter with an arbitrary initial value that only increments.
When the value reaches the upper range it wraps around to zero.
At least two samples of this value need to be compared over time.";
}
amm:typedef gauge32 {
amm:type INT;
description
"A 32-bit value sampling some quantized measurement.
The value can increase or decrease arbitrarily over time.";
}
amm:typedef gauge64 {
amm:type VAST;
description
"A 64-bit value sampling some quantized measurement.
The value can increase or decrease arbitrarily over time.";
}
amm:typedef timestamp {
amm:type TP;
description
"A time point representing the system clock at which a specific
occurrence happened.
The specific occurrence must be defined in the description
of any node defined using this type.";
}
// Restrictions on AC item types for specific purposes
amm:typedef eval-tgt {
amm:union {
amm:type SIMPLE; // special case of literal value result
amm:type VALUE-OBJ; // produces an eval-tgt
amm:type EXPR;
}
description
"A value which can be the target of an evaluation.";
}
amm:typedef EXPR-item {
amm:union {
amm:type SIMPLE;
amm:type VALUE-OBJ; // produces an eval-tgt
amm:type TYPE-REF; // treated as unary operator
amm:type OPER;
}
description
"Each item of an EXPR list.";
}
amm:typedef EXPR {
amm:ulist {
amm:type EXPR-item;
}
description
"The contents of an EXPR container.";
}
amm:typedef exec-tgt {
amm:union {
amm:type exec-item;
amm:type MAC;
}
description
"A value which can be the target of an execution.";
}
amm:typedef exec-item {
amm:union {
amm:type CTRL;
amm:type VALUE-OBJ; // produces an exec-tgt
}
description
"A reference to an object which can be executed.
The value-object must be typed to contain an exec-tgt.";
}
amm:typedef MAC {
amm:ulist {
amm:type EXEC-item;
}
description
"The contents of a MAC container are an ordered list of
executable values.";
}
amm:typedef RPTT-item {
amm:union {
amm:type VALUE-OBJ;
amm:type EXPR;
}
description
"Each item of a RPTT.
Each item references a value-producing object or contains an
expression to be evaluated.";
}
amm:typedef RPTT {
amm:ulist {
amm:type RPTT-item;
}
description
"The contents of a report template, encoded as the sequence of items.";
}
}
<CODE ENDS>¶
The following is the ADM module implementing the entities described in Section 4.3:¶
<CODE BEGINS> file "ietf-dtnma-agent.yang"
module ietf-dtnma-agent {
yang-version 1.1;
namespace "ari:/ietf-dtnma-agent/";
prefix da;
amm:enum 1;
import ietf-amm {
prefix amm;
}
organization
"IETF Delay Tolerant Networking (DTN) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/dtn/>
WG List: <mailto:dtn@ietf.org>
Editor: Brian Sipos
<mailto:brian.sipos+ietf@gmail.com>";
description
"This module implements the DTN Management Architecture (DTNMA)
Agent core functionality.";
reference
"draft-birrane-dtn-adm";
revision 2023-06-08 {
description
"Updated for latest AMM contents.";
reference
"draft-birrane-dtn-adm";
}
feature rules {
description
"Conforming to this feature enables time-based and
state-based autonomy rules.";
}
amm:edd sw_vendor {
amm:type TEXTSTR;
description
"The vendor for this Agent implementation.";
}
amm:edd sw_version {
amm:type TEXTSTR;
description
"The version for this Agent implementation.";
}
amm:edd capability {
amm:tblt {
amm:key "adm_name";
amm:column adm_name {
amm:type TEXTSTR;
description
"The module name of the ADM";
}
amm:column enum {
amm:type VAST;
description
"The module enumeration of the ADM";
}
amm:column revision {
amm:type TEXTSTR;
description
"The specific revision the agent supports.";
}
amm:column features {
amm:ulist {
amm:type TEXTSTR;
}
description
"The features of the ADM which the agent supports.";
}
}
description
"A table to indicate the ADM capability of the sending agent.";
}
amm:const hello {
amm:enum 0;
amm:type amm:RPTT;
amm:init-value "/AC/(./EDD/sw_vendor,./EDD/sw_version,./EDD/capability)";
description
"A report template to indicate the presence of an agent
on a network.";
}
// Agent internal counters and states
amm:edd num_msg_rx {
amm:type amm:counter64;
}
amm:edd num_msg_rx_failed {
amm:type amm:counter64;
}
amm:edd num_msg_tx {
amm:type amm:counter64;
}
amm:edd num_exec_started {
amm:type amm:counter64;
}
amm:edd num_exec_succeeded {
amm:type amm:counter64;
}
amm:edd num_exec_failed {
amm:type amm:counter64;
}
amm:edd exec_running {
amm:tblt {
amm:key "pid";
amm:column pid {
amm:type UVAST;
}
amm:column target {
amm:type amm:ANY;
}
amm:column state {
amm:type byte {
enum waiting { value 0; }
enum running { value 1; }
}
}
}
}
// MAC helper controls
amm:ctrl if_then_else {
amm:parameter condition {
amm:type amm:EXPR;
description
"The condition to evaluate.";
}
amm:parameter on_truthy {
amm:type amm:EXEC-item;
description
"The object to execute when the condition is truthy.";
}
amm:parameter on_falsy {
amm:union {
amm:type amm:EXEC-item;
amm:type NULL;
}
amm:default "null";
description
"An optional execution when the condition is falsey.";
}
amm:result branch {
amm:type BOOL;
description
"Indication of which branch was executed.";
}
description
"Evaluate an expression and follow one of two branches of
further evaluation.";
}
amm:ctrl catch {
amm:parameter try {
amm:type amm:EXEC-item;
description
"The object to execute.";
}
amm:parameter on_failure {
amm:union {
amm:type amm:EXEC-item;
amm:type NULL;
}
amm:default "null";
description
"An optional execution after failure.";
}
description
"Attempt to execute an object, and if there is some failure catch it
and execute an alternative object.";
}
amm:ctrl inspect {
amm:parameter ref {
amm:type amm:VALUE-OBJ;
description
"An object to produce a value from.";
}
amm:result val {
amm:type amm:ANY;
description
"The produced value.";
}
description
"Produce a result value to inspect the agent state.
This does not perform any EXPR evaluation or RPTT handling.";
}
amm:ctrl report_on {
amm:parameter rptt {
amm:type amm:RPTT;
}
description
"Generate a report on an object without needing to define an object.
The parameter is a single RPTT list that would be produced by an object.
If used for more than one-shot diagnostics, defining a RPTT
(e.g. in a VAR) is more efficient because the RPTT item would not
be present in the report.";
}
grouping obj-list-params {
amm:parameter include_adm {
amm:type BOOL;
amm:default "false";
description
"If true, listings will include objects from ADMs";
}
description
"Common parameters for object listing";
}
amm:typedef hellotyp {
amm:union {
amm:type BYTE;
amm:type UINT;
}
}
amm:edd typedef_list {
uses obj-list-params;
amm:tblt {
amm:key "obj";
amm:column obj {
amm:type TYPEDEF;
}
}
description
"A table of TYPEDEF within the agent.";
}
// Objects related to VAR handling
amm:edd var_list {
uses obj-list-params;
amm:tblt {
amm:key "obj";
amm:column obj {
amm:type VAR;
}
amm:column type {
amm:type amm:TYPE-REF;
}
}
description
"A table of VAR within the agent.";
}
amm:ctrl var_present {
amm:parameter obj {
amm:type VAR;
description
"A reference to a VAR within an ODM only.";
}
amm:parameter type {
amm:type amm:TYPE-REF;
description
"The type for the VAR object.";
}
amm:parameter init {
amm:union {
amm:type NULL;
amm:type amm:EXPR;
}
amm:default "null";
description
"An optional initializer expression.";
}
description
"Ensure a specific VAR is present.";
}
amm:ctrl var_absent {
amm:parameter obj {
amm:type VAR;
description
"A reference to a VAR within an ODM only.";
}
description
"Ensure a specific VAR is not present.";
}
// Objects related to SBR handling
amm:edd sbr_list {
if-feature "rules";
amm:tblt {
amm:key "obj";
amm:column obj {
amm:type SBR;
}
amm:column action {
amm:type amm:MAC;
description
"The execution when this rule triggers.";
}
amm:column start_time {
amm:type amm:TIME;
}
amm:column condition {
amm:type amm:EXPR;
}
amm:column min_interval {
amm:type TD;
}
amm:column max_count {
amm:type UVAST;
}
}
}
amm:edd tbr_list {
if-feature "rules";
amm:tblt {
amm:key "obj";
amm:column obj {
amm:type TBR;
}
amm:column action {
amm:type amm:MAC;
description
"The execution when this rule triggers.";
}
amm:column start_time {
amm:type amm:TIME;
}
amm:column period {
amm:type TD;
}
amm:column max_count {
amm:type UVAST;
}
}
}
grouping numeric-unary-operands {
amm:operand val {
amm:type amm:NUMERIC;
description
"The single value.";
}
description
"Numeric unary operand";
}
grouping numeric-binary-operands {
amm:operand left {
amm:type amm:NUMERIC;
description
"The left-side operand.";
}
amm:operand right {
amm:type amm:NUMERIC;
description
"The left-side operand.";
}
description
"Numeric bianry operands";
}
grouping numeric-unary-result {
amm:result val {
amm:type amm:NUMERIC;
description
"The single value.";
}
description
"Numeric result";
}
grouping integer-unary-operands {
amm:operand val {
amm:type amm:INTEGER;
description
"The single value.";
}
description
"Integer unary operand";
}
grouping integer-binary-operands {
amm:operand left {
amm:type amm:INTEGER;
description
"The left-side operand.";
}
amm:operand right {
amm:type amm:INTEGER;
description
"The left-side operand.";
}
description
"Integer bianry operands";
}
grouping integer-unary-result {
amm:result val {
amm:type amm:INTEGER;
description
"The single value.";
}
description
"Integer result";
}
grouping bool-unary-operands {
amm:operand val {
amm:type BOOL;
description
"The single value.";
}
description
"Boolean unary operand";
}
grouping bool-binary-operands {
amm:operand left {
amm:type BOOL;
description
"The left-side operand.";
}
amm:operand right {
amm:type BOOL;
description
"The left-side operand.";
}
description
"Boolean bianry operands";
}
grouping bool-unary-result {
amm:result val {
amm:type BOOL;
description
"The single value.";
}
description
"Boolean result";
}
amm:oper negate {
uses numeric-unary-operands;
uses numeric-unary-result;
description
"Negate a value.
This is equivalent to multiplying by -1 but a shorter
expression.";
}
amm:oper add {
uses numeric-binary-operands;
uses numeric-unary-result;
description
"Add two numeric values.
The operands are cast to the least compatible numeric type
before the arithmetic.";
}
amm:oper sub {
uses numeric-binary-operands;
uses numeric-unary-result;
}
amm:oper multiply {
uses numeric-binary-operands;
uses numeric-unary-result;
}
amm:oper divide {
uses numeric-binary-operands;
uses numeric-unary-result;
}
amm:oper bit_not {
uses integer-unary-operands;
uses integer-unary-result;
}
amm:oper bit_and {
uses integer-binary-operands;
uses integer-unary-result;
}
amm:oper bit_or {
uses integer-binary-operands;
uses integer-unary-result;
}
amm:oper bit_xor {
uses integer-binary-operands;
uses integer-unary-result;
}
amm:oper bool_not {
uses bool-binary-operands;
uses bool-unary-result;
}
amm:oper bool_and {
uses bool-binary-operands;
uses bool-unary-result;
}
amm:oper bool_or {
uses bool-binary-operands;
uses bool-unary-result;
}
amm:oper bool_xor {
uses bool-binary-operands;
uses bool-unary-result;
}
amm:oper compare_eq {
uses numeric-binary-operands;
uses bool-unary-result;
}
amm:oper compare_ne {
uses numeric-binary-operands;
uses bool-unary-result;
}
amm:oper compare_gt {
uses numeric-binary-operands;
uses bool-unary-result;
}
amm:oper compare_ge {
uses numeric-binary-operands;
uses bool-unary-result;
}
amm:oper compare_lt {
uses numeric-binary-operands;
uses bool-unary-result;
description
"Compare two operands by value.
The result is true if the left value is less than the right.
The operands are cast to the least compatible numeric type
before the comparison.";
}
amm:oper compare_le {
uses numeric-binary-operands;
uses bool-unary-result;
description
"Compare two operands by value.
The result is true if the left value is less than or
equal to the right.
The operands are cast to the least compatible numeric type
before the comparison.";
}
}
<CODE ENDS>¶
This section presents an overview of fine-grained application security using Access Control Lists (ACLs).¶
Access Control shall be a function of the Agent. A table of entries associating permission tags with groups of objects shall be queried at runtime to ensure privileged access, while simultaneously allowing efficient implementation on an embedded device.¶
The concepts presented are in agreement with the Network Configuration Access Control Model (NACM) documented in [RFC8341].¶
Permissions are defined using an Access Control Tag (AT). Each AT is a bit mask corresponding to a series of flags. For example three bits would be required for read, write, and execute permissions. Tags are similar in principle to file permissions on Unix, which tracks flags for Read/Write/Execute.¶
An AT could be stored in a CBOR unsigned integer. For example 0x800C would be a valid tag for an AT with four access controls of four bits each.¶
Groups provide a general-purpose configuration to map an AT to a set of objects.¶
An annotative name may be associated with a group, and a numeric group ID is used for for cross-referencing.¶
The ACL ADM listed in Appendix C.5 provides capabilities to view and modify groups.¶
The following entities within an Agent may retain group associations:¶
A CTRL is provided to allow an object's group to be re-assigned. If a group is deleted all permissions associated with the group shall also be deleted, and objects previously belonging to the group shall inherit the default permissions.¶
Access control permissions shall be assigned using the combination of a Group, ARI Pattern (defined in [I-D.birrane-dtn-ari]), and Access Control Tag. At runtime the Agent shall retain a table of these tuples to store all necessary permissions. The table shall be queried by the Agent to find the corresponding AT for each managed object. If an object does not have an AT in the table then the default AT shall be used.¶
The Agent shall use the Group corresponding to the appropriate execution context when querying for permissions. For more information see Appendix C.2.3.¶
An object's ARI shall be used by the Agent when querying the table. An important consideration is that an ARI contains a namespace-id and object-id, both of which may be expressed in either a text or numeric form. When looking up permissions the Agent must use the ARI of the object itself - which can match all four possible forms - and NOT limit lookup to a particular ARI used by the Manager to reference an object.¶
If the Agent discovers multiple tuples that correspond to an object, the AT with least permission should be applied to the object. For example, if three tuples would allow an operation and the fourth would not, the Agent should deny permission.¶
Permissions shall be loaded during agent initialization and may be changed by an operator with sufficient permission. The default access level shall deny all operations.¶
An agent implementation should provide a way to audit assignment of permissions.¶
Each execution context shall be associated with a group. For direct execution the group is expected to correspond to the Manager that caused the execution to occur. For delayed execution such as a TBR the execution context shall refer to the group of the applicable object. When creating reports the ability to produce the report and send to a Manager is driven by permissions of the group of the Manager receiving the report.¶
TBD There may be cases where an object is initialized as protected but assigned to a variable that is not protected, allowing another Manager a means of working around access controls. In this early version of the document we do not protect against actions of a malicious Agent, or a privileged manager abusing its privileges. An Agent shall prevent an unprivileged Manager from abusing permissions to perform an unprivileged action.¶
Access control shall be enforced in the following way for processing activities described in Section 6.¶
When a variable is dereferenced the Agent shall look up the AT associated with the object. This is similar to other name-based access control systems such as AppArmor in Linux.¶
Read permission shall be required for an object to be passed as a parameter.¶
Execute permission shall be required for the object producing a value, executing, or being evaluated. There is one exception: if an OBJ-REF produces itself then Read permission is required.¶
Write permission is required for any object that could be modified by an operation. Note that result storage is ephemeral and parameters are passed by value, so any modifications to a VAR would be made by a limited number of special CTRLs in the agent ADM such as store_var.¶
Read permission is required if the OBJ-REF is a single value that will be reported directly.¶
Execute permission is required if the OBJ-REF is a RPTT that will be used to generate a RPT.¶
Manager roles are implementation-specific and do not need to be specified in the ADM. However the likely manger roles are Trusted (all permissions) and Read-Only.¶
The following is the ADM module implementing the functionality described in Appendix C:¶
<CODE BEGINS> file "ietf-amm.yang"
module "ietf-dtnma-agent-acl" {
yang-version 1.1;
namespace "ari:/ietf-dtnma-agent-acl";
prefix "acl";
amm:enum 0;
import "ietf-amm" {
prefix "amm";
}
organization
"IETF Delay Tolerant Networking (DTN) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/dtn/>
WG List: <mailto:dtn@ietf.org>
Editor: Brian Sipos
<mailto:brian.sipos+ietf@gmail.com>";
description
"This module implements the DTN Management Architecture (DTNMA)
Agent Access Control List (ACL) functionality.";
reference
"draft-birrane-dtn-adm";
revision 2023-12-12 {
description
"Initial version for latest AMM document";
reference
"draft-birrane-dtn-adm";
}
amm:typedef tag {
amm:type amm:permissions;
description "Datatype for access control list tags";
}
amm:typedef permissions {
amm:type amm:BYTE {
amm:int-labels {
bit tag-read {position 0; description "Permission bit for Read";}
bit tag-write {position 1; description "Permission bit for Write";}
bit tag-execute {position 2; description "Permission bit for Execute/Evaluate";}
bit tag-reserved {position 3; description "Reserved for future use";}
}
}
}
amm:typedef result {
amm:type amm:INT {
amm:int-labels {
enum success {value 0; description "Call was successful";}
enum error-generic {value 1; description "Generic call failure";}
enum error-permission-denied {value 2; description "Caller does not have permission";}
}
}
}
amm:ctrl set-default-access-tag {
amm:enum 1;
amm:parameter tag {
amm:type tag;
amm:default 0;
description "Tag value to set";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Set default ACL tag to use if no permissions are found for an object.";
}
amm:ctrl set-default-group-access-tag {
amm:enum 2;
amm:parameter tag {
amm:type tag;
amm:default 0;
description "Tag value to set";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Set default ACL tag to use if no permissions found for a group.
This shall take precedence over the default object permissions";
}
amm:ctrl upsert-permission {
amm:enum 3;
amm:parameter group {
amm:type amm:NUMERIC;
description "Identify the group being assigned the permission";
}
amm:parameter object-pattern {
amm:type amm:TEXTSTR;
description "ARI pattern to determine which objects shall be assigned the permission";
}
amm:parameter tag {
amm:type tag;
amm:default 0;
description "Permission tag value to set";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Ensures that an access control permission is set for the given group and ARI pattern.";
}
amm:ctrl discard-permission {
amm:enum 4;
amm:parameter group {
amm:type amm:NUMERIC;
description "Identify the group";
}
amm:parameter object-pattern {
amm:type amm:TEXTSTR;
description "ARI pattern";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Discard any permissions for the given group and ARI pattern.";
}
// TODO: view-permissions(group)
//
// Group Controls
//
amm:ctrl upsert-group {
amm:enum 5;
amm:parameter id {
amm:type amm:NUMERIC;
description "Uniquely identify the group";
}
amm:parameter name {
amm:type amm:TEXTSTR;
amm:default "";
description "Name of the group";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Ensure that after the control completes a group exists with the given information";
}
amm:ctrl discard-group {
amm:enum 6;
amm:parameter group {
amm:type amm:NUMERIC;
description "Identify the group";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Discard any group with the given information";
}
amm:ctrl current-group-id {
amm:enum 7;
amm:result group-id {
amm:type amm:NUMERIC;
description "The group ID, or 0 if none";
}
description "Get the group ID for the current execution context.";
}
// TODO: view-group
// TODO: view-groups
// TODO: Provide a TBL for groups??
//
// Object/Group Controls
//
amm:ctrl set-object-group {
amm:enum 8;
amm:parameter object {
amm:type amm:OBJ-REF;
description "Identify the object";
}
amm:parameter group {
amm:type amm:NUMERIC;
description "Identify the group";
}
amm:result error-code{
amm:type result;
description "If non-zero, an indicator of an error.";
}
description "Assigns the given group to the object";
}
amm:ctrl get-object-group {
amm:enum 9;
amm:parameter object {
amm:type amm:OBJ-REF;
description "Identify the object";
}
amm:result group-id {
amm:type amm:NUMERIC;
description "The group ID, or 0 if none";
}
description "Discard any group with the given information";
}
}
<CODE ENDS>¶
For the sake of adhering to the proper syntax for ARIs, all of the example reports are timestamped at 2023-01-01T00:00:00Z.¶
ari:/dtnma-agent/CTRL/report_on(/example-adm/EDD/intvalue)¶
Executing that results in a report containing the following:¶
( /example-adm/EDD/intvalue, /TP/20230101T000000Z, /INT/10 )¶
If the produced value has a semantic type which is ambiguous within the EDD type, the report would instead contain:¶
( /example-adm/EDD/intvalue, /TP/20230101T000000Z, /example-adm/TYPEDEF/mycounter(/INT/10) )¶
For a similar CONST that contains an RPTT value, the report would contain:¶
( ../EDD/intvalue, ../EDD/boolvalue )¶
( /example-adm/CONST/report1, /TP/20230101T000000Z, /INT/10, /true )¶
The following participants contributed technical material, use cases, and useful thoughts on the overall approach captured in this document: David Linko, Sarah Heiner, and Jenny Cao of the Johns Hopkins University Applied Physics Laboratory.¶