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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.


Table of Contents

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.

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

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].

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.

OID Tree Identification
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.

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.

BP ADM Nicknames
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

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.

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.

BP Metadata
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

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.

BPA Primitive Values
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)

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.

 
+----------+------------+-------+----------------------------+------+
|   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                             |
+-------------------------------------------------------------------+                            
               

BP Full Report
 
+----------+------------+-------+----------------------------+------+
|   Name   |    MID     |  OID  |        Description         | Type |
+----------+------------+-------+----------------------------+------+
| Endpoint | 0xC80D0101 |[13].1 |  All known Endpoint Info   | RPT  |
|  Report  |            |       |                            |      |                  
+----------+------------+-------+----------------------------+------+
|                            Definition                             |
+-------------------------------------------------------------------+ 
| 0x03 0xC00B0120 0xC00B0121 0xC00B0122
+-------------------------------------------------------------------+                            
               

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.

7.1. Summary

BP Controls
Name MID OID # Prms Prms
Reset All Counts 0x810E0100 [14].0 0 ()

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

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", 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.

12.2. Normative References

[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.

Author's Address

Edward J. Birrane Johns Hopkins Applied Physics Laboratory EMail: Edward.Birrane@jhuapl.edu