Delay-Tolerant Networking E. Birrane Internet-Draft Johns Hopkins Applied Physics Laboratory Intended status: Experimental June 29, 2016 Expires: December 31, 2016 Asynchronous Management Protocol Agent Application Data Model draft-birrane-dtn-adm-agent-02 Abstract This document describes an Application Data Model (ADM) for an Asynchronous Management Protocol (AMP) Agent. The AMP Agent represents a managed device in the Asynchronous Management Architecture. This ADM identifies the Externally Defined Data, Variables, Report Templates, Controls, Macros, Literals, Operators, and meta-data associated with an Agent. The information outlined in this document MUST be supported by any software claiming to act as a managed device within the AMP. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://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 December 31, 2016. Copyright Notice Copyright (c) 2016 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 (http://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 Birrane Expires December 31, 2016 [Page 1] Internet-Draft Agent ADM June 2016 include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Technical Notes . . . . . . . . . . . . . . . . . . . . . 3 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. OID Tree Identification . . . . . . . . . . . . . . . . . . . 3 2.1. Nicknames . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2. OID Shorthand . . . . . . . . . . . . . . . . . . . . . . 5 3. Metadata Definitions . . . . . . . . . . . . . . . . . . . . 5 4. Externally Defined Data . . . . . . . . . . . . . . . . . . . 6 5. Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Report Templates . . . . . . . . . . . . . . . . . . . . . . 8 7. Controls . . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.2. Control Specification . . . . . . . . . . . . . . . . . . 10 7.2.1. Overview . . . . . . . . . . . . . . . . . . . . . . 10 7.2.2. ADM Controls . . . . . . . . . . . . . . . . . . . . 11 7.2.3. Variable Controls . . . . . . . . . . . . . . . . . . 11 7.2.4. Report Controls . . . . . . . . . . . . . . . . . . . 15 7.2.5. Macro Controls . . . . . . . . . . . . . . . . . . . 21 7.2.6. TRL Controls . . . . . . . . . . . . . . . . . . . . 25 7.2.7. SRL Controls . . . . . . . . . . . . . . . . . . . . 28 8. Literals . . . . . . . . . . . . . . . . . . . . . . . . . . 32 8.1. Configurable Literals Description . . . . . . . . . . . . 32 9. Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 10. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 36 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 37 11.1. Parameterizing a Control . . . . . . . . . . . . . . . . 37 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 13.1. Informative References . . . . . . . . . . . . . . . . . 40 13.2. Normative References . . . . . . . . . . . . . . . . . . 40 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41 1. Introduction An Application Data Model (ADM) provides an interface for the management of an application or protocol over the Asynchronous Management Protocol [AMP] that is independent of the nuances of its software implementation. In this respect, the ADM is conceptually similar to the Managed Information Base (MIB) used by SNMP, but contains additional information relating to command opcodes and more expressive syntax for automated behavior. Birrane Expires December 31, 2016 [Page 2] Internet-Draft Agent ADM June 2016 1.1. Technical Notes o This document describes Version 0.3 of the Agent ADM. o The OID Root for this ADM is NOT correctly set. A sample OID Root is used in this version of the specification and MAY change in future versions of this ADM. o Currently, ADMs are organizing documents and not used to automatically generate software. Future versions of this ADM should include a specification in a data modeling language (such as YANG) to better enable software generation. o Agent applications MAY choose to ignore the name, description, or OID information associated with the component definitions within this ADM as these items are only used to provide human-readable information associated with user interfaces and may not be necessary on a deployed managed device. 1.2. Scope This ADM specifies the globally unique identifiers and descriptions for all items associated with an AMP Agent. Any implementation claiming compliance with an AMP Agent and communicating with an AMP Manager MUST be conformant with this specification. That is, it must collect or compute all identified data, perform identified Controls/ Operators, understand identified Literals/metadata, and generate Report Entries to defined Report Templates. 1.3. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 2. OID Tree Identification The Managed Identifiers (MIDs) used with this ADM encapsulate OIDs within a globally managed OID tree. The OID node from which all of the MIDs in this specification derive is called the "Agent ADM OID Root". This section identifies this root in the overall OID tree. Birrane Expires December 31, 2016 [Page 3] Internet-Draft Agent ADM June 2016 +--------------------+----------------------------------------------+ | Agent ADM OID ROOT | iso.identified-organization.dod.internet. | | STRING | mgmt.amp.agent | | | | | Agent ADM ROOT ID | 1.3.6.1.2.3.3 | | STRING | | | | | | Agent ADM ROOT OID | 2B 06 01 02 03 03 | | (octets) | | +--------------------+----------------------------------------------+ OID Tree Identification The subtree under the Agent ADM OID ROOT contains eight subbranches that capture metadata, EDDs, Variables, Report Templates, Controls, Literals, Macros, and Operators as illustrated in Figure 1. AGENT ADM ROOT (1.3.6.1.2.3.3) | | Meta- ED Vars Rpt | Data Data Def Tmpl | Ctrls Literals Macros Ops (.0) (.1) (.2) (.3) | (.4) (.5) (.6) (.7) +-------+---------+------+-----+---+------+----------+---------+ Figure 1: Agent ADM OID Subtree 2.1. Nicknames The nicknames defined by this ADM are given in Table 1. Birrane Expires December 31, 2016 [Page 4] Internet-Draft Agent ADM June 2016 +--------+----------------------------+-----------------------------+ | Unique | Label | OID as ASN.1 BER | | ID | | | +--------+----------------------------+-----------------------------+ | 0 | Agent Metadata | 0x2B060102030300 | | | | | | 1 | Agent Primitive Values | 0x2B060102030301 | | | | | | 2 | Agent Computed Values | 0x2B060102030302 | | | | | | 3 | Agent Reports | 0x2B060102030303 | | | | | | 4 | Agent Controls | 0x2B060102030304 | | | | | | 5 | Agent Literals | 0x2B060102030305 | | | | | | 6 | Agent Macros | 0x2B060102030306 | | | | | | 7 | Agent Operators | 0x2B060102030307 | | | | | | 8 | Agent Root | 0x2B0601020303 | +--------+----------------------------+-----------------------------+ Table 1: Agent ADM Nicknames 2.2. OID Shorthand The components in this specification are identified by their AMP MID value. However, for easier traceability back to the OIDs encapsulated in MIDs, an OID string is also provided for each component. These OID strings are provided in a shorthand that makes use of the nicknames defined in Table 1 and uses the form [nickname].relative-oid. For example, the OID String [4].3.2.1 corresponds to the OID 2B060102030304030201, with 2B060102030304 being the expansion of nickname 04 and 030201 being the relative OID. 3. Metadata Definitions ADM metadata consists of the items necessary to uniquely identify the ADM to Managers within the AMA. Birrane Expires December 31, 2016 [Page 5] Internet-Draft Agent ADM June 2016 +---------+------------+--------+------------------+------+---------+ | Item | MID (Hex) | OID | Description | Type | Value | | | | (Str) | | | | +---------+------------+--------+------------------+------+---------+ | Name | 0x80000100 | [0].0 | The human- | STR | AMP | | | | | readable ADM | | Agent | | | | | name. | | ADM | +---------+------------+--------+------------------+------+---------+ | Version | 0x80000101 | [0].1 | The ADM version. | STR | v0.2 | +---------+------------+--------+------------------+------+---------+ Table 2: AMP Agent Metadata 4. Externally Defined Data Externally Defined Data (EDD) definitions represent those values that MUST be collected by the AMP Agent. Changing or updating EDD definitions requires making changes to the AMP Agent application and/ or its supporting firmware. The EDDs exposed through this ADM as defined as follows. Birrane Expires December 31, 2016 [Page 6] Internet-Draft Agent ADM June 2016 +-----------+------------+-------+---------------------------+------+ | Name | MID | OID | Description | Type | +-----------+------------+-------+---------------------------+------+ | Num | 0x80010100 | [1].0 | # Reports known to the | UINT | | Reports | | | Agent. | | +-----------+------------+-------+---------------------------+------+ | Sent | 0x80010101 | [1].1 | # Reports sent by this | UINT | | Reports | | | Agent since last reset. | | +-----------+------------+-------+---------------------------+------+ | Num TRL | 0x80010102 | [1].2 | # Time-Based Rules (TRLs) | UINT | | | | | running on the Agent. | | +-----------+------------+-------+---------------------------+------+ | Run TRL | 0x80010103 | [1].3 | # Time-Based Rules (TRLs) | UINT | | | | | run by the Agent since | | | | | | last reset. | | +-----------+------------+-------+---------------------------+------+ | Num SRL | 0x80010104 | [1].4 | # State-Based Rules | UINT | | | | | (SRLs) running on the | | | | | | Agent. | | +-----------+------------+-------+---------------------------+------+ | Run SRL | 0x80010105 | [1].5 | # State-Based Rules | UINT | | | | | (SRLs) run by the Agent | | | | | | since last reset. | | +-----------+------------+-------+---------------------------+------+ | Num Lit | 0x80010106 | [1].6 | # Literal definitions | UINT | | | | | known to the Agent. | | +-----------+------------+-------+---------------------------+------+ | Num | 0x80010107 | [1].7 | # Variables known to the | UINT | | Variables | | | Agent. | | +-----------+------------+-------+---------------------------+------+ | Num | 0x80010108 | [1].8 | # Macro definitions | UINT | | Macros | | | configured on the Agent. | | +-----------+------------+-------+---------------------------+------+ | Run | 0x80010109 | [1].9 | # Macros run by the Agent | UINT | | Macros | | | since the last reset. | | +-----------+------------+-------+---------------------------+------+ | Num | 0x8001010A | [1].A | # Controls known by the | UINT | | Controls | | | Agent. | | +-----------+------------+-------+---------------------------+------+ | Run | 0x8001010B | [1].B | # Controls run by the | UINT | | Controls | | | Agent since the last | | | | | | reset. | | +-----------+------------+-------+---------------------------+------+ | Current | 0x8001010C | [1].C | Current time. | TS | | Time | | | | | +-----------+------------+-------+---------------------------+------+ Table 3: AMP Agent EDD Values Birrane Expires December 31, 2016 [Page 7] Internet-Draft Agent ADM June 2016 5. Variables Variable definitions are expressions used to calculate data values, on the fly, from a set of other Variable definitions, EDDs, or Literals using any of the Operators known to the Agent. The Variables defined by this ADM are as follows. +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Num | 0x81020100 | [2].0 | # Rules know to the Agent | UINT | | Rules | | | (# TRL + # SRL). | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x03 0x80010102 0x80010104 0x83070100 | +-------------------------------------------------------------------+ Table 4: AMP Agent Variables 6. Report Templates A Report Template (RPTT) is a listing of data items including EDD definitions, Variable definitions, and other Report Templates returned from an AMP Agent. The Report Templates defined by this ADM are as follows. +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Full | 0x82030100 | [3].0 | All known Meta-Data, | RPT | | Report | | | EDD, and VAR Values | | | | | | known by the Agent. | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x0F 0x80000100 0x80000101 0x80010100 0x80010101 0x80010102 | | 0x80010103 0x80010104 0x80010105 0x80010106 0x80010107 | | 0x80010108 0x80010109 0x8001010A 0x8001010B 0x81020100 | +-------------------------------------------------------------------+ Table 5: AMP Agent Report Templates Birrane Expires December 31, 2016 [Page 8] Internet-Draft Agent ADM June 2016 7. Controls Controls represent well-known command opcodes that can be run by the Agent in response to direct requests by an AMP Manager, or in response to time- or state-based rules on the Agent itself. Controls may be (and often are) parameterized. Parameters are captured as special extensions within the MID itself. In cases where a given control accepts parameters, the MID flag byte will note that the encapsulated OID represents a parameterized OID and the OID will be augmented with the parameters for a specific instance of the Control, as described in [AMP]. This section first summarizes and then describes in detail each Control defined by this ADM. 7.1. Summary The Controls known to an AMP Agent are listed in Table 6. +--------------+-------------+--------+------+----------------------+ | Name | MID | OID | # | Prms | | | | | Prms | | +--------------+-------------+--------+------+----------------------+ | ListADMs | 0x83040100 | [4].0 | 0 | | +--------------+-------------+--------+------+----------------------+ | AddVar | 0xC3040101 | [4].1 | 4 | MID Id, EXPR Def, | | | | | | BYTE Type, BYTE Flg | +--------------+-------------+--------+------+----------------------+ | DelVar | 0xC3040102 | [4].2 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListVars | 0x83040103 | [4].3 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescVars | 0xC3040104 | [4].4 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddRptTpl | 0xC3040105 | [4].5 | 2 | MID ID, MC Template | +--------------+-------------+--------+------+----------------------+ | DelRptTpl | 0xC3040106 | [4].6 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListRptTpls | 0x83040107 | [4].7 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescRptTpls | 0xC3040108 | [4].8 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | GenerateRpts | 0xC3040109 | [4].9 | 2 | MC IDs, DC RxMgrs | +--------------+-------------+--------+------+----------------------+ | AddMacro | 0xC304010A | [4].A | 3 | STR Name, MID ID, MC | | | | | | Def | +--------------+-------------+--------+------+----------------------+ Birrane Expires December 31, 2016 [Page 9] Internet-Draft Agent ADM June 2016 | DelMacro | 0xC304010B | [4].B | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListMacros | 0x8304010C | [4].C | 0 | | +--------------+-------------+--------+------+----------------------+ | DescMacros | 0xC304010D | [4].D | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddTRL | 0xC304010E | [4].E | 5 | MID ID, TS Start, | | | | | | SDNV Period, SDNV | | | | | | Cnt, MC Action | +--------------+-------------+--------+------+----------------------+ | DelTRL | 0xC304010F | [4].F | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListTRLs | 0x83040110 | [4].10 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescTRLs | 0xC3040111 | [4].11 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddSRL | 0xC30401012 | [4].12 | 5 | MID ID, TS Start, | | | | | | PRED State, SDNV | | | | | | Cnt, MC Action | +--------------+-------------+--------+------+----------------------+ | DelSRL | 0xC3040113 | [4].13 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListSRLs | 0x83040114 | [4].14 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescSRLs | 0xC3040115 | [4].15 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | StoreVar | 0xC3040116 | [4].16 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ResetCounts | 0x83040117 | [4].17 | 0 | | +--------------+-------------+--------+------+----------------------+ Table 6: AMP Agent Controls 7.2. Control Specification 7.2.1. Overview This section lists the description, parameters, and reports generated for each Control specified in this ADM. The "DESCRIPTION" section lists the functional requirements of the Control when run on an Agent. The "PARAMETERS" section illustrates and describes the ordered set of data items provided to the Control, when run on the Agent. The "REPORT ENTRIES GENERATED" section describes the format of any Report Entries sent from the Agent to a Manager as a result of Birrane Expires December 31, 2016 [Page 10] Internet-Draft Agent ADM June 2016 running the Control. The entry itself is modeled as a Typed Data Collection (TDC) in the AMP and this section will describe the type and number of Data Blobs that will be present in that TDC. This section ONLY describes Report Entries that are specific to the Control. Cases where policy requires Agents to send summary Report Entries when Controls either run or fail to run due to error, are not considered in this section as they are not specific to any one Control. Any Control summary Report Entries should be as described in [AMP]. Report Entries generated on an Agent by a Control will either be directly sent to the Manager executing the Control or otherwise batched and send with other report messages destined for the receiving Manager. This behavior will be based on the policy associated with the AMP Agent and is not specified in this ADM. 7.2.2. ADM Controls 7.2.2.1. ListADMs DESCRIPTION The ListADMs control causes the Agent to produce a Report Entry detailing the name of each ADM supported by the Agent. An Agent supports an ADM when the Agent claims full conformance with the components detailed in the ADM. PARAMETERS This control does not take any parameters. REPORT ENTRIES GENERATED This control will generate a RPTE capturing the list of ADMs supported by this Agent. Each Value in the entry will be of type STR and contain the name of a supported ADM. 7.2.3. Variable Controls 7.2.3.1. AddVar DESCRIPTION The AddVar Control configures a new Variable definition on the Agent. The generated variable should be read as Type ID = Eval(Initializer) Birrane Expires December 31, 2016 [Page 11] Internet-Draft Agent ADM June 2016 Upon successful receipt of the Variable definition, the Agent MUST store the definition and be able to calculate the value at some point in the future. This capability MUST exist even through a reset of the Agent application. NOTE: It MUST be considered an error if the Id associated with the new Variable definition is already defined on the Agent with a different associated definition or type. PARAMETERS This Control accepts 3 parameters used to identify and define the new Variable as illustrated in Figure 2. +--------+-------------+--------+ | Id | Initializer | Type | | [MID] | [EXPR] | [BYTE] | +--------+-------------+--------+ Figure 2: AddVar Parameters Where: Id The MID value identifying the new Variable definition. This value may appear in future Variable definitions, Report Template definitions, or Expressions. Initializer The Expression used to calculate the initial Variable value. Once this Expression is used to compute an initial value it may be disarded. Type The data type of the Variable. Note, this data type may be used to "cast" the value to something other than what is implied by the Expression. For example, the Type of a Variable may be set to INT even if the initializing Expression computes a floating-point value. The Type designation MUST be either EXPR or a numeric type. NOTE: If the Variable type is EXPR, then the initializer Expression itself MUST be copied as the value of the Variable and MUST NOT be evaluated to generate a value. AMP does not support Expressions whose evaluation result type is EXPR. REPORT ENTRIES GENERATED This Control generates no Report Entries. Birrane Expires December 31, 2016 [Page 12] Internet-Draft Agent ADM June 2016 7.2.3.2. DelVars DESCRIPTION The DelVars Control removes one or more Variable definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT store the definition of any identified Variables and MUST NOT recognize these Variables in the future, to include evaluating Expressions already in existence on the Agent. An Agent MUST NOT remove a Variable that is defined by a supported ADM. PARAMETERS This Control accepts 1 parameter used to identify the set of Variables to be removed as illustrated in Figure 3. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 3: DelVars Parameters Where: Ids To Remove = The list of Variable identifiers to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given Variable identifier is not found on the Agent. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.3.3. ListVars DESCRIPTION The ListVars Control produces a listing of every Variable identifier (MID) known to the Agent. A Variable is "known" by the Agent if it is defined in an ADM supported by the Agent, or was configured on the Agent by a run of the AddVar Control. PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the list of Variable identifiers supported by this Agent. The RPTE will contain the typed values illustrated in Figure 4. Birrane Expires December 31, 2016 [Page 13] Internet-Draft Agent ADM June 2016 +--------------------+ | Known Variable IDs | | [MC] | +--------------------+ Figure 4: ListVars Report Format Where: Known Variable IDs The list of Variable MIDs know by the Agent. 7.2.3.4. DescVars DESCRIPTION The DescVars Control produces a detailed description of every Variable identifier (MID) known to the Agent. A detailed description of a Variable is the set of information used to configure the Variable on the Agent. PARAMETERS This Control accepts 1 parameter used to identify the set of Variables to be described as illustrated in Figure 5. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 5: DescVars Parameters Where: Ids to Describe The list of Variable identifiers to be described by the Agent. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the description of each requested Variable as illustrated in Figure 6. Birrane Expires December 31, 2016 [Page 14] Internet-Draft Agent ADM June 2016 +-------+ | Entry | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # VARS | Types | VAR 1 |... | VAR N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ____________/ \____________ / \ +-------+--------+--------+ | ID | TYPE | Value | | [MID] | [BYTE] | [BLOB] | +-------+--------+--------+ Figure 6: DescVars Report Format Where: VARS The Typed Data Collection holding the set of Variables being described. ID N The MID for the Nth Variable. TYPE N The TYPE of the Nth Variable. Value N The serialized value of the Variable, based on its type. Note: this is NOT the initializing Expression for the Variable, as the itializing Expression MAY be forgotten by the Agent after it is finished initializing the Variable value. 7.2.4. Report Controls Birrane Expires December 31, 2016 [Page 15] Internet-Draft Agent ADM June 2016 7.2.4.1. AddRptTpl DESCRIPTION The AddRptTpl Control configures a new Report Template definition on the Agent. A Report Template definition assigns a single MID value to represent an ordered collection of other MID values. This ordered collection may include EDDs, Variables, and other Report Templates. Upon successful receipt of the Report Template definition, the Agent MUST store the definition and be able to produce Report Entries to this template at some point in the future. This capability MUST persist through a reset of the Agent application. NOTE: It MUST be considered an error if the Id associated with the new Report Template definition is already defined on the Agent with a different associated definition or type. It MUST NOT be considered an error if the Agent already has configured the exact same Report Template when this message is received. Put another way, this Control should be considered idempotent. PARAMETERS This Control accepts 2 parameters used to identify and define the new Report Template as illustrated in Figure 7. +--------+------------+ | Rpt Id | Definition | | [MID] | [MC] | +--------+------------+ Figure 7: AddRptDef Parameters Where: Rpt Id The MID value identifying the new Report Template definition. Definition The ordered collection of MID values to be included in a Report Entry generated to this template. When a Report Entry is generated by an Agent in conformance with this template, the values of each MID in this MC is included in the entry. However, the identifier for each item from the template is NOT included in the entry. REPORT ENTRIES GENERATED This Control generates no Report Entries. Birrane Expires December 31, 2016 [Page 16] Internet-Draft Agent ADM June 2016 7.2.4.2. DelRptTpls DESCRIPTION The DelRptTpls Control removes one or more Report Template definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT produce Report Entries for this template An Agent MUST NOT remove a Report Template that is defined by a supported ADM. PARAMETERS This Control accepts 1 parameter used to identify the set of Report Templates definitions to be removed as illustrated in Figure 8. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 8: DelRptTpls Parameters Where: Ids To Remove The list of Report Template identifiers to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given Report Template identifier is not found on the Agent. REPORT ENTRIES GENERATED This control generates no Report Entries. 7.2.4.3. ListRptTpls DESCRIPTION The ListRptTpls Control produces a listing of every Report Template identifier (MID) known to the Agent. PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the list of Report Template identifiers supported by this Agent. The RPTE will contain the typed values illustrated in Figure 9. Birrane Expires December 31, 2016 [Page 17] Internet-Draft Agent ADM June 2016 +---------------+ | Known Reports | | [MC] | +---------------+ Figure 9: ListRptTpls Report Format Where: Known Reports The list of Report Template MIDs known by the Agent. 7.2.4.4. DescRptTpls DESCRIPTION The DescRptTpls Control produces a detailed description of every Report Template identifier (MID) known to the Agent. PARAMETERS This Control accepts 1 parameter used to identify the set of Report Templates to be described as illustrated in Figure 10. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 10: DescRptTpls Parameters Where: Ids to Describe The list of Report Template identifiers to be described by the Agent. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the description of each requested Report Template known by the receiving Agent as illustrated in Figure 11. Birrane Expires December 31, 2016 [Page 18] Internet-Draft Agent ADM June 2016 +-------+ | Entry | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # Tpls | Types | Tpl 1 |... | Tpl N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || _________/ \_________ / \ +-------+------------+ | ID | Definition | | [MID] | [MC] | +-------+------------+ Figure 11: DescRptTpls Report Format Where: Tpl N The Nth Report Template being described. ID N The MID identifying the Nth Report Template. Definition N The MC identifying the Nth Report Template. 7.2.4.5. GenerateRpts DESCRIPTION The GenerateRpts Control causes the Agent to produce a Report Entry for each identified Report Templates and send them to one or more identified Managers. PARAMETERS This Control accepts 2 parameters used to identify the set of Report Entries to be generated as illustrated in Figure 12. Birrane Expires December 31, 2016 [Page 19] Internet-Draft Agent ADM June 2016 +---------------------+---------------------+ | Reports to Generate | Managers to Receive | | [MC] | [DC] | +---------------------+---------------------+ Figure 12: GenerateRpts Parameters Where: Reports to Generate The list of Report Templates that should have Report Entries generated for them by the Agent. Managers to Receive The list of URIs identifying the Managers that should receive the generated reports. Note: a DC of length 0 is allowed by this Control. When such a DC is provided, the generated Report Entries MUST be sent only to the Manager that sent the Control. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the description of each requested Report Template as known by the receiving Agent. The format for this Report Entry is illustrated in Figure 13. Birrane Expires December 31, 2016 [Page 20] Internet-Draft Agent ADM June 2016 +---------+ +---------+ | Entry 1 | | Entry N | | [RPTE] | ... | [RPTE] | +---------+ +---------+ || || _________/ \________ / \ +-------+--------+ | ID | Values | | [MID] | [TDC] | +-------+--------+ || || ___________________________/ \_______________________________ / \ +----------+-------------+---------+---------+ +---------+ | # Values | Value Types | Value 1 | Value 2 | | Value N | | [SDNV] | [BLOB] | [BLOB] | [BLOB] | ... | [BLOB] | +----------+-------------+---------+---------+ +---------+ Figure 13: GenerateRpts Report Entry Format Where: Entry N The Nth Report Entry generated by this Control. Each Report Entry consists of an MID ID and a TDC of values. 7.2.5. Macro Controls 7.2.5.1. AddMacroDef DESCRIPTION The AddMacroDef Control configures a new Macro definition on the Agent. A Macro definition assigns a single MID value to represent an ordered collection of Controls and/or other Macros to be run in sequence. Upon successful receipt of the Macro definition, the Agent MUST store the definition and be able to run this Macro at some point in the future. This capability MUST exist even through a reset of the Agent application. NOTE: It MUST be considered an error if the Id associated with the new Macro definition is already defined on the Agent with a different associated definition or type. It MUST NOT be considered an error if the Agent already has configured the Birrane Expires December 31, 2016 [Page 21] Internet-Draft Agent ADM June 2016 exact same Macro when this message is received. Put another way, this Control should be considered idempotent. PARAMETERS This Control accepts 3 parameters used to identify and define the new Macro as illustrated in Figure 14. +------------+----------+----------+ | Macro Name | Macro Id | Controls | | [STR] | [MID] | [MC] | +------------+----------+----------+ Figure 14: AddMacroDef Parameters Where: Macro Name The human-readable name of the Macro. Agents MAY choose to ignore this value. Macro Id The MID value identifying the new Macro definition. Controls The ordered collection of Controls and/or other Macros to be run when the Macro is run. The Controls that define the Macro must include parameters in their MID identification when added to the Macro. This ADM provides no capability to add parameters to the Controls of a Macro after the Macro has been defined. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.5.2. DelMacroDefs DESCRIPTION The DelMacroDefs Control removes one or more Macro definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT run the removed Macros and MUST NOT recognize these Macros in the future, to include rule actions requesting that the removed Macros be run. PARAMETERS This Control accepts 1 parameter used to identify the set of Macro definitions to be removed as illustrated in Figure 15. Birrane Expires December 31, 2016 [Page 22] Internet-Draft Agent ADM June 2016 +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 15: DelMacroDefs Parameters Where: Ids To Remove The list of Macros to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given Macro identifier is not found on the Agent. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.5.3. ListMacroDefs DESCRIPTION The ListMacroDefs Control produces a listing of every Macro identifier (MID) known to the Agent. PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This control will generate a Report Entry capturing the list of Macro identifiers supported by this Agent. The RPTE will contain the typed values illustrated in Figure 16. +--------------+ | Known Macros | | [MC] | +--------------+ Figure 16: ListMacroDefs Report Entry Format Where: Known Macros The list of Macro MIDs known by the Agent. 7.2.5.4. DescMacroDefs DESCRIPTION The DescMacroDefs Control produces a detailed description of every Macro identifier (MID) known to the Agent. Birrane Expires December 31, 2016 [Page 23] Internet-Draft Agent ADM June 2016 PARAMETERS This Control accepts 1 parameter used to identify the set of Macros to be described as illustrated in Figure 17. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 17: DescMacroDefs Parameters Where: Ids to Describe The list of Macro identifiers to be described by the Agent. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the description of each requested Macro as known by the receiving Agent. The format for this entry is illustrated in Figure 18. +-------+ | Entry | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+------------+ +------------+ | # Defs | Types | MacroDef 1 |...| MacroDef N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+------------+ +------------+ || || ________/ \__________ / \ +-------+------------+ | ID | Definition | | [MID] | [MC] | +-------+------------+ Figure 18: DescMacroDefs Report Format Where: Defs Birrane Expires December 31, 2016 [Page 24] Internet-Draft Agent ADM June 2016 The Typed Data Collection holding the set of Macros being described. Each Data Blob in the TDC will hold an element of type MACRO. 7.2.6. TRL Controls 7.2.6.1. AddTimeRule DESCRIPTION The AddTimeRule Control configures a new Time-Based Rule (TRL) definition on the Agent. A TRL instructs the Agent to run an action (a collection of Controls and/or Macros) over time, and to stop after so many runs of the action. Upon successful receipt of the TRL definition, the Agent MUST store the definition and be able to run this TRL at some point in the future. This capability MUST exist even through a reset of the Agent. Additionally, through a reset, the Agent must remember the number of runs of the action, even if the periodic evaluation of the rule is offset by the time taken by the reset. NOTE: It MUST be considered an error if the Id associated with the new TRL definition is already defined on the Agent. PARAMETERS This Control accepts 5 parameters used to identify and define the new TRL as illustrated in Figure 19. +-------+-------+------------+--------+--------+ | Id | Start | Period (s) | Count | Action | | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | +-------+-------+------------+--------+--------+ Figure 19: AddTimeRule Parameters Where: Id The MID used to identify this TRL. Start The time at which the TRL should start to be evaluated. This timestamp may represent either a relative or absolute time. Period The interval, measured in seconds, between runs of the action. Birrane Expires December 31, 2016 [Page 25] Internet-Draft Agent ADM June 2016 Count The number of times to run the action associated with the TRL, after which the TRL should be removed from the Agent. The special value of 0 indicates that the rule should be run indefinitely until it is removed by a DelTimeRules Control. Action The collection of Controls or Macros to be run periodically by the TRL. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.6.2. DelTimeRules DESCRIPTION The DelTimeRules Control removes one or more TRL definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT run the removed TRLs and MUST NOT recognize these TRLs in the future. PARAMETERS This Control accepts 1 parameter used to identify the set of TRL definitions to be removed as illustrated in Figure 20. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 20: DelTimeRules Parameters Where: Ids To Remove The list of TRLs to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given TRL identifier is not found on the Agent. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.6.3. ListTimeRules DESCRIPTION The ListTimeRules Control produces a listing of every TRL identifier (MID) known to the Agent. Birrane Expires December 31, 2016 [Page 26] Internet-Draft Agent ADM June 2016 PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the list of TRL MIDs supported by this Agent. The RPTE will contain the typed values illustrated in Figure 21. +------------+ | Known TRLs | | [MC] | +------------+ Figure 21: ListTimeRules Report Entry Format Where: Known TRLs The list of TRL MIDs known by the Agent. 7.2.6.4. DescTimeRules DESCRIPTION The DescTimeRules Control produces a detailed description of every TRL identifier (MID) known to the Agent. PARAMETERS This Control accepts 1 parameter used to identify the set of TRLs to be described as illustrated in Figure 22. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 22: DescTimeRules Parameters Where: Ids to Describe The list of TRL identifiers to be described by the Agent. REPORT ENTRIES GENERATED This control will generate a Report Entry capturing the description of each requested TRL as known by the receiving Agent. The format for this Report Entry is illustrated in Figure 23. Birrane Expires December 31, 2016 [Page 27] Internet-Draft Agent ADM June 2016 +-------+ | Entry | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # TRLs | Types | TRL 1 |... | TRL N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ___________________/ \_____________________ / \ +-------+-------+--------+--------+--------+ | ID | Start | Period | Count | Action | | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | +-------+-------+--------+--------+--------+ Figure 23: DescTimeRules Report Entry Format 7.2.7. SRL Controls 7.2.7.1. AddStateRule DESCRIPTION The AddStateRule Control configures a new State-Based Rule (SRL) definition on the Agent. A SRL instructs the Agent to run some action when a given Predicate evaluates to true, and to stop after so many runs of an action. The Agent MUST evaluate the SRL Predicate every second. Upon successful receipt of the SRL definition, the Agent MUST store the definition and be able to run this SRL at some point in the future. This capability MUST exist even through a reset of the Agent application. Additionally, through a reset, the Agent must remember the number of runs of the action. NOTE: It MUST be considered an error if the Id associated with the new SRL definition is already defined on the Agent. PARAMETERS This Control accepts 5 parameters used to identify and define the new SRL as illustrated in Figure 24. Birrane Expires December 31, 2016 [Page 28] Internet-Draft Agent ADM June 2016 +-------+-------+--------+--------+--------+ | ID | START | COND | COUNT | ACTION | | [MID] | [TS] | [PRED] | [SDNV] | [MC] | +-------+-------+--------+--------+--------+ Figure 24: AddStateRule Parameters Where: Id The MID used to identify this SRL. Start The time at which the SRL should start to be evaluated. This timestamp may represent either a relative or absolute timestamp. Condition The Predicate that MUST evaluate to true in order to run the action associated with this SRL. Count The number of times to evaluate the Predicate associated with the SRL, after which the SRL should be removed from the Agent. The special value of 0 indicates that the SRL should be evaluated indefinitely until it is removed by a DelStateRules Control. Action The collection of Controls and Macros to be run when the SRL Predicate evaluates to true. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.7.2. DelStateRules DESCRIPTION The DelStateRules Control removes one or more SRL definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT run the removed SRLs and MUST NOT recognize these SRLs in the future. PARAMETERS This Control accepts 1 parameter used to identify the set of SRL definitions to be removed as illustrated in Figure 25. Birrane Expires December 31, 2016 [Page 29] Internet-Draft Agent ADM June 2016 +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 25: DelStateRules Parameters Where: Ids To Remove The list of SRLs to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given SRL identifier is not found on the Agent. REPORT ENTRIES GENERATED This Control generates no Report Entries. 7.2.7.3. ListStateRules DESCRIPTION The ListStateRules Control produces a listing of every SRL identifier (MID) known to the Agent. PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This Control will generate a Report Entry capturing the list of SRL MIDs supported by this Agent. The RPTE will contain the typed values illustrated in Figure 26. +------------+ | Known SRLs | | [MC] | +------------+ Figure 26: ListStateRules Report Entry Format Where: Known SRLs = The list of SRL MIDs known by the Agent. 7.2.7.4. DescStateRules DESCRIPTION The DescStateRules Control produces a detailed description of every SRL identifier (MID) known to the Agent. Birrane Expires December 31, 2016 [Page 30] Internet-Draft Agent ADM June 2016 PARAMETERS This Control accepts 1 parameter used to identify the set of SRLs to be described as illustrated in Figure 27. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 27: DescStateRules Parameters Where: Ids to Describe The list of SRL identifiers to be described by the Agent. REPORT ENTRIES GENERATED This Control will generate a Report capturing the description of each requested SRL as known by the receiving Agent. The format for this Report Entry is illustrated in Figure 28. +-------+ | Entry | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # SRLs | Types | SRL 1 |... | SRL N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || __________________/ \____________________ / \ +-------+-------+--------+--------+-------+ | ID | START | COND | COUNT | ACT | | [MID] | [TS] | [PRED] | [SDNV] | [MC] | +-------+-------+--------+--------+-------+ Figure 28: DescStateRules Report Entry Format Birrane Expires December 31, 2016 [Page 31] Internet-Draft Agent ADM June 2016 7.2.8. ResetCounts DESCRIPTION The ResetCounts Control resets all Agent ADM statistics reported in the Agent ADM report. This reset sets all counters back to 0 and sets the "Last Reset Time" to the time when this control was run. PARAMETERS This Control takes no parameters. REPORT ENTRIES GENERATED This Control generates no Report Entries. 8. Literals This section describes the set of Literals available to all AMP Agents. Applications and protocols in other ADMs do not need to redefine these Literals, as they may be used in any expressions evaluated by any Agent. +------------+-----------+-------+------------+--------+------------+ | Name | MID (Hex) | OID | Value | Type | Params | +------------+-----------+-------+------------+--------+------------+ | AMP Epoch | 87050100 | [5].0 | 1347148800 | UINT | None | +------------+-----------+-------+------------+--------+------------+ | User VAST | C7050101 | [5].1 | Varies | INT | VAST Value | +------------+-----------+-------+------------+--------+------------+ | User UVAST | C7050102 | [5].2 | Varies | UINT | SDNV Value | +------------+-----------+-------+------------+--------+------------+ | User Float | C7050103 | [5].3 | Varies | REAL32 | BLOB Value | +------------+-----------+-------+------------+--------+------------+ | User | C7050104 | [5].4 | Varies | REAL64 | BLOB Value | | Double | | | | | | +------------+-----------+-------+------------+--------+------------+ | User | C7050105 | [5].5 | Varies | STR | STR Value | | String | | | | | | +------------+-----------+-------+------------+--------+------------+ | User BLOB | C7050106 | [5].6 | Varies | BLOB | BLOB Value | +------------+-----------+-------+------------+--------+------------+ Table 7: AMP Agent Literals 8.1. Configurable Literals Description Birrane Expires December 31, 2016 [Page 32] Internet-Draft Agent ADM June 2016 8.1.1. User VAST DESCRIPTION The User VAST Literal is configured to specify a specific signed Vast (64-bit Integer). PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 29. +--------+ | Value | | [VAST] | +--------+ Figure 29: Operator User VAST Parameters Where: Value The VAST being identified by this Literal. 8.1.2. User UVAST DESCRIPTION The User VAST Literal is configured to specify a specific unsigned Vast (64-bit Integer). PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 30. +--------+ | Value | | [SDNV] | +--------+ Figure 30: Operator User UVAST Parameters Where: Value The UVAST, encoded as an SDNV, being identified by this Literal. 8.1.3. User Float DESCRIPTION Birrane Expires December 31, 2016 [Page 33] Internet-Draft Agent ADM June 2016 The User Float Literal is configured to specify a specific 32-bit, Single Precision Floating Point Value stored in IEEE-754 format. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 31. +--------+ | Value | | [BLOB] | +--------+ Figure 31: Operator User Float Parameters Where: Value The 32-bit floating point value in IEEE-754 format, serialized in network byte order. 8.1.4. User Double DESCRIPTION The User Double Literal is configuredto specify a specific 64-bit, Double Precision Floating Point Value stored in IEEE-754 format. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 32. +--------+ | Value | | [BLOB] | +--------+ Figure 32: Operator User Double Parameters Where: Value The 64-bit floating point value in IEEE-754 format, serialized in network byte order. 8.1.5. User String DESCRIPTION The User String Literal is configured to specify a specific NULL-terminated character string. Birrane Expires December 31, 2016 [Page 34] Internet-Draft Agent ADM June 2016 PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 33. +-------+ | Value | | [STR] | +-------+ Figure 33: Operator User String Parameters Where: Value The NULL-terminated string represented by this Literal. 8.1.6. User BLOB DESCRIPTION The User BLOB Literal is configured to specify a specific sized array of BYTES. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 34. +--------+ | Value | | [BLOB] | +--------+ Figure 34: Operator User BLOB Parameters Where: Value The sized byte-array of the BLOB represented by this Literal. 9. Macros Macro definitions are ordered collections of Controls that can be sequentially run. Each Control in a Macro MUST either be a non- parameterized Control, or a parameterized Control with parameters specified. There is no capability to add parameters to a Control after it has been encapsulated in a Macro. The Controls that define a Macro item are represented by a MID Collection (MC). Birrane Expires December 31, 2016 [Page 35] Internet-Draft Agent ADM June 2016 +----------+------------+-------+-----------------------------+ | Name | MID | OID | Description | +----------+------------+-------+-----------------------------+ | User | 0xC6060100 | [6].0 | List all user-defined data | | List | | | | +----------+------------+-------+-----------------------------+ | Definition | +-------------------------------------------------------------+ | 0x04 0x83040103 0x83040107 0x8304010C 0x83040110 0x83040114 | +-------------------------------------------------------------+ Table 8: AMP Agent Macro Definitions 10. Operators This section describes the set of Operators available to all AMP Agents. Applications and protocols in other ADMs do not need to redefine these operators, as they may be used in any expressions evaluated by any Agent. +------+------------+--------+--------------------------+-----------+ | Name | MID | OID | Description | # | | | | | | Operands | +------+------------+--------+--------------------------+-----------+ | + | 0x88070100 | [7].0 | Addition | 2 | +------+------------+--------+--------------------------+-----------+ | - | 0x88070101 | [7].1 | Subtraction | 2 | +------+------------+--------+--------------------------+-----------+ | * | 0x88070102 | [7].2 | Multiplication | 2 | +------+------------+--------+--------------------------+-----------+ | / | 0x88070103 | [7].3 | Division | 2 | +------+------------+--------+--------------------------+-----------+ | % | 0x88070104 | [7].4 | Modulo | 2 | +------+------------+--------+--------------------------+-----------+ | ^ | 0x88070105 | [7].5 | Exponentiation | 2 | +------+------------+--------+--------------------------+-----------+ | & | 0x88070106 | [7].6 | Bitwise AND | 2 | +------+------------+--------+--------------------------+-----------+ | | | 0x88070107 | [7].7 | Bitwise OR | 2 | +------+------------+--------+--------------------------+-----------+ | # | 0x88070108 | [7].8 | Bitwise XOR | 2 | +------+------------+--------+--------------------------+-----------+ | ~ | 0x88070109 | [7].9 | Bitwise NOT | 1 | +------+------------+--------+--------------------------+-----------+ | && | 0x8807010A | [7].A | Logical AND | 2 | +------+------------+--------+--------------------------+-----------+ | || | 0x8807010B | [7].B | Logical OR | 2 | +------+------------+--------+--------------------------+-----------+ Birrane Expires December 31, 2016 [Page 36] Internet-Draft Agent ADM June 2016 | ! | 0x8807010C | [7].C | Logical NOT | 1 | +------+------------+--------+--------------------------+-----------+ | abs | 0x8807010D | [7].D | Absolute Value | 1 | +------+------------+--------+--------------------------+-----------+ | < | 0x8807010E | [7].E | Less than | 2 | +------+------------+--------+--------------------------+-----------+ | > | 0x8807010F | [7].F | Greater than | 2 | +------+------------+--------+--------------------------+-----------+ | <= | 0x88070110 | [7].10 | Less than or equal to | 2 | +------+------------+--------+--------------------------+-----------+ | >= | 0x88070111 | [7].11 | Greater than or equal to | 2 | +------+------------+--------+--------------------------+-----------+ | != | 0x88070112 | [7].12 | Not equal | 2 | +------+------------+--------+--------------------------+-----------+ | == | 0x88070113 | [7].13 | Equal to | 2 | +------+------------+--------+--------------------------+-----------+ | << | 0x88070114 | [7].14 | Bitwise Left Shift | 2 | +------+------------+--------+--------------------------+-----------+ | >> | 0x88070115 | [7].15 | Bitwise Right Shift | 2 | +------+------------+--------+--------------------------+-----------+ | STOR | 0x88070116 | [7].16 | Store value of Parm 2 in | 2 | | | | | Parm 1 | | +------+------------+--------+--------------------------+-----------+ Table 9: AMP Agent Atomic Data 11. Examples This section describes several examples of working with MIDs within the AMP using examples from this ADM. 11.1. Parameterizing a Control This section uses the example of the "Add Variable Definition" Control, which takes three parameters and can be summarized by the following pseudo-code notation: AddVar(MID new_id, EXPR init, BYTE type) Where "new_id" is the MID of the newly created Variable definition, "init" is the Expression that is used to compute the initial value, and "type" is the enumeration of the resultant type of the Variable. An example set of parameters for this Control are as follows. Birrane Expires December 31, 2016 [Page 37] Internet-Draft Agent ADM June 2016 +-----------+------+--------------+---------------------------------+ | Parameter | Type | Value | Description | +-----------+------+--------------+---------------------------------+ | new_id | MID | 0x9101040102 | A compressed-OID MID with an | | | | | issuer field - all user-defined | | | | | MIDs in the AMP are required to | | | | | have an issuer field. | +-----------+------+--------------+---------------------------------+ | def | EXPR | 0x03 | The expression (# TRL) + (# | | | | 0x80010102 | SRL) in postfix. | | | | 0x80010104 | | | | | 0x88070100 | | +-----------+------+--------------+---------------------------------+ | type | BYTE | 0x0B | UINT | +-----------+------+--------------+---------------------------------+ Given these parameters, the Control to add this particular Variable to a receiving Agent is as follows. Birrane Expires December 31, 2016 [Page 38] Internet-Draft Agent ADM June 2016 AddVar Control Parameterization Example +--------+--------+--------+--------+ | Flags | Issuer | OID | Tag | | [BYTE] | [SDNV] |[VARIED]| [SDNV] | <=== MID | | (opt) | | (opt) | Definition +--------+--------+--------+--------+ || ____________________/ \________________ / \ +----------+--------------+------------+ | Nickname | Relative OID | Parameters | <=== Compressed, | [SDNV] | [BLOB] | [TDC] | Parameterized OID +----------+--------------+------------+ Definition || ________________________/ \_________ / \ +----------+--------+ +--------+ | # Params | Parm 1 | | Parm N | <=== Parameter DC | [SDNV] | [BLOB] | ... | [BLOB] | Definition +----------+--------+ +--------+ || __________________/ \______________ / \ +--------+---------+ +---------+ Single ===> | Length | Octet 1 | ... | Octet N | Parameter | [SDNV] | [BYTE] | | [BYTE] | +--------+---------+ +---------+ Figure 35: Parameterized OID Format Given this format, the overall MID for the AddVar Control is as follows. MID Nick- Flag Name OID BLOB Parameters +-----+------+-------------+------------------------------+ | | | Len Octets | | | | +----+--------+ 04031416090591010401020D0380 | | | C3 | 04 | 01 | 02 | 0101028001010488070100010B | +-----+------+-------------+------------------------------+ The Parameters TDC can be further broken out as follows. Birrane Expires December 31, 2016 [Page 39] Internet-Draft Agent ADM June 2016 (3 Parms) (MID,EXPR,BYTE) (MID ID) # BLOBS Type Blob Parm 1 BLOB +----------+----------------+-----------------+ | SDNV | Len Octets | Len Octets | |----------+-----+----------+----+------------+ ... | 04 | 03 | 141609 | 05 | 9101040102 | +----------+-----+----------+----+------------+ (EXPR Initializer) (BYTE Type) Parm 2 BLOB Parm 3 BLOB +-----------------------------------------------+ | Len Octets | Len Octets | +----+----------------------------+-----+-------+ | 0D | 03800101028001010488070100 | 01 | 0B | +---------------------------------+-----+-------+ 12. IANA Considerations At this time, this protocol has no fields registered by IANA. This ADM does define a root OID which will require a formal allocation. This ADM does define a series of nicknames which also will require a formal allocation. 13. References 13.1. Informative References [AMA] Birrane, E., "Asynchronous Management Architecture", draft-birrane-dtn-ama-00 (work in progress), August 2015. [I-D.irtf-dtnrg-dtnmp] Birrane, E. and V. Ramachandran, "Delay Tolerant Network Management Protocol", draft-irtf-dtnrg-dtnmp-01 (work in progress), December 2014. 13.2. Normative References [AMP] Birrane, E., "Asynchronous Management Protocol", draft- birrane-dtn-amp-00 (work in progress), August 2015. Birrane Expires December 31, 2016 [Page 40] Internet-Draft Agent ADM June 2016 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Author's Address Edward J. Birrane Johns Hopkins Applied Physics Laboratory Email: Edward.Birrane@jhuapl.edu Birrane Expires December 31, 2016 [Page 41]