Delay-Tolerant Networking E. Birrane Internet-Draft Johns Hopkins Applied Physics Laboratory Intended status: Experimental December 31, 2015 Expires: July 3, 2016 Bundle Protocol Agent Application Data Model draft-birrane-dtn-adm-bp-00 Abstract This document describes an Application Data Model (ADM) for a Bundle Protocol Agent (BPA). This ADM identifies the Primitive Values, Computed values, Reports, Controls, Macros, Literals, Operators, and meta-data associated with a BPA. The information outlined in this document MUST be supported by any software claiming to act as a managed BPA within the Asynchronous Management Protocol (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 July 3, 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 include Simplified BSD License text as described in Section 4.e of Birrane Expires July 3, 2016 [Page 1] Internet-Draft BP ADM December 2015 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 . . . . . . . . . . . . . . . . . . . 4 2.1. Nicknames . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. OID Shorthand . . . . . . . . . . . . . . . . . . . . . . 5 3. Metadata Definitions . . . . . . . . . . . . . . . . . . . . 6 4. Primitive Values . . . . . . . . . . . . . . . . . . . . . . 6 5. Computed Values . . . . . . . . . . . . . . . . . . . . . . . 10 6. Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7. Controls . . . . . . . . . . . . . . . . . . . . . . . . . . 11 7.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . 12 7.2. Control Specification . . . . . . . . . . . . . . . . . . 12 7.2.1. Overview . . . . . . . . . . . . . . . . . . . . . . 12 7.2.2. BP Controls . . . . . . . . . . . . . . . . . . . . . 12 8. Literals . . . . . . . . . . . . . . . . . . . . . . . . . . 13 9. Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 10. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 13 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 12.1. Informative References . . . . . . . . . . . . . . . . . 13 12.2. Normative References . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 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. 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. These agents provide the mechanism through which applications and protocols are managed through the AMP. Birrane Expires July 3, 2016 [Page 2] Internet-Draft BP ADM December 2015 Bundle Protocol Agents (BPAs) are software instances that implement functionality required by the Bundle Protocol ([RFC5050]). The BPA ADM provides the set of information known to an AMP Agent for the management of a BPA via the AMP. 1.1. Technical Notes o This document describes Version 0.1 of the BP 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 BPA management via an AMP Agent. Any BPA implementation claiming compliance with the BP ADM MUST compute all identified primitive data when requested by an AMP Agent. Also, any BPA implementation claiming compliance with the BPA ADM MUST execute all identified controls when requested by an AMP Agent. Any AMP Agent claiming to support the BPA ADM must compute all identifier 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]. Birrane Expires July 3, 2016 [Page 3] Internet-Draft BP ADM December 2015 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 "BP ADM OID Root". This section identifies this root in the overall OID tree. NOTE: This version of the BP ADM uses a proxy BP ADM Root that has NOT been assigned. The BP ADM Root in this version of the document is only used for experimental purposes and MAY change before the final release of this specification. +------------+------------------------------------------------------+ | BP ADM OID | iso.identified-organization.dod.internet.mgmt.amp.bp | | ROOT | | | STRING | | | | | | BP ADM | 1.3.6.1.2.3.1 | | ROOT ID | | | STRING | | | | | | BP ADM | 2B 06 01 02 03 01 | | ROOT OID | | | (octets) | | +------------+------------------------------------------------------+ OID Tree Identification The subtree under the BP ADM OID ROOT contains eight subbranches that capture metadata, Primitive Values, Computed Values, Reports, Controls, Literals, Macros, and Operators as illustrated in Figure 1. BP ADM ROOT (1.3.6.1.2.3.1) | | Meta- Primitive Computed | Data Data Data Rpts | Ctrls Literals Macros Ops (.0) (.1) (.2) (.3) | (.4) (.5) (.6) (.7) +-------+---------+------+---------+------+----------+---------+ Figure 1: BP ADM OID Subtree Birrane Expires July 3, 2016 [Page 4] Internet-Draft BP ADM December 2015 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. +--------+----------------------------+-----------------------------+ | Unique | Label | OID as ASN.1 BER | | ID | | | +--------+----------------------------+-----------------------------+ | 10 | BP Metadata | 0x2B060102030100 | | | | | | 11 | BP Primitive Values | 0x2B060102030101 | | | | | | 12 | BP Computed Values | 0x2B060102030102 | | | | | | 13 | BP Reports | 0x2B060102030103 | | | | | | 14 | BP Controls | 0x2B060102030104 | | | | | | 15 | BP Literals | 0x2B060102030105 | | | | | | 16 | BP Macros | 0x2B060102030106 | | | | | | 17 | BP Operators | 0x2B060102030107 | | | | | | 18 | BP Root | 0x2B0601020301 | +--------+----------------------------+-----------------------------+ Table 1: BP 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 [14].3.2.1 corresponds to the OID 2B060102030104030201, with 2B060102030104 being the expansion of nickname 14 and 030201 being the relative OID. Birrane Expires July 3, 2016 [Page 5] Internet-Draft BP ADM December 2015 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. +---------+------------+---------+-------------------+------+-------+ | Name | MID (Hex) | OID | Description | Type | Value | | | | (Str) | | | | +---------+------------+---------+-------------------+------+-------+ | Label | 0x800A0100 | [10].0 | The human- | STR | BP | | | | | readable ADM | | ADM | | | | | name. | | | +---------+------------+---------+-------------------+------+-------+ | Version | 0x800A0101 | [10].1 | The ADM version. | STR | v0.1 | +---------+------------+---------+-------------------+------+-------+ Table 2: BP Metadata 4. Primitive Values Primitive Value definitions represent those values that MUST be collected by the BPA. Changing or updating Primitive Value definitions requires making changes to the BPA application and/ or its supporting firmware. +------------+------------+-------+-----------------+-------+-------+ | Name | MID | OID | Description | Type | Parms | +------------+------------+-------+-----------------+-------+-------+ | BP Node ID | 0x800B0100 | [11]. | The node | STR | None | | | | 0 | administrative | | | | | | | endpoint. | | | +------------+------------+-------+-----------------+-------+-------+ | BP Node | 0x800B0101 | [11]. | The latest | STR | None | | Version | | 1 | version of the | | | | | | | BP supported by | | | | | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Available | 0x800B0102 | [11]. | Bytes available | UVAST | None | | Storage | | 2 | for bundle | | | | | | | storage. | | | +------------+------------+-------+-----------------+-------+-------+ | Last Reset | 0x800B0103 | [11]. | The last time | UVAST | None | | Time | | 3 | that BP | | | | | | | counters were | | | | | | | reset, either | | | | | | | due to | | | | | | | execution of a | | | Birrane Expires July 3, 2016 [Page 6] Internet-Draft BP ADM December 2015 | | | | reset control | | | | | | | or a restart of | | | | | | | the node | | | | | | | itself. | | | +------------+------------+-------+-----------------+-------+-------+ | Num Regist | 0x800B0104 | [11]. | # | UINT | None | | rations | | 4 | Registrations. | | | +------------+------------+-------+-----------------+-------+-------+ | Num Pend | 0x800B0105 | [11]. | # bundles | UINT | None | | Fwd | | 5 | pending | | | | | | | forwarding. | | | +------------+------------+-------+-----------------+-------+-------+ | Num Pend | 0x800B0106 | [11]. | # bundles | UINT | None | | Dis | | 6 | awaiting | | | | | | | dispatch. | | | +------------+------------+-------+-----------------+-------+-------+ | Num in | 0x800B0107 | [11]. | # bundles . | UINT | None | | Cust | | 7 | | | | +------------+------------+-------+-----------------+-------+-------+ | Num Pend | 0x800B0108 | [11]. | # bundles | UINT | None | | Reassembly | | 8 | pending re- | | | | | | | assembly. | | | +------------+------------+-------+-----------------+-------+-------+ | Bundles By | 0xC00B0109 | [11]. | # bundles of | UINT | (UINT | | Priority | | 9 | the given | | Mask) | | | | | priority. | | | | | | | Priority is | | | | | | | given as a | | | | | | | priority mask | | | | | | | where Bulk=0x1, | | | | | | | Normal=0x2, | | | | | | | Express=0x4. | | | | | | | Any bundles | | | | | | | matching any of | | | | | | | the masked | | | | | | | priorities will | | | | | | | be included in | | | | | | | the returned | | | | | | | count. | | | +------------+------------+-------+-----------------+-------+-------+ | Bytes By | 0xC00B010A | [11]. | # bytes of the | UINT | (UINT | | Priority | | A | given priority. | | Mask) | | | | | Priority is | | | | | | | given as a | | | | | | | priority mask | | | | | | | where Bulk=0x1, | | | | | | | Normal=0x2, | | | | | | | Express=0x4. | | | Birrane Expires July 3, 2016 [Page 7] Internet-Draft BP ADM December 2015 | | | | Any bundles | | | | | | | matching any of | | | | | | | the masked | | | | | | | priorities will | | | | | | | be included in | | | | | | | the returned | | | | | | | count. | | | +------------+------------+-------+-----------------+-------+-------+ | Src | 0xC00B010B | [11]. | # bundles | UINT | (UINT | | Bundles By | | B | sourced by this | | Mask) | | Priority | | | node of the | | | | | | | given priority. | | | | | | | Priority is | | | | | | | given as a | | | | | | | priority mask | | | | | | | where Bulk=0x1, | | | | | | | Normal=0x2, | | | | | | | Express=0x4. | | | | | | | Any bundles | | | | | | | sourced by this | | | | | | | node and | | | | | | | matching any of | | | | | | | the masked | | | | | | | priorities will | | | | | | | be included in | | | | | | | the returned | | | | | | | count. | | | +------------+------------+-------+-----------------+-------+-------+ | Src Bytes | 0xC00B010C | [11]. | # bytes of | UINT | (UINT | | By | | C | bundles sourced | | Mask) | | Priority | | | by this node of | | | | | | | the given | | | | | | | priority. | | | | | | | Priority is | | | | | | | given as a | | | | | | | priority mask | | | | | | | where Bulk=0x1, | | | | | | | Normal=0x2, | | | | | | | Express=0x4. | | | | | | | Any bundles | | | | | | | sourced by this | | | | | | | node and | | | | | | | matching any of | | | | | | | the masked | | | | | | | priorities will | | | | | | | be included in | | | | | | | the returned | | | | | | | count. | | | Birrane Expires July 3, 2016 [Page 8] Internet-Draft BP ADM December 2015 +------------+------------+-------+-----------------+-------+-------+ | Num | 0x800B010D | [11]. | # fragmented | UINT | None | | Fragmented | | D | bundles. | | | | Bundles | | | | | | +------------+------------+-------+-----------------+-------+-------+ | Num | 0x800B010E | [11]. | # bundles with | UINT | None | | Fragments | | E | fragmentary | | | | Produced | | | payloads | | | | | | | produced by | | | | | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Num Failed | 0xC00B010F | [11]. | # bundles | UINT | UINT( | | by Reason | | F | failed for any | | Mask) | | | | | of the given | | | | | | | reasons. | | | | | | | (NoInfo=0x1, | | | | | | | Expired=0x2, | | | | | | | UniFwd=0x4, | | | | | | | Cancelled=0x8, | | | | | | | NoStorage=0x10, | | | | | | | BadEID=0x20, | | | | | | | NoRoute=0x40, | | | | | | | NoContact=0x80, | | | | | | | BadBlock=0x100) | | | +------------+------------+-------+-----------------+-------+-------+ | Num | 0x800B0110 | [11]. | # bundles | UINT | None | | Bundles | | 10 | deleted by this | | | | Deleted | | | node. | | | +------------+------------+-------+-----------------+-------+-------+ | Failed | 0x800B0111 | [11]. | # bundle fails | UINT | None | | Custody | | 11 | at this node. | | | | Bundles | | | | | | +------------+------------+-------+-----------------+-------+-------+ | Failed | 0x800B0112 | [11]. | # bytes of | UINT | None | | Custody | | 12 | fails at this | | | | Bytes | | | node. | | | +------------+------------+-------+-----------------+-------+-------+ | Failed | 0x800B0113 | [11]. | # bundle not | UINT | None | | Forward | | 13 | forwarded by | | | | Bundles | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Failed | 0x800B0114 | [11]. | # bytes not | UINT | None | | Forward | | 14 | forwarded by | | | | Bytes | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Abandoned | 0x800B0115 | [11]. | # bundles | UINT | None | | Bundles | | 15 | abandoned by | | | | | | | this node. | | | Birrane Expires July 3, 2016 [Page 9] Internet-Draft BP ADM December 2015 +------------+------------+-------+-----------------+-------+-------+ | Abandoned | 0x800B0116 | [11]. | # bytes | UINT | None | | Bytes | | 16 | abandoned by | | | | | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Discarded | 0x800B0117 | [11]. | # bundles | UINT | None | | Bundles | | 17 | discarded by | | | | | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Discarded | 0x800B0118 | [11]. | # bytes | UINT | None | | Bytes | | 18 | discarded by | | | | | | | this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Endpoint | 0x800B0119 | [11]. | CSV list of | STR | None | | Names | | 19 | Endpoint names | | | | | | | for this node. | | | +------------+------------+-------+-----------------+-------+-------+ | Endpoint | 0xC00B0120 | [11]. | Is the given | UINT | (STR | | Active | | 20 | endpoint | | Endpo | | | | | active? (0 = | | int | | | | | no). | | Name) | +------------+------------+-------+-----------------+-------+-------+ | Endpoint | 0xC00B0121 | [11]. | Is the given | UINT | (STR | | Singleton | | 21 | endpoint a | | Endpo | | | | | singleton? (0 = | | int | | | | | no). | | Name) | +------------+------------+-------+-----------------+-------+-------+ | Endpoint | 0xC00B0122 | [11]. | Does the | UINT | (STR | | Policy | | 22 | endpoint | | Endpo | | | | | abandon on | | int | | | | | fail? (0 = no). | | Name) | +------------+------------+-------+-----------------+-------+-------+ Table 3: BPA Primitive Values 5. Computed Values The BP ADM defines no 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 July 3, 2016 [Page 10] Internet-Draft BP ADM December 2015 +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Full | 0x880D0100 |[13].0 | All known Meta-Data, | RPT | | Report | | | Primitive, and Computed | | | | | | Values on the Agent. | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x2C 0x800A0100 0x800A0101 0x800B0100 0x800B0101 0x800B0102 | | 0x800B0103 0x800B0104 0x800B0105 0x800B0106 0x800B0107 | | 0x800B0108 0xC00B0109010101 0xC00B0109010102 | | 0xC00B0109010104 0xC00B010A010101 0xC00B010A010102 | | 0xC00B010A010104 0xC00B010B010101 0xC00B010B010102 | | 0xC00B010B010104 0xC00B010C010101 0xC00B010C010102 | | 0xC00B010C010104 0x800B010D 0x800B010E 0xC00B010F010101 | | 0xC00B010F010102 0xC00B010F010104 0xC00B010F010108 | | 0xC00B010F010110 0xC00B010F010120 0xC00B010F010140 | | 0xC00B010F010180 0xC00B010F01020100 0xC00B0110 0xC00B0111 | | 0xC00B0112 0xC00B0113 0xC00B0114 0xC00B0115 0xC00B0116 | | 0xC00B0117 0xC00B0118 0xC00B0119 | +-------------------------------------------------------------------+ Table 4: BP Full Report +----------+------------+-------+----------------------------+------+ | Name | MID | OID | Description | Type | +----------+------------+-------+----------------------------+------+ | Endpoint | 0xC80D0101 |[13].1 | All known Endpoint Info | RPT | | Report | | | | | +----------+------------+-------+----------------------------+------+ | Definition | +-------------------------------------------------------------------+ | 0x03 0xC00B0120 0xC00B0121 0xC00B0122 +-------------------------------------------------------------------+ Table 5: BP Endpoint Report 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. Birrane Expires July 3, 2016 [Page 11] Internet-Draft BP ADM December 2015 7.1. Summary +------------------+------------+--------+--------+------+ | Name | MID | OID | # Prms | Prms | +------------------+------------+--------+--------+------+ | Reset All Counts | 0x810E0100 | [14].0 | 0 | () | +------------------+------------+--------+--------+------+ Table 6: BP 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. 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. BP Controls Birrane Expires July 3, 2016 [Page 12] Internet-Draft BP ADM December 2015 7.2.2.1. ResetAllCounts DESCRIPTION The ResetAllCounts control causes the Agent to reset all counts associated with bundle or byte statistics and to set the Last Reset Time of the BP Primitive Data to the time when the control was run. PARAMETERS This control does not take any parameters. REPORTS GENERATED This control does not produce any reports. 8. Literals The BP ADM does not define any literals. 9. Macros The BP ADM does not define any macros. 10. Operators The BP ADM does not define any operators. 11. IANA Considerations At this time, this protocol has no fields registered by IANA. 12. References 12.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. 12.2. Normative References [AMP] Birrane, E., "Asynchronous Management Protocol", draft- birrane-dtn-amp-00 (work in progress), August 2015. Birrane Expires July 3, 2016 [Page 13] Internet-Draft BP ADM December 2015 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol Specification", RFC 5050, DOI 10.17487/RFC5050, November 2007, . [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 July 3, 2016 [Page 14]