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

Versions: 00 01

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

Abstract

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

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                ION 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 Admin ADM JSON Encoding . . . . . . . . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  15
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  15
     6.1.  Informative References  . . . . . . . . . . . . . . . . .  15
     6.2.  Normative References  . . . . . . . . . . . . . . . . . .  15
   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.

   The ION Administration ADM contains all of the functionality that is
   required for the proper configuration and management of ION nodes.

1.1.  Technical Notes

   o  This document describes Version 0.0 of the ION Admin 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                ION Admin ADM                   March 2019


1.2.  Scope

   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.

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




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


Internet-Draft                ION Admin ADM                   March 2019


   that particular ADM.  This is important for identification purposes
   of the ADMs and to ensure version control of the encoding.

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/ionadmin |
                  |                 |                  |
                  | ADM Enumeration |        7         |
                  +-----------------+------------------+

                      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                ION Admin ADM                   March 2019


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

                     Table 2: ION Admin ADM Nicknames

4.  ION Admin ADM JSON Encoding

   The following is the JSON encoding of the ION Administration
   Application Data Model:


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



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


Internet-Draft                ION Admin ADM                   March 2019


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



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


Internet-Draft                ION Admin ADM                   March 2019


      "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



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


Internet-Draft                ION Admin ADM                   March 2019


                      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"



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


Internet-Draft                ION Admin ADM                   March 2019


      }],
      "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



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


Internet-Draft                ION Admin ADM                   March 2019


                      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



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


Internet-Draft                ION Admin ADM                   March 2019


                      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



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


Internet-Draft                ION Admin ADM                   March 2019


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



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


Internet-Draft                ION Admin ADM                   March 2019


      "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"
      }, {



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


Internet-Draft                ION Admin ADM                   March 2019


        "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



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


Internet-Draft                ION Admin ADM                   March 2019


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


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.

   [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






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


Internet-Draft                ION Admin ADM                   March 2019


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


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