[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03

Delay-Tolerant Networking                                     E. Birrane
Internet-Draft                                               E. DiPietro
Intended status: Experimental                                   D. Linko
Expires: September 12, 2019     Johns Hopkins Applied Physics Laboratory
                                                          March 11, 2019


              Bundle Protocol Agent Application Data Model
                      draft-birrane-dtn-adm-bp-03

Abstract

   This document describes the Application Data Model (ADM) for a Bundle
   Protocol Agent (BPA) in compliance with the template provided by
   [I-D.birrane-dtn-adm].

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 https://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 September 12, 2019.

Copyright Notice

   Copyright (c) 2019 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
   (https://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.




Birrane, et al.        Expires September 12, 2019               [Page 1]


Internet-Draft                   BP ADM                       March 2019


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Technical Notes . . . . . . . . . . . . . . . . . . . . .   2
     1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   3
   2.  Structure and Design of this ADM  . . . . . . . . . . . . . .   3
   3.  Naming and Identification . . . . . . . . . . . . . . . . . .   3
     3.1.  Namespace and Nicknames . . . . . . . . . . . . . . . . .   4
   4.  BP Agent ADM JSON Encoding  . . . . . . . . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  14
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  14
     6.1.  Informative References  . . . . . . . . . . . . . . . . .  14
     6.2.  Normative References  . . . . . . . . . . . . . . . . . .  14
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  15

1.  Introduction

   An Application Data Model (ADM) provides a guaranteed interface for
   the management of an application or protocol in accordance with the
   Asynchronous Management Architecture (AMA) defined in
   [I-D.birrane-dtn-ama].  The ADM described in this document complies
   with the ADM Template provided in [I-D.birrane-dtn-adm] as encoded
   using the JSON syntax.

   Bundle Protocol Agents (BPAs) are software instances that implement
   functionality required by the Bundle Protocol ([I-D.ietf-dtn-bpbis]).
   The BPA ADM provides the set of information necessary to remotely
   manage such agents.

1.1.  Technical Notes

   o  This document describes Version 0.1 of the BP ADM.

   o  The AMM Resource Identifier (ARI) for this ADM is NOT correctly
      set.  A sample ARI is used in this version of the specification
      and MAY change in future versions of this ADM until an ARI
      registry is established.  This notice will be removed at that
      time.

   o  Agent applications MAY choose to ignore the name, description, or
      other annotative information associated with the component
      definitions within this ADM where such items are only used to
      provide human-readable information or are otherwise not necessary
      to manage a device.






Birrane, et al.        Expires September 12, 2019               [Page 2]


Internet-Draft                   BP ADM                       March 2019


1.2.  Scope

   This ADM specifies those components of the Asynchronous Management
   Model (AMM) common to the management of any instance of a BPA.

   Any Manager software implementing this ADM MUST perform the
   responsibilities of an AMA Manager as outlined in
   [I-D.birrane-dtn-adm] as they relate to the objects included in this
   document.

   Any Agent software implementing this ADM MUST perform the
   responsibilities of an AMA Agent as outlined in [I-D.birrane-dtn-adm]
   as they relate to the objects included in this document.

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.  Structure and Design of this ADM

   The BP Agent ADM's structure is in accordance to
   [I-D.birrane-dtn-adm].  This ADM contains metadata, edd, report
   templates, and controls.  Externally Defined Data (EDD) are values
   that are calculated external to the ADM system.  Report Templates are
   ordered sets of data descriptions that show how values will be
   represented in a corresponding report.  Controls are predefined and
   sometimes parameterized opcodes that can be run on an Agent.
   Controls are preconfigured in Agents and Managers as part of ADM
   support.  There are no variables, table templates, macros, constants,
   or operators in this ADM at this time.  The contents of this ADM are
   derived from the main functions and data that are needed to configure
   and manage bundle protocol operations on an ION node.

   All ADMs have metadata that includes the name, namespace, and version
   of the ADM as well as the name of the organization that is issuing
   that particular ADM.  This is important for identification purposes
   of the ADMs and to ensure version control.  The main elements of BP
   that are discussed in this ADM are endpoints, the priority of
   bundles/bytes, and whether or not the bundles/bytes were transferred
   successfully.

3.  Naming and Identification

   This section outlines the namespaces used to uniquely identify ADM
   objects in this specification.




Birrane, et al.        Expires September 12, 2019               [Page 3]


Internet-Draft                   BP ADM                       March 2019


3.1.  Namespace and Nicknames

   In accordance with [I-D.birrane-dtn-adm], every ADM is assigned a
   moderated Namespace.  In accordance with [I-D.birrane-dtn-amp], these
   namespaces may be enumerated for compactness.  The namespace and ADM
   identification for these objects is defined as follows.

                    +-----------------+--------------+
                    |    Identifier   |    Value     |
                    +-----------------+--------------+
                    |    Namespace    | DTN/bp_agent |
                    |                 |              |
                    | ADM Enumeration |      2       |
                    +-----------------+--------------+

                      Table 1: Namespace Information

   Given the above ADM enumeration, in accordance with
   [I-D.birrane-dtn-amp], the following AMP nicknames are defined.

                +----------+------------------------------+
                | Nickname |          Collection          |
                +----------+------------------------------+
                |    40    |      DTN/bp_agent/Const      |
                |          |                              |
                |    41    |      DTN/bp_agent/Ctrl       |
                |          |                              |
                |    42    |       DTN/bp_agent/Edd       |
                |          |                              |
                |    43    |       DTN/bp_agent/Mac       |
                |          |                              |
                |    44    |      DTN/bp_agent/Oper       |
                |          |                              |
                |    45    |      DTN/bp_agent/Rptt       |
                |          |                              |
                |    47    |      DTN/bp_agent/Tblt       |
                |          |                              |
                |    49    |       DTN/bp_agent/Var       |
                |          |                              |
                |    50    |      DTN/bp_agent/Mdat       |
                |          |                              |
                |  51-59   |    DTN/bp_agent/Reserved     |
                +----------+------------------------------+

                      Table 2: BP Agent ADM Nicknames






Birrane, et al.        Expires September 12, 2019               [Page 4]


Internet-Draft                   BP ADM                       March 2019


4.  BP Agent ADM JSON Encoding

   The following is the JSON encoding for the Bundle Protocol Agent ADM:

   {
     "Mdat": [{
         "name": "name",
         "type": "STR",
         "value": "bp_agent",
         "description": "The human-readable name of the ADM."
       },
       {
         "name": "namespace",
         "type": "STR",
         "value": "DTN/bp_agent",
         "description": "The namespace of the ADM."
       },
       {
         "name": "version",
         "type": "STR",
         "value": "v0.1",
         "description": "The version of the ADM"
       },
       {
         "name": "organization",
         "type": "STR",
         "value": "JHUAPL",
         "description": "The name of the issuing organization of the
                         ADM."
       }
     ],

     "Edd": [{
         "name": "bp_node_id",
         "type": "STR",
         "description": "The node administration endpoint"
       },
       {
         "name": "bp_node_version",
         "type": "STR",
         "description": "The latest version of the BP supported by this
                         node"
       },
       {
         "name": "available_storage",
         "type": "UVAST",
         "description": "Bytes available for bundle storage"
       },



Birrane, et al.        Expires September 12, 2019               [Page 5]


Internet-Draft                   BP ADM                       March 2019


       {
         "name": "last_reset_time",
         "type": "UVAST",
         "description": "The last time that BP counters were reset,
                         either due to execution of a reset control or
                         a restart of the node itself"
       },
       {
         "name": "num_registrations",
         "type": "UINT",
         "description": "number of registrations"
       },
       {
         "name": "num_pend_fwd",
         "type": "UINT",
         "description": "number of bundles pending forwarding"
       },
       {
         "name": "num_pend_dis",
         "type": "UINT",
         "description": "number of bundles awaiting dispatch"
       },
       {
         "name": "num_in_cust",
         "type": "UINT",
         "description": "number of bundles"
       },
       {
         "name": "num_pend_reassembly",
         "type": "UINT",
         "description": "number of bundles pending reassembly"
       },
       {
         "name": "bundles_by_priority",
         "type": "UINT",
         "parmspec": [{
           "type": "UINT",
           "name": "mask"
         }],
         "description": "Number of bundles for 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"
       },
       {
         "name": "bytes_by_priority",
         "type": "UINT",



Birrane, et al.        Expires September 12, 2019               [Page 6]


Internet-Draft                   BP ADM                       March 2019


         "parmspec": [{
           "type": "UINT",
           "name": "mask"
         }],
         "description": "Number of 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."
       },
       {
         "name": "src_bundles_by_priority",
         "type": "UINT",
         "parmspec": [{
           "type": "UINT",
           "name": "mask"
         }],
         "description": "Number 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."
       },
       {
         "name": "src_bytes_by_priority",
         "type": "UINT",
         "parmspec": [{
           "type": "UINT",
           "name": "mask"
         }],
         "description": "Number of bytes 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"
       },
       {
         "name": "num_fragmented_bundles",
         "type": "UINT",
         "description": "number of fragmented bundles"
       },
       {
         "name": "num_fragments_produced",
         "type": "UINT",
         "description": "Number of bundles with fragmentary payloads
                         produced by this node"



Birrane, et al.        Expires September 12, 2019               [Page 7]


Internet-Draft                   BP ADM                       March 2019


       },
       {
         "name": "num_failed_by_reason",
         "type": "UINT",
         "parmspec": [{
           "type": "UINT",
           "name": "mask"
         }],
         "description": "Number of 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)"
       },
       {
         "name": "num_bundles_deleted",
         "type": "UINT",
         "description": "number of bundles deleted by this node"
       },
       {
         "name": "failed_custody_bundles",
         "type": "UINT",
         "description": "number of bundle fails at this node"
       },
       {
         "name": "failed_custody_bytes",
         "type": "UINT",
         "description": "number bytes of fails at this node"
       },
       {
         "name": "failed_forward_bundles",
         "type": "UINT",
         "description": "number bundles not forwarded by this node"
       },
       {
         "name": "failed_forward_bytes",
         "type": "UINT",
         "description": "number of bytes not forwaded by this node"
       },
       {
         "name": "abandoned_bundles",
         "type": "UINT",
         "description": "number of bundles abandoned by this node"
       },
       {
         "name": "abandoned_bytes",
         "type": "UINT",
         "description": "number of bytes abandoned by this node"
       },



Birrane, et al.        Expires September 12, 2019               [Page 8]


Internet-Draft                   BP ADM                       March 2019


       {
         "name": "discarded_bundles",
         "type": "UINT",
         "description": "number of bundles discarded by this node"
       },
       {
         "name": "discarded_bytes",
         "type": "UINT",
         "description": "number of bytes discarded by this node"
       },
       {
         "name": "endpoint_names",
         "type": "STR",
         "description": "CSV list of endpoint names for this node"
       },
       {
         "name": "endpoint_active",
         "type": "UINT",
         "parmspec": [{
           "type": "STR",
           "name": "endpoint_name"
         }],
         "description": "is the given endpoint active? (0=no)"
       },
       {
         "name": "endpoint_singleton",
         "type": "UINT",
         "parmspec": [{
           "type": "STR",
           "name": "endpoint_name"
         }],
         "description": "is the given endpoint singleton? (0=no)"
       },
       {
         "name": "endpoint_policy",
         "type": "UINT",
         "parmspec": [{
           "type": "STR",
           "name": "endpoint_name"
         }],
         "description": "Does the endpoint abandon on fail (0=no)"
       }
     ],

     "Rptt": [{
         "name": "full_report",
         "definition": [
           {



Birrane, et al.        Expires September 12, 2019               [Page 9]


Internet-Draft                   BP ADM                       March 2019


       "ns": "DTN/bp_agent",
       "nm": "Mdat.name"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Mdat.version"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bp_node_id"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bp_node_version"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.available_storage"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.last_reset_time"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_registrations"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_pend_fwd"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_pend_dis"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_in_cust"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_pend_reassembly"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bundles_by_priority(1)"
     },
           {



Birrane, et al.        Expires September 12, 2019              [Page 10]


Internet-Draft                   BP ADM                       March 2019


       "ns": "DTN/bp_agent",
       "nm": "Edd.bundles_by_priority(2)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bundles_by_priority(4)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bytes_by_priority(1)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bytes_by_priority(2)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.bytes_by_priority(4)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bundles_by_priority(1)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bundles_by_priority(2)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bundles_by_priority(4)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bytes_by_priority(1)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bytes_by_priority(2)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.src_bytes_by_priority(4)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_fragmented_bundles"
     },
           {



Birrane, et al.        Expires September 12, 2019              [Page 11]


Internet-Draft                   BP ADM                       March 2019


       "ns": "DTN/bp_agent",
       "nm": "Edd.num_fragments_produced"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(1)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(2)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(4)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(8)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(16)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(32)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(64)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(128)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_failed_by_reason(256)"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.num_bundles_deleted"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.failed_custody_bundles"
     },
           {



Birrane, et al.        Expires September 12, 2019              [Page 12]


Internet-Draft                   BP ADM                       March 2019


       "ns": "DTN/bp_agent",
       "nm": "Edd.failed_custody_bytes"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.failed_forward_bundles"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.failed_forward_bytes"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.abandoned_bundles"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.discarded_bundles"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.discarded_bytes"
     },
           {
       "ns": "DTN/bp_agent",
       "nm": "Edd.endpoint_names"
     }
         ],
         "description": "This is all known meta-data, EDD, and VAR
                         values known by the agent."
       },
       {
         "name": "endpoint_report",
         "parmspec": [{
           "type": "STR",
           "name": "endpoint_id"
         }],
         "definition": [{
             "ns": "DTN/bp_agent",
             "nm": "edd.endpoint_active",
             "ap": [{
               "type": "ParmName",
               "value": "endpoint_id"
             }]
           },
           {
             "ns": "DTN/bp_agent",
             "nm": "edd.endpoint_singleton",



Birrane, et al.        Expires September 12, 2019              [Page 13]


Internet-Draft                   BP ADM                       March 2019


             "ap": [{
               "type": "ParmName",
               "value": "endpoint_id"
             }]
           },
           {
             "ns": "DTN/bp_agent",
             "nm": "edd.endpoint_policy",
             "ap": [{
               "type": "ParmName",
               "value": "endpoint_id"
             }]
           }
         ],
         "description": "This is all known endpoint information"
       }
     ],

     "Ctrl": [{
       "name": "reset_all_counts",
       "description": "This 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."
     }]
   }



5.  IANA Considerations

   At this time, this protocol has no fields registered by IANA.

6.  References

6.1.  Informative References

   [I-D.birrane-dtn-ama]
              Birrane, E., "Asynchronous Management Architecture",
              draft-birrane-dtn-ama-07 (work in progress), June 2018.

6.2.  Normative References

   [I-D.birrane-dtn-adm]
              Birrane, E., DiPietro, E., and D. Linko, "AMA Application
              Data Model", draft-birrane-dtn-adm-02 (work in progress),
              June 2018.




Birrane, et al.        Expires September 12, 2019              [Page 14]


Internet-Draft                   BP ADM                       March 2019


   [I-D.birrane-dtn-amp]
              Birrane, E., "Asynchronous Management Protocol", draft-
              birrane-dtn-amp-04 (work in progress), June 2018.

   [I-D.ietf-dtn-bpbis]
              Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol
              Version 7", draft-ietf-dtn-bpbis-12 (work in progress),
              November 2018.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

Authors' Addresses

   Edward J. Birrane
   Johns Hopkins Applied Physics Laboratory

   Email: Edward.Birrane@jhuapl.edu


   Evana DiPietro
   Johns Hopkins Applied Physics Laboratory

   Email: Evana.DiPietro@jhuapl.edu


   David Linko
   Johns Hopkins Applied Physics Laboratory

   Email: David.Linko@jhuapl.edu



















Birrane, et al.        Expires September 12, 2019              [Page 15]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/