Delay-Tolerant Networking E. Birrane Internet-Draft Johns Hopkins Applied Physics Laboratory Intended status: Experimental August 20, 2015 Expires: February 21, 2016 Asynchronous Management Protocol Agent Application Data Model draft-birrane-dtn-adm-agent-00 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 Primitive Values, Computed values, Reports, 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 February 21, 2016. Copyright Notice Copyright (c) 2015 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 February 21, 2016 [Page 1] Internet-Draft Agent ADM August 2015 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. Primitive Values . . . . . . . . . . . . . . . . . . . . . . 6 5. Computed Values . . . . . . . . . . . . . . . . . . . . . . . 8 6. Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. Controls . . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.2. Control Specification . . . . . . . . . . . . . . . . . . 11 7.2.1. Overview . . . . . . . . . . . . . . . . . . . . . . 11 7.2.2. ADM Controls . . . . . . . . . . . . . . . . . . . . 11 7.2.3. Computed Value Controls . . . . . . . . . . . . . . . 12 7.2.4. Report Controls . . . . . . . . . . . . . . . . . . . 17 7.2.5. Macro Controls . . . . . . . . . . . . . . . . . . . 22 7.2.6. TRL Controls . . . . . . . . . . . . . . . . . . . . 27 7.2.7. SRL Controls . . . . . . . . . . . . . . . . . . . . 31 8. Literals . . . . . . . . . . . . . . . . . . . . . . . . . . 35 8.1. Configurable Literals Description . . . . . . . . . . . . 35 9. Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 10. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 39 11. Parameterization Examples . . . . . . . . . . . . . . . . . . 40 11.1. AddCompVal Definition . . . . . . . . . . . . . . . . . 40 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 13.1. Informative References . . . . . . . . . . . . . . . . . 43 13.2. Normative References . . . . . . . . . . . . . . . . . . 43 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 43 1. Introduction An Application Data Model (ADM) provides a guaranteed 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 February 21, 2016 [Page 2] Internet-Draft Agent ADM August 2015 Agents within the Asynchronous Management Architecture [AMA] represent applications running on managed devices that are responsible for implementing the AMA services of configuration, reporting, control, and administration. 1.1. Technical Notes o This document describes Version 0.1 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 Values, Controls, Literals, and Operators 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 compute all identified data, perform identified controls/operators, and understand identified literals/ metadata. 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 February 21, 2016 [Page 3] Internet-Draft Agent ADM August 2015 NOTE: This version of the Agent ADM uses a proxy Agent ADM Root that has NOT been assigned. The Agent ADM Root in this version of the document is only used for experimental purposes and MAY change before the final release of this specification. +--------------------+----------------------------------------------+ | 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, Primitive Values, Computed Values, Reports, Controls, Literals, Macros, and Operators as illustrated in Figure 1. AGENT ADM ROOT (1.3.6.1.2.3.3) | | Meta- Primitive Computed | Data Data Data Rpts | Ctrls Literals Macros Ops (.0) (.1) (.2) (.3) | (.4) (.5) (.6) (.7) +-------+---------+------+---------+------+----------+---------+ Figure 1: Agent ADM OID Subtree 2.1. Nicknames The following managed nicknames are provided to generate compressed OIDs within the AMP. Compressed OIDs enable shortening of common subtrees into a single numerical identifier to avoid the significant repetition incumbent with using OIDs from a common subtree. The nicknames defined by this ADM are given in Table 1. Birrane Expires February 21, 2016 [Page 4] Internet-Draft Agent ADM August 2015 +--------+----------------------------+-----------------------------+ | 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. This includes items such as the name of the ADM, its version, and any nicknames used within the ADM. Birrane Expires February 21, 2016 [Page 5] Internet-Draft Agent ADM August 2015 +---------+------------+--------+------------------+------+---------+ | Name | MID (Hex) | OID | Description | Type | Value | | | | (Str) | | | | +---------+------------+--------+------------------+------+---------+ | Label | 0x80000100 | [0].0 | The human- | STR | AMP | | | | | readable ADM | | Agent | | | | | name. | | ADM | +---------+------------+--------+------------------+------+---------+ | Version | 0x80000101 | [0].1 | The ADM version. | STR | v0.1 | +---------+------------+--------+------------------+------+---------+ Table 2: AMP Agent Metadata 4. Primitive Values Primitive Value definitions represent those values that MUST be collected by the AMP Agent. Changing or updating Primitive Value definitions requires making changes to the AMP Agent application and/ or its supporting firmware. Birrane Expires February 21, 2016 [Page 6] Internet-Draft Agent ADM August 2015 +----------+------------+-------+----------------------------+------+ | 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 (SRLs) | UINT | | | | | running on the Agent. | | +----------+------------+-------+----------------------------+------+ | Run SRL | 0x80010105 | [1].5 | # State-Based Rules (SRLs) | UINT | | | | | run by the Agent since | | | | | | last reset. | | +----------+------------+-------+----------------------------+------+ | Num Lit | 0x80010106 | [1].6 | # Literal definitions | UINT | | | | | known to the Agent. | | +----------+------------+-------+----------------------------+------+ | Num | 0x80010107 | [1].7 | # Computed Values known to | UINT | | Computed | | | the 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. | | +----------+------------+-------+----------------------------+------+ Table 3: AMP Agent Primitive Values Birrane Expires February 21, 2016 [Page 7] Internet-Draft Agent ADM August 2015 5. Computed Values Computed Value definitions are expressions used to calculate data values, on the fly, from a set of other Computed Value definitions, Primitive Value definitions, or Literals using any of the Operations known to the Agent. The expressions that define a Computed Value item are represented by MID Collections (MCs), which are ordered listings of the MIDs representing the expression arranged in postfix notation. For example, the expression "# TRL Rules Defined" + "# SRL Rules Defined" would be represented as follows: Original Expression : NUM_TRL + NUM_SRL Postfix Expression : NUM_TRL NUM_SRL + Convert to MIDs : 0x80010102 0x80010104 0x83070100 Resultant MC : 0x03 80010102 80010104 83070100 +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Num | 0x84020100 | [2].0 | # Rules know to the Agent | UINT | | Rules | | | (# TRL + # SRL). | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x03 0x80010102 0x80010104 0x83070100 | +-------------------------------------------------------------------+ Table 4: AMP Agent Computed Values 6. Reports A Report is a listing of data items including Primitive Value definitions, Computed Value definitions, and other Reports returned from an AMP Agent. Similar to Computed Values, Report definitions are captured as a MID Collection (MC), which is the ordered set of MIDs identifying individual data items that comprise the report. Birrane Expires February 21, 2016 [Page 8] Internet-Draft Agent ADM August 2015 +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Full | 0x88030100 | [3].0 | All known Meta-Data, | RPT | | Report | | | Primitive, and Computed | | | | | | Values on the Agent. | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x0F 0x80000100 0x80000101 0x80010100 0x80010101 0x80010102 | | 0x80010103 0x80010104 0x80010105 0x80010106 0x80010107 | | 0x80010108 0x80010109 0x8001010A 0x8001010B 0x84020100 | +-------------------------------------------------------------------+ Table 5: AMP Agent Reports 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. Note: There is no concept of a user-defined Control in the AMP system. All Controls are well-documented in ADMs with specific definitions of their behavior. 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]. 7.1. Summary The Controls known to an AMP Agent are listed in Table 6. +--------------+-------------+--------+------+----------------------+ | Name | MID | OID | # | Prms | | | | | Prms | | +--------------+-------------+--------+------+----------------------+ | ListADMs | 0x81040100 | [4].0 | 0 | | +--------------+-------------+--------+------+----------------------+ | AddCompVal | 0xC1040102 | [4].2 | 3 | MID Id, EXPR | | | | | | Definition, BYTE | | | | | | Type | +--------------+-------------+--------+------+----------------------+ | DelCompVals | 0xC1040103 | [4].3 | 1 | MC IDs | Birrane Expires February 21, 2016 [Page 9] Internet-Draft Agent ADM August 2015 +--------------+-------------+--------+------+----------------------+ | ListCompVals | 0x81040104 | [4].4 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescCompVals | 0xC1040105 | [4].5 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddRptDef | 0xC1040106 | [4].6 | 2 | MID ID, MC RptDef | +--------------+-------------+--------+------+----------------------+ | DelRptDef | 0xC1040107 | [4].7 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListRptDefs | 0x81040108 | [4].8 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescRptDefs | 0xC1040109 | [4].9 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | GenerateRpts | 0xC104010A | [4].A | 2 | MC IDs, DC RxMgrs | +--------------+-------------+--------+------+----------------------+ | AddMacro | 0xC104010B | [4].B | 3 | STR Name, MID ID, MC | | | | | | Def | +--------------+-------------+--------+------+----------------------+ | DelMacro | 0xC104010C | [4].C | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListMacros | 0x8104010D | [4].D | 0 | | +--------------+-------------+--------+------+----------------------+ | DescMacros | 0xC104010E | [4].E | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddTRL | 0xC104010F | [4].F | 5 | MID ID, TS Start, | | | | | | SDNV Period, SDNV | | | | | | Count, MC Action | +--------------+-------------+--------+------+----------------------+ | DelTRL | 0xC1040110 | [4].10 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListTRLs | 0x81040111 | [4].11 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescTRLs | 0xC1040112 | [4].12 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | AddSRL | 0xC10401013 | [4].13 | 5 | MID ID, TS Start, | | | | | | PRED State, SDNV | | | | | | COunt, MC Action | +--------------+-------------+--------+------+----------------------+ | DelSRL | 0xC1040114 | [4].14 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ | ListSRLs | 0x81040115 | [4].15 | 0 | | +--------------+-------------+--------+------+----------------------+ | DescSRLs | 0xC1040116 | [4].16 | 1 | MC IDs | +--------------+-------------+--------+------+----------------------+ Table 6: AMP Agent Controls Birrane Expires February 21, 2016 [Page 10] Internet-Draft Agent ADM August 2015 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. A parameterized Control is represented in the AMP by a MID encapsulating a parameterized OID. OID parameters are captured as a Data Collection (DC). The DC capturing these parameters is elided for clarity, as the DC is only the container used to transmit the parameters between the Agent and Manager and not expected as input to the Control itself. The "REPORTS GENERATED" section describes the format of any Reports sent from the Agent to a Manager as a result of running the Control. This section ONLY describes Reports that are specific to the Control. Cases where policy requires Agents to send summary Reports 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 reports should be as described in [AMP]. Reports 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 Reports 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 detailing the name of each ADM supported by the Agent. When an ADM is listed in this Report, it means that the Agent claims full conformance with the components detailed in the listed ADM. PARAMETERS This control does not take any parameters. REPORTS GENERATED Birrane Expires February 21, 2016 [Page 11] Internet-Draft Agent ADM August 2015 This control will generated a Report capturing the list of ADMs supported by this Agent. The format for this Report is illustrated in Figure 2. +--------+------------+ +------------+ | # ADMs | ADM 1 Name | ... | ADM N Name | | [SDNV] | [STR] | | [STR] | +--------+------------+ +------------+ Figure 2: ListADMs Report Format Where: # ADMs The number of ADMs known to the agent. ADM N Name The human-readable string associated with the Nth ADM, captured as a NULL-terminated string. 7.2.3. Computed Value Controls 7.2.3.1. AddCompVal DESCRIPTION The AddCompVal Control configures a new Computed Value definition on the Agent. The generated value should be read as Type ID = Def Upon successful receipt of the Computed Value 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 Computed Value 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 Computed Value 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 Computed Value. The parameters for this control are illustrated in Figure 3. Birrane Expires February 21, 2016 [Page 12] Internet-Draft Agent ADM August 2015 +--------+------------+--------+ | Id | Definition | Type | | [MID] | [EXPR] | [BYTE] | +--------+------------+--------+ Figure 3: AddCompVal Parameters Where: Id = The MID value identifying the new Computed Value definition. This value may appear in future Computed Value definitions, Report definitions, or Expressions. Definition = The Expression used to calculate this Computed Value. Type = The data type of the Computed Value. 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 Computed Value may be set to INT even if the defining Expression contains all floating-point values. The Type designation MUST be a numeric type, as the defining Expression is a set of mathematical functions on numeric types. REPORTS GENERATED This Control generates no Reports. 7.2.3.2. DelCompVals DESCRIPTION The DelCompVals Control removes one or more Computed Value definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT store the definition of any identified Computed Values and MUST NOT recognize these Computed Values in the future, to include evaluating Expressions already in existence on the Agent. An Agent MUST NOT remove a Computed Value that is defined by a supported ADM. PARAMETERS This Control accepts 1 parameter used to identify the set of Computed Values to be removed. The parameters for this control are illustrated in Figure 4. Birrane Expires February 21, 2016 [Page 13] Internet-Draft Agent ADM August 2015 +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 4: DelCompVals Parameters Where: Ids To Remove = The list of Computed Value identifiers to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given Computed Value identifier is not found on the Agent. REPORTS GENERATED This Control generates no Reports. 7.2.3.3. ListCompVals DESCRIPTION The ListCompVals Control produces a listing of every Computed Value identifier (MID) known to the Agent. A Computed Value 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 AddCompVal Control. PARAMETERS This Control takes no parameters. REPORTS GENERATED This Control will generate a Report capturing the list of Computed Value identifiers supported by this Agent. The Report will be included in the next "Data Report" message sent by the Agent to the querying Manager. The format for this Report is illustrated in Figure 5. +-----------------------+ | Known Computed Values | | [MC] | +-----------------------+ Figure 5: ListCompVals Report Format Where: Known Computed Values = The list of Computed Value MIDs know by the Agent. Birrane Expires February 21, 2016 [Page 14] Internet-Draft Agent ADM August 2015 7.2.3.4. DescCompVals DESCRIPTION The DescCompVals Control produces a detailed description of every Computed Value identifier (MID) known to the Agent. a detailed description of a Computed Value is the set of information used to configure the Computed Value on the Agent. PARAMETERS This Control accepts 1 parameter used to identify the set of Computed Values to be described. The parameters for this control are illustrated in Figure 6. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 6: DescCompVals Parameters Where: Ids to Describe= The list of Computed Value identifiers to be described by the Agent. REPORTS GENERATED This control will generate a Report capturing the description of each requested Computed Value as known by the receiving Agent. The format for this Report is illustrated in Figure 7. Birrane Expires February 21, 2016 [Page 15] Internet-Draft Agent ADM August 2015 +-------+ | Defs | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # Defs | Types | Def 1 |... | Def N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ____________/ \_______________ / \ +-------+--------+------------+ | ID | TYPE | Definition | | [MID] | [BYTE] | [EXPR] | +-------+--------+------------+ Figure 7: DescCompVals Report Format Where: Defs = The Typed Data Collection holding the set of Computed Values being described, as a series of type DEF. The TDC structure is comprised of the # Defs, Types, and DEF structures, as discussed below. # Defs = The number of Computed Value definitions included in this TDC. Types = The set of BYTE values identifying the types of the items in the TDC. For this Control, each entry will be of type DEF. Def N = The DEF structure (serialized into a BLOB, describing the Nth Computed Value definition. Each DEF structure is comprised of the ID, TYPE, and Definition of the Computed Value. Birrane Expires February 21, 2016 [Page 16] Internet-Draft Agent ADM August 2015 7.2.4. Report Controls 7.2.4.1. AddRptDef DESCRIPTION The AddRptDef Control configures a new Report definition on the Agent. A Report definition assigns a single MID value to represent an ordered collection of other MID values. This ordered collection may include Primitive Values, Computed Values, and other Reports. Upon successful receipt of the Report definition, the Agent MUST store the definition and be able to produce this Report 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 Report 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 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. The parameters for this control are illustrated in Figure 8. +--------+------------+ | Rpt Id | Definition | | [MID] | [MC] | +--------+------------+ Figure 8: AddRptDef Parameters Where: Rpt Id = The MID value identifying the new Report definition. Definition = The ordered collection of MID values to be included in the Report when it is generated. When this Report is generated by an Agent, the values of each MID in this MC is included in the report. However, the identifier for each item is NOT included in the Report. REPORTS GENERATED This Control generates no Reports. Birrane Expires February 21, 2016 [Page 17] Internet-Draft Agent ADM August 2015 7.2.4.2. DelRptDefs DESCRIPTION The DelRptDefs Control removes one or more Report definitions from the Agent. Upon successful receipt and run of this Control, the Agent MUST NOT produce the removed Reports and MUST NOT recognize these Reports in the future, to include rule actions requesting that the removed Reports be generated. An Agent MUST NOT remove a Report that is defined by a supported ADM. PARAMETERS This Control accepts 1 parameter used to identify the set of Report definitions to be removed. The parameters for this control are illustrated in Figure 9. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 9: DelRptDefs Parameters Where: Ids = The list of Report identifiers to be removed from the Agent. NOTE: It MUST NOT be considered an error if a given Report identifier is not found on the Agent. REPORTS GENERATED This control generates no Reports. 7.2.4.3. ListRptDefs DESCRIPTION The ListRptDefs Control produces a listing of every Report identifier (MID) known to the Agent. PARAMETERS This Control takes no parameters. REPORTS GENERATED This Control will generate a Report capturing the list of Report identifiers supported by this Agent. The Report will be included in the next "Data Report" message sent by the Agent to the querying Manager. The format for this Report is illustrated in Figure 10. Birrane Expires February 21, 2016 [Page 18] Internet-Draft Agent ADM August 2015 +---------------+ | Known Reports | | [MC] | +---------------+ Figure 10: ListRptDefs Report Format Where: Known Reports = The list of Report MIDs known by the Agent. 7.2.4.4. DescRptDefs DESCRIPTION The DescRptDefs Control produces a detailed description of every Report identifier (MID) known to the Agent. PARAMETERS This Control accepts 1 parameter used to identify the set of Reports to be described. The parameters for this control are illustrated in Figure 11. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 11: DescRptDefs Parameters Where: Ids to Describe = The list of Report identifiers to be described by the Agent. REPORTS GENERATED This control will generate a Report capturing the description of each requested Report as known by the receiving Agent. The format for this Report is illustrated in Figure 12. Birrane Expires February 21, 2016 [Page 19] Internet-Draft Agent ADM August 2015 +-------+ | Defs | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # Defs | Types | Def 1 |... | Def N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ____________/ \_______________ / \ +-------+--------+------------+ | ID | TYPE | Definition | | [MID] | [BYTE] | [MC] | +-------+--------+------------+ Figure 12: DescRptDefs Report Format Where: Defs = The Typed Data Collection holding the set of Reports being described, as a series of type DEF. The TDC structure is comprised of the # Defs, Types, and DEF structures, as discussed below. # Defs = The number of Report definitions included in this TDC. Types = The set of BYTE values identifying the types of the items in the TDC. For this Control, each entry will be of type DEF. Def N = The DEF structure (serialized into a BLOB, describing the Nth Report definition. Each DEF structure is comprised of the ID, TYPE, and Definition of the Report. NOTE: The type of each Report definition is of type Report. Birrane Expires February 21, 2016 [Page 20] Internet-Draft Agent ADM August 2015 7.2.4.5. GenerateRpts DESCRIPTION The GenerateRpts Control causes the Agent to produce one or more known Reports and send them to one or more Managers. PARAMETERS This Control accepts 2 parameters used to identify the set of Reports to be generated. The parameters for this control are illustrated in Figure 13. +---------------------+---------------------+ | Reports to Generate | Managers to Receive | | [MC] | [DC] | +---------------------+---------------------+ Figure 13: GenerateRpts Parameters Where: Reports to Generate = The list of Reports that should be generated 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 Reports MUST be sent only to the Manager that sent the Control. REPORTS GENERATED This Control will generate a Report capturing the description of each requested Report as known by the receiving Agent. The format for this Report is illustrated in Figure 14. Birrane Expires February 21, 2016 [Page 21] Internet-Draft Agent ADM August 2015 +----------+ +----------+ | Report 1 | | Report N | | [RPT] | ... | [RPT] | +----------+ +----------+ || || _________/ \________ / \ +-------+---------+ | ID | Entries | | [MID] | [TDC] | +-------+---------+ || || ___________________________/ \__________________________________ / \ +-----------+-------------+---------+---------+ +---------+ | # Entries | Entry Types | Entry 1 | Entry 2 | | Entry N | | [SDNV] | [BLOB] | [BLOB] | [BLOB] | ... | [BLOB] | +-----------+-------------+---------+---------+ +---------+ Figure 14: GenerateRpts Report Format Where: Report N = The Nth Report generated by this Control. Each Report consists of an ID and Entries, as described below. ID= = The identifier of the Report. This identifier MUST be matched to a known Report definition with the same identifier on the Manager so as to be able to decode the contents of the report. Entries = The TDC capturing the series of data items that comprise this Report. Each Entry is a tuple of entry type and entry binary data. 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 Birrane Expires February 21, 2016 [Page 22] Internet-Draft Agent ADM August 2015 represent an ordered collection of Controls 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 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. The parameters for this control are illustrated in Figure 15. +------------+----------+----------+ | Macro Name | Macro Id | Controls | | [STR] | [MID] | [MC] | +------------+----------+----------+ Figure 15: 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 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. REPORTS GENERATED This Control generates no Reports. Birrane Expires February 21, 2016 [Page 23] Internet-Draft Agent ADM August 2015 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. The parameters for this control are illustrated in Figure 16. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 16: 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. REPORTS GENERATED This Control generates no Reports. 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. REPORTS GENERATED This control will generate a Report capturing the list of Macro identifiers supported by this Agent. The format for this Report is illustrated in Figure 17. Birrane Expires February 21, 2016 [Page 24] Internet-Draft Agent ADM August 2015 +--------------+ | Known Macros | | [MC] | +--------------+ Figure 17: ListMacroDefs Report 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. PARAMETERS This Control accepts 1 parameter used to identify the set of Macros to be described. The parameters for this control are illustrated in Figure 18. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 18: DescMacroDefs Parameters Where: Ids to Describe = The list of Macro identifiers to be described by the Agent. REPORTS GENERATED This Control will generate a Report capturing the description of each requested Macro as known by the receiving Agent. The format for this Report is illustrated in Figure 19. Birrane Expires February 21, 2016 [Page 25] Internet-Draft Agent ADM August 2015 +-------+ | Defs | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # Defs | Types | Def 1 |... | Def N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ____________/ \_______________ / \ +-------+--------+------------+ | ID | TYPE | Definition | | [MID] | [BYTE] | [MC] | +-------+--------+------------+ Figure 19: DescMacroDefs Report Format Where: Defs = The Typed Data Collection holding the set of Macros being described, as a series of type DEF. The TDC structure is comprised of the # Defs, Types, and DEF structures, as discussed below. # Defs = The number of Macro descriptions included in this TDC. Types = The set of BYTE values identifying the types of the items in the TDC. For this Control, each entry will be of type DEF. Def N = The DEF structure (serialized into a BLOB, describing the Nth Macro definition. Each DEF structure is comprised of the ID, TYPE, and Definition of the Report. NOTE: The type of each Report definition is of type Macro. Birrane Expires February 21, 2016 [Page 26] Internet-Draft Agent ADM August 2015 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 perform some Macro periodically over time, and to stop after so many runs of the Macro. 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 application. Additionally, through a reset, the Agent must remember the number of runs of the Macro, 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 with a different associated definition. It MUST NOT be considered an error if the Agent already has configured the exact same TRL when this message is received. Put another way, this Control should be considered idempotent. PARAMETERS This Control accepts 5 parameters used to identify and define the new TRL. The parameters for this Control are illustrated in Figure 20. +-------+-------+------------+--------+--------+ | Id | Start | Period (s) | Count | Action | | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | +-------+-------+------------+--------+--------+ Figure 20: AddTimeRule Parameters Where: ID= The MID used to identify this TRL. Start= The time at which the rule should start to be evaluated. This timestamp may represent either a relative or absolute time. Period= Birrane Expires February 21, 2016 [Page 27] Internet-Draft Agent ADM August 2015 The interval, measured in seconds, between runs of the associated rule action. 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 Macro to be run on every run of the TRL, stored as a MC. REPORTS GENERATED This Control generates no Reports. 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. The parameters for this control are illustrated in Figure 21. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 21: 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. REPORTS GENERATED This Control generates no Reports. Birrane Expires February 21, 2016 [Page 28] Internet-Draft Agent ADM August 2015 7.2.6.3. ListTimeRules DESCRIPTION The ListTimeRules Control produces a listing of every TRL identifier (MID) known to the Agent. PARAMETERS This Control takes no parameters. REPORTS GENERATED This Control will generate a Report capturing the list of TRL MIDs supported by this Agent. The format for this Report is illustrated in Figure 22. +------------+ | Known TRLs | | [MC] | +------------+ Figure 22: ListTimeRules Report 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. The parameters for this control are illustrated in Figure 23. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 23: DescTimeRules Parameters Where: Ids to Describe = The list of TRL identifiers to be described by the Agent. Birrane Expires February 21, 2016 [Page 29] Internet-Draft Agent ADM August 2015 REPORTS GENERATED This control will generate a Report capturing the description of each requested TRL as known by the receiving Agent. The format for this Report is illustrated in Figure 24. +-------+ | TRLs | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # TRLs | Types | TRL 1 |... | TRL N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ___________________/ \_____________________ / \ +-------+-------+--------+--------+--------+ | ID | Start | Period | Count | Action | | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | +-------+-------+--------+--------+--------+ Figure 24: DescTimeRules Report Format Where: TRLs = The Typed Data Collection holding the set of TRLs being described, as a series of type TRL. The TDC structure is comprised of the # TRLs, Types, and TRL structures, as discussed below. # TRLs = The number of TRL descriptions included in this TDC. Types = The set of BYTE values identifying the types of the items in the TDC. For this Control, each entry will be of type TRL. TRL N = The TRL structure (serialized into a BLOB, describing the Nth TRL definition. Each TRL structure is comprised of the ID, Birrane Expires February 21, 2016 [Page 30] Internet-Draft Agent ADM August 2015 Start, Period, Count, and Action of the TRL. These are as defined in the AddTimeRule Control. 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 Macro when a given Predicate evaluates to true, and to stop after so many Predicate evaluations. 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 evaluations of the SRL predicate, 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 SRL definition is already defined on the Agent with a different associated definition. It MUST NOT be considered an error if the Agent already has configured the exact same SRL when this message is received. Put another way, this Control should be considered idempotent. PARAMETERS This Control accepts 5 parameters used to identify and define the new SRL. The parameters for this Control are illustrated in Figure 25. +-------+-------+-----------+--------+--------+ | Id | Start | Predicate | Count | Action | | [MID] | [TS] | [PRED] | [SDNV] | [MC] | +-------+-------+-----------+--------+--------+ Figure 25: AddStateRule Parameters Where: Id = The MID used to identify this SRL. Start = Birrane Expires February 21, 2016 [Page 31] Internet-Draft Agent ADM August 2015 The time at which the rule should start to be evaluated. This timestamp may represent either a relative or absolute timestamp. Predicate = The numerical expression 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 rule should be evaluated indefinitely until it is removed by a DelStateRules Control. Action = The Macro, stored as a MC, to be run when the SRL predicate evaluates to true. REPORTS GENERATED This Control generates no Reports. 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. The parameters for this control are illustrated in Figure 26. +---------------+ | Ids To Remove | | [MC] | +---------------+ Figure 26: 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. Birrane Expires February 21, 2016 [Page 32] Internet-Draft Agent ADM August 2015 REPORTS GENERATED This Control generates no Reports. 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. REPORTS GENERATED This control will generate a Report capturing the list of SRL MIDs supported by this Agent. The format for this Report is illustrated in Figure 27. +------------+ | Known SRLs | | [MC] | +------------+ Figure 27: ListStateRules Report 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. PARAMETERS This Control accepts 1 parameter used to identify the set of SRLs to be described. The parameters for this control are illustrated in Figure 28. +-----------------+ | Ids To Describe | | [MC] | +-----------------+ Figure 28: DescStateRules Parameters Where: Birrane Expires February 21, 2016 [Page 33] Internet-Draft Agent ADM August 2015 Ids to Describe = The list of SRL identifiers to be described by the Agent. REPORTS 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 is illustrated in Figure 29. +-------+ | SRLs | | [TDC] | +-------+ || || __________________/ \____________________ / \ +--------+--------+--------+ +--------+ | # SRLs | Types | SRL 1 |... | SRL N | | [SDNV] | [BLOB] | [BLOB] | | [BLOB] | +--------+--------+--------+ +--------+ || || ______________________/ \______________________ / \ +-------+-------+-----------+--------+--------+ | ID | Start | Predicate | Count | Action | | [MID] | [TS] | [PRED] | [SDNV] | [MC] | +-------+-------+-----------+--------+--------+ Figure 29: DescStateRules Report Format Where: SRLs = The Typed Data Collection holding the set of SRLs being described, as a series of type SRL. The TDC structure is comprised of the # SRLs, Types, and SRL structures, as discussed below. # SRLs = The number of SRL descriptions included in this TDC. Types = The set of BYTE values identifying the types of the items in the TDC. For this Control, each entry will be of type SRL. SRL N = Birrane Expires February 21, 2016 [Page 34] Internet-Draft Agent ADM August 2015 The SRL structure (serialized into a BLOB, describing the Nth SRL definition. Each SRL structure is comprised of the ID, Start, Period, Count, and Action of the SRL. These are as defined in the AddStateRule Control. 8. Literals This section describes the standard 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 | 82050100 | [5].0 | 1348025776 | UINT | None | +------------+-----------+-------+------------+--------+------------+ | User VAST | 82050101 | [5].1 | Varies | INT | VAST Value | +------------+-----------+-------+------------+--------+------------+ | User UVAST | 82050102 | [5].2 | Varies | UINT | SDNV Value | +------------+-----------+-------+------------+--------+------------+ | User Float | 82050103 | [5].3 | Varies | REAL32 | BLOB Value | +------------+-----------+-------+------------+--------+------------+ | User | 82050104 | [5].4 | Varies | REAL64 | BLOB Value | | Double | | | | | | +------------+-----------+-------+------------+--------+------------+ | User | 82050105 | [5].5 | Varies | STR | STR Value | | String | | | | | | +------------+-----------+-------+------------+--------+------------+ | User BLOB | 82050106 | [5].6 | Varies | BLOB | BLOB Value | +------------+-----------+-------+------------+--------+------------+ Table 7: AMP Agent Literals 8.1. Configurable Literals Description 8.1.1. User VAST DESCRIPTION The User VAST Literal is configured with information from a user in the system (via a Manager) to specify a specific signed Vast (64-bit Integer) for an AMP Agent. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 30. Birrane Expires February 21, 2016 [Page 35] Internet-Draft Agent ADM August 2015 +--------+ | Value | | [VAST] | +--------+ Figure 30: 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 with information from a user in the system (via a Manager) to specify a specific unsigned Vast (64-bit Integer) for an AMP Agent. This Literal should be preferred for any guaranteed unsigned value in the AMP as it uses the SDNV format to more efficiently convey smaller unsigned values. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 31. +--------+ | Value | | [SDNV] | +--------+ Figure 31: Operator User UVAST Parameters Where: Value The UVAST, encoded as an SDNV, being identified by this Literal. 8.1.3. User Float DESCRIPTION The User Float Literal is configured with information from a user in the system (via a Manager) 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 32. Birrane Expires February 21, 2016 [Page 36] Internet-Draft Agent ADM August 2015 +--------+ | Value | | [BLOB] | +--------+ Figure 32: 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 configured with information from a user in the system (via a Manager) to 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 33. +--------+ | Value | | [BLOB] | +--------+ Figure 33: 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 with information from a user in the system (via a Manager) to specify a specific NULL- terminated character string. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 34. Birrane Expires February 21, 2016 [Page 37] Internet-Draft Agent ADM August 2015 +-------+ | Value | | [STR] | +-------+ Figure 34: 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 with information from a user in the system (via a Manager) to specify a specific sized array of Bytes. PARAMETERS The Literal accepts 1 parameters, as illustrated in Figure 35. +--------+ | Value | | [BLOB] | +--------+ Figure 35: 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 February 21, 2016 [Page 38] Internet-Draft Agent ADM August 2015 +----------+------------+-------+----------------------------+ | Name | MID | OID | Description | +----------+------------+-------+----------------------------+ | User | 0xC9060100 | [6].0 | List all user-defined data | | List | | | | +----------+------------+-------+----------------------------+ | Definition | +------------------------------------------------------------+ | 0x04 0x81040104 0x8104010D 0x81040111 0x81040115 | +------------------------------------------------------------+ Table 8: AMP Agent Macro Definitions 10. Operators This section describes the standard 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 | +------+------------+--------+-------------------------+------------+ | + | 0x83070100 | [7].0 | Addition | 2 | +------+------------+--------+-------------------------+------------+ | - | 0x83070101 | [7].1 | Subtraction | 2 | +------+------------+--------+-------------------------+------------+ | * | 0x83070102 | [7].2 | Multiplication | 2 | +------+------------+--------+-------------------------+------------+ | / | 0x83070103 | [7].3 | Division | 2 | +------+------------+--------+-------------------------+------------+ | % | 0x83070104 | [7].4 | Modulo | 2 | +------+------------+--------+-------------------------+------------+ | ^ | 0x83070105 | [7].5 | Exponentiation | 2 | +------+------------+--------+-------------------------+------------+ | & | 0x83070106 | [7].6 | Bitwise AND | 2 | +------+------------+--------+-------------------------+------------+ | | | 0x83070107 | [7].7 | Bitwise OR | 2 | +------+------------+--------+-------------------------+------------+ | # | 0x83070108 | [7].8 | Bitwise XOR | 2 | +------+------------+--------+-------------------------+------------+ | ~ | 0x83070109 | [7].9 | Bitwise NOT | 1 | +------+------------+--------+-------------------------+------------+ | && | 0x8307010A | [7].A | Logical AND | 2 | +------+------------+--------+-------------------------+------------+ | || | 0x8307010B | [7].B | Logical OR | 2 | +------+------------+--------+-------------------------+------------+ | ! | 0x8307010C | [7].C | Logical NOT | 1 | Birrane Expires February 21, 2016 [Page 39] Internet-Draft Agent ADM August 2015 +------+------------+--------+-------------------------+------------+ | abs | 0x8307010D | [7].D | Absolute Value | 1 | +------+------------+--------+-------------------------+------------+ | < | 0x8307010E | [7].E | Less than | 2 | +------+------------+--------+-------------------------+------------+ | > | 0x8307010F | [7].F | Greater than | 2 | +------+------------+--------+-------------------------+------------+ | <= | 0x83070110 | [7].10 | Less than or equal to | 2 | +------+------------+--------+-------------------------+------------+ | >= | 0x83070111 | [7].11 | Greater than or equal | 2 | | | | | to | | +------+------------+--------+-------------------------+------------+ | != | 0x83070112 | [7].12 | Not equal | 2 | +------+------------+--------+-------------------------+------------+ | == | 0x83070113 | [7].13 | Equal to | 2 | +------+------------+--------+-------------------------+------------+ | << | 0x83070114 | [7].14 | Bitwise Left Shift | 2 | +------+------------+--------+-------------------------+------------+ | >> | 0x83070115 | [7].15 | Bitwise Right Shift | 2 | +------+------------+--------+-------------------------+------------+ Table 9: AMP Agent Atomic Data 11. Parameterization Examples This section describes examples of parameterization within the AMP using examples from this ADM. 11.1. AddCompVal Definition Consider the control "Add Computed Value Definition", which takes three parameters, given the following pseudo-code notation: AddCompVal(MID new_id, EXPR def, BYTE type) Where "new_id" is the MID of the newly created Computed Value definition, "def" is the Expression that is used to compute the value, and "type" is the enumeration of the resultant type of the value after it has been evaluated. Consider that we would like to use this Control to define the Computed Value "# of Rules" from Table 4. The values for the parameters in this example would be as follows. Birrane Expires February 21, 2016 [Page 40] Internet-Draft Agent ADM August 2015 +-----------+------+--------------+---------------------------------+ | Parameter | Type | Value | Description | +-----------+------+--------------+---------------------------------+ | new_id | MID | 0x9401040102 | We assume that this is a | | | | | compressed OID with an issuer | | | | | field set to 1. 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 | | | | | 0x83070100 | | +-----------+------+--------------+---------------------------------+ | type | BYTE | 0x02 | UINT | +-----------+------+--------------+---------------------------------+ The MID for the AddCompVal Control is given in this ADM as a full, parameterized OID, which, from [AMP] is formatted as follows. Birrane Expires February 21, 2016 [Page 41] Internet-Draft Agent ADM August 2015 Expanded Parameterized OID Format +--------+--------+--------+--------+ | Flags | Issuer | OID | Tag | | [BYTE] | [SDNV] |[VARIED]| [SDNV] | <=== MID | | (opt) | | (opt) | Definition +--------+--------+--------+--------+ || ____________________/ \________________ / \ +----------+--------------+------------+ | Nickname | Relative OID | Parameters | <=== Compressed, | [SDNV] | [BLOB] | [DC] | 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 36: Parameterized OID Format Given this format, the overall MID for the AddCompVal Control is as follows. MID Nick- Flag Name OID BLOB Parameters +-----+------+-------------+-------------------------------------------------+ | | | Len Octets | | | | +----+--------+ | | C1 | 04 | 01 | 02 |030494010401020D038001010280010104830701000101 | +-----+------+-------------+-------------------------------------------------+ The Parameters DC can be further broken out as follows. Birrane Expires February 21, 2016 [Page 42] Internet-Draft Agent ADM August 2015 Num Prms Parm 1 BLOB Parm 2 BLOB Parm 3 BLOB +-----+------------------+-------------------------------------------------+ | | Len Octets | Len Octets | Len Octets | | +-----+------------+-----+----------------------------+-----+--------+ | 03 | 05 | 9401040102 | 0D | 03800101028001010483070100 | 01 | 01 | +-----+-----+------------+-----+----------------------------+-----+--------+ 12. IANA Considerations At this time, this protocol has no fields registered by IANA. 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. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric Values in Protocols", RFC 6256, DOI 10.17487/RFC6256, May 2011, . Author's Address Edward J. Birrane Johns Hopkins Applied Physics Laboratory Email: Edward.Birrane@jhuapl.edu Birrane Expires February 21, 2016 [Page 43]