Delay-Tolerant Networking M. Sinkiat Internet-Draft ASRC Space And Defense, NASA GSFC Intended status: Informational S. Jacobs Expires: March 12, 2016 E. Birrane Johns Hopkins Applied Physics Laboratory September 9, 2015 AMP Manager SQL Interface draft-birrane-dtn-ampmgr-sql-00 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 http://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 March 12, 2016. Copyright Notice Copyright (c) 2015 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 Sinkiat, et al. Expires March 12, 2016 [Page 1] Internet-Draft MGRSQL September 2015 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 4 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Table Naming . . . . . . . . . . . . . . . . . . . . . . 4 3. Database Overview . . . . . . . . . . . . . . . . . . . . . . 4 4. Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. Data Types - lvtDataTypes . . . . . . . . . . . . . . . . 6 4.2. Incoming State - lvtIncomingState . . . . . . . . . . . . 7 4.3. MID Category - lvtMIDCategory . . . . . . . . . . . . . . 9 4.4. OID Category - lvtMIDOIDType . . . . . . . . . . . . . . 10 4.5. MID Type - lvtMIDType . . . . . . . . . . . . . . . . . . 10 4.6. Outgoing State - lvtOutgoingState . . . . . . . . . . . . 11 5. ADM Support . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1. ADM Nicknames - dbtADMNicknames . . . . . . . . . . . . . 13 5.2. Supported ADMs - dbtADMs . . . . . . . . . . . . . . . . 14 5.3. ProtoMIDs . . . . . . . . . . . . . . . . . . . . . . . . 14 5.3.1. Individual MID Parameter - dbtProtoMIDParameter . . . 15 5.3.2. MID Parameter Collection - dbtProtoMIDParameters . . 15 5.3.3. ProtoMIDs - dbtProtoMIDs . . . . . . . . . . . . . . 16 6. Agent Support . . . . . . . . . . . . . . . . . . . . . . . . 17 6.1. Registered Agents - dbtRegisteredAgents . . . . . . . . . 17 7. MID Information . . . . . . . . . . . . . . . . . . . . . . . 18 7.1. Data Collections . . . . . . . . . . . . . . . . . . . . 18 7.1.1. Data Collection Entry - dbtDataCollection . . . . . . 18 7.1.2. Data Collection - dbtDataCollections . . . . . . . . 19 7.2. MID Collections . . . . . . . . . . . . . . . . . . . . . 19 7.2.1. MID Collection Entry - dbtMIDCollection . . . . . . . 19 7.2.2. MID Collection - dbtMIDCollections . . . . . . . . . 20 7.3. MIDs - dbtMIDs . . . . . . . . . . . . . . . . . . . . . 20 7.4. OIDs - dbtOIDs . . . . . . . . . . . . . . . . . . . . . 22 8. Outgoing Message Support . . . . . . . . . . . . . . . . . . 23 8.1. Outgoing Messages - dbtOutgoingMessages . . . . . . . . . 24 8.2. Outgoing Message Groups - dbtOutgoingMessageGroup . . . . 24 9. Incoming Message Support . . . . . . . . . . . . . . . . . . 25 9.1. Incoming Messages - dbtIncomingMessages . . . . . . . . . 26 9.2. Incoming Message Groups - dbtIncomingMessageGroup . . . . 26 Sinkiat, et al. Expires March 12, 2016 [Page 2] Internet-Draft MGRSQL September 2015 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 12. Normative References . . . . . . . . . . . . . . . . . . . . 27 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction This document presents a 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). 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 ([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. 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. Sinkiat, et al. Expires March 12, 2016 [Page 3] Internet-Draft MGRSQL September 2015 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. Conventions 2.1. Table Naming This specification uses a naming convention to delineate between two types of database tables: those containing mutable data and those containing immutable data. Tables containing mutable data are named with the prefix "dbt" where tables containing immutable data are named with the prefix "lvt", as defined below. o dbt - This prefix stands for "Database Table" and is prepended to the name of any database table holding data that can be changed by an administrator (such as when adding support for a new Application Data Model), by a user (such as when adding a new command), or by a Manager (such as when storing a series of received reports). o lvt - This prefix stands for "Limited Value Table" and is prepended to the name of any database table holding constant values that are not subject to change by administrators, regular users, or AMP Managers. These tables are only updates when there is a change to the AMP specification itself. 3. 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. Sinkiat, et al. Expires March 12, 2016 [Page 4] Internet-Draft MGRSQL September 2015 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. Constants tables are all prefaced with "lvt". 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 MID Information - These tables capture all information used to define Managed Identifiers (MIDs) for the Manager. This includes MID definitions from ADMs custom definitions from users in the system. These tables also capture parameters, object identifiers, and MID 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 16 dbt tables and 7 lvt tables, as in Figure 1. Sinkiat, et al. Expires March 12, 2016 [Page 5] Internet-Draft MGRSQL September 2015 +-------------------------+------------------------+ | Table Name | Table Type | +-------------------------+------------------------+ | lvtDataTypes | Constants | | lvtIncomingState | Constants | | lvtMIDCategory | Constants | | lvtMIDOIDType | Constants | | lvtMIDType | Constants | | lvtOutgoingState | Constants | | dbtADMNicknames | ADM Support | | dbtADMs | ADM Support | | dbtProtoMIDParameter | ADM Support | | dbtProtoMIDParameters | ADM Support | | dbtProtoMIDs | ADM Support | | dbtRegisteredAgents | Agent Support | | dbtDataCollection | MID Information | | dbtDataCollections | MID Information | | dbtMIDCollection | MID Information | | dbtMIDCollections | MID Information | | dbtMIDs | MID Information | | dbtOIDs | MID Information | | dbtOutgoingMessageGroup | Outgoing Support | | dbtOutgoingMessages | Outgoing Support | | dbtIncomingMessageGroup | Incoming Support | | dbtIncomingMessages | Incoming Support | +-------------------------+------------------------+ Figure 1: amp_core tables 4. Constants 4.1. Data Types - lvtDataTypes Data types, as defined in the AMP, enumerate the types of information associated with collections of data, such as defined in MID parameters, computed values, and report definitions. The format of the table is as follows. +-------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+------------------+------+-----+---------+-------+ | ID | int(10) unsigned | NO | PRI | NULL | | | Name | varchar(50) | NO | UNI | | | | Description | varchar(255) | NO | | | | +-------------+------------------+------+-----+---------+-------+ lvtDataTypes Sinkiat, et al. Expires March 12, 2016 [Page 6] Internet-Draft MGRSQL September 2015 ID 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 below. +----+--------+-------------------------------------+ | ID | Name | Description | +----+--------+-------------------------------------+ | 0 | BYTE | 8-bits; Standard Byte | | 1 | INT | Signed 32-bit Integer | | 2 | UINT | Unsigned 32-bit Integer | | 3 | VAST | Signed 64-bit Integer | | 4 | UVAST | Unsigned 64-bit Integer | | 5 | REAL32 | Single-Precision Floating Point | | 6 | REAL64 | Double-Precision Floating Point | | 7 | STR | Character String | | 8 | BLOB | Binary Large Object (Length + Data) | | 9 | SDNV | Self-Delineating Numerical Value | | 10 | TS | Timestamp | | 11 | DC | Data Collection | | 12 | MID | Managed Identifier | | 13 | MC | Managed Identifier Collection | | 14 | EXPR | Expression | | 15 | DEF | Definition | | 16 | TRL | Time-Based Rule | | 17 | SRL | State-Based Rule | | 18 | TDC | Typed Data Collection | | 19 | RPT | Report | | 20 | MACRO | Macro | | 21 | UNK | Unknown Type | +----+--------+-------------------------------------+ lvtDataTypes Example 4.2. Incoming State - lvtIncomingState 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. Sinkiat, et al. Expires March 12, 2016 [Page 7] Internet-Draft MGRSQL September 2015 The lvtIncomingState table identifies three different wait states associated with receiving reports from Agents. The format of the table is defined as follows. +-------------+---------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+---------------------+------+-----+---------+-------+ | ID | tinyint(3) unsigned | NO | PRI | NULL | | | Name | varchar(50) | NO | | | | | Description | varchar(255) | NO | | | | +-------------+---------------------+------+-----+---------+-------+ lvtIncomingState 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. Sinkiat, et al. Expires March 12, 2016 [Page 8] Internet-Draft MGRSQL September 2015 +----+--------------+-----------------------------------------+ | ID | Name | Description | +----+--------------+-----------------------------------------+ | 0 | Initializing | Manager is receiving reports. | | 1 | Ready | Manager has completed reception. | | 2 | Processed | Application is done processing reports. | +----+--------------+-----------------------------------------+ lvtIncomingState Example 4.3. MID Category - lvtMIDCategory The lvtMIDCategory table identifies the three different MID categories as defined in the AMP. The format of the table is defined as follows. +-------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+------------------+------+-----+---------+-------+ | ID | int(10) unsigned | NO | PRI | NULL | | | Name | varchar(50) | NO | UNI | | | | Description | varchar(255) | NO | | | | +-------------+------------------+------+-----+---------+-------+ lvtMIDCategory ID The primary key for this table, and the enumerated value of the MID category. Name The name associated with the MID Category (Atomic, Computed, Collection). Description The description associated with the MID Category. An example of such a table is illustrated below. +----+------------+-----------------+ | ID | Name | Description | +----+------------+-----------------+ | 0 | Atomic | Measured Values | | 1 | Computed | Computed Values | | 2 | Collection | Array of Values | +----+------------+-----------------+ lvtMIDCategory Example Sinkiat, et al. Expires March 12, 2016 [Page 9] Internet-Draft MGRSQL September 2015 4.4. OID Category - lvtMIDOIDType The lvtMIDOIDType table identifies the four different OID categories as defined in the AMP. The format of the table is defined as follows. +-------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+------------------+------+-----+---------+-------+ | ID | int(10) unsigned | NO | PRI | NULL | | | Name | varchar(50) | NO | UNI | | | | Description | varchar(255) | NO | | | | +-------------+------------------+------+-----+---------+-------+ lvtMIDOIDType ID The primary key for this table, and the enumerated value of the OID category. Name The name associated with the OID Category. Description The description associated with the OID Category. An example of such a table is illustrated below. +----+------------------------------+-------------+ | ID | Name | Description | +----+------------------------------+-------------+ | 0 | Full OID | | | 1 | Parameterized OID | | | 2 | Compressed Full OID | | | 3 | Compressed Parameterized OID | | +----+------------------------------+-------------+ lvtMIDOIDType Example 4.5. MID Type - lvtMIDType The lvtMIDType table identifies the four different MID types as defined in the AMP. The format of the table is defined as follows. Sinkiat, et al. Expires March 12, 2016 [Page 10] Internet-Draft MGRSQL September 2015 +-------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+------------------+------+-----+---------+-------+ | ID | int(10) unsigned | NO | PRI | NULL | | | Name | varchar(50) | NO | UNI | | | | Description | varchar(255) | NO | | | | +-------------+------------------+------+-----+---------+-------+ lvtMIDType ID The primary key for this table, and the enumerated value of the MID type. Name The name associated with the MID type. Description The description associated with the MID type. An example of such a table is illustrated below. +----+----------+-------------+ | ID | Name | Description | +----+----------+-------------+ | 0 | Data | | | 1 | Control | | | 2 | Literal | | | 3 | Operator | | +----+----------+-------------+ lvtMIDType Example 4.6. Outgoing State - lvtOutgoingState 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 lvtOutgoingState table identifies four different wait states associated with sending controls to Agents. The format of the table is defined as follows. Sinkiat, et al. Expires March 12, 2016 [Page 11] Internet-Draft MGRSQL September 2015 +-------------+--------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+--------------+------+-----+---------+-------+ | ID | tinyint(4) | NO | PRI | NULL | | | Name | varchar(50) | NO | | | | | Description | varchar(255) | NO | | | | +-------------+--------------+------+-----+---------+-------+ lvtOutgoingState 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. 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. Sinkiat, et al. Expires March 12, 2016 [Page 12] Internet-Draft MGRSQL September 2015 +----+--------------+---------------------------------+ | 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. | +----+--------------+---------------------------------+ lvtOutgoingState Example 5. ADM Support 5.1. ADM Nicknames - dbtADMNicknames The dbtADMNicknames table identifies all of the nicknames associated with supported ADMs. A Nickname in the AMA is an enumeration of a common OID subtree defined in the context of an ADM. Nickname enumerations MUST be unique. The format of the table is defined as follows. +----------------+------------------+------+-----+------------+-----------+ | Field | Type | Null | Key | Default | Extra | +----------------+------------------+------+-----+------------+-----------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_incr | | ADM_ID | int(10) unsigned | NO | MUL | NULL | | | Nickname_UID | int(10) unsigned | NO | | NULL | | | Nickname_Label | varchar(25) | NO | | "" | | | OID | int(10) unsigned | NO | MUL | NULL | | +----------------+------------------+------+-----+------------+-----------+ dbtADMNicknames ID The primary key for this table. ADM_ID This is a foreign key into the dbtADMs table and identifies the ADM that defined this nickname. Nickname_UID The globally unique enumeration of the common OID subtree. Nickname_Label A description of the nickname (e.g., "Agent ADM Reports"). OID Sinkiat, et al. Expires March 12, 2016 [Page 13] Internet-Draft MGRSQL September 2015 This is a foreign key into the dbtOIDs table and points to the common OID associated with this nickname. 5.2. Supported ADMs - dbtADMs The dbtADMs 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 | +---------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | Label | varchar(255) | NO | UNI | | | | Version | varchar(255) | NO | | | | | OID | int(10) unsigned | NO | MUL | NULL | | +---------+------------------+------+-----+---------+----------------+ dbtADMs ID The primary key for this table. Label 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. OID This is a foreign key into the dbtOIDs table and points to the common OID associated with this ADM, if the ADM defines such a common OID. 5.3. ProtoMIDs MIDs identifying items such as Controls may accept parameters to customize their behavior. When defined in the context of an ADM, a parameterized MID only includes the non-parameterized portion of the MID followed by the expected data types for the parameterized portion of the MID. This, essentially, acts as a template for populating a specific instance of the MID with actual data. This "template" is referred to as a protoMID, as it is used to generate MID instances. The amp_core database schema identifies three tables used to capture protoMID definitions from ADMs: dbtProtoMIDParameter, dbtProtoMIDParameters, and dbtProtoMIDs. Sinkiat, et al. Expires March 12, 2016 [Page 14] Internet-Draft MGRSQL September 2015 5.3.1. Individual MID Parameter - dbtProtoMIDParameter The dbtProtoMIDParameter table contains a row for each parameter associated with a protoMID. All of the parameters for a protoMID, together, are considered a "collection" of parameters. The format of the table is as follows. +-----------------+------------------+------+-----+---------+-----------+ | Field | Type | Null | Key | Default | Extra | +-----------------+------------------+------+-----+---------+-----------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_incr | | CollectionID | int(10) unsigned | YES | MUL | NULL | | | ParameterOrder | int(10) unsigned | NO | | 0 | | | ParameterTypeID | int(10) unsigned | YES | MUL | NULL | | +-----------------+------------------+------+-----+---------+-----------+ dbtProtoMIDParameter ID The primary key for this table. CollectionID The name of the collection for this parameter. A parameter collection is the ordered set of parameters that describe a ProtoMID. This is a foreign key into the dbtProtoMIDParameters table. ParameterOrder The 0-based ordering of this parameter within the collection. ParameterTypeID The type of this parameter. This must be one of the known AMP types and, as such, is a foreign key into the lvtDataTypes table. 5.3.2. MID Parameter Collection - dbtProtoMIDParameters The dbtProtoMIDParameters table represents the ordered set of parameters associated with a ProtoMID. The format of the table is as follows. Sinkiat, et al. Expires March 12, 2016 [Page 15] Internet-Draft MGRSQL September 2015 +---------+------------------+------+-----+------------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+------------------+------+-----+------------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | Comment | varchar(255) | NO | | No Comment | | +---------+------------------+------+-----+------------+----------------+ dbtProtoMIDParameters ID The primary key for this table. Comment A human-readable description of the collection. It is recommended that this reference the ProtoMID whose parameter collection is being represented (e.g, "Parameters for AddReportDefinition(MID id, MC contents)"). 5.3.3. ProtoMIDs - dbtProtoMIDs The dbtProtoMIDs table stores all known ProtoMIDs. The format of the table is as follows. +--------------+------------------+------+-----+----------------+----------+ | Field | Type | Null | Key | Default | Extra | +--------------+------------------+------+-----+----------------+----------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_inc | | NicknameID | int(10) unsigned | YES | MUL | NULL | | | OID | int(10) unsigned | NO | MUL | NULL | | | ParametersID | int(10) unsigned | YES | MUL | NULL | | | DataType | int(10) unsigned | NO | MUL | 0 | | | OIDType | int(10) unsigned | NO | MUL | 0 | | | Type | int(10) unsigned | NO | MUL | 0 | | | Category | int(10) unsigned | NO | MUL | 0 | | | Name | varchar(50) | NO | | Unnamed | | | Description | varchar(255) | NO | | No Description | | +--------------+------------------+------+-----+----------------+----------+ dbtProtoMIDs ID The primary key for this table. NicknameID The nickname associated with this MID, if applicable. This is a foreign key into the dbtADMNicknames table. OID Sinkiat, et al. Expires March 12, 2016 [Page 16] Internet-Draft MGRSQL September 2015 The OID associated with the ProtoMID. This is a foreign key into the dbtOIDs table. ParametersID The parameter collection for this ProtoMID. This is a foreign key into the dbtProtoMIDParameters table. DataType The data type associated with this MID. This is a foreign key into the lvtDataTypes table. OIDType The type of OID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDOIDType table. Type The type of MID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDType table. Type The category of MID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDCategory table. Name A human-readable name for this ProtoMID. Comment A human-readable description of the ProtoMID. 6. Agent Support 6.1. Registered Agents - dbtRegisteredAgents The dbtRegisteredAgents 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 | +---------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | AgentId | varchar(128) | NO | | ipn:0.0 | | +---------+------------------+------+-----+---------+----------------+ dbtRegisteredAgents ID The primary key for this table. Sinkiat, et al. Expires March 12, 2016 [Page 17] Internet-Draft MGRSQL September 2015 AgentId 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. 7. MID Information 7.1. Data Collections Data collection tables capture the Data Collection (DC) data type as defined in [AMP]. Similar to the ProtoMIDParameter(s) table, 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. 7.1.1. Data Collection Entry - dbtDataCollection The dbtDataCollection table holds data collection entries, one per row. The format of the table is defined as follows. +--------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------------+------------------+------+-----+---------+-------+ | CollectionID | int(10) unsigned | NO | PRI | NULL | | | DataOrder | int(10) unsigned | NO | PRI | 0 | | | DataType | int(10) unsigned | NO | MUL | NULL | | | DataBlob | blob | YES | | NULL | | +--------------+------------------+------+-----+---------+-------+ dbtDataCollection CollectionID The Data Collection to which this entry belongs. DataOrder The 0-based order of this entry in the encapsulating collection. DataType The type of this data collection. This is a foreign key to the lvtDataTypes table. DataBlob The binary value of the data collection entry in hexadecimal. This string does not include a pre-pended "0x" and should assume that two characters, together, form a single byte. Sinkiat, et al. Expires March 12, 2016 [Page 18] Internet-Draft MGRSQL September 2015 Therefore, the hex value 0xBEEFFEED would be represented as the string value 'BEEFFEED'. 7.1.2. Data Collection - dbtDataCollections The dbtDataCollections table holds information for a particular collection of data entries (from dbtDataCollection). The format of the table is defined as follows. +-------+------------------+------+-----+----------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------+------------------+------+-----+----------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | Label | varchar(255) | NO | | Unnamed | | +-------+------------------+------+-----+----------+----------------+ dbtDataCollections ID The Data Collection identifier. Label A human-readable description of the Data Collection. 7.2. MID Collections A MID Collection is an ordered set of MID values, similar to a Data Collection, which is an ordered set of Data values. One table is used to represent the MID Collection, and another table is used to capture the ordered MIDs in the collection. 7.2.1. MID Collection Entry - dbtMIDCollection The dbtMIDCollection table holds MID collection entries, one per row. The format of the table is defined as follows. +--------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------------+------------------+------+-----+---------+-------+ | CollectionID | int(10) unsigned | NO | PRI | NULL | | | MidID | int(10) unsigned | NO | PRI | NULL | | | MIDOrder | int(10) unsigned | NO | PRI | 0 | | +--------------+------------------+------+-----+---------+-------+ dbtMIDCollection CollectionID The MID Collection to which this entry belongs. Sinkiat, et al. Expires March 12, 2016 [Page 19] Internet-Draft MGRSQL September 2015 MidID The identifier for this MID. This is a foreign key into the dbtMIDs table. MIDOrder The 0-based order of this entry in the encapsulating collection. 7.2.2. MID Collection - dbtMIDCollections The dbtMIDCollections table holds information for a particular collection of MIDs (from dbtMIDCollection). The format of the table is defined as follows. +---------+------------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | Comment | varchar(255) | YES | | NULL | | +---------+------------------+------+-----+---------+----------------+ dbtMIDCollections ID The MID Collection identifier. Label A human-readable description of the MID Collection. 7.3. MIDs - dbtMIDs The dbtMIDs table captures the MIDs in the database. Some MIDs will be auto-populated from ADMs. Others will be added dynamically by users of the system. As per [AMP], a MID without an identified Issuer field is assumed to be as defined in an ADM. The format of the table is defined as follows. Sinkiat, et al. Expires March 12, 2016 [Page 20] Internet-Draft MGRSQL September 2015 +--------------+---------------------+------+-----+----------+-------------+ | Field | Type | Null | Key | Default | Extra | +--------------+---------------------+------+-----+----------+-------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_incr | | NicknameID | int(10) unsigned | YES | MUL | NULL | | | OID | int(10) unsigned | NO | MUL | NULL | | | ParametersID | int(10) unsigned | YES | MUL | NULL | | | Type | int(10) unsigned | NO | MUL | NULL | | | Category | int(10) unsigned | NO | MUL | NULL | | | IssuerFlag | bit(1) | NO | | b'0' | | | TagFlag | bit(1) | NO | | b'0' | | | OIDType | int(10) unsigned | YES | MUL | NULL | | | IssuerID | bigint(20) unsigned | NO | | 0 | | | TagValue | bigint(20) unsigned | NO | | 0 | | | DataType | int(10) unsigned | NO | MUL | NULL | | | Name | varchar(50) | NO | | Unnamed | | | Description | varchar(255) | NO | | None | | +--------------+---------------------+------+-----+----------+-------------+ dbtMIDs ID The primary key for this table. NicknameID The Nickname associated with this MID, if the encapsulated OID is a compressed OID. This is an optional field but, if present, is a foreign key into the dbtADMNicknames table. OID The OID of the encapsulated MID. This is a foreign key into the dbtOIDs table. ParametersID The parameters associated with this MID, if this MID encapsulates a parameterized OID. This is a foreign key in the dbtDataCollections table, as parameters are captured as a Data Collection. Type The type associated with this MID. This is a foreign key into the lvtMIDType table. Category The category associated with this MID. This is a foreign key into the lvtMIDCategory table. IssuerFlag Sinkiat, et al. Expires March 12, 2016 [Page 21] Internet-Draft MGRSQL September 2015 A binary value representing whether the MID has an issuer field (value 1) or not (value 0). TagFlag A binary value representing whether the MID has a tag field (value 1) or not (value 0). OIDType The type of the encapsulated OID. This is a foreign key into the lvtMIDOIDType table. IssuerID The optional Issuer of the MID, to be NOT NULL if the IssuerFlag is set to 1, and NULL otherwise. The IssuerID is captured in a hexadecimal binary value. It is currently assumed that the IssuerID will not exceed 64 bits. TagValue The optional Tag of the MID, to be NOT NULL if the TagFlag is set to 1, and NULL otherwise. The TagValue is captured in a hexadecimal binary value. It is currently assumed that the TagValue will not exceed 64 bits in length. DataType The data type associated with this MID. This is a foreign key into the lvtDataTypes table. Name A human-readable string representation of the MID Name. TagValue A human-readable string representation of the MID Description. 7.4. OIDs - dbtOIDs The dbtOIDs table captures the Object Identifiers encapsulated in a MID. For Full OIDs, this includes the length and octet set captured using Binary Encoding Rules (BER), as specified in [AMP]. For compressed OIDs, this includes the relative OID from some root tree, also encoded as a length and octet set captured using BER. The format of the table is defined as follows. Sinkiat, et al. Expires March 12, 2016 [Page 22] Internet-Draft MGRSQL September 2015 +-------------+------------------+------+-----+------------+-----------+ | Field | Type | Null | Key | Default | Extra | +-------------+------------------+------+-----+------------+-----------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_incr | | IRI_Label | varchar(255) | NO | MUL | NONE | | | Dot_Label | varchar(255) | NO | | 1.2.3.4 | | | Encoded | varchar(255) | NO | | BEEFFEED | | | Description | varchar(255) | NO | | None | | +-------------+------------------+------+-----+------------+-----------+ dbtOIDs ID The primary key for this table. IRI_Label The Internationalized Resource Identifier (IRI) representation for this OID. Dot_Label The dot notation representation of this OID. Encoded The BER-encoded representation of this OID, in hexadecimal. This string does not include a pre-pended "0x" and should assume that two characters, together, form a single byte. Therefore, the hex value 0xBEEFFEED would be represented as the string value 'BEEFFEED'. Description A human-readable description of the OID. 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 MID collection of the MIDs to be run on the Agent. Sinkiat, et al. Expires March 12, 2016 [Page 23] Internet-Draft MGRSQL September 2015 8.1. Outgoing Messages - dbtOutgoingMessages The dbtOutgoingMessages table captures a single MID Collection holding the set of Control MIDs 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 | +------------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | OutgoingID | int(10) unsigned | NO | MUL | NULL | | | StartTS | bigint(20) | NO | | 0 | | | MidCollID | int(10) unsigned | NO | MUL | NULL | | +------------+------------------+------+-----+---------+----------------+ dbtOutgoingMessages ID The primary key for this table. OutgoingID The outgoing message group to which this outgoing message belongs. This is a foreign key into the dbtOutgoingMessageGroup table. StartTS The time at which the controls in the MID Collection should be run. This may be an absolute or relative time, as defined in [AMP] MidCollID The MID Collection comprising this outgoing message. This is a foreign key into the dbtMIDCollections table. 8.2. Outgoing Message Groups - dbtOutgoingMessageGroup The dbtOutgoingMessageGroup table captures an outgoing message group, which is one or more outgoing messages. The format of the table is defined as follows. Sinkiat, et al. Expires March 12, 2016 [Page 24] Internet-Draft MGRSQL September 2015 +------------+------------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +------------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | CreatedTS | datetime | YES | | NULL | | | ModifiedTS | datetime | YES | | NULL | | | State | tinyint(4) | NO | MUL | NULL | | | AgentID | int(10) unsigned | NO | MUL | NULL | | +------------+------------------+------+-----+---------+----------------+ dbtOutgoingMessageGroup ID The primary key for this table. CreatedTS The time at which the outgoing message group was created. ModifiedTS 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 foreign keyed into the lvtOutgoingState table. AgentID 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 into the dbtRegisteredAgents 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. Sinkiat, et al. Expires March 12, 2016 [Page 25] Internet-Draft MGRSQL September 2015 9.1. Incoming Messages - dbtIncomingMessages The dbtIncomingMessages table captures information returned from an AMP Agent. The format of the table is defined as follows. +------------+------------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +------------+------------------+------+-----+---------+----------------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_increment | | IncomingID | int(10) unsigned | NO | MUL | NULL | | | Content | blob | YES | | NULL | | +------------+------------------+------+-----+---------+----------------+ dbtIncomingMessages ID The primary key for this table. IncomingID The incoming message group to which this incoming message belongs. This is a foreign key into the dbtIncomingMessageGroup table. Content A Blob representing the raw values returned by an AMP Agent as passed through an AMP Manager. 9.2. Incoming Message Groups - dbtIncomingMessageGroup The dbtIncomingMessageGroup 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 | +-------------+---------------------+------+-----+---------+-----------+ | ID | int(10) unsigned | NO | PRI | NULL | auto_incr | | ReceivedTS | datetime | YES | | NULL | | | GeneratedTS | datetime | YES | | NULL | | | State | tinyint(3) unsigned | NO | MUL | NULL | | | AgentID | int(10) unsigned | NO | MUL | NULL | | +-------------+---------------------+------+-----+---------+-----------+ dbtIncomingMessageGroup ID The primary key for this table. Sinkiat, et al. Expires March 12, 2016 [Page 26] Internet-Draft MGRSQL September 2015 ReceivedTS The time at which the incoming message group was received by the AMP Manager. GeneratedTS 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 foreign keyed into the lvtIncomingState table. AgentID The identifier of the Agent sending this incoming message group. 10. IANA Considerations At this time, this schema definition has no fields registered by IANA. 11. Security Considerations Security considerations are outside of the scope of this document. 12. Normative References [AMA] Birrane, E., "Asynchronous Management Architecture", draft-birrane-dtn-ama-01 (work in progress), August 2015. [AMP] Birrane, E., "Asynchronous Management Protocol", draft- birrane-dtn-amp-01 (work in progress), August 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . 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. Sinkiat, et al. Expires March 12, 2016 [Page 27] Internet-Draft MGRSQL September 2015 Authors' Addresses Mark A. Sinkiat ASRC Space And Defense, NASA GSFC Email: mark.a.sinkiat@nasa.gov Samantha K. Jacobs Johns Hopkins Applied Physics Laboratory Email: Samantha.Jacobs@jhuapl.edu Edward J. Birrane Johns Hopkins Applied Physics Laboratory Email: Edward.Birrane@jhuapl.edu Sinkiat, et al. Expires March 12, 2016 [Page 28]