Internet DRAFT - draft-birrane-dtn-ampmgr-sql
draft-birrane-dtn-ampmgr-sql
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
Abstract
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.
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.
Birrane, et al. Expires January 3, 2019 [Page 1]
Internet-Draft MGRSQL July 2018
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 . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Requirements Language . . . . . . . . . . . . . . . . . . 4
2. Database Overview . . . . . . . . . . . . . . . . . . . . . . 4
3. Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Data Types - data_types . . . . . . . . . . . . . . . . . 6
3.2. Incoming State - incoming_state . . . . . . . . . . . . . 6
3.3. Outgoing State - outgoing_state . . . . . . . . . . . . . 8
4. ADM Support . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1. ADM Nicknames - adm_nickname . . . . . . . . . . . . . . 9
4.2. Supported ADMs - adm . . . . . . . . . . . . . . . . . . 10
4.3. ARIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.1. Individual ARI Parameter - parmspec . . . . . . . . . 11
4.3.2. ARI Parameter Collection - parmspec_set . . . . . . . 12
4.3.3. ARI - ari . . . . . . . . . . . . . . . . . . . . . . 12
4.3.4. ARI - ari_definition . . . . . . . . . . . . . . . . 13
5. Agent Support . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. Registered Agents - registered_agents . . . . . . . . . . 14
6. ARI Information . . . . . . . . . . . . . . . . . . . . . . . 15
6.1. Data Collections . . . . . . . . . . . . . . . . . . . . 15
6.1.1. Data Collection Entry - data_value . . . . . . . . . 15
6.1.2. Data Collection - data_set . . . . . . . . . . . . . 17
6.2. ARI Collections . . . . . . . . . . . . . . . . . . . . . 17
6.2.1. ARI Collection Entry - ac . . . . . . . . . . . . . . 17
6.2.2. ARI Collection - ac_set . . . . . . . . . . . . . . . 18
7. Operator Support . . . . . . . . . . . . . . . . . . . . . . 18
7.1. In Type Set - in_type_set . . . . . . . . . . . . . . . . 18
7.2. In Type - in_type . . . . . . . . . . . . . . . . . . . . 19
8. Outgoing Message Support . . . . . . . . . . . . . . . . . . 19
8.1. Outgoing Messages - outgoing_message . . . . . . . . . . 20
8.2. Outgoing Message Groups - outgoing_message_group . . . . 20
9. Incoming Message Support . . . . . . . . . . . . . . . . . . 21
9.1. Incoming Messages - incoming_messages . . . . . . . . . . 22
9.2. Incoming Message Groups - incoming_message_group . . . . 22
10. Compound Data Types . . . . . . . . . . . . . . . . . . . . . 23
Birrane, et al. Expires January 3, 2019 [Page 2]
Internet-Draft MGRSQL July 2018
10.1. TNVC Support . . . . . . . . . . . . . . . . . . . . . . 23
10.1.1. Type Name Value Collection - tnvc . . . . . . . . . 23
10.1.2. Type Name Value Collection Set - tnvc_set . . . . . 24
10.2. Expression Support . . . . . . . . . . . . . . . . . . . 24
10.2.1. Expression Set - expression_set . . . . . . . . . . 24
10.2.2. Individual Expression - expression . . . . . . . . . 25
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
12. Security Considerations . . . . . . . . . . . . . . . . . . . 25
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
13.1. Informative References . . . . . . . . . . . . . . . . . 25
13.2. Normative References . . . . . . . . . . . . . . . . . . 26
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction
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).
1.1. Purpose
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.
Birrane, et al. Expires January 3, 2019 [Page 3]
Internet-Draft MGRSQL July 2018
1.2. Scope
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.
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. Database Overview
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.
o Constants - These tables contain those constants defined in the
AMP and AMA specifications as well as certain constants that are
defined in this specification.
o ADM Support - These tables capture all information that is solely
defined in an ADM. Outside of adding support for a new ADM, the
data in these tables should never be changed.
o AMP Agent Support - These tables capture information about Agents
in the system.
o Compound Data Types Support- These tables capture information
about TNVCs and expressions.
Birrane, et al. Expires January 3, 2019 [Page 4]
Internet-Draft MGRSQL July 2018
o Operator Support- These tables capture the information that is
needed to utilize operators.
o ARI Information - These tables capture all information used to
define Managed Identifiers (ARIs) for the Manager. This includes
ARI definitions from ADMs custom definitions from users in the
system. These tables also capture parameters, object identifiers,
and ARI collections.
o Outgoing Support - These tables capture information provided by an
application to a Manager to be sent out to an AMP agent.
o Incoming Support - These tables capture information provided by an
Agent and incoming to the Manager to be passed along to the
application.
The specification comprises tables, as in Figure 1.
+-----------------------+------------------------+
| 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
Birrane, et al. Expires January 3, 2019 [Page 5]
Internet-Draft MGRSQL July 2018
3. Constants
3.1. Data Types - data_types
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.
The format of the table is as follows.
+-------------+------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| enumeration | int(10) unsigned | NO | PRI | | |
| name | varchar(50) | NO | UNI | | |
| description | varchar(255) | NO | | "" | |
+-------------+------------------+------+-----+---------+-------+
data_types
enumeration
The primary key for this table, and the enumerated value of
the data type from the AMP specification.
Name
The name associated with this data type.
Description
The description associated with this data type.
An example of such a table is illustrated in [I-D.birrane-dtn-adm].
3.2. Incoming State - incoming_state
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.
The incoming_state table identifies three different wait states
associated with receiving reports from Agents. The format of the
table is defined as follows.
Birrane, et al. Expires January 3, 2019 [Page 6]
Internet-Draft MGRSQL July 2018
+-------------+---------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+---------------------+------+-----+---------+-------+
| state_id | tinyint(3) unsigned | NO | PRI | | |
| name | varchar(50) | NO | | | |
| description | varchar(255) | NO | | | |
+-------------+---------------------+------+-----+---------+-------+
incoming_state
state_id
The primary key for this table, and the enumerated value of
the incoming state. Three states are defined in this
specification, as follows.
0 - Initializing
This state signifies that a Manager is receiving a
set of information and rows associated with this
state should not be read by an application.
1 - Ready
This state signifies that a Manager has completed
receiving reports and that rows associated with this
state may be processed by an application.
2 - Processed
This state signifies that an application has
completed processing reports and that either a
Manager or an application can remove rows associated
with this state at any time.
Name
The name associated with the incoming state (Initializing,
Ready, Processed).
Description
The description associated with the incoming state.
An example of such a table is illustrated below.
Birrane, et al. Expires January 3, 2019 [Page 7]
Internet-Draft MGRSQL July 2018
+----+--------------+-----------------------------------------+
| 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
3.3. Outgoing State - outgoing_state
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.
The outgoing_state table identifies four different wait states
associated with sending controls to Agents. The format of the table
is defined as follows.
+-------------+--------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| state_id | tinyint(4) | NO | PRI | | |
| name | varchar(50) | NO | | | |
| description | varchar(255) | NO | | | |
+-------------+--------------+------+-----+---------+-------+
outgoing_state
state_id
The primary key for this table, and the enumerated value of
the outgoing state. Four states are defined in this
specification, as follows.
0 - Initializing
This state signifies that an application is preparing
a set of controls and rows associated with this state
should not be read by a Manager.
1 - Ready
This state signifies that an application has
completed preparing the controls and that rows
associated with this state may be processed by the
Manager for sending to one or more Agents.
Birrane, et al. Expires January 3, 2019 [Page 8]
Internet-Draft MGRSQL July 2018
2 - Processing
This state signifies that the Manager is in the
process of sending associated controls to one or more
Agents. Rows in this state should not be modified by
an application as it could affect the controls sent
by the Manager.
3 - Sent
This state signifies that the Manager has completed
sending the set of controls and that either a Manager
or an application can remove rows associated with
this state at any time.
name
The name associated with the outgoing state (Initializing,
Ready, Processing, Sent).
description
The description associated with the outgoing state.
An example of such a table is illustrated below.
+----------+--------------+---------------------------------+
| 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
4. ADM Support
4.1. ADM Nicknames - adm_nickname
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.
Birrane, et al. Expires January 3, 2019 [Page 9]
Internet-Draft MGRSQL July 2018
+----------------+------------------+------+-----+---------+-------+
| 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
adm_id
The primary key for this table.
nickname_enum
The enumeration of the nickname.
label
This is the label of the nickname.
4.2. Supported ADMs - 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.
+-------------+-----------------+------+-----+---------+---------------+
| 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
adm_id
The primary key for this table.
name
The name of the supported ADM.
version
The string representing the version of the ADM. A string is
used to allow for a variety of version formats.
description
This is the description of the ADM.
Birrane, et al. Expires January 3, 2019 [Page 10]
Internet-Draft MGRSQL July 2018
Organization
This is the issuing organization of the ADM.
4.3. ARIs
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.
4.3.1. Individual ARI Parameter - 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 |
+-----------+------------------+------+-----+---------+-------+
| 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
name
The name of the parmspec collection.
parm_id
The id of the collection for this parameter. A parameter
collection is the ordered set of parameters that describe an
ARI. This is a foreign key that corresponds to the parm_id
of the parmspec_set table.
parm_order
The 0-based ordering of this parameter within the collection.
type_id
Birrane, et al. Expires January 3, 2019 [Page 11]
Internet-Draft MGRSQL July 2018
The type of this parameter. This must be one of the known
AMP types and, as such, is a foreign key that corresponds to
the enumeration of the data_type table.
4.3.2. ARI Parameter Collection - 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 |
+---------+------------------+------+-----+--------+----------------+
| parm_id | int(10) unsigned | NO | PRI | | auto_increment |
|comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+--------+----------------+
parmspec_set
parm_id
The primary key for this table.
comment
This is the description of the parmspec set.
4.3.3. ARI - 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 |
+--------------+-------------------+------+-----+----------+----------+
| 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
curr_id
The primary key for this table.
Birrane, et al. Expires January 3, 2019 [Page 12]
Internet-Draft MGRSQL July 2018
name
The name of the ARI.
ari_id
This is the id of the ARI. This is a foreign key that
corresponds to the ari_id in the ari_definition table.
data_id
This is a foreign key to the data_set table that corresponds
with the data_id of the data_set table.
description
This is the description of the ari.
4.3.4. ARI - 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 |
+---------------+-----------------+------+-----+---------+----------+
| 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
ari_id
The primary key for this table.
nn_id
The nickname associated with this ARI, if applicable. This
is a foreign key that corresponds to the id in the
adm_nickname table.
parm_id
The parameter collection for this ARI. This is a foreign key
that corresponds to the parm_id in the parm_set table.
Birrane, et al. Expires January 3, 2019 [Page 13]
Internet-Draft MGRSQL July 2018
issuer_flag
A binary value representing whether the ARI has an issuer
field (value 1) or not (value 0).
tag_flag
A binary value representing whether the ARI has a tag field
(value 1) or not (value 0).
type_id
The data type associated with this ARI. This is a foreign
key that corresponds to the data_id in the data_types table.
name
A human-readable name for this ARI.
ari_bytestring
The enumeration of the ARI.
structure_id
This is the structure type of the ARI (EDD, VAR,etc.). This
is a foreign key that corresponds to the data_id in the
data_types table.
in_type_id
This is the in types that are needed to use a specific
operator. This is a foreign key that corresponds to the
in_type_id in the in_type_set table.
5. Agent Support
5.1. Registered Agents - 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.
+------------+-----------------+------+-----+---------+---------------+
| 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
registry_id
The primary key for this table.
Birrane, et al. Expires January 3, 2019 [Page 14]
Internet-Draft MGRSQL July 2018
agent_id
This is the identifier for the Agent, suitable for passing
into a network send call. A string representation is
selected to best capture the identifier format for a
particular network.
6. ARI Information
6.1. Data Collections
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.
6.1.1. Data Collection Entry - 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 | 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
data_id
The id of the data collection. This is a foreign key that
corresponds with the data_id of the data_set table.
data_order
Birrane, et al. Expires January 3, 2019 [Page 15]
Internet-Draft MGRSQL July 2018
The 0-based order of this entry in the encapsulating
collection.
data_type
The type of this data collection. This is a foreign key that
corresponds to the enumeration in the data_types table.
tnvc_id
This is a foreign key that corresponds to the tnvc_id of the
tnvc_set table.
ac_id
This is a foreign key that corresponds to the ac_id of the
ac_set table.
byte
The byte value shows the value of the data (if the piece of
data is a byte). If the data is not a byte, this field MUST
be NULL.
vast
The vast value shows the value of the data (if the piece of
data is of type int or vast). If the data is not an int or
vast, this field MUST be NULL.
uvast
The uvast value shows the value of the data (if the piece of
data is of type uint or vast). If the data is not an uint or
uvast, this field MUST be NULL.
real
The real value shows the value of the data (if the piece of
data is of type real32 or real64). If the data is not a
real32 or real64, this field MUST be NULL.
Str
The str field shows the value of the data (if the piece of
data is of type string). If the data is not a string, this
field MUST be NULL.
Bool
The bool field shows the value of the data (if the piece of
data is of type boolean). If the data is not a boolean, this
field MUST be NULL.
ts
Birrane, et al. Expires January 3, 2019 [Page 16]
Internet-Draft MGRSQL July 2018
The ts field shows the value of the data (if the piece of
data is of type timestamp). If the data is not a timestamp,
this field MUST be NULL.
6.1.2. Data Collection - 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.
+-------+------------------+------+-----+----------+----------------+
| Field | Type | Null | Key | Default | Extra |
+-------+------------------+------+-----+----------+----------------+
|data_id| int(10) unsigned | NO | PRI | | auto_increment |
|comment| varchar(255) | NO | | | |
+-------+------------------+------+-----+----------+----------------+
data_set
data_id
The Data Collection identifier. This is a primary key.
comment
This is a description of the data set.
6.2. ARI Collections
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.
6.2.1. ARI Collection Entry - 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 | MUL | | |
| ac_order | int(10) unsigned | NO | | 0 | |
| ari_id | int(10) unsigned | NO | MUL | | |
+----------+------------------+------+-----+---------+-------+
ac
ac_id
Birrane, et al. Expires January 3, 2019 [Page 17]
Internet-Draft MGRSQL July 2018
The ARI Collection to which this entry belongs. This is a
foreign key that corresponds with the ac_id of the ac_set
table.
ari_id
The identifier for this ARI. This is a foreign key that
corresponds to the ari_id in the ari_definition table.
ac_order
The 0-based order of this entry in the encapsulating
collection.
6.2.2. ARI Collection - 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 |
+---------+------------------+------+-----+---------+----------------+
| ac_id | int(10) unsigned | NO | PRI | | auto_increment |
| comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+---------+----------------+
ac_set
ac_id
The ARI Collection identifier.
7. Operator Support
7.1. In Type Set - 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 |
| comment | varchar(255) | NO | | | |
+----------+------------------+------+-----+---------+----------------+
in_type_set
in_type_id
Birrane, et al. Expires January 3, 2019 [Page 18]
Internet-Draft MGRSQL July 2018
The in_type set identifier.
comment
The description of the in_type set.
7.2. In Type - in_type
The in_type table holds information about operator in types. 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
in_type_id
The in_type set identifier. This is a foreign key that
corresponds to the in_type_id of the in_type_set table.
name
The name of the operator in type.
order
The order of the operator in type in the set.
type id
This is the type of the operator in_type. This is a foreign
key that corresponds to the enumeration in the data_types
table.
8. Outgoing Message Support
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.
Birrane, et al. Expires January 3, 2019 [Page 19]
Internet-Draft MGRSQL July 2018
8.1. Outgoing Messages - 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 |
+------------+-----------------+------+-----+---------+---------------+
| 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
message_id
The primary key for this table.
group_id
The outgoing message group to which this outgoing message
belongs. This is a foreign key that corresponds to the id in
the outgoing_message_group table.
start_ts
The time at which the controls in the ARI Collection should
be run. This may be an absolute or relative time, as defined
in [I-D.birrane-dtn-amp].
ac_id
The ARI Collection comprising this outgoing message. This is
a foreign key that corresponds to the ac_id of the ac_set
table.
8.2. Outgoing Message Groups - 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.
Birrane, et al. Expires January 3, 2019 [Page 20]
Internet-Draft MGRSQL July 2018
+------------+-----------------+------+-----+---------+---------------+
| 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
group_id
The primary key for this table.
created_ts
The time at which the outgoing message group was created.
modified_ts
The last time at which the message group was modified.
state
The current state of the outgoing message group. This state
provides a contention-avoidance mechanism between an
application and an AMP Manager. This is a foreign key that
corresponds to the state_id of the outgoing_state table.
agent_id
The identifier of the Agent receiving this message group.
Currently, a message group is only sent to one Agent.
Sending to multiple Agents is accomplished with multiple
entries in this table. This is a foreign key that
corresponds to the registry_id in the registered_agents
table.
9. Incoming Message Support
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.
Birrane, et al. Expires January 3, 2019 [Page 21]
Internet-Draft MGRSQL July 2018
9.1. Incoming Messages - 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 |
+------------+-----------------+------+-----+---------+---------------+
| 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
message_id
The primary key for this table.
group_id
The incoming message group to which this incoming message
belongs. This is a foreign key that corresponds with the
group_id in the incoming_message_group table.
ac_id
This is a foreign key that corresponds to the id in the
ac_set table.
9.2. Incoming Message Groups - 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 |
+-------------+---------------------+------+-----+---------+-----------+
| 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
group_id
The primary key for this table.
Birrane, et al. Expires January 3, 2019 [Page 22]
Internet-Draft MGRSQL July 2018
recieved_ts
The time at which the incoming message group was received by
the AMP Manager.
generated_ts
The time at which the incoming message group was generated by
the sending AMP Agent.
state
The current state of the incoming message group. This state
provides a contention-avoidance mechanism between an
application and an AMP Manager. This is a foreign key that
corresponds to the data_id in the data_types table.
agent_id
The identifier of the Agent sending this incoming message
group. This is a foreign key that corresponds to the
registry_id in the registered_agents table.
10. Compound Data Types
10.1. TNVC Support
10.1.1. Type Name Value Collection - tnvc
The tnvc table is a group of tnv collections.
+----------+------------------+------+-----+---------+-----------+
| 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
tnvc_id
The identifier of the TNV collection. This is a foreign key
that corresponds to the tnvc_id in the tnvc_set table.
order
The order of the tnvc in the set.
name
The name of the tnvc.
Birrane, et al. Expires January 3, 2019 [Page 23]
Internet-Draft MGRSQL July 2018
value
The value of the tnvc. This is a foreign key that
corresponds to the data_id in the data_set table.
10.1.2. Type Name Value Collection Set - tnvc_set
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 |
+----------+-----------------+------+-----+---------+-----------+
| tnvc_id | int(10) unsigned| NO | PRI | NULL | auto_incr |
| comment | varchar(255) | NO | | | |
+----------+-----------------+------+-----+---------+-----------+
tnv_collection
tnvc_id
The identifier of the TNV collection. This is a primary key.
comment
This is the description of the tnvc set.
10.2. Expression Support
10.2.1. Expression Set - 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 |
| comment | varchar(255) | NO | | | |
+---------+------------------+------+-----+---------+-----------+
expression_set
expr_id
The identifier of the expression. This is a primary key.
comment
This is the description of the expression.
Birrane, et al. Expires January 3, 2019 [Page 24]
Internet-Draft MGRSQL July 2018
10.2.2. Individual Expression - 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.
+-----------+------------------+------+-----+---------+-----------+
| 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
expr_id
The identifier of the expression. This is a foreign key that
corresponds to the expr_id in the expression_set table.
order_num
The 0-based order of this entry in the encapsulating
collection.
ari_id
This is the ari id. This is a foreign key that corresponds
to the ari_id in the ari_definition table.
11. IANA Considerations
At this time, this schema definition has no fields registered by
IANA.
12. Security Considerations
Security considerations are outside of the scope of this document.
13. References
13.1. Informative References
[I-D.birrane-dtn-ama]
Birrane, E., "Asynchronous Management Architecture",
draft-birrane-dtn-ama-07 (work in progress), June 2018.
Birrane, et al. Expires January 3, 2019 [Page 25]
Internet-Draft MGRSQL July 2018
13.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>.
Appendix A. Acknowledgements
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.
Authors' Addresses
Edward J. Birrane
Johns Hopkins Applied Physics Laboratory
Email: Edward.Birrane@jhuapl.edu
Evana DiPietro
Johns Hopkins Applied Physics Laboratory
Email: Evana.DiPietro@jhuapl.edu
David Linko
Johns Hopkins Applied Physics Laboratory
Email: David.Linko@jhuapl.edu
Birrane, et al. Expires January 3, 2019 [Page 26]
Internet-Draft MGRSQL July 2018
Mark A. Sinkiat
ASRC Space And Defense, NASA GSFC
Email: mark.a.sinkiat@nasa.gov
Birrane, et al. Expires January 3, 2019 [Page 27]
