| 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 |
ION Administration Application Data Model
draft-birrane-dtn-adm-ionadmin-01
This document describes the Application Data Model (ADM) for the administration of ION in compliance with the template provided by [I-D.birrane-dtn-adm].
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 (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.
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 Administration ADM contains all of the functionality that is required for the proper configuration and management of ION nodes.
This ADM specifies those components of the Asynchronous Management Model (AMM) common to the administration of 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.
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.
The ION Admin ADM's structure is in accordance with [I-D.birrane-dtn-adm]. This ADM contains metadata, edd, table templates, and controls. Externally Defined Data (EDD) are values that are calculated external to the ADM system. 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, 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 the node on the local computer that is running ION. The core functions of the administration of ION nodes that are included in this ADM deal with contacts (information about periods of data transmission), ranges (periods of time when the distance between two nodes is constant), occupancy limits (the maximum amount of megabytes of storage space in ION's SDR non volatile heap and/or local file system), rates of data production, congestion, consumption (rate of continuous data delivery to local BP applications), and time.
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 of the encoding.
This section outlines the namespaces used to uniquely identify ADM objects in this specification.
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/ionadmin |
| ADM Enumeration | 7 |
Given the above ADM enumeration, in accordance with [I-D.birrane-dtn-amp], the following AMP nicknames are defined.
| Nickname | Collection |
|---|---|
| 140 | DTN/ION/ionadmin/Const |
| 141 | DTN/ION/ionadmin/Ctrl |
| 142 | DTN/ION/ionadmin/Edd |
| 143 | DTN/ION/ionadmin/Mac |
| 144 | DTN/ION/ionadmin/Oper |
| 145 | DTN/ION/ionadmin/Rptt |
| 147 | DTN/ION/ionadmin/Tblt |
| 149 | DTN/ION/ionadmin/Var |
| 150 | DTN/ION/ionadmin/Mdat |
| 151-159 | DTN/ION/ionadmin/Reserved |
{
"Mdat": [{
"name": "name",
"type": "STR",
"value": "ion_admin",
"description": "The human-readable name of the ADM."
},
{
"name": "namespace",
"type": "STR",
"value": "DTN/ION/ionadmin",
"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": "clock_error",
"type": "UINT",
"description": "This is how accurate the ION Agent's clock is
described as number of seconds, an absolute
value."
},
{
"name": "clock_sync",
"type": "UINT",
"description": "This is whether or not the the computer on
which the local ION node is running has a
synchronized clock."
},
{
"name": "congestion_alarm_control",
"type": "UINT",
"description": "This is whether or not the node has a control
that will set off alarm if it will become
congested at some future time."
},
{
"name": "congestion_end_time_forecasts",
"type": "UINT",
"description": "This is the time horizon beyond which we don't
attempt to forecast congestion"
},
{
"name": "consumption_rate",
"type": "UINT",
"description": "This is the mean rate of continuous data
delivery to local BP applications."
},
{
"name": "inbound_file_system_occupancy_limit",
"type": "UINT",
"description": "This is the maximum number of megabytes of
storage space in ION's local file system that
can be used for the storage of inbound zero-copy
objects. The default heap limit is 1 Terabyte."
},
{
"name": "inbound_heap_occupancy_limit",
"type": "UINT",
"description": "This is the maximum number of megabytes of
storage space in ION's SDR non-volatile heap
that can be used for the storage of inbound
zero-copy objects. The default heap limit is
20% of the SDR data space's total heap size."
},
{
"name": "number",
"type": "UINT",
"description": "This is a CBHE node number which uniquely
identifies the node in the delay-tolerant
network."
},
{
"name": "outbound_file_system_occupancy_limit",
"type": "UINT",
"description": "This is the maximum number of megabytes of
storage space in ION's local file system that
can be used for the storage of outbound
zero-copy objects. The default heap limit is
1 Terabyte."
},
{
"name": "outbound_heap_occupancy_limit",
"type": "UINT",
"description": "This is the maximum number of megabytes of
storage space in ION's SDR non-volatile heap
that can be used for the storage of outbound
zero-copy objects. The default heap limit is
20% of the SDR data space's total heap size."
},
{
"name": "production_rate",
"type": "UINT",
"description": "This is the rate of local data production."
},
{
"name": "ref_time",
"type": "TV",
"description": "This is the reference time that will be used
for interpreting relative time values from now
until the next revision of reference time."
},
{
"name": "time_delta",
"type": "UINT",
"description": "The time delta is used to compensate for error
(drift) in clocks, particularly spacecraft
clocks. The hardware clock on a spacecraft
might gain or lose a few seconds every month,
to the point at which its understanding of the
current time - as reported out by the operating
system - might differ significantly from the
actual value of Unix Epoch time as reported by
authoritative clocks on Earth. To compensate for
this difference without correcting the clock
itself (which can be difficult and dangerous),
ION simply adds the time delta to the Epoch
time reported by the operating system."
},
{
"name": "version",
"type": "STR",
"description": "This is the version of ION that is currently
installed."
}
],
"Tblt": [{
"name": "contacts",
"columns": [{
"type": "TV",
"name": "start_time"
}, {
"type": "TV",
"name": "stop_time"
}, {
"type": "UINT",
"name": "source_node"
}, {
"type": "UINT",
"name": "dest_node"
}, {
"type": "UVAST",
"name": "xmit_data"
}, {
"type": "UVAST",
"name": "confidence"
}],
"description": "This table shows all scheduled periods of data
transmission."
},
{
"name": "ranges",
"columns": [{
"type": "TV",
"name": "start"
}, {
"type": "TV",
"name": "stop"
}, {
"type": "UINT",
"name": "node"
}, {
"type": "UINT",
"name": "other_node"
}, {
"type": "UINT",
"name": "distance"
}],
"description": "This table shows all predicted periods of
constant distance between nodes."
}
],
"Ctrl": [{
"name": "node_init",
"parmspec": [{
"type": "UINT",
"name": "node_nbr"
}, {
"type": "STR",
"name": "config_file"
}],
"description": "Until this control is executed, the local ION
node does not exist and most ionadmin controls
will fail. The control configures the local node
to be identified by node_number, a CBHE node
number which uniquely identifies the node in
the delay-tolerant network. It also configures
ION's data space (SDR) and shared working-memory
region. For this purpose it uses a set of
default settings if no argument follows
node_number or if the argument following
node_number is ''; otherwise it uses the
configuration settings found in a configuration
file. If configuration file name is provided,
then the configuration file's name is
implicitly 'hostname.ionconfig'; otherwise,
ion_config_filename is taken to be the explicit
configuration file name."
},
{
"name": "node_clock_error_set",
"parmspec": [{
"type": "UINT",
"name": "known_maximum_clock_error"
}],
"description": "This management control sets ION's understanding
of the accuracy of the scheduled start and stop
times of planned contacts, in seconds. The
default value is 1."
},
{
"name": "node_clock_sync_set",
"parmspec": [{
"type": "BOOL",
"name": "new_state"
}],
"description": "This management control reports whether or not
the computer on which the local ION node is
running has a synchronized clock."
},
{
"name": "node_congestion_alarm_control_set",
"parmspec": [{
"type": "STR",
"name": "congestion_alarm_control"
}],
"description": "This management control establishes a control
which will automatically be executed whenever
ionadmin predicts that the node will become
congested at some future time."
},
{
"name": "node_congestion_end_time_forecasts_set",
"parmspec": [{
"type": "UINT",
"name": "end_time_for_congestion_forcasts"
}],
"description": "This management control sets the end time for
computed congestion forecasts. Setting
congestion forecast horizon to zero sets the
congestion forecast end time to infinite time
in the future: if there is any predicted net
growth in bundle storage space occupancy at all,
following the end of the last scheduled contact,
then eventual congestion will be predicted. The
default value is zero, i.e., no end time."
},
{
"name": "node_consumption_rate_set",
"parmspec": [{
"type": "UINT",
"name": "planned_data_consumption_rate"
}],
"description": "This management control sets ION's expectation
of the mean rate of continuous data delivery to
local BP applications throughout the period of
time over which congestion forecasts are
computed. For nodes that function only as routers
this variable will normally be zero. A value of
-1, which is the default, indicates that the
rate of local data consumption is unknown; in
that case local data consumption is not
considered in the computation of congestion
forecasts."
},
{
"name": "node_contact_add",
"parmspec": [{
"type": "TV",
"name": "start"
}, {
"type": "TV",
"name": "stop"
}, {
"type": "UINT",
"name": "from_node_id"
}, {
"type": "UINT",
"name": "to_node_id"
}, {
"type": "UVAST",
"name": "data_rate"
}, {
"type": "UVAST",
"name": "prob"
}],
"description": "This control schedules a period of data
transmission from source_node to dest_node. The
period of transmission will begin at start_time
and end at stop_time, and the rate of data
transmission will be xmit_data_rate bytes/second.
Our confidence in the contact defaults to 1.0,
indicating that the contact is scheduled - not
that non-occurrence of the contact is impossible,
just that occurrence of the contact is planned
and scheduled rather than merely imputed from
ast node behavior. In the latter case,
confidence indicates our estimation of the
likelihood of this potential contact."
},
{
"name": "node_contact_del",
"parmspec": [{
"type": "TV",
"name": "start"
}, {
"type": "UINT",
"name": "node_id"
}, {
"type": "STR",
"name": "dest"
}],
"description": "This control deletes the scheduled period of
data transmission from source_node to dest_node
starting at start_time. To delete all contacts
between some pair of nodes, use '*' as
start_time."
},
{
"name": "node_inbound_heap_occupancy_limit_set",
"parmspec": [{
"type": "UINT",
"name": "heap_occupancy_limit"
}, {
"type": "UINT",
"name": "file_system_occupancy_limit"
}],
"description": "This management control sets the maximum number
of megabytes of storage space in ION's SDR
non-volatile heap that can be used for the
storage of inbound zero-copy objects. A value
of -1 for either limit signifies 'leave
unchanged'. The default heap limit is 30% of
the SDR data space's total heap size."
},
{
"name": "node_outbound_heap_occupancy_limit_set",
"parmspec": [{
"type": "UINT",
"name": "heap_occupancy_limit"
}, {
"type": "UINT",
"name": "file_system_occupancy_limit"
}],
"description": "This management control sets the maximum number
of megabytes of storage space in ION's SDR
non-volatile heap that can be used for the
storage of outbound zero-copy objects. A value
of -1 for either limit signifies 'leave
unchanged'. The default heap limit is 30% of
the SDR data space's total heap size."
},
{
"name": "node_production_rate_set",
"parmspec": [{
"type": "UINT",
"name": "planned_data_production_rate"
}],
"description": "This management control sets ION's expectation
of the mean rate of continuous data origination
by local BP applications throughout the period
of time over which congestion forecasts are
computed. For nodes that function only as
routers this variable will normally be zero. A
value of -1, which is the default, indicates
that the rate of local data production is unknown;
in that case local data production is not
considered in the computation of congestion
forecasts."
},
{
"name": "node_range_add",
"parmspec": [{
"type": "TV",
"name": "start"
}, {
"type": "TV",
"name": "stop"
}, {
"type": "UINT",
"name": "node"
}, {
"type": "UINT",
"name": "other_node"
}, {
"type": "UINT",
"name": "distance"
}],
"description": "This control predicts a period of time during
which the distance from node to other_node will
be constant to within one light second. The
period will begin at start_time and end at
stop_time, and the distance between the nodes
during that time will be distance light seconds."
},
{
"name": "node_range_del",
"parmspec": [{
"type": "TV",
"name": "start"
}, {
"type": "UINT",
"name": "node"
}, {
"type": "UINT",
"name": "other_node"
}],
"description": "This control deletes the predicted period of
constant distance between node and other_node
starting at start_time. To delete all ranges
between some pair of nodes, use '*' as
start_time."
},
{
"name": "node_ref_time_set",
"parmspec": [{
"type": "TV",
"name": "time"
}],
"description": "This is used to set the reference time that will
be used for interpreting relative time values
from now until the next revision of reference
time. Note that the new reference time can be
a relative time, i.e., an offset beyond the
current reference time."
},
{
"name": "node_time_delta_set",
"parmspec": [{
"type": "UINT",
"name": "local_time_sec_after_epoch"
}],
"description": "This management control sets ION's understanding
of the current difference between correct time
and the Unix Epoch time values reported by the
clock for the local ION node's computer. This
delta is automatically applied to locally
obtained time values whenever ION needs to know
the current time."
}
]
}
The following is the JSON encoding of the ION Administration Application Data Model:
At this time, this protocol has no fields registered by IANA.
| [I-D.birrane-dtn-ama] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-07, June 2018. |
| [I-D.birrane-dtn-adm] | Birrane, E., DiPietro, E. and D. Linko, "AMA Application Data Model", Internet-Draft draft-birrane-dtn-adm-02, June 2018. |
| [I-D.birrane-dtn-amp] | Birrane, E., "Asynchronous Management Protocol", Internet-Draft draft-birrane-dtn-amp-04, 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. |