idnits 2.17.1 draft-birrane-dtn-ampmgr-sql-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 2, 2018) is 2122 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'AMP' is mentioned on line 539, but not defined == Outdated reference: A later version (-06) exists of draft-birrane-dtn-adm-02 == Outdated reference: A later version (-08) exists of draft-birrane-dtn-amp-04 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Delay-Tolerant Networking E. Birrane 3 Internet-Draft E. DiPietro 4 Intended status: Informational D. Linko 5 Expires: January 3, 2019 Johns Hopkins Applied Physics Laboratory 6 M. Sinkiat 7 ASRC Space And Defense, NASA GSFC 8 July 2, 2018 10 AMP Manager SQL Interface 11 draft-birrane-dtn-ampmgr-sql-01 13 Abstract 15 This document describes a proposed public interface through which an 16 application, such as a network management console, interacts with an 17 Asynchronous Management Protocol (AMP) Manager via a database 18 supporting the Structured Query Language (SQL). The use of SQL as an 19 interfacing layer provides a natural way to describe interactions 20 with an AMP Manager independent of a particular implementation of 21 either the Manager or the application. Specifically, this document 22 presents a database schema capturing how to send controls to a 23 Manager and how to accept reports received by a Manager from one or 24 more AMP Agents. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 3, 2019. 43 Copyright Notice 45 Copyright (c) 2018 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 4 64 2. Database Overview . . . . . . . . . . . . . . . . . . . . . . 4 65 3. Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.1. Data Types - data_types . . . . . . . . . . . . . . . . . 6 67 3.2. Incoming State - incoming_state . . . . . . . . . . . . . 6 68 3.3. Outgoing State - outgoing_state . . . . . . . . . . . . . 8 69 4. ADM Support . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 4.1. ADM Nicknames - adm_nickname . . . . . . . . . . . . . . 9 71 4.2. Supported ADMs - adm . . . . . . . . . . . . . . . . . . 10 72 4.3. ARIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 4.3.1. Individual ARI Parameter - parmspec . . . . . . . . . 11 74 4.3.2. ARI Parameter Collection - parmspec_set . . . . . . . 12 75 4.3.3. ARI - ari . . . . . . . . . . . . . . . . . . . . . . 12 76 4.3.4. ARI - ari_definition . . . . . . . . . . . . . . . . 13 77 5. Agent Support . . . . . . . . . . . . . . . . . . . . . . . . 14 78 5.1. Registered Agents - registered_agents . . . . . . . . . . 14 79 6. ARI Information . . . . . . . . . . . . . . . . . . . . . . . 15 80 6.1. Data Collections . . . . . . . . . . . . . . . . . . . . 15 81 6.1.1. Data Collection Entry - data_value . . . . . . . . . 15 82 6.1.2. Data Collection - data_set . . . . . . . . . . . . . 17 83 6.2. ARI Collections . . . . . . . . . . . . . . . . . . . . . 17 84 6.2.1. ARI Collection Entry - ac . . . . . . . . . . . . . . 17 85 6.2.2. ARI Collection - ac_set . . . . . . . . . . . . . . . 18 86 7. Operator Support . . . . . . . . . . . . . . . . . . . . . . 18 87 7.1. In Type Set - in_type_set . . . . . . . . . . . . . . . . 18 88 7.2. In Type - in_type . . . . . . . . . . . . . . . . . . . . 19 89 8. Outgoing Message Support . . . . . . . . . . . . . . . . . . 19 90 8.1. Outgoing Messages - outgoing_message . . . . . . . . . . 20 91 8.2. Outgoing Message Groups - outgoing_message_group . . . . 20 92 9. Incoming Message Support . . . . . . . . . . . . . . . . . . 21 93 9.1. Incoming Messages - incoming_messages . . . . . . . . . . 22 94 9.2. Incoming Message Groups - incoming_message_group . . . . 22 95 10. Compound Data Types . . . . . . . . . . . . . . . . . . . . . 23 96 10.1. TNVC Support . . . . . . . . . . . . . . . . . . . . . . 23 97 10.1.1. Type Name Value Collection - tnvc . . . . . . . . . 23 98 10.1.2. Type Name Value Collection Set - tnvc_set . . . . . 24 99 10.2. Expression Support . . . . . . . . . . . . . . . . . . . 24 100 10.2.1. Expression Set - expression_set . . . . . . . . . . 24 101 10.2.2. Individual Expression - expression . . . . . . . . . 25 102 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 103 12. Security Considerations . . . . . . . . . . . . . . . . . . . 25 104 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 105 13.1. Informative References . . . . . . . . . . . . . . . . . 25 106 13.2. Normative References . . . . . . . . . . . . . . . . . . 26 107 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 26 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 110 1. Introduction 112 This document presents a public interface through which an 113 application, such as a network management console, interacts with an 114 Asynchronous Management Protocol ([I-D.birrane-dtn-amp]) Manager via 115 a database supporting the Structured Query Language (SQL). Such an 116 interface is useful as an implementation independent way of 117 specifying how an application may interact with an AMP Manager to 118 issue commands (such as through a custom graphical user interface) 119 and to receive reports (as they are received by one or more AMP 120 Agents). 122 1.1. Purpose 124 This document describes a database layout comprised of a series of 125 names tables and the columns the comprise those tables. Where 126 appropriate, primary and foreign key constraints are also discussed. 127 This set of tables presents a data model through which all AMP 128 Manager roles and responsibilities, as defined in the Asynchronous 129 Management Architecture ([I-D.birrane-dtn-ama]), can be accomplished. 131 Application developers can use this specification to describe how to 132 populate a database with AMP-related information such that an AMP 133 Manager implementation can read and use this data to effect AMP 134 behavior. By reading and writing the tables in accordance with this 135 specification, applications can claim conformance with the AMP 136 Manager regardless of which AMP Manager implementation is used, so 137 long as such a Manager is also in conformance with this 138 specification. 140 AMP Manager developers use this specification to describe how AMP 141 users input actions to the Manager and how to send received reports 142 back to those users. 144 1.2. Scope 146 This document covers table names and the names, data types, default 147 values, and comments associated with each column of each names table. 148 These types should be appropriate for any database implementing a SQL 149 interface and SHOULD NOT use any language or function specific to a 150 particular SQL database vendor. 152 This document does not specify the setup, configuration, 153 administration, or other function associated with a particular SQL 154 database vendor. Further, this document does not specify how either 155 the application or the AMP Manager log on to the database, or how 156 database communications are verified and secured. Finally, this 157 document does not discuss the architecture associated with 158 incorporating a database between an application and an AMP Manager, 159 as such architectures are likely tightly coupled to a network 160 deployment. 162 1.3. Requirements Language 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in RFC 2119 [RFC2119]. 168 2. Database Overview 170 This specification assumes that all tables exist in a database called 171 "amp_core", capturing the information necessary to capture core 172 operations associated with the AMP Manager. 174 The schema contains tables capturing information about various areas 175 of the AMP Manager interface. The following table types are defined. 177 o Constants - These tables contain those constants defined in the 178 AMP and AMA specifications as well as certain constants that are 179 defined in this specification. 181 o ADM Support - These tables capture all information that is solely 182 defined in an ADM. Outside of adding support for a new ADM, the 183 data in these tables should never be changed. 185 o AMP Agent Support - These tables capture information about Agents 186 in the system. 188 o Compound Data Types Support- These tables capture information 189 about TNVCs and expressions. 191 o Operator Support- These tables capture the information that is 192 needed to utilize operators. 194 o ARI Information - These tables capture all information used to 195 define Managed Identifiers (ARIs) for the Manager. This includes 196 ARI definitions from ADMs custom definitions from users in the 197 system. These tables also capture parameters, object identifiers, 198 and ARI collections. 200 o Outgoing Support - These tables capture information provided by an 201 application to a Manager to be sent out to an AMP agent. 203 o Incoming Support - These tables capture information provided by an 204 Agent and incoming to the Manager to be passed along to the 205 application. 207 The specification comprises tables, as in Figure 1. 209 +-----------------------+------------------------+ 210 | Table Name | Table Type | 211 +-----------------------+------------------------+ 212 | data_type | Constants | 213 | incoming_state | Constants | 214 | outgoing_state | Constants | 215 | tnvc_set | Compound Data Type | 216 | tnvc | Compound Data Type | 217 | expression_set | Compound Data Type | 218 | expression | Compound Data Type | 219 | in_type_set | Operator Support | 220 | in_type | Operator Support | 221 | adm_nickname | ADM Support | 222 | adm | ADM Support | 223 | parmspec | ADM Support | 224 | parmspec_set | ADM Support | 225 | registered_agents | Agent Support | 226 | data | ARI Information | 227 | data_set | ARI Information | 228 | ac | ARI Information | 229 | ac_set | ARI Information | 230 | ari | ARI Information | 231 | ari_definition | ARI Information | 232 | outgoing_message_group| Outgoing Support | 233 | outgoing_message | Outgoing Support | 234 | incoming_message_group| Incoming Support | 235 | incoming_message | Incoming Support | 236 +-----------------------+------------------------+ 238 Figure 1: amp_core tables 240 3. Constants 242 3.1. Data Types - data_types 244 Data types, as defined in the AMP, enumerate the types of information 245 associated with collections of data, such as defined in ARI 246 parameters, computed values, and report definitions. 248 The format of the table is as follows. 250 +-------------+------------------+------+-----+---------+-------+ 251 | Field | Type | Null | Key | Default | Extra | 252 +-------------+------------------+------+-----+---------+-------+ 253 | enumeration | int(10) unsigned | NO | PRI | | | 254 | name | varchar(50) | NO | UNI | | | 255 | description | varchar(255) | NO | | "" | | 256 +-------------+------------------+------+-----+---------+-------+ 258 data_types 260 enumeration 261 The primary key for this table, and the enumerated value of 262 the data type from the AMP specification. 264 Name 265 The name associated with this data type. 267 Description 268 The description associated with this data type. 270 An example of such a table is illustrated in [I-D.birrane-dtn-adm]. 272 3.2. Incoming State - incoming_state 274 When reports are being received by a Manager from an Agent, they will 275 be written into various Incoming Support table types. However, the 276 application reviewing these incoming reports should not start to read 277 them until the Manager has finished receiving and persisting them 278 into the database. 280 The incoming_state table identifies three different wait states 281 associated with receiving reports from Agents. The format of the 282 table is defined as follows. 284 +-------------+---------------------+------+-----+---------+-------+ 285 | Field | Type | Null | Key | Default | Extra | 286 +-------------+---------------------+------+-----+---------+-------+ 287 | state_id | tinyint(3) unsigned | NO | PRI | | | 288 | name | varchar(50) | NO | | | | 289 | description | varchar(255) | NO | | | | 290 +-------------+---------------------+------+-----+---------+-------+ 292 incoming_state 294 state_id 295 The primary key for this table, and the enumerated value of 296 the incoming state. Three states are defined in this 297 specification, as follows. 299 0 - Initializing 300 This state signifies that a Manager is receiving a 301 set of information and rows associated with this 302 state should not be read by an application. 304 1 - Ready 305 This state signifies that a Manager has completed 306 receiving reports and that rows associated with this 307 state may be processed by an application. 309 2 - Processed 310 This state signifies that an application has 311 completed processing reports and that either a 312 Manager or an application can remove rows associated 313 with this state at any time. 315 Name 316 The name associated with the incoming state (Initializing, 317 Ready, Processed). 319 Description 320 The description associated with the incoming state. 322 An example of such a table is illustrated below. 324 +----+--------------+-----------------------------------------+ 325 | ID | Name | Description | 326 +----+--------------+-----------------------------------------+ 327 | 0 | Initializing | Manager is receiving reports. | 328 | 1 | Ready | Manager has completed reception. | 329 | 2 | Processed | Application is done processing reports. | 330 +----+--------------+-----------------------------------------+ 332 incoming_state example 334 3.3. Outgoing State - outgoing_state 336 When controls are being sent via a Manager to an Agent, they will be 337 written into various Outgoing Support table types. However, the 338 Manager receiving these outgoing controls should not start to read 339 them until the application has finished writing them into the 340 database. 342 The outgoing_state table identifies four different wait states 343 associated with sending controls to Agents. The format of the table 344 is defined as follows. 346 +-------------+--------------+------+-----+---------+-------+ 347 | Field | Type | Null | Key | Default | Extra | 348 +-------------+--------------+------+-----+---------+-------+ 349 | state_id | tinyint(4) | NO | PRI | | | 350 | name | varchar(50) | NO | | | | 351 | description | varchar(255) | NO | | | | 352 +-------------+--------------+------+-----+---------+-------+ 354 outgoing_state 356 state_id 357 The primary key for this table, and the enumerated value of 358 the outgoing state. Four states are defined in this 359 specification, as follows. 361 0 - Initializing 362 This state signifies that an application is preparing 363 a set of controls and rows associated with this state 364 should not be read by a Manager. 366 1 - Ready 367 This state signifies that an application has 368 completed preparing the controls and that rows 369 associated with this state may be processed by the 370 Manager for sending to one or more Agents. 372 2 - Processing 373 This state signifies that the Manager is in the 374 process of sending associated controls to one or more 375 Agents. Rows in this state should not be modified by 376 an application as it could affect the controls sent 377 by the Manager. 379 3 - Sent 380 This state signifies that the Manager has completed 381 sending the set of controls and that either a Manager 382 or an application can remove rows associated with 383 this state at any time. 385 name 386 The name associated with the outgoing state (Initializing, 387 Ready, Processing, Sent). 389 description 390 The description associated with the outgoing state. 392 An example of such a table is illustrated below. 394 +----------+--------------+---------------------------------+ 395 | state_id | name | description | 396 +----------+--------------+---------------------------------+ 397 | 0 | Initializing | Application writing controls. | 398 | 1 | Ready | Ready for Sending to Agent. | 399 | 2 | Processing | Manager sending controls. | 400 | 3 | Sent | Manager send completed. | 401 +----------+--------------+---------------------------------+ 403 outgoing_state Example 405 4. ADM Support 407 4.1. ADM Nicknames - adm_nickname 409 The adm_nicknames table identifies all of the nicknames associated 410 with supported ADMs. A Nickname is the compression of a shared 411 portion of an ARI. Nickname enumerations MUST be unique. The format 412 of the table is defined as follows. 414 +----------------+------------------+------+-----+---------+-------+ 415 | Field | Type | Null | Key | Default | Extra | 416 +----------------+------------------+------+-----+---------+-------+ 417 | adm_id | int(10) unsigned | NO | MUL | | | 418 | nickname_enum | int(10) unsigned | NO | | | | 419 | label | varchar(255) | NO | | | | 420 +----------------+------------------+------+-----+------------+----+ 422 adm_nicknames 424 adm_id 425 The primary key for this table. 427 nickname_enum 428 The enumeration of the nickname. 430 label 431 This is the label of the nickname. 433 4.2. Supported ADMs - adm 435 The adm table identifies all of the ADMs supported by the AMP Manager 436 and associated application. The format of the table is as follows. 438 +-------------+-----------------+------+-----+---------+---------------+ 439 | Field | Type | Null | Key | Default | Extra | 440 +-------------+-----------------+------+-----+---------+---------------+ 441 | adm_id | int(10) unsigned| NO | PRI | | auto_increment| 442 | name | varchar(255) | NO | UNI | | | 443 | version | varchar(255) | NO | | | | 444 | description | varchar(255) | NO | | | | 445 | Organization| varchar(255) | NO | | | | 446 +--------------+------------------+------+-----+---------+-------------+ 448 adm 450 adm_id 451 The primary key for this table. 453 name 454 The name of the supported ADM. 456 version 457 The string representing the version of the ADM. A string is 458 used to allow for a variety of version formats. 460 description 461 This is the description of the ADM. 463 Organization 464 This is the issuing organization of the ADM. 466 4.3. ARIs 468 ARIs identifying items such as Controls may accept parameters to 469 customize their behavior. When defined in the context of an ADM, a 470 parameterized ARI only includes the non-parameterized portion of the 471 ARI followed by the expected data types for the parameterized portion 472 of the ARI. This, essentially, acts as a template for populating a 473 specific instance of the ARI with actual data. 475 This "template" is referred to as a ARI, as it is used to generate 476 ARI instances. The instances of an ARI are called ARI definitions. 477 The amp_core database schema identifies three tables used to capture 478 ARI definitions from ADMs: parmspec, parmspec_set, ari, and 479 ari_definition. 481 4.3.1. Individual ARI Parameter - parmspec 483 The parmspec table contains a row for each parameter associated with 484 an ARI. All of the parameters for an ARI, together, are considered a 485 "collection" of parameters. The format of the table is as follows. 487 +-----------+------------------+------+-----+---------+-------+ 488 | Field | Type | Null | Key | Default | Extra | 489 +-----------+------------------+------+-----+---------+-------+ 490 | name | varchar(45) | NO | | | | 491 | parm_id | int(10) unsigned | YES | MUL | NULL | | 492 | parm_order| int(10) unsigned | NO | UNI | 0 | | 493 | type_id | int(10) unsigned | YES | MUL | NULL | | 494 +-----------+------------------+------+-----+---------+-------+ 496 parmspec 498 name 499 The name of the parmspec collection. 501 parm_id 502 The id of the collection for this parameter. A parameter 503 collection is the ordered set of parameters that describe an 504 ARI. This is a foreign key that corresponds to the parm_id 505 of the parmspec_set table. 507 parm_order 508 The 0-based ordering of this parameter within the collection. 510 type_id 511 The type of this parameter. This must be one of the known 512 AMP types and, as such, is a foreign key that corresponds to 513 the enumeration of the data_type table. 515 4.3.2. ARI Parameter Collection - parmspec_set 517 The parmspec_set table represents the ordered set of parameters 518 associated with an ARI. The format of the table is as follows. 520 +---------+------------------+------+-----+--------+----------------+ 521 | Field | Type | Null | Key | Default| Extra | 522 +---------+------------------+------+-----+--------+----------------+ 523 | parm_id | int(10) unsigned | NO | PRI | | auto_increment | 524 |comment | varchar(255) | NO | | | | 525 +---------+------------------+------+-----+--------+----------------+ 527 parmspec_set 529 parm_id 530 The primary key for this table. 532 comment 533 This is the description of the parmspec set. 535 4.3.3. ARI - ari 537 The ari table captures the ARIs in the database. Some ARIs will be 538 auto-populated from ADMs. Others will be added dynamically by users 539 of the system. As per [AMP], an ARI without an identified Issuer 540 field is assumed to be as defined in an ADM. The format of the table 541 is defined as follows. 543 +--------------+-------------------+------+-----+----------+----------+ 544 | Field | Type | Null | Key | Default | Extra | 545 +--------------+-------------------+------+-----+----------+----------+ 546 | curr_id | int(10) unsigned | NO | PRI | | | 547 | name | varchar(50) | NO | UNI | Unnamed | | 548 | ari_id | int(10) unsigned | NO | MUL | | | 549 | data_id | int(10) unsigned | NO | MUL | | | 550 | description | varchar(255) | YES | | | | 551 +--------------+-------------------+------+-----+----------+----------+ 553 ari 555 curr_id 556 The primary key for this table. 558 name 559 The name of the ARI. 561 ari_id 562 This is the id of the ARI. This is a foreign key that 563 corresponds to the ari_id in the ari_definition table. 565 data_id 566 This is a foreign key to the data_set table that corresponds 567 with the data_id of the data_set table. 569 description 570 This is the description of the ari. 572 4.3.4. ARI - ari_definition 574 The ari_definition table stores the metadata of all known ARIs. The 575 format of the table is as follows. 577 +---------------+-----------------+------+-----+---------+----------+ 578 | Field | Type | Null | Key | Default | Extra | 579 +---------------+-----------------+------+-----+---------+----------+ 580 | ari_id | int(10) unsigned| NO | PRI | | auto_inc | 581 | name | varchar(50) | NO | UNI | Unnamed | | 582 | type_id | int(10) unsigned| NO | MUL | NULL | | 583 | nn_id | int(10) unsigned| YES | MUL | NULL | | 584 | ari_bytestring| varchar(255) | NO | | | | 585 | parm_id | int(10) unsigned| YES | MUL | NULL | | 586 | issuer | bigint unsigned | YES | | NULL | | 587 | tag | bigint unsigned | YES | | NULL | | 588 | structure_id | varchar(255) | YES | MUL | NULL | | 589 | in_type_id | int(10) unsigned| YES | MUL | NULL | | 590 +---------------+-----------------+------+-----+---------+----------+ 592 ari_definition 594 ari_id 595 The primary key for this table. 597 nn_id 598 The nickname associated with this ARI, if applicable. This 599 is a foreign key that corresponds to the id in the 600 adm_nickname table. 602 parm_id 603 The parameter collection for this ARI. This is a foreign key 604 that corresponds to the parm_id in the parm_set table. 606 issuer_flag 607 A binary value representing whether the ARI has an issuer 608 field (value 1) or not (value 0). 610 tag_flag 611 A binary value representing whether the ARI has a tag field 612 (value 1) or not (value 0). 614 type_id 615 The data type associated with this ARI. This is a foreign 616 key that corresponds to the data_id in the data_types table. 618 name 619 A human-readable name for this ARI. 621 ari_bytestring 622 The enumeration of the ARI. 624 structure_id 625 This is the structure type of the ARI (EDD, VAR,etc.). This 626 is a foreign key that corresponds to the data_id in the 627 data_types table. 629 in_type_id 630 This is the in types that are needed to use a specific 631 operator. This is a foreign key that corresponds to the 632 in_type_id in the in_type_set table. 634 5. Agent Support 636 5.1. Registered Agents - registered_agents 638 The registered_agents table lists the network identifiers for each 639 Agent known in the network. The format of the table is defined as 640 follows. 642 +------------+-----------------+------+-----+---------+---------------+ 643 | Field | Type | Null | Key | Default | Extra | 644 +------------+-----------------+------+-----+---------+---------------+ 645 | registry_id| int(10) unsigned| NO | PRI | | auto_increment| 646 | agent_id | varchar(128) | NO | | ipn:0.0 | | 647 +------------+-----------------+------+-----+---------+---------------+ 649 registered_agents 651 registry_id 652 The primary key for this table. 654 agent_id 655 This is the identifier for the Agent, suitable for passing 656 into a network send call. A string representation is 657 selected to best capture the identifier format for a 658 particular network. 660 6. ARI Information 662 6.1. Data Collections 664 Data collection tables capture the Data Collection (DC) data type as 665 defined in [I-D.birrane-dtn-amp]. Similar to the parmspec and 666 parmspec_set tables, Data Collections are represented as an ordered 667 collection of individual data items, with one table representing the 668 collection itself, and another table holding the ordered data within 669 the collection. 671 6.1.1. Data Collection Entry - data_value 673 The data_value table holds data collection entries, one per row. The 674 format of the table is defined as follows. 676 +------------+------------------+------+-----+---------+-------+ 677 | Field | Type | Null | Key | Default | Extra | 678 +------------+------------------+------+-----+---------+-------+ 679 | data_id | int(10) unsigned | NO | MUL | | | 680 | data_order | int(10) unsigned | NO | UNI | 0 | | 681 | data_type | int(10) unsigned | NO | MUL | | | 682 | ari_id | blob | YES | MUL | NULL | | 683 | byte | longblob | YES | | NULL | | 684 | tnvc_id | int(10) unsigned | NO | MUL | | | 685 | ac_id | int(10) unsigned | NO | MUL | | | 686 | vast | bigint | YES | | NULL | | 687 | uvast | bigint unsigned | YES | | NULL | | 688 | real | longblob | YES | | NULL | | 689 | str | varchar(255) | YES | | NULL | | 690 | bool | boolean | YES | | NULL | | 691 | ts | datetime | YES | | NULL | | 692 +------------+------------------+------+-----+---------+-------+ 694 data_value 696 data_id 697 The id of the data collection. This is a foreign key that 698 corresponds with the data_id of the data_set table. 700 data_order 701 The 0-based order of this entry in the encapsulating 702 collection. 704 data_type 705 The type of this data collection. This is a foreign key that 706 corresponds to the enumeration in the data_types table. 708 tnvc_id 709 This is a foreign key that corresponds to the tnvc_id of the 710 tnvc_set table. 712 ac_id 713 This is a foreign key that corresponds to the ac_id of the 714 ac_set table. 716 byte 717 The byte value shows the value of the data (if the piece of 718 data is a byte). If the data is not a byte, this field MUST 719 be NULL. 721 vast 722 The vast value shows the value of the data (if the piece of 723 data is of type int or vast). If the data is not an int or 724 vast, this field MUST be NULL. 726 uvast 727 The uvast value shows the value of the data (if the piece of 728 data is of type uint or vast). If the data is not an uint or 729 uvast, this field MUST be NULL. 731 real 732 The real value shows the value of the data (if the piece of 733 data is of type real32 or real64). If the data is not a 734 real32 or real64, this field MUST be NULL. 736 Str 737 The str field shows the value of the data (if the piece of 738 data is of type string). If the data is not a string, this 739 field MUST be NULL. 741 Bool 742 The bool field shows the value of the data (if the piece of 743 data is of type boolean). If the data is not a boolean, this 744 field MUST be NULL. 746 ts 747 The ts field shows the value of the data (if the piece of 748 data is of type timestamp). If the data is not a timestamp, 749 this field MUST be NULL. 751 6.1.2. Data Collection - data_set 753 The data_collection_set table holds information for a particular 754 collection of data entries (from data_value). The format of the 755 table is defined as follows. 757 +-------+------------------+------+-----+----------+----------------+ 758 | Field | Type | Null | Key | Default | Extra | 759 +-------+------------------+------+-----+----------+----------------+ 760 |data_id| int(10) unsigned | NO | PRI | | auto_increment | 761 |comment| varchar(255) | NO | | | | 762 +-------+------------------+------+-----+----------+----------------+ 764 data_set 766 data_id 767 The Data Collection identifier. This is a primary key. 769 comment 770 This is a description of the data set. 772 6.2. ARI Collections 774 A ARI Collection is an ordered set of ARI values, similar to a Data 775 Collection, which is an ordered set of Data values. One table is 776 used to represent the ARI Collection, and another table is used to 777 capture the ordered ARIs in the collection. 779 6.2.1. ARI Collection Entry - ac 781 The ac table holds ARI collection entries, one per row. The format 782 of the table is defined as follows. 784 +----------+------------------+------+-----+---------+-------+ 785 | Field | Type | Null | Key | Default | Extra | 786 +----------+------------------+------+-----+---------+-------+ 787 | ac_id | int(10) unsigned | NO | MUL | | | 788 | ac_order | int(10) unsigned | NO | | 0 | | 789 | ari_id | int(10) unsigned | NO | MUL | | | 790 +----------+------------------+------+-----+---------+-------+ 792 ac 794 ac_id 795 The ARI Collection to which this entry belongs. This is a 796 foreign key that corresponds with the ac_id of the ac_set 797 table. 799 ari_id 800 The identifier for this ARI. This is a foreign key that 801 corresponds to the ari_id in the ari_definition table. 803 ac_order 804 The 0-based order of this entry in the encapsulating 805 collection. 807 6.2.2. ARI Collection - ac_set 809 The ac_set table holds information for a particular collection of 810 ARIs (from the ac table). The format of the table is defined as 811 follows. 813 +---------+------------------+------+-----+---------+----------------+ 814 | Field | Type | Null | Key | Default | Extra | 815 +---------+------------------+------+-----+---------+----------------+ 816 | ac_id | int(10) unsigned | NO | PRI | | auto_increment | 817 | comment | varchar(255) | NO | | | | 818 +---------+------------------+------+-----+---------+----------------+ 820 ac_set 822 ac_id 823 The ARI Collection identifier. 825 7. Operator Support 827 7.1. In Type Set - in_type_set 829 The in_type_set table holds information for a particular collection 830 of operator in types (from the in_types table). The format of the 831 table is defined as follows. 833 +----------+------------------+------+-----+---------+----------------+ 834 | Field | Type | Null | Key | Default | Extra | 835 +----------+------------------+------+-----+---------+----------------+ 836 |in_type_id| int(10) unsigned | NO | PRI | | auto_increment | 837 | comment | varchar(255) | NO | | | | 838 +----------+------------------+------+-----+---------+----------------+ 840 in_type_set 842 in_type_id 843 The in_type set identifier. 845 comment 846 The description of the in_type set. 848 7.2. In Type - in_type 850 The in_type table holds information about operator in types. The 851 format of the table is defined as follows. 853 +----------+------------------+------+-----+---------+----------------+ 854 | Field | Type | Null | Key | Default | Extra | 855 +----------+------------------+------+-----+---------+----------------+ 856 |in_type_id| int(10) unsigned | NO | PRI | | auto_increment | 857 | name | varchar(255) | NO | | | | 858 | order | int(10) unsigned | NO | | | | 859 | type id | int(10) unsigned | NO | MUL | | | 860 +----------+------------------+------+-----+---------+----------------+ 862 in_type_set 864 in_type_id 865 The in_type set identifier. This is a foreign key that 866 corresponds to the in_type_id of the in_type_set table. 868 name 869 The name of the operator in type. 871 order 872 The order of the operator in type in the set. 874 type id 875 This is the type of the operator in_type. This is a foreign 876 key that corresponds to the enumeration in the data_types 877 table. 879 8. Outgoing Message Support 881 Outgoing messages are those that are written into the database by an 882 application and read by an AMP Manager, formatted, and sent to one or 883 more AMP Agents. 885 The database represents outgoing messages in two tables. One table 886 holds information for the entire outgoing message group, and another 887 table captures each individual outgoing message. An individual 888 outgoing message is simply a ARI collection of the ARIs to be run on 889 the Agent. 891 8.1. Outgoing Messages - outgoing_message 893 The outgoing_message table captures a single ARI Collection holding 894 the set of Control ARIs to be sent to an Agent as part of a Message 895 Group. The format of the table is defined as follows. 897 +------------+-----------------+------+-----+---------+---------------+ 898 | Field | Type | Null | Key | Default | Extra | 899 +------------+-----------------+------+-----+---------+---------------+ 900 | message_id | int(10) unsigned| NO | PRI | | auto_increment| 901 | group_id | int(10) unsigned| NO | MUL | | | 902 | start_ts | datetime | NO | | 0 | | 903 | ac_id | int(10) unsigned| NO | MUL | | | 904 +------------+-----------------+------+-----+---------+---------------+ 906 outgoing_message 908 message_id 909 The primary key for this table. 911 group_id 912 The outgoing message group to which this outgoing message 913 belongs. This is a foreign key that corresponds to the id in 914 the outgoing_message_group table. 916 start_ts 917 The time at which the controls in the ARI Collection should 918 be run. This may be an absolute or relative time, as defined 919 in [I-D.birrane-dtn-amp]. 921 ac_id 922 The ARI Collection comprising this outgoing message. This is 923 a foreign key that corresponds to the ac_id of the ac_set 924 table. 926 8.2. Outgoing Message Groups - outgoing_message_group 928 The outgoing_message_group table captures an outgoing message group, 929 which is one or more outgoing messages. The format of the table is 930 defined as follows. 932 +------------+-----------------+------+-----+---------+---------------+ 933 | Field | Type | Null | Key | Default | Extra | 934 +------------+-----------------+------+-----+---------+---------------+ 935 | group_id | int(10) unsigned| NO | PRI | | auto_increment| 936 | created_ts | datetime | YES | | NULL | | 937 | modified_ts| datetime | YES | | NULL | | 938 | state | tinyint(4) | NO | MUL | | | 939 | agent_id | int(10) unsigned| NO | MUL | | | 940 +------------+-----------------+------+-----+---------+---------------+ 942 outgoing_message_group 944 group_id 945 The primary key for this table. 947 created_ts 948 The time at which the outgoing message group was created. 950 modified_ts 951 The last time at which the message group was modified. 953 state 954 The current state of the outgoing message group. This state 955 provides a contention-avoidance mechanism between an 956 application and an AMP Manager. This is a foreign key that 957 corresponds to the state_id of the outgoing_state table. 959 agent_id 960 The identifier of the Agent receiving this message group. 961 Currently, a message group is only sent to one Agent. 962 Sending to multiple Agents is accomplished with multiple 963 entries in this table. This is a foreign key that 964 corresponds to the registry_id in the registered_agents 965 table. 967 9. Incoming Message Support 969 Incoming messages are those that are written into the database by an 970 AMP Manager and read by an application wishing to understand the 971 status of an AMP Agent. 973 The database represents incoming messages in two tables. One table 974 holds information for the entire incoming message group, and another 975 table captures each individual incoming message. 977 9.1. Incoming Messages - incoming_messages 979 The incoming_messages table captures information returned from an AMP 980 Agent. The format of the table is defined as follows. 982 +------------+-----------------+------+-----+---------+---------------+ 983 | Field | Type | Null | Key | Default | Extra | 984 +------------+-----------------+------+-----+---------+---------------+ 985 | message_id | int(10) unsigned| NO | PRI | NULL | auto_increment| 986 | group_id | int(10) unsigned| NO | MUL | NULL | | 987 | ac_id | int(10) unsigned| YES | MUL | NULL | | 988 +------------+-----------------+------+-----+---------+---------------+ 990 incoming_messages 992 message_id 993 The primary key for this table. 995 group_id 996 The incoming message group to which this incoming message 997 belongs. This is a foreign key that corresponds with the 998 group_id in the incoming_message_group table. 1000 ac_id 1001 This is a foreign key that corresponds to the id in the 1002 ac_set table. 1004 9.2. Incoming Message Groups - incoming_message_group 1006 The incoming_message_group table captures an incoming message group, 1007 which is one or more incoming messages. The format of the table is 1008 defined as follows. 1010 +-------------+---------------------+------+-----+---------+-----------+ 1011 | Field | Type | Null | Key | Default | Extra | 1012 +-------------+---------------------+------+-----+---------+-----------+ 1013 | group_id | int(10) unsigned | NO | PRI | | auto_incr | 1014 | recieved_ts | datetime | YES | | NULL | | 1015 | generated_ts| datetime | YES | | NULL | | 1016 | state | tinyint(3) unsigned | NO | MUL | | | 1017 | agent_id | int(10) unsigned | NO | MUL | | | 1018 +-------------+---------------------+------+-----+---------+-----------+ 1020 incoming_message_group 1022 group_id 1023 The primary key for this table. 1025 recieved_ts 1026 The time at which the incoming message group was received by 1027 the AMP Manager. 1029 generated_ts 1030 The time at which the incoming message group was generated by 1031 the sending AMP Agent. 1033 state 1034 The current state of the incoming message group. This state 1035 provides a contention-avoidance mechanism between an 1036 application and an AMP Manager. This is a foreign key that 1037 corresponds to the data_id in the data_types table. 1039 agent_id 1040 The identifier of the Agent sending this incoming message 1041 group. This is a foreign key that corresponds to the 1042 registry_id in the registered_agents table. 1044 10. Compound Data Types 1046 10.1. TNVC Support 1048 10.1.1. Type Name Value Collection - tnvc 1050 The tnvc table is a group of tnv collections. 1052 +----------+------------------+------+-----+---------+-----------+ 1053 | Field | Type | Null | Key | Default | Extra | 1054 +----------+------------------+------+-----+---------+-----------+ 1055 | tnvc_id | int(10) unsigned | NO | PRI | | auto_incr | 1056 | order | int(10) unsigned | NO | UNI | | | 1057 | name | int(10) unsigned | YES | | | | 1058 | value | int(10) unsigned | NO | MUL | | | 1059 +----------+------------------+------+-----+---------+-----------+ 1061 tnvc 1063 tnvc_id 1064 The identifier of the TNV collection. This is a foreign key 1065 that corresponds to the tnvc_id in the tnvc_set table. 1067 order 1068 The order of the tnvc in the set. 1070 name 1071 The name of the tnvc. 1073 value 1074 The value of the tnvc. This is a foreign key that 1075 corresponds to the data_id in the data_set table. 1077 10.1.2. Type Name Value Collection Set - tnvc_set 1079 The tnvc_set table provides the information of a TNV (Type-Name- 1080 Value) collection that describes data values in the AMM. 1082 +----------+-----------------+------+-----+---------+-----------+ 1083 | Field | Type | Null | Key | Default | Extra | 1084 +----------+-----------------+------+-----+---------+-----------+ 1085 | tnvc_id | int(10) unsigned| NO | PRI | NULL | auto_incr | 1086 | comment | varchar(255) | NO | | | | 1087 +----------+-----------------+------+-----+---------+-----------+ 1089 tnv_collection 1091 tnvc_id 1092 The identifier of the TNV collection. This is a primary key. 1094 comment 1095 This is the description of the tnvc set. 1097 10.2. Expression Support 1099 10.2.1. Expression Set - expression_set 1101 The expression_set table shows the id of the expression as well as 1102 whether it is true or false. This table is a collection of 1103 expressions. 1105 +---------+------------------+------+-----+---------+-----------+ 1106 | Field | Type | Null | Key | Default | Extra | 1107 +---------+------------------+------+-----+---------+-----------+ 1108 | expr_id | int(10) unsigned | NO | PRI | NULL | auto_incr | 1109 | comment | varchar(255) | NO | | | | 1110 +---------+------------------+------+-----+---------+-----------+ 1112 expression_set 1114 expr_id 1115 The identifier of the expression. This is a primary key. 1117 comment 1118 This is the description of the expression. 1120 10.2.2. Individual Expression - expression 1122 An expression is an AC in which a series of items are ordered so as 1123 to produce a valid post-fix mathematical expression. This table 1124 contains all of the information that are included in each expression. 1126 +-----------+------------------+------+-----+---------+-----------+ 1127 | Field | Type | Null | Key | Default | Extra | 1128 +-----------+------------------+------+-----+---------+-----------+ 1129 | expr_id | int(10) unsigned | NO | PRI | NULL | auto_incr | 1130 | order_num | int(10) unsigned | NO | UNI | NULL | | 1131 | ari_id | int(10) unsigned | NO | MUL | NULL | | 1132 +-----------+------------------+------+-----+---------+-----------+ 1134 expression 1136 expr_id 1137 The identifier of the expression. This is a foreign key that 1138 corresponds to the expr_id in the expression_set table. 1140 order_num 1141 The 0-based order of this entry in the encapsulating 1142 collection. 1144 ari_id 1145 This is the ari id. This is a foreign key that corresponds 1146 to the ari_id in the ari_definition table. 1148 11. IANA Considerations 1150 At this time, this schema definition has no fields registered by 1151 IANA. 1153 12. Security Considerations 1155 Security considerations are outside of the scope of this document. 1157 13. References 1159 13.1. Informative References 1161 [I-D.birrane-dtn-ama] 1162 Birrane, E., "Asynchronous Management Architecture", 1163 draft-birrane-dtn-ama-07 (work in progress), June 2018. 1165 13.2. Normative References 1167 [I-D.birrane-dtn-adm] 1168 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 1169 Data Model", draft-birrane-dtn-adm-02 (work in progress), 1170 June 2018. 1172 [I-D.birrane-dtn-amp] 1173 Birrane, E., "Asynchronous Management Protocol", draft- 1174 birrane-dtn-amp-04 (work in progress), June 2018. 1176 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1177 Requirement Levels", BCP 14, RFC 2119, 1178 DOI 10.17487/RFC2119, March 1997, 1179 . 1181 Appendix A. Acknowledgements 1183 The following participants contributed technical material, use cases, 1184 and useful thoughts on the overall approach to this database 1185 specification: Leor Bleir of the NASA Goddard Space Flight Center, 1186 Michael Deschu and Shane Knudsen of Hammers Company, Inc. on behalf 1187 of the NASA Goddard Space Flight Center, and Paul Swencon of ASRC 1188 Space And Defense on behalf of the NASA Goddard Space Flight Center. 1190 Authors' Addresses 1192 Edward J. Birrane 1193 Johns Hopkins Applied Physics Laboratory 1195 Email: Edward.Birrane@jhuapl.edu 1197 Evana DiPietro 1198 Johns Hopkins Applied Physics Laboratory 1200 Email: Evana.DiPietro@jhuapl.edu 1202 David Linko 1203 Johns Hopkins Applied Physics Laboratory 1205 Email: David.Linko@jhuapl.edu 1206 Mark A. Sinkiat 1207 ASRC Space And Defense, NASA GSFC 1209 Email: mark.a.sinkiat@nasa.gov