<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[
<!ENTITY RFC6256 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6256.xml">
<!ENTITY RFC4838 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4838.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC5050 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5050.xml">
<!ENTITY RFC6257 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6257.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdep"4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="no" ?>
<?rfc subcompact="no" ?>

<rfc category="exp" ipr="trust200902" docName="draft-birrane-dtn-adm-ion-bpadmin-01" obsoletes="" updates="" submissionType="IETF" xml:lang="en">

   <!-- ***** FRONT MATTER ***** -->
   <front> 
      <title abbrev="BP Admin ADM">Bundle Protocol Agent Application Data Model</title>
      <author fullname="Edward J. Birrane" initials="E.B." surname="Birrane">
         <organization> Johns Hopkins Applied Physics Laboratory </organization>
         <address>
            <email>Edward.Birrane@jhuapl.edu</email>
         </address>
      </author>
      <author fullname="Evana DiPietro" initials="E.D." surname="DiPietro">
         <organization> Johns Hopkins Applied Physics Laboratory </organization>
         <address>
            <email>Evana.DiPietro@jhuapl.edu</email>
         </address>
      </author>
      <author fullname="David Linko" initials="D.L." surname="Linko">
         <organization> Johns Hopkins Applied Physics Laboratory </organization>
         <address>
            <email>David.Linko@jhuapl.edu</email>
         </address>
      </author>
      <date year="2019" />
      
       <!-- Meta-data Declarations -->
      <area>General</area>
      <workgroup>Delay-Tolerant Networking</workgroup>
      <keyword>DTN</keyword>
      <keyword>Network Management</keyword>

      <abstract>
         <t>
            This document describes the Application Data Model (ADM) for the
            administration of Bundle Protocol (BP) ION in compliance with the template
            provided by <xref target="I-D.birrane-dtn-adm"/>.
         </t>
      </abstract>
   </front>
  
   <middle>
      <section title="Introduction" toc="default">
         <t>
            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 <xref target="I-D.birrane-dtn-ama"/>. 
            The ADM described in this document complies with the 
            ADM Template provided in <xref target="I-D.birrane-dtn-adm"/> 
            as encoded using the JSON syntax.
         </t>
         <t>
            The ION Bundle Protocol Administration ADM contains all of the functionality that is required for the configuration and management of BP on the local ION node.

         </t>
             
         <section title="Technical Notes" toc="default">
            <t>
               <list style="symbols">
                  <t>
                     This document describes Version 0.0 of the ION BP Admin ADM.
                  </t>
                  <t>
                     The Asynchronous 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.
                  </t>
                  <t>
                     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.                     
                  </t>              
               </list>
            </t>
         </section>
      
         <section title="Scope" toc="default">
            <t>
               This ADM specifies those components of the Asynchronous 
               Management Model (AMM) common to the configuration and management of Bundle Protocol in ION. 
            </t>
            <t>
               Any Manager software implementing this ADM MUST perform the responsibilities of an AMA Manager as outlined in <xref target="I-D.birrane-dtn-adm"/> as they relate to the objects included in this document.
            </t>
            <t>
               Any Agent software implementing this ADM MUST perform the responsibilities
               of an AMA Agent as outlined in <xref target="I-D.birrane-dtn-adm"/> as they relate to the objects included in this document.
            </t>
         </section>
         
         <section title="Requirements Language" toc="default">
            <t>
               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 
               <xref target="RFC2119" pageno="false" format="default">RFC 2119</xref>.
            </t>
         </section>   
                 
      </section>
      <section title="Structure and Design of this ADM">
        <t>
          The BP Admin ADM's structure is in accordance to <xref target="I-D.birrane-dtn-adm"/>. This ADM contains metadata, table templates, and controls. Table Templates are column templates that will be followed by any instance of this table available in the network. They may not be created dynamically within the network by Managers. 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, report templates, constants, macros, edd, 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 BP in accordance with (WHICH VERSION OF BP). 
        </t>
        <t>
          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 table templates and controls in this ADM deal with inducts, outducts, schemes, and protocols, the most important things needed for the proper administration of Bundle Protocol. 
        </t>
      </section>
      <section title="Naming and Identification">
         <t>
            This section outlines the namespaces used to uniquely identify
            ADM objects in this specification.
         </t>

         <section title="Namespace and Nicknames">
            <t>
                In accordance with <xref target="I-D.birrane-dtn-adm"/>, every ADM
               is assigned a moderated Namespace. In accordance with 
               <xref target="I-D.birrane-dtn-amp"/>, these namespaces may be
               enumerated for compactness. The namespace and ADM identification
               for these objects is defined as follows.
              
            </t>
          <texttable anchor="agent_ns" title="Namespace Information" align="center">
               <ttcol align="center">Identifier</ttcol>
               <ttcol align="center">Value</ttcol>
               
               <c>Namespace</c>
               <c>DTN/ION/bpadmin/</c>

               <c>ADM Enumeration</c>
               <c>5</c>
            </texttable>
                              
      <t>
              Given the above ADM enumeration, in accordance with 
              <xref target="I-D.birrane-dtn-amp"/>, the following AMP
              nicknames are defined.
            </t>
            
            <texttable anchor="bpadmin_nn" title="ION BP ADM Nicknames" align="center" style="full">
               <ttcol width="10%" align="center">Nickname</ttcol>
               <ttcol width="45%" align="center">Collection</ttcol>
               
               <c>100</c>
               <c>DTN/ION/bpadmin/Const</c>

               <c>101</c>
               <c>DTN/ION/bpadmin/Ctrl</c>

               <c>102</c>
               <c>DTN/ION/bpadmin/Edd</c>

               <c>103</c>
               <c>DTN/ION/bpadmin/Mac</c>

               <c>104</c>
               <c>DTN/ION/bpadmin/Oper</c>

               <c>105</c>
               <c>DTN/ION/bpadmin/Rptt</c>

               <c>107</c>
               <c>DTN/ION/bpadmin/Tblt</c>

               <c>109</c>
               <c>DTN/ION/bpadmin/Var</c>

               <c>110</c>
               <c>DTN/ION/bpadmin/Mdat</c>

               <c>111-119</c>
               <c>DTN/ION/bpadmin/Reserved</c>

            </texttable>
         
         </section>
      </section>

      <section title="ION BP Admin ADM JSON Encoding">
        <t>
          The following is the JSON encoding of the Bundle Protocol Admin Application Data Model:
          <figure>
            <artwork>
{
  "Mdat": [{
      "name": "name",
      "type": "STR",
      "value": "ion_bp_admin",
      "description": "The human-readable name of the ADM."
    },
    {
      "name": "namespace",
      "type": "STR",
      "value": "DTN/ION/bpadmin",
      "description": "The namespace of the ADM"
    },
    {
      "name": "version",
      "type": "STR",
      "value": "v0.0",
      "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_version",
    "type": "STR",
    "description": "Version of installed ION BP Admin utility."
  }],
  "Tblt": [{
      "name": "endpoints",
      "columns": [{
        "type": "STR",
        "name": "scheme_name"
      }, {
        "type": "STR",
        "name": "endpoint_nss"
      }, {
        "type": "UINT",
        "name": "app_pid"
      }, {
        "type": "STR",
        "name": "recv_rule"
      }, {
        "type": "STR",
        "name": "rcv_script"
      }],
      "description": "Local endpoints, regardless of scheme name."
    },
    {
      "name": "inducts",
      "columns": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "STR",
        "name": "cli_control"
      }],
      "description": "Inducts established locally for the indicated 
                      CL protocol."
    },
    {
      "name": "outducts",
      "columns": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "UINT",
        "name": "clo_pid"
      }, {
        "type": "STR",
        "name": "clo_control"
      }, {
        "type": "UINT",
        "name": "max_payload_length"
      }],
      "description": "If protocolName is specified, this table lists 
                      all outducts established locally for the 
                      indicated CL protocol. Otherwise, it lists all 
                      locally established outducts, regardless of 
                      their protocol."
    },
    {
      "name": "protocols",
      "columns": [{
        "type": "STR",
        "name": "name"
      }, {
        "type": "UINT",
        "name": "payload_bpf"
      }, {
        "type": "UINT",
        "name": "overhead_bpf"
      }, {
        "type": "UINT",
        "name": "protocol class"
      }],
      "description": "Convergence layer protocols that can currently 
                      be utilized at the local node."
    },
    {
      "name": "schemes",
      "columns": [{
        "type": "STR",
        "name": "scheme_name"
      }, {
        "type": "UINT",
        "name": "fwd_pid"
      }, {
        "type": "STR",
        "name": "fwd_cmd"
      }, {
        "type": "UINT",
        "name": "admin_app_pid"
      }, {
        "type": "STR",
        "name": "admin_app_cmd"
      }],
      "description": "Declared endpoint naming schemes."
    },
    {
      "name": "egress_plans",
      "columns": [{
        "type": "STR",
        "name": "neighbor_eid"
      }, {
        "type": "UINT",
        "name": "clm_pid"
      }, {
        "type": "UINT",
        "name": "nominal_rate"
      }],
      "description": "Egress plans."
    }
  ],
  "Ctrl": [{
      "name": "endpoint_add",
      "parmspec": [{
        "type": "STR",
        "name": "endpoint_id"
      }, {
        "type": "UINT",
        "name": "type"
      }, {
        "type": "STR",
        "name": "rcv_script"
      }],
      "description": "Establish DTN endpoint named endpointId on the 
                      local node. The remaining parameters indicate 
                      what is to be done when bundles destined for 
                      this endpoint arrive at a time when no 
                      application has the endpoint open for bundle 
                      reception. If type is 'x', then such bundles 
                      are to be discarded silently and immediately. 
                      If type is 'q', then such bundles are to be 
                      enqueued for later delivery and, if recvScript 
                      is provided, recvScript is to be executed."
    },
    {
      "name": "endpoint_change",
      "parmspec": [{
        "type": "STR",
        "name": "endpoint_id"
      }, {
        "type": "UINT",
        "name": "type"
      }, {
        "type": "STR",
        "name": "rcv_script"
      }],
      "description": "Change the action taken when bundles destined 
                      for this endpoint arrive at a time when no 
                      application has the endpoint open for bundle 
                      reception."
    },
    {
      "name": "endpoint_del",
      "parmspec": [{
        "type": "STR",
        "name": "endpoint_id"
      }],
      "description": "Delete the endpoint identified by endpointId. 
                      The control will fail if any bundles are 
                      currently pending delivery to this endpoint."
    },
    {
      "name": "induct_add",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "STR",
        "name": "cli_control"
      }],
      "description": "Establish a duct for reception of bundles via 
                      the indicated CL protocol. The duct's data 
                      acquisition structure is used and populated by 
                      the induct task whose operation is initiated by 
                      cliControl at the time the duct is started."
    },
    {
      "name": "induct_change",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "STR",
        "name": "cli_control"
      }],
      "description": "Change the control used to initiate operation 
                      of the induct task for the indicated duct."
    },
    {
      "name": "induct_del",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Delete the induct identified by protocolName and 
                      ductName. The control will fail if any bundles 
                      are currently pending acquisition via this 
                      induct."
    },
    {
      "name": "induct_start",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Start the indicated induct task as defined for 
                      the indicated CL protocol on the local node."
    },
    {
      "name": "induct_stop",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Stop the indicated induct task as defined for 
                      the indicated CL protocol on the local node."
    },
    {
      "name": "manage_heap_max",
      "parmspec": [{
        "type": "UINT",
        "name": "max_database_heap_per_acquisition"
      }],
      "description": "Declare the maximum number of bytes of SDR heap 
                      space that will be occupied by any single bundle 
                      acquisition activity (nominally the acquisition 
                      of a single bundle, but this is at the 
                      discretion of the convergence-layer input task). 
                      All data acquired in excess of this limit will 
                      be written to a temporary file pending extraction 
                      and dispatching of the acquired bundle or 
                      bundles. The default is the minimum allowed 
                      value (560 bytes), which is the approximate size 
                      of a ZCO file reference object; this is the 
                      minimum SDR heap space occupancy in the event 
                      that all acquisition is into a file."
    },
    {
      "name": "outduct_add",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "STR",
        "name": "clo_command"
      }, {
        "type": "UINT",
        "name": "max_payload_length"
      }],
      "description": "Establish a duct for transmission of bundles via 
                      the indicated CL protocol. the duct's data 
                      transmission structure is serviced by the outduct 
                      task whose operation is initiated by 
                      CLOcommand at the time the duct is started. A 
                      value of zero for maxPayloadLength indicates 
                      that bundles of any size can be accommodated; 
                      this is the default."
    },
    {
      "name": "outduct_change",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }, {
        "type": "STR",
        "name": "clo_control"
      }, {
        "type": "UINT",
        "name": "max_payload_length"
      }],
      "description": "Set new values for the indicated duct's payload 
                      size limit and the control that is used to 
                      initiate operation of the outduct task for this 
                      duct."
    },
    {
      "name": "outduct_del",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Delete the outduct identified by protocolName 
                      and ductName. The control will fail if any 
                      bundles are currently pending transmission 
                      via this outduct."
    },
    {
      "name": "outduct_start",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Start the indicated outduct task as defined for 
                      the indicated CL protocol on the local node."
    },
    {
      "name": "egress_plan_block",
      "parmspec": [{
        "type": "STR",
        "name": "plan_name"
      }],
      "description": "Disable transmission of bundles queued for 
                      transmission to the indicated node and 
                      reforwards all non-critical bundles currently 
                      queued for transmission to this node. This may 
                      result in some or all of these bundles being 
                      enqueued for transmission to the psuedo-node 
                      limbo."
    },
    {
      "name": "egress_plan_unblock",
      "parmspec": [{
        "type": "STR",
        "name": "plan_name"
      }],
      "description": "Re-enable transmission of bundles to the 
                      indicated node and reforwards all bundles in 
                      limbo in the hope that the unblocking of this 
                      egress plan will enable some of them to be 
                      transmitted."
    },
    {
      "name": "outduct_stop",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "STR",
        "name": "duct_name"
      }],
      "description": "Stop the indicated outduct task as defined for 
                      the indicated CL protocol on the local node."
    },
    {
      "name": "protocol_add",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }, {
        "type": "UINT",
        "name": "payload_bytes_per_frame"
      }, {
        "type": "UINT",
        "name": "overhead_bytes_per_frame"
      }, {
        "type": "UINT",
        "name": "nominal_data_rate"
      }],
      "description": "Establish access to the named convergence layer 
                      protocol at the local node. The 
                      payloadBytesPerFrame and overheadBytesPerFrame 
                      arguments are used in calculating the estimated 
                      transmission capacity consumption of each 
                      bundle, to aid in route computation and 
                      congesting forecasting. The optional 
                      nominalDataRate argument overrides the hard 
                      coded default continuous data rate for the 
                      indicated protocol for purposes of rate control. 
                      For all promiscuous prototocols-that is, 
                      protocols whose outducts are not specifically 
                      dedicated to transmission to a single identified 
                      convergence-layer protocol endpoint- the 
                      protocol's applicable nominal continuous data 
                      rate is the data rate that is always used for 
                      rate control over links served by that protocol; 
                      data rates are not extracted from contact graph 
                      information. This is because only the induct and 
                      outduct throttles for non-promiscuous protocols 
                      (LTP, TCP) can be dynamically adjusted in 
                      response to changes in data rate between the 
                      local node and its neighbors, as enacted per the 
                      contact plan. Even for an outduct of a 
                      non-promiscuous protocol the nominal data rate 
                      may be the authority for rate control, in the 
                      event that the contact plan lacks identified 
                      contacts with the node to which the outduct is 
                      mapped."
    },
    {
      "name": "protocol_del",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }],
      "description": "Delete the convergence layer protocol identified 
                      by protocolName. The control will fail if any 
                      ducts are still locally declared for this 
                      protocol."
    },
    {
      "name": "protocol_start",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }],
      "description": "Start all induct and outduct tasks for inducts 
                      and outducts that have been defined for the 
                      indicated CL protocol on the local node."
    },
    {
      "name": "protocol_stop",
      "parmspec": [{
        "type": "STR",
        "name": "protocol_name"
      }],
      "description": "Stop all induct and outduct tasks for inducts 
                      and outducts that have been defined for the 
                      indicated CL protocol on the local node."
    },
    {
      "name": "scheme_add",
      "parmspec": [{
        "type": "STR",
        "name": "scheme_name"
      }, {
        "type": "STR",
        "name": "forwarder_control"
      }, {
        "type": "STR",
        "name": "admin_app_control"
      }],
      "description": "Declares an endpoint naming scheme for use in 
                      endpoint IDs, which are structured as URIs: 
                      schemeName:schemeSpecificPart. forwarderControl 
                      will be executed when the scheme is started on 
                      this node, to initiate operation of a forwarding 
                      daemon for this scheme. adminAppControl will 
                      also be executed when the scheme is started on 
                      this node, to initiate operation of a daemon 
                      that opens a custodian endpoint identified within 
                      this scheme so that it can receive and process 
                      custody signals and bundle status reports."
    },
    {
      "name": "scheme_change",
      "parmspec": [{
        "type": "STR",
        "name": "scheme_name"
      }, {
        "type": "STR",
        "name": "forwarder_control"
      }, {
        "type": "STR",
        "name": "admin_app_control"
      }],
      "description": "Set the indicated scheme's forwarderControl and 
                      adminAppControl to the strings provided as 
                      arguments."
    },
    {
      "name": "scheme_del",
      "parmspec": [{
        "type": "STR",
        "name": "scheme_name"
      }],
      "description": "Delete the scheme identified by schemeName. The 
                      control will fail if any bundles identified in 
                      this scheme are pending forwarding, 
                      transmission, or delivery."
    },
    {
      "name": "scheme_start",
      "parmspec": [{
        "type": "STR",
        "name": "scheme_name"
      }],
      "description": "Start the forwarder and administrative endpoint 
                      tasks for the indicated scheme task on the local 
                      node."
    },
    {
      "name": "scheme_stop",
      "parmspec": [{
        "type": "STR",
        "name": "scheme_name"
      }],
      "description": "Stop the forwarder and administrative endpoint 
                      tasks for the indicated scheme task on the 
                      local node."
    },
    {
      "name": "watch",
      "parmspec": [{
        "type": "UINT",
        "name": "status"
      }, {
        "type": "STR",
        "name": "activity_spec"
      }],
      "description": "Enable/Disable production of a continuous stream 
                      of user selected Bundle Protocol activity 
                      indication characters. A watch parameter of 1 
                      selects all BP activity indication characters, 0 
                      deselects allBP activity indication characters; 
                      any other activitySpec such as acz~ selects all 
                      activity indication characters in the string, 
                      deselecting all others. BP will print each 
                      selected activity indication character to stdout 
                      every time a processing event of the associated 
                      type occurs: a new bundle is queued for 
                      forwarding, b bundle is queued for transmission, 
                      c bundle is popped from its transmission queue, 
                      m custody acceptance signal is received, w 
                      custody of bundle is accepted, x custody of 
                      bundle is refused, y bundle is accepted upon 
                      arrival, z bundle is queued for delivery to an 
                      application, ~ bundle is abandoned (discarded) 
                      on attempt to forward it, ! bundle is destroyed 
                      due to TTL expiration, &amp; custody refusal 
                      signal is recieved, # bundle is queued for 
                      re-forwarding due to CL protocol failures, 
                      j bundle is placed in 'limbo' for possible 
                      future reforwarding, k bundle is removed from 
                      'limbo' and queued for reforwarding, $ bundle's 
                      custodial retransmission timeout interval 
                      expired."
    }
  ]
}
      </artwork>
    </figure>
  </t>
      </section>

				    
    <section anchor="IANA" title="IANA Considerations" toc="default">
      <t>
		At this time, this protocol has no fields registered by IANA.
	  </t>
    </section>
  </middle>

   <!--  *****BACK MATTER ***** -->
   <back>
      <references title="Informative References">
               <?rfc include="reference.I-D.draft-birrane-dtn-ama-07"?>
         
      </references>
      
      <references title="Normative References">
       
         &RFC2119;     
       
        
         
 <?rfc include="reference.I-D.draft-birrane-dtn-adm-02"?>
 <?rfc include="reference.I-D.draft-birrane-dtn-amp-04"?>
      </references>
    
  </back>
</rfc>