| 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
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).
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 (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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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.
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.
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.
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].
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 ROOT STRING | iso.identified-organization.dod.internet.mgmt.amp.bp |
| BP ADM ROOT ID STRING | 1.3.6.1.2.3.1 |
| BP ADM ROOT OID (octets) | 2B 06 01 02 03 01 |
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
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.
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 ID | Label | OID as ASN.1 BER |
|---|---|---|
| 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 |
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.
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 (Str) | Description | Type | Value |
|---|---|---|---|---|---|
| Label | 0x800A0100 | [10].0 | The human-readable ADM name. | STR | BP ADM |
| Version | 0x800A0101 | [10].1 | The ADM version. | STR | v0.1 |
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].0 | The node administrative endpoint. | STR | None |
| BP Node Version | 0x800B0101 | [11].1 | The latest version of the BP supported by this node. | STR | None |
| Available Storage | 0x800B0102 | [11].2 | Bytes available for bundle storage. | UVAST | None |
| Last Reset Time | 0x800B0103 | [11].3 | The last time that BP counters were reset, either due to execution of a reset control or a restart of the node itself. | UVAST | None |
| Num Registrations | 0x800B0104 | [11].4 | # Registrations. | UINT | None |
| Num Pend Fwd | 0x800B0105 | [11].5 | # bundles pending forwarding. | UINT | None |
| Num Pend Dis | 0x800B0106 | [11].6 | # bundles awaiting dispatch. | UINT | None |
| Num in Cust | 0x800B0107 | [11].7 | # bundles . | UINT | None |
| Num Pend Reassembly | 0x800B0108 | [11].8 | # bundles pending re-assembly. | UINT | None |
| Bundles By Priority | 0xC00B0109 | [11].9 | # bundles of the given 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. | UINT | (UINT Mask) |
| Bytes By Priority | 0xC00B010A | [11].A | # bytes of the given 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. | UINT | (UINT Mask) |
| Src Bundles By Priority | 0xC00B010B | [11].B | # bundles sourced 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. | UINT | (UINT Mask) |
| Src Bytes By Priority | 0xC00B010C | [11].C | # bytes of bundles sourced 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. | UINT | (UINT Mask) |
| Num Fragmented Bundles | 0x800B010D | [11].D | # fragmented bundles. | UINT | None |
| Num Fragments Produced | 0x800B010E | [11].E | # bundles with fragmentary payloads produced by this node. | UINT | None |
| Num Failed by Reason | 0xC00B010F | [11].F | # bundles failed for any of the given reasons. (NoInfo=0x1, Expired=0x2, UniFwd=0x4, Cancelled=0x8, NoStorage=0x10, BadEID=0x20, NoRoute=0x40, NoContact=0x80, BadBlock=0x100) | UINT | UINT(Mask) |
| Num Bundles Deleted | 0x800B0110 | [11].10 | # bundles deleted by this node. | UINT | None |
| Failed Custody Bundles | 0x800B0111 | [11].11 | # bundle fails at this node. | UINT | None |
| Failed Custody Bytes | 0x800B0112 | [11].12 | # bytes of fails at this node. | UINT | None |
| Failed Forward Bundles | 0x800B0113 | [11].13 | # bundle not forwarded by this node. | UINT | None |
| Failed Forward Bytes | 0x800B0114 | [11].14 | # bytes not forwarded by this node. | UINT | None |
| Abandoned Bundles | 0x800B0115 | [11].15 | # bundles abandoned by this node. | UINT | None |
| Abandoned Bytes | 0x800B0116 | [11].16 | # bytes abandoned by this node. | UINT | None |
| Discarded Bundles | 0x800B0117 | [11].17 | # bundles discarded by this node. | UINT | None |
| Discarded Bytes | 0x800B0118 | [11].18 | # bytes discarded by this node. | UINT | None |
| Endpoint Names | 0x800B0119 | [11].19 | CSV list of Endpoint names for this node. | STR | None |
| Endpoint Active | 0xC00B0120 | [11].20 | Is the given endpoint active? (0 = no). | UINT | (STR Endpoint Name) |
| Endpoint Singleton | 0xC00B0121 | [11].21 | Is the given endpoint a singleton? (0 = no). | UINT | (STR Endpoint Name) |
| Endpoint Policy | 0xC00B0122 | [11].22 | Does the endpoint abandon on fail? (0 = no). | UINT | (STR Endpoint Name) |
The BP ADM defines no computed values.
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.
+----------+------------+-------+----------------------------+------+
| 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 |
+-------------------------------------------------------------------+
+----------+------------+-------+----------------------------+------+
| Name | MID | OID | Description | Type |
+----------+------------+-------+----------------------------+------+
| Endpoint | 0xC80D0101 |[13].1 | All known Endpoint Info | RPT |
| Report | | | | |
+----------+------------+-------+----------------------------+------+
| Definition |
+-------------------------------------------------------------------+
| 0x03 0xC00B0120 0xC00B0121 0xC00B0122
+-------------------------------------------------------------------+
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.
| Name | MID | OID | # Prms | Prms |
|---|---|---|---|---|
| Reset All Counts | 0x810E0100 | [14].0 | 0 | () |
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.
The BP ADM does not define any literals.
The BP ADM does not define any macros.
The BP ADM does not define any operators.
At this time, this protocol has no fields registered by IANA.
| [AMA] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-00, August 2015. |
| [I-D.irtf-dtnrg-dtnmp] | Birrane, E. and V. Ramachandran, "Delay Tolerant Network Management Protocol", Internet-Draft draft-irtf-dtnrg-dtnmp-01, December 2014. |
| [AMP] | Birrane, E., "Asynchronous Management Protocol", Internet-Draft draft-birrane-dtn-amp-00, 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. |
| [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. |