ION Administration Application Data Model
draft-birrane-dtn-adm-ionadmin-00

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 January 3, 2019.

Copyright Notice

Copyright (c) 2018 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.

Table of Contents

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

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

• This document describes Version 0.0 of the ION Admin ADM.
• 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.
• 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.

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.

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

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

4. ION Admin ADM JSON Encoding

{
  "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."
    },
    {
      "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 when the node will be predicted to be no
        longer congested."
    },
    {
      "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
        30% 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 30% 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": "utc_delta",
      "type": "UINT",
      "description": "The UTC 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 UTC 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 UTC 
        delta to the UTC 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":"STR","name":"dest_node"},
        {"type":"REAL32","name":"xmit_data"},
        {"type":"REAL32","name":"prob"}
      ],
      "description": "This table shows all scheduled periods of data 
        transmission."
    },
    {
      "name": "describe_usage",
      "columns": [
        {"type":"UINT","name":"current_data_space_occupancy"},
        {"type":"UINT","name":"total_zcp_space_occupancy"},
        {"type":"UINT","name":"max_lvl_occupancy"}
      ],
      "description": "This table shows ION's current data space 
        occupancy (the number of megabytes of space in the SDR 
        non-volatile heap and file system that are occupied by 
        inbound and outbound zero-copy objects), the total 
        zero-copy-object space occupancy ceiling, and the maximum level
        of occupancy predicted by the most recent ionadmin 
        congestion forecast computation."
    },
    {
      "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":"node_id"},
        {"type":"STR","name":"dest"},
        {"type":"FLOAT32","name":"data_rate"},
        {"type":"FLOAT32","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 past 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_utc_delta_set",
      "parmspec": [
        {"type":"UINT","name":"local_time_sec_after_utc"}
      ],
      "description": "This management control sets ION's understanding 
        of the current difference between correct UTC time and the 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."
    },
    {
      "name": "list_contacts",
      "description": "Lists all schedule periods of data transmission." 
    },
    {
      "name": "list_usage",
      "description": "Lists ION's current data space occupancy." 
    },
    {
      "name": "list_ranges",
      "description": "Lists all predefined periods of constant distance 
        between nodes." 
    }
  ]
}
      

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

5. IANA Considerations

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

6. References

6.1. Informative References

6.2. Normative References

Authors' Addresses