| Delay-Tolerant Networking | E. Birrane |
| Internet-Draft | E. DiPietro |
| Intended status: Informational | D. Linko |
| Expires: January 3, 2019 | Johns Hopkins Applied Physics Laboratory |
| M. Sinkiat | |
| ASRC Space And Defense, NASA GSFC | |
| July 2, 2018 |
AMP Manager SQL Interface
draft-birrane-dtn-ampmgr-sql-01
This document describes a proposed public interface through which an application, such as a network management console, interacts with an Asynchronous Management Protocol (AMP) Manager via a database supporting the Structured Query Language (SQL). The use of SQL as an interfacing layer provides a natural way to describe interactions with an AMP Manager independent of a particular implementation of either the Manager or the application. Specifically, this document presents a database schema capturing how to send controls to a Manager and how to accept reports received by a Manager from one or more AMP Agents.
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 (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.
This document presents a public interface through which an application, such as a network management console, interacts with an Asynchronous Management Protocol ([I-D.birrane-dtn-amp]) Manager via a database supporting the Structured Query Language (SQL). Such an interface is useful as an implementation independent way of specifying how an application may interact with an AMP Manager to issue commands (such as through a custom graphical user interface) and to receive reports (as they are received by one or more AMP Agents).
This document describes a database layout comprised of a series of names tables and the columns the comprise those tables. Where appropriate, primary and foreign key constraints are also discussed. This set of tables presents a data model through which all AMP Manager roles and responsibilities, as defined in the Asynchronous Management Architecture ([I-D.birrane-dtn-ama]), can be accomplished.
Application developers can use this specification to describe how to populate a database with AMP-related information such that an AMP Manager implementation can read and use this data to effect AMP behavior. By reading and writing the tables in accordance with this specification, applications can claim conformance with the AMP Manager regardless of which AMP Manager implementation is used, so long as such a Manager is also in conformance with this specification.
AMP Manager developers use this specification to describe how AMP users input actions to the Manager and how to send received reports back to those users.
This document covers table names and the names, data types, default values, and comments associated with each column of each names table. These types should be appropriate for any database implementing a SQL interface and SHOULD NOT use any language or function specific to a particular SQL database vendor.
This document does not specify the setup, configuration, administration, or other function associated with a particular SQL database vendor. Further, this document does not specify how either the application or the AMP Manager log on to the database, or how database communications are verified and secured. Finally, this document does not discuss the architecture associated with incorporating a database between an application and an AMP Manager, as such architectures are likely tightly coupled to a network deployment.
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.
This specification assumes that all tables exist in a database called "amp_core", capturing the information necessary to capture core operations associated with the AMP Manager.
The schema contains tables capturing information about various areas of the AMP Manager interface. The following table types are defined.
+-----------------------+------------------------+
| Table Name | Table Type |
+-----------------------+------------------------+
| data_type | Constants |
| incoming_state | Constants |
| outgoing_state | Constants |
| tnvc_set | Compound Data Type |
| tnvc | Compound Data Type |
| expression_set | Compound Data Type |
| expression | Compound Data Type |
| in_type_set | Operator Support |
| in_type | Operator Support |
| adm_nickname | ADM Support |
| adm | ADM Support |
| parmspec | ADM Support |
| parmspec_set | ADM Support |
| registered_agents | Agent Support |
| data | ARI Information |
| data_set | ARI Information |
| ac | ARI Information |
| ac_set | ARI Information |
| ari | ARI Information |
| ari_definition | ARI Information |
| outgoing_message_group| Outgoing Support |
| outgoing_message | Outgoing Support |
| incoming_message_group| Incoming Support |
| incoming_message | Incoming Support |
+-----------------------+------------------------+
Figure 1: amp_core tables
The specification comprises tables, as in Figure 1.
Data types, as defined in the AMP, enumerate the types of information associated with collections of data, such as defined in ARI parameters, computed values, and report definitions.
+-------------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| enumeration | int(10) unsigned | NO | PRI | | |
| name | varchar(50) | NO | UNI | | |
| description | varchar(255) | NO | | "" | |
+-------------+------------------+------+-----+---------+-------+
data_types
The format of the table is as follows.
An example of such a table is illustrated in [I-D.birrane-dtn-adm].
When reports are being received by a Manager from an Agent, they will be written into various Incoming Support table types. However, the application reviewing these incoming reports should not start to read them until the Manager has finished receiving and persisting them into the database.
+-------------+---------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+---------------------+------+-----+---------+-------+
| state_id | tinyint(3) unsigned | NO | PRI | | |
| name | varchar(50) | NO | | | |
| description | varchar(255) | NO | | | |
+-------------+---------------------+------+-----+---------+-------+
incoming_state
The incoming_state table identifies three different wait states associated with receiving reports from Agents. The format of the table is defined as follows.
+----+--------------+-----------------------------------------+
| ID | Name | Description |
+----+--------------+-----------------------------------------+
| 0 | Initializing | Manager is receiving reports. |
| 1 | Ready | Manager has completed reception. |
| 2 | Processed | Application is done processing reports. |
+----+--------------+-----------------------------------------+
incoming_state example
An example of such a table is illustrated below.
When controls are being sent via a Manager to an Agent, they will be written into various Outgoing Support table types. However, the Manager receiving these outgoing controls should not start to read them until the application has finished writing them into the database.
+-------------+--------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| state_id | tinyint(4) | NO | PRI | | |
| name | varchar(50) | NO | | | |
| description | varchar(255) | NO | | | |
+-------------+--------------+------+-----+---------+-------+
outgoing_state
The outgoing_state table identifies four different wait states associated with sending controls to Agents. The format of the table is defined as follows.
+----------+--------------+---------------------------------+
| state_id | name | description |
+----------+--------------+---------------------------------+
| 0 | Initializing | Application writing controls. |
| 1 | Ready | Ready for Sending to Agent. |
| 2 | Processing | Manager sending controls. |
| 3 | Sent | Manager send completed. |
+----------+--------------+---------------------------------+
outgoing_state Example
An example of such a table is illustrated below.
+----------------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+----------------+------------------+------+-----+---------+-------+
| adm_id | int(10) unsigned | NO | MUL | | |
| nickname_enum | int(10) unsigned | NO | | | |
| label | varchar(255) | NO | | | |
+----------------+------------------+------+-----+------------+----+
adm_nicknames
The adm_nicknames table identifies all of the nicknames associated with supported ADMs. A Nickname is the compression of a shared portion of an ARI. Nickname enumerations MUST be unique. The format of the table is defined as follows.
+-------------+-----------------+------+-----+---------+---------------+
| Field | Type | Null | Key | Default | Extra |
+-------------+-----------------+------+-----+---------+---------------+
| adm_id | int(10) unsigned| NO | PRI | | auto_increment|
| name | varchar(255) | NO | UNI | | |
| version | varchar(255) | NO | | | |
| description | varchar(255) | NO | | | |
| Organization| varchar(255) | NO | | | |
+--------------+------------------+------+-----+---------+-------------+
adm
The adm table identifies all of the ADMs supported by the AMP Manager and associated application. The format of the table is as follows.
ARIs identifying items such as Controls may accept parameters to customize their behavior. When defined in the context of an ADM, a parameterized ARI only includes the non-parameterized portion of the ARI followed by the expected data types for the parameterized portion of the ARI. This, essentially, acts as a template for populating a specific instance of the ARI with actual data.
This "template" is referred to as a ARI, as it is used to generate ARI instances. The instances of an ARI are called ARI definitions. The amp_core database schema identifies three tables used to capture ARI definitions from ADMs: parmspec, parmspec_set, ari, and ari_definition.
+-----------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-----------+------------------+------+-----+---------+-------+
| name | varchar(45) | NO | | | |
| parm_id | int(10) unsigned | YES | MUL | NULL | |
| parm_order| int(10) unsigned | NO | UNI | 0 | |
| type_id | int(10) unsigned | YES | MUL | NULL | |
+-----------+------------------+------+-----+---------+-------+
parmspec
The parmspec table contains a row for each parameter associated with an ARI. All of the parameters for an ARI, together, are considered a "collection" of parameters. The format of the table is as follows.
+---------+------------------+------+-----+--------+----------------+
| Field | Type | Null | Key | Default| Extra |
+---------+------------------+------+-----+--------+----------------+
| parm_id | int(10) unsigned | NO | PRI | | auto_increment |
|comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+--------+----------------+
parmspec_set
The parmspec_set table represents the ordered set of parameters associated with an ARI. The format of the table is as follows.
+--------------+-------------------+------+-----+----------+----------+ | Field | Type | Null | Key | Default | Extra | +--------------+-------------------+------+-----+----------+----------+ | curr_id | int(10) unsigned | NO | PRI | | | | name | varchar(50) | NO | UNI | Unnamed | | | ari_id | int(10) unsigned | NO | MUL | | | | data_id | int(10) unsigned | NO | MUL | | | | description | varchar(255) | YES | | | | +--------------+-------------------+------+-----+----------+----------+
ari
The ari table captures the ARIs in the database. Some ARIs will be auto-populated from ADMs. Others will be added dynamically by users of the system. As per [AMP], an ARI without an identified Issuer field is assumed to be as defined in an ADM. The format of the table is defined as follows.
+---------------+-----------------+------+-----+---------+----------+
| Field | Type | Null | Key | Default | Extra |
+---------------+-----------------+------+-----+---------+----------+
| ari_id | int(10) unsigned| NO | PRI | | auto_inc |
| name | varchar(50) | NO | UNI | Unnamed | |
| type_id | int(10) unsigned| NO | MUL | NULL | |
| nn_id | int(10) unsigned| YES | MUL | NULL | |
| ari_bytestring| varchar(255) | NO | | | |
| parm_id | int(10) unsigned| YES | MUL | NULL | |
| issuer | bigint unsigned | YES | | NULL | |
| tag | bigint unsigned | YES | | NULL | |
| structure_id | varchar(255) | YES | MUL | NULL | |
| in_type_id | int(10) unsigned| YES | MUL | NULL | |
+---------------+-----------------+------+-----+---------+----------+
ari_definition
The ari_definition table stores the metadata of all known ARIs. The format of the table is as follows.
+------------+-----------------+------+-----+---------+---------------+
| Field | Type | Null | Key | Default | Extra |
+------------+-----------------+------+-----+---------+---------------+
| registry_id| int(10) unsigned| NO | PRI | | auto_increment|
| agent_id | varchar(128) | NO | | ipn:0.0 | |
+------------+-----------------+------+-----+---------+---------------+
registered_agents
The registered_agents table lists the network identifiers for each Agent known in the network. The format of the table is defined as follows.
Data collection tables capture the Data Collection (DC) data type as defined in [I-D.birrane-dtn-amp]. Similar to the parmspec and parmspec_set tables, Data Collections are represented as an ordered collection of individual data items, with one table representing the collection itself, and another table holding the ordered data within the collection.
+------------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+------------+------------------+------+-----+---------+-------+
| data_id | int(10) unsigned | NO | MUL | | |
| data_order | int(10) unsigned | NO | UNI | 0 | |
| data_type | int(10) unsigned | NO | MUL | | |
| ari_id | blob | YES | MUL | NULL | |
| byte | longblob | YES | | NULL | |
| tnvc_id | int(10) unsigned | NO | MUL | | |
| ac_id | int(10) unsigned | NO | MUL | | |
| vast | bigint | YES | | NULL | |
| uvast | bigint unsigned | YES | | NULL | |
| real | longblob | YES | | NULL | |
| str | varchar(255) | YES | | NULL | |
| bool | boolean | YES | | NULL | |
| ts | datetime | YES | | NULL | |
+------------+------------------+------+-----+---------+-------+
data_value
The data_value table holds data collection entries, one per row. The format of the table is defined as follows.
+-------+------------------+------+-----+----------+----------------+
| Field | Type | Null | Key | Default | Extra |
+-------+------------------+------+-----+----------+----------------+
|data_id| int(10) unsigned | NO | PRI | | auto_increment |
|comment| varchar(255) | NO | | | |
+-------+------------------+------+-----+----------+----------------+
data_set
The data_collection_set table holds information for a particular collection of data entries (from data_value). The format of the table is defined as follows.
A ARI Collection is an ordered set of ARI values, similar to a Data Collection, which is an ordered set of Data values. One table is used to represent the ARI Collection, and another table is used to capture the ordered ARIs in the collection.
+----------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+----------+------------------+------+-----+---------+-------+
| ac_id | int(10) unsigned | NO | MUL | | |
| ac_order | int(10) unsigned | NO | | 0 | |
| ari_id | int(10) unsigned | NO | MUL | | |
+----------+------------------+------+-----+---------+-------+
ac
The ac table holds ARI collection entries, one per row. The format of the table is defined as follows.
+---------+------------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+---------+------------------+------+-----+---------+----------------+
| ac_id | int(10) unsigned | NO | PRI | | auto_increment |
| comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+---------+----------------+
ac_set
The ac_set table holds information for a particular collection of ARIs (from the ac table). The format of the table is defined as follows.
+----------+------------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+----------+------------------+------+-----+---------+----------------+
|in_type_id| int(10) unsigned | NO | PRI | | auto_increment |
| comment | varchar(255) | NO | | | |
+----------+------------------+------+-----+---------+----------------+
in_type_set
The in_type_set table holds information for a particular collection of operator in types (from the in_types table). The format of the table is defined as follows.
+----------+------------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+----------+------------------+------+-----+---------+----------------+
|in_type_id| int(10) unsigned | NO | PRI | | auto_increment |
| name | varchar(255) | NO | | | |
| order | int(10) unsigned | NO | | | |
| type id | int(10) unsigned | NO | MUL | | |
+----------+------------------+------+-----+---------+----------------+
in_type_set
The in_type table holds information about operator in types. The format of the table is defined as follows.
Outgoing messages are those that are written into the database by an application and read by an AMP Manager, formatted, and sent to one or more AMP Agents.
The database represents outgoing messages in two tables. One table holds information for the entire outgoing message group, and another table captures each individual outgoing message. An individual outgoing message is simply a ARI collection of the ARIs to be run on the Agent.
+------------+-----------------+------+-----+---------+---------------+
| Field | Type | Null | Key | Default | Extra |
+------------+-----------------+------+-----+---------+---------------+
| message_id | int(10) unsigned| NO | PRI | | auto_increment|
| group_id | int(10) unsigned| NO | MUL | | |
| start_ts | datetime | NO | | 0 | |
| ac_id | int(10) unsigned| NO | MUL | | |
+------------+-----------------+------+-----+---------+---------------+
outgoing_message
The outgoing_message table captures a single ARI Collection holding the set of Control ARIs to be sent to an Agent as part of a Message Group. The format of the table is defined as follows.
+------------+-----------------+------+-----+---------+---------------+
| Field | Type | Null | Key | Default | Extra |
+------------+-----------------+------+-----+---------+---------------+
| group_id | int(10) unsigned| NO | PRI | | auto_increment|
| created_ts | datetime | YES | | NULL | |
| modified_ts| datetime | YES | | NULL | |
| state | tinyint(4) | NO | MUL | | |
| agent_id | int(10) unsigned| NO | MUL | | |
+------------+-----------------+------+-----+---------+---------------+
outgoing_message_group
The outgoing_message_group table captures an outgoing message group, which is one or more outgoing messages. The format of the table is defined as follows.
Incoming messages are those that are written into the database by an AMP Manager and read by an application wishing to understand the status of an AMP Agent.
The database represents incoming messages in two tables. One table holds information for the entire incoming message group, and another table captures each individual incoming message.
+------------+-----------------+------+-----+---------+---------------+
| Field | Type | Null | Key | Default | Extra |
+------------+-----------------+------+-----+---------+---------------+
| message_id | int(10) unsigned| NO | PRI | NULL | auto_increment|
| group_id | int(10) unsigned| NO | MUL | NULL | |
| ac_id | int(10) unsigned| YES | MUL | NULL | |
+------------+-----------------+------+-----+---------+---------------+
incoming_messages
The incoming_messages table captures information returned from an AMP Agent. The format of the table is defined as follows.
+-------------+---------------------+------+-----+---------+-----------+
| Field | Type | Null | Key | Default | Extra |
+-------------+---------------------+------+-----+---------+-----------+
| group_id | int(10) unsigned | NO | PRI | | auto_incr |
| recieved_ts | datetime | YES | | NULL | |
| generated_ts| datetime | YES | | NULL | |
| state | tinyint(3) unsigned | NO | MUL | | |
| agent_id | int(10) unsigned | NO | MUL | | |
+-------------+---------------------+------+-----+---------+-----------+
incoming_message_group
The incoming_message_group table captures an incoming message group, which is one or more incoming messages. The format of the table is defined as follows.
+----------+------------------+------+-----+---------+-----------+ | Field | Type | Null | Key | Default | Extra | +----------+------------------+------+-----+---------+-----------+ | tnvc_id | int(10) unsigned | NO | PRI | | auto_incr | | order | int(10) unsigned | NO | UNI | | | | name | int(10) unsigned | YES | | | | | value | int(10) unsigned | NO | MUL | | | +----------+------------------+------+-----+---------+-----------+
tnvc
The tnvc table is a group of tnv collections.
+----------+-----------------+------+-----+---------+-----------+
| Field | Type | Null | Key | Default | Extra |
+----------+-----------------+------+-----+---------+-----------+
| tnvc_id | int(10) unsigned| NO | PRI | NULL | auto_incr |
| comment | varchar(255) | NO | | | |
+----------+-----------------+------+-----+---------+-----------+
tnv_collection
The tnvc_set table provides the information of a TNV (Type-Name-Value) collection that describes data values in the AMM.
+---------+------------------+------+-----+---------+-----------+
| Field | Type | Null | Key | Default | Extra |
+---------+------------------+------+-----+---------+-----------+
| expr_id | int(10) unsigned | NO | PRI | NULL | auto_incr |
| comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+---------+-----------+
expression_set
The expression_set table shows the id of the expression as well as whether it is true or false. This table is a collection of expressions.
+-----------+------------------+------+-----+---------+-----------+
| Field | Type | Null | Key | Default | Extra |
+-----------+------------------+------+-----+---------+-----------+
| expr_id | int(10) unsigned | NO | PRI | NULL | auto_incr |
| order_num | int(10) unsigned | NO | UNI | NULL | |
| ari_id | int(10) unsigned | NO | MUL | NULL | |
+-----------+------------------+------+-----+---------+-----------+
expression
An expression is an AC in which a series of items are ordered so as to produce a valid post-fix mathematical expression. This table contains all of the information that are included in each expression.
At this time, this schema definition has no fields registered by IANA.
Security considerations are outside of the scope of this document.
| [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. |
The following participants contributed technical material, use cases, and useful thoughts on the overall approach to this database specification: Leor Bleir of the NASA Goddard Space Flight Center, Michael Deschu and Shane Knudsen of Hammers Company, Inc. on behalf of the NASA Goddard Space Flight Center, and Paul Swencon of ASRC Space And Defense on behalf of the NASA Goddard Space Flight Center.