Internet DRAFT - draft-birrane-dtn-adm-ion-bpadmin
draft-birrane-dtn-adm-ion-bpadmin
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-ion-bpadmin-01
Abstract
This document describes the Application Data Model (ADM) for the
administration of Bundle Protocol (BP) ION 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 Admin 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 . . . . . . . . . . . . . . . . . . 4
3.1. Namespace and Nicknames . . . . . . . . . . . . . . . . . 4
4. ION BP Admin ADM JSON Encoding . . . . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1. Informative References . . . . . . . . . . . . . . . . . 17
6.2. Normative References . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
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.
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.
1.1. Technical Notes
o This document describes Version 0.0 of the ION BP Admin ADM.
o 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.
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 Admin ADM March 2019
1.2. Scope
This ADM specifies those components of the Asynchronous Management
Model (AMM) common to the configuration and management of Bundle
Protocol in ION.
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 Admin ADM's structure is in accordance to
[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).
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.
Birrane, et al. Expires September 12, 2019 [Page 3]
Internet-Draft BP Admin ADM March 2019
3. Naming and Identification
This section outlines the namespaces used to uniquely identify ADM
objects in this specification.
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/ION/bpadmin/ |
| | |
| ADM Enumeration | 5 |
+-----------------+------------------+
Table 1: Namespace Information
Given the above ADM enumeration, in accordance with
[I-D.birrane-dtn-amp], the following AMP nicknames are defined.
Birrane, et al. Expires September 12, 2019 [Page 4]
Internet-Draft BP Admin ADM March 2019
+----------+------------------------------+
| Nickname | Collection |
+----------+------------------------------+
| 100 | DTN/ION/bpadmin/Const |
| | |
| 101 | DTN/ION/bpadmin/Ctrl |
| | |
| 102 | DTN/ION/bpadmin/Edd |
| | |
| 103 | DTN/ION/bpadmin/Mac |
| | |
| 104 | DTN/ION/bpadmin/Oper |
| | |
| 105 | DTN/ION/bpadmin/Rptt |
| | |
| 107 | DTN/ION/bpadmin/Tblt |
| | |
| 109 | DTN/ION/bpadmin/Var |
| | |
| 110 | DTN/ION/bpadmin/Mdat |
| | |
| 111-119 | DTN/ION/bpadmin/Reserved |
+----------+------------------------------+
Table 2: ION BP ADM Nicknames
4. ION BP Admin ADM JSON Encoding
The following is the JSON encoding of the Bundle Protocol Admin
Application Data Model:
{
"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",
Birrane, et al. Expires September 12, 2019 [Page 5]
Internet-Draft BP Admin ADM March 2019
"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."
Birrane, et al. Expires September 12, 2019 [Page 6]
Internet-Draft BP Admin ADM March 2019
},
{
"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"
Birrane, et al. Expires September 12, 2019 [Page 7]
Internet-Draft BP Admin ADM March 2019
}, {
"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
Birrane, et al. Expires September 12, 2019 [Page 8]
Internet-Draft BP Admin ADM March 2019
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
Birrane, et al. Expires September 12, 2019 [Page 9]
Internet-Draft BP Admin ADM March 2019
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"
Birrane, et al. Expires September 12, 2019 [Page 10]
Internet-Draft BP Admin ADM March 2019
}, {
"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
Birrane, et al. Expires September 12, 2019 [Page 11]
Internet-Draft BP Admin ADM March 2019
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."
Birrane, et al. Expires September 12, 2019 [Page 12]
Internet-Draft BP Admin ADM March 2019
},
{
"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"
}, {
Birrane, et al. Expires September 12, 2019 [Page 13]
Internet-Draft BP Admin ADM March 2019
"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."
},
{
Birrane, et al. Expires September 12, 2019 [Page 14]
Internet-Draft BP Admin ADM March 2019
"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"
Birrane, et al. Expires September 12, 2019 [Page 15]
Internet-Draft BP Admin ADM March 2019
}, {
"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"
}, {
Birrane, et al. Expires September 12, 2019 [Page 16]
Internet-Draft BP Admin ADM March 2019
"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, & 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."
}
]
}
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.
Birrane, et al. Expires September 12, 2019 [Page 17]
Internet-Draft BP Admin ADM March 2019
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.
[I-D.birrane-dtn-amp]
Birrane, E., "Asynchronous Management Protocol", draft-
birrane-dtn-amp-04 (work in progress), June 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 18]
