idnits 2.17.00 (12 Aug 2021) /tmp/idnits46975/draft-birrane-dtn-adm-ionadmin-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([I-D.birrane-dtn-adm]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 564 has weird spacing: '...lt heap limit...' -- The document date (March 11, 2019) is 1160 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-03) exists of draft-birrane-dtn-adm-02 == Outdated reference: A later version (-08) exists of draft-birrane-dtn-amp-04 Summary: 2 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: Experimental D. Linko 5 Expires: September 12, 2019 Johns Hopkins Applied Physics Laboratory 6 March 11, 2019 8 ION Administration Application Data Model 9 draft-birrane-dtn-adm-ionadmin-01 11 Abstract 13 This document describes the Application Data Model (ADM) for the 14 administration of ION in compliance with the template provided by 15 [I-D.birrane-dtn-adm]. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 12, 2019. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Technical Notes . . . . . . . . . . . . . . . . . . . . . 2 53 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2. Structure and Design of this ADM . . . . . . . . . . . . . . 3 56 3. Naming and Identification . . . . . . . . . . . . . . . . . . 4 57 3.1. Namespace and Nicknames . . . . . . . . . . . . . . . . . 4 58 4. ION Admin ADM JSON Encoding . . . . . . . . . . . . . . . . . 5 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 61 6.1. Informative References . . . . . . . . . . . . . . . . . 15 62 6.2. Normative References . . . . . . . . . . . . . . . . . . 15 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 65 1. Introduction 67 An Application Data Model (ADM) provides a guaranteed interface for 68 the management of an application or protocol in accordance with the 69 Asynchronous Management Architecture (AMA) defined in 70 [I-D.birrane-dtn-ama]. The ADM described in this document complies 71 with the ADM Template provided in [I-D.birrane-dtn-adm] as encoded 72 using the JSON syntax. 74 The ION Administration ADM contains all of the functionality that is 75 required for the proper configuration and management of ION nodes. 77 1.1. Technical Notes 79 o This document describes Version 0.0 of the ION Admin ADM. 81 o The AMM Resource Identifier (ARI) for this ADM is NOT correctly 82 set. A sample ARI is used in this version of the specification 83 and MAY change in future versions of this ADM until an ARI 84 registry is established. This notice will be removed at that 85 time. 87 o Agent applications MAY choose to ignore the name, description, or 88 other annotative information associated with the component 89 definitions within this ADM where such items are only used to 90 provide human-readable information or are otherwise not necessary 91 to manage a device. 93 1.2. Scope 95 This ADM specifies those components of the Asynchronous Management 96 Model (AMM) common to the administration of ION. 98 Any Manager software implementing this ADM MUST perform the 99 responsibilities of an AMA Manager as outlined in 100 [I-D.birrane-dtn-adm] as they relate to the objects included in this 101 document. 103 Any Agent software implementing this ADM MUST perform the 104 responsibilities of an AMA Agent as outlined in [I-D.birrane-dtn-adm] 105 as they relate to the objects included in this document. 107 1.3. Requirements Language 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in RFC 2119 [RFC2119]. 113 2. Structure and Design of this ADM 115 The ION Admin ADM's structure is in accordance with 116 [I-D.birrane-dtn-adm]. This ADM contains metadata, edd, table 117 templates, and controls. Externally Defined Data (EDD) are values 118 that are calculated external to the ADM system. Table Templates are 119 column templates that will be followed by any instance of this table 120 available in the network. They may not be created dynamically within 121 the network by Managers. Controls are predefined and sometimes 122 parameterized opcodes that can be run on an Agent. Controls are 123 preconfigured in Agents and Managers as part of ADM support. There 124 are no variables, report templates, macros, constants, or operators 125 in this ADM at this time. 127 The contents of this ADM are derived from the main functions and data 128 that are needed to configure and manage the node on the local 129 computer that is running ION. The core functions of the 130 administration of ION nodes that are included in this ADM deal with 131 contacts (information about periods of data transmission), ranges 132 (periods of time when the distance between two nodes is constant), 133 occupancy limits (the maximum amount of megabytes of storage space in 134 ION's SDR non volatile heap and/or local file system), rates of data 135 production, congestion, consumption (rate of continuous data delivery 136 to local BP applications), and time. 138 All ADMs have metadata that includes the name, namespace, and version 139 of the ADM, as well as the name of the organization that is issuing 140 that particular ADM. This is important for identification purposes 141 of the ADMs and to ensure version control of the encoding. 143 3. Naming and Identification 145 This section outlines the namespaces used to uniquely identify ADM 146 objects in this specification. 148 3.1. Namespace and Nicknames 150 In accordance with [I-D.birrane-dtn-adm], every ADM is assigned a 151 moderated Namespace. In accordance with [I-D.birrane-dtn-amp], these 152 namespaces may be enumerated for compactness. The namespace and ADM 153 identification for these objects is defined as follows. 155 +-----------------+------------------+ 156 | Identifier | Value | 157 +-----------------+------------------+ 158 | Namespace | DTN/ION/ionadmin | 159 | | | 160 | ADM Enumeration | 7 | 161 +-----------------+------------------+ 163 Table 1: Namespace Information 165 Given the above ADM enumeration, in accordance with 166 [I-D.birrane-dtn-amp], the following AMP nicknames are defined. 168 +----------+------------------------------+ 169 | Nickname | Collection | 170 +----------+------------------------------+ 171 | 140 | DTN/ION/ionadmin/Const | 172 | | | 173 | 141 | DTN/ION/ionadmin/Ctrl | 174 | | | 175 | 142 | DTN/ION/ionadmin/Edd | 176 | | | 177 | 143 | DTN/ION/ionadmin/Mac | 178 | | | 179 | 144 | DTN/ION/ionadmin/Oper | 180 | | | 181 | 145 | DTN/ION/ionadmin/Rptt | 182 | | | 183 | 147 | DTN/ION/ionadmin/Tblt | 184 | | | 185 | 149 | DTN/ION/ionadmin/Var | 186 | | | 187 | 150 | DTN/ION/ionadmin/Mdat | 188 | | | 189 | 151-159 | DTN/ION/ionadmin/Reserved | 190 +----------+------------------------------+ 192 Table 2: ION Admin ADM Nicknames 194 4. ION Admin ADM JSON Encoding 196 The following is the JSON encoding of the ION Administration 197 Application Data Model: 199 { 200 "Mdat": [{ 201 "name": "name", 202 "type": "STR", 203 "value": "ion_admin", 204 "description": "The human-readable name of the ADM." 205 }, 206 { 207 "name": "namespace", 208 "type": "STR", 209 "value": "DTN/ION/ionadmin", 210 "description": "The namespace of the ADM." 211 }, 212 { 213 "name": "version", 214 "type": "STR", 215 "value": "v0.0", 216 "description": "The version of the ADM." 217 }, 218 { 219 "name": "organization", 220 "type": "STR", 221 "value": "JHUAPL", 222 "description": "The name of the issuing organization of the 223 ADM." 224 } 225 ], 227 "Edd": [{ 228 "name": "clock_error", 229 "type": "UINT", 230 "description": "This is how accurate the ION Agent's clock is 231 described as number of seconds, an absolute 232 value." 233 }, 234 { 235 "name": "clock_sync", 236 "type": "UINT", 237 "description": "This is whether or not the the computer on 238 which the local ION node is running has a 239 synchronized clock." 240 }, 241 { 242 "name": "congestion_alarm_control", 243 "type": "UINT", 244 "description": "This is whether or not the node has a control 245 that will set off alarm if it will become 246 congested at some future time." 247 }, 248 { 249 "name": "congestion_end_time_forecasts", 250 "type": "UINT", 251 "description": "This is the time horizon beyond which we don't 252 attempt to forecast congestion" 253 }, 254 { 255 "name": "consumption_rate", 256 "type": "UINT", 257 "description": "This is the mean rate of continuous data 258 delivery to local BP applications." 259 }, 260 { 261 "name": "inbound_file_system_occupancy_limit", 262 "type": "UINT", 263 "description": "This is the maximum number of megabytes of 264 storage space in ION's local file system that 265 can be used for the storage of inbound zero-copy 266 objects. The default heap limit is 1 Terabyte." 267 }, 268 { 269 "name": "inbound_heap_occupancy_limit", 270 "type": "UINT", 271 "description": "This is the maximum number of megabytes of 272 storage space in ION's SDR non-volatile heap 273 that can be used for the storage of inbound 274 zero-copy objects. The default heap limit is 275 20% of the SDR data space's total heap size." 276 }, 277 { 278 "name": "number", 279 "type": "UINT", 280 "description": "This is a CBHE node number which uniquely 281 identifies the node in the delay-tolerant 282 network." 283 }, 284 { 285 "name": "outbound_file_system_occupancy_limit", 286 "type": "UINT", 287 "description": "This is the maximum number of megabytes of 288 storage space in ION's local file system that 289 can be used for the storage of outbound 290 zero-copy objects. The default heap limit is 291 1 Terabyte." 292 }, 293 { 294 "name": "outbound_heap_occupancy_limit", 295 "type": "UINT", 296 "description": "This is the maximum number of megabytes of 297 storage space in ION's SDR non-volatile heap 298 that can be used for the storage of outbound 299 zero-copy objects. The default heap limit is 300 20% of the SDR data space's total heap size." 301 }, 302 { 303 "name": "production_rate", 304 "type": "UINT", 305 "description": "This is the rate of local data production." 306 }, 307 { 308 "name": "ref_time", 309 "type": "TV", 310 "description": "This is the reference time that will be used 311 for interpreting relative time values from now 312 until the next revision of reference time." 313 }, 314 { 315 "name": "time_delta", 316 "type": "UINT", 317 "description": "The time delta is used to compensate for error 318 (drift) in clocks, particularly spacecraft 319 clocks. The hardware clock on a spacecraft 320 might gain or lose a few seconds every month, 321 to the point at which its understanding of the 322 current time - as reported out by the operating 323 system - might differ significantly from the 324 actual value of Unix Epoch time as reported by 325 authoritative clocks on Earth. To compensate for 326 this difference without correcting the clock 327 itself (which can be difficult and dangerous), 328 ION simply adds the time delta to the Epoch 329 time reported by the operating system." 330 }, 331 { 332 "name": "version", 333 "type": "STR", 334 "description": "This is the version of ION that is currently 335 installed." 336 } 337 ], 339 "Tblt": [{ 340 "name": "contacts", 341 "columns": [{ 342 "type": "TV", 343 "name": "start_time" 344 }, { 345 "type": "TV", 346 "name": "stop_time" 347 }, { 348 "type": "UINT", 349 "name": "source_node" 350 }, { 351 "type": "UINT", 352 "name": "dest_node" 353 }, { 354 "type": "UVAST", 355 "name": "xmit_data" 356 }, { 357 "type": "UVAST", 358 "name": "confidence" 360 }], 361 "description": "This table shows all scheduled periods of data 362 transmission." 363 }, 364 { 365 "name": "ranges", 366 "columns": [{ 367 "type": "TV", 368 "name": "start" 369 }, { 370 "type": "TV", 371 "name": "stop" 372 }, { 373 "type": "UINT", 374 "name": "node" 375 }, { 376 "type": "UINT", 377 "name": "other_node" 378 }, { 379 "type": "UINT", 380 "name": "distance" 381 }], 382 "description": "This table shows all predicted periods of 383 constant distance between nodes." 384 } 385 ], 387 "Ctrl": [{ 388 "name": "node_init", 389 "parmspec": [{ 390 "type": "UINT", 391 "name": "node_nbr" 392 }, { 393 "type": "STR", 394 "name": "config_file" 395 }], 396 "description": "Until this control is executed, the local ION 397 node does not exist and most ionadmin controls 398 will fail. The control configures the local node 399 to be identified by node_number, a CBHE node 400 number which uniquely identifies the node in 401 the delay-tolerant network. It also configures 402 ION's data space (SDR) and shared working-memory 403 region. For this purpose it uses a set of 404 default settings if no argument follows 405 node_number or if the argument following 406 node_number is ''; otherwise it uses the 407 configuration settings found in a configuration 408 file. If configuration file name is provided, 409 then the configuration file's name is 410 implicitly 'hostname.ionconfig'; otherwise, 411 ion_config_filename is taken to be the explicit 412 configuration file name." 413 }, 414 { 415 "name": "node_clock_error_set", 416 "parmspec": [{ 417 "type": "UINT", 418 "name": "known_maximum_clock_error" 419 }], 420 "description": "This management control sets ION's understanding 421 of the accuracy of the scheduled start and stop 422 times of planned contacts, in seconds. The 423 default value is 1." 424 }, 425 { 426 "name": "node_clock_sync_set", 427 "parmspec": [{ 428 "type": "BOOL", 429 "name": "new_state" 430 }], 431 "description": "This management control reports whether or not 432 the computer on which the local ION node is 433 running has a synchronized clock." 434 }, 435 { 436 "name": "node_congestion_alarm_control_set", 437 "parmspec": [{ 438 "type": "STR", 439 "name": "congestion_alarm_control" 440 }], 441 "description": "This management control establishes a control 442 which will automatically be executed whenever 443 ionadmin predicts that the node will become 444 congested at some future time." 445 }, 446 { 447 "name": "node_congestion_end_time_forecasts_set", 448 "parmspec": [{ 449 "type": "UINT", 450 "name": "end_time_for_congestion_forcasts" 451 }], 452 "description": "This management control sets the end time for 453 computed congestion forecasts. Setting 454 congestion forecast horizon to zero sets the 455 congestion forecast end time to infinite time 456 in the future: if there is any predicted net 457 growth in bundle storage space occupancy at all, 458 following the end of the last scheduled contact, 459 then eventual congestion will be predicted. The 460 default value is zero, i.e., no end time." 461 }, 462 { 463 "name": "node_consumption_rate_set", 464 "parmspec": [{ 465 "type": "UINT", 466 "name": "planned_data_consumption_rate" 467 }], 468 "description": "This management control sets ION's expectation 469 of the mean rate of continuous data delivery to 470 local BP applications throughout the period of 471 time over which congestion forecasts are 472 computed. For nodes that function only as routers 473 this variable will normally be zero. A value of 474 -1, which is the default, indicates that the 475 rate of local data consumption is unknown; in 476 that case local data consumption is not 477 considered in the computation of congestion 478 forecasts." 479 }, 480 { 481 "name": "node_contact_add", 482 "parmspec": [{ 483 "type": "TV", 484 "name": "start" 485 }, { 486 "type": "TV", 487 "name": "stop" 488 }, { 489 "type": "UINT", 490 "name": "from_node_id" 491 }, { 492 "type": "UINT", 493 "name": "to_node_id" 494 }, { 495 "type": "UVAST", 496 "name": "data_rate" 497 }, { 498 "type": "UVAST", 499 "name": "prob" 500 }], 501 "description": "This control schedules a period of data 502 transmission from source_node to dest_node. The 503 period of transmission will begin at start_time 504 and end at stop_time, and the rate of data 505 transmission will be xmit_data_rate bytes/second. 506 Our confidence in the contact defaults to 1.0, 507 indicating that the contact is scheduled - not 508 that non-occurrence of the contact is impossible, 509 just that occurrence of the contact is planned 510 and scheduled rather than merely imputed from 511 ast node behavior. In the latter case, 512 confidence indicates our estimation of the 513 likelihood of this potential contact." 514 }, 515 { 516 "name": "node_contact_del", 517 "parmspec": [{ 518 "type": "TV", 519 "name": "start" 520 }, { 521 "type": "UINT", 522 "name": "node_id" 523 }, { 524 "type": "STR", 525 "name": "dest" 526 }], 527 "description": "This control deletes the scheduled period of 528 data transmission from source_node to dest_node 529 starting at start_time. To delete all contacts 530 between some pair of nodes, use '*' as 531 start_time." 532 }, 533 { 534 "name": "node_inbound_heap_occupancy_limit_set", 535 "parmspec": [{ 536 "type": "UINT", 537 "name": "heap_occupancy_limit" 538 }, { 539 "type": "UINT", 540 "name": "file_system_occupancy_limit" 541 }], 542 "description": "This management control sets the maximum number 543 of megabytes of storage space in ION's SDR 544 non-volatile heap that can be used for the 545 storage of inbound zero-copy objects. A value 546 of -1 for either limit signifies 'leave 547 unchanged'. The default heap limit is 30% of 548 the SDR data space's total heap size." 549 }, 550 { 551 "name": "node_outbound_heap_occupancy_limit_set", 552 "parmspec": [{ 553 "type": "UINT", 554 "name": "heap_occupancy_limit" 555 }, { 556 "type": "UINT", 557 "name": "file_system_occupancy_limit" 558 }], 559 "description": "This management control sets the maximum number 560 of megabytes of storage space in ION's SDR 561 non-volatile heap that can be used for the 562 storage of outbound zero-copy objects. A value 563 of -1 for either limit signifies 'leave 564 unchanged'. The default heap limit is 30% of 565 the SDR data space's total heap size." 566 }, 567 { 568 "name": "node_production_rate_set", 569 "parmspec": [{ 570 "type": "UINT", 571 "name": "planned_data_production_rate" 572 }], 573 "description": "This management control sets ION's expectation 574 of the mean rate of continuous data origination 575 by local BP applications throughout the period 576 of time over which congestion forecasts are 577 computed. For nodes that function only as 578 routers this variable will normally be zero. A 579 value of -1, which is the default, indicates 580 that the rate of local data production is unknown; 581 in that case local data production is not 582 considered in the computation of congestion 583 forecasts." 584 }, 585 { 586 "name": "node_range_add", 587 "parmspec": [{ 588 "type": "TV", 589 "name": "start" 590 }, { 591 "type": "TV", 592 "name": "stop" 593 }, { 594 "type": "UINT", 595 "name": "node" 596 }, { 597 "type": "UINT", 598 "name": "other_node" 599 }, { 600 "type": "UINT", 601 "name": "distance" 602 }], 603 "description": "This control predicts a period of time during 604 which the distance from node to other_node will 605 be constant to within one light second. The 606 period will begin at start_time and end at 607 stop_time, and the distance between the nodes 608 during that time will be distance light seconds." 609 }, 610 { 611 "name": "node_range_del", 612 "parmspec": [{ 613 "type": "TV", 614 "name": "start" 615 }, { 616 "type": "UINT", 617 "name": "node" 618 }, { 619 "type": "UINT", 620 "name": "other_node" 621 }], 622 "description": "This control deletes the predicted period of 623 constant distance between node and other_node 624 starting at start_time. To delete all ranges 625 between some pair of nodes, use '*' as 626 start_time." 627 }, 628 { 629 "name": "node_ref_time_set", 630 "parmspec": [{ 631 "type": "TV", 632 "name": "time" 633 }], 634 "description": "This is used to set the reference time that will 635 be used for interpreting relative time values 636 from now until the next revision of reference 637 time. Note that the new reference time can be 638 a relative time, i.e., an offset beyond the 639 current reference time." 640 }, 641 { 642 "name": "node_time_delta_set", 643 "parmspec": [{ 644 "type": "UINT", 645 "name": "local_time_sec_after_epoch" 646 }], 647 "description": "This management control sets ION's understanding 648 of the current difference between correct time 649 and the Unix Epoch time values reported by the 650 clock for the local ION node's computer. This 651 delta is automatically applied to locally 652 obtained time values whenever ION needs to know 653 the current time." 654 } 655 ] 656 } 658 5. IANA Considerations 660 At this time, this protocol has no fields registered by IANA. 662 6. References 664 6.1. Informative References 666 [I-D.birrane-dtn-ama] 667 Birrane, E., "Asynchronous Management Architecture", 668 draft-birrane-dtn-ama-07 (work in progress), June 2018. 670 6.2. Normative References 672 [I-D.birrane-dtn-adm] 673 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 674 Data Model", draft-birrane-dtn-adm-02 (work in progress), 675 June 2018. 677 [I-D.birrane-dtn-amp] 678 Birrane, E., "Asynchronous Management Protocol", draft- 679 birrane-dtn-amp-04 (work in progress), June 2018. 681 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 682 Requirement Levels", BCP 14, RFC 2119, 683 DOI 10.17487/RFC2119, March 1997, 684 . 686 Authors' Addresses 688 Edward J. Birrane 689 Johns Hopkins Applied Physics Laboratory 691 Email: Edward.Birrane@jhuapl.edu 692 Evana DiPietro 693 Johns Hopkins Applied Physics Laboratory 695 Email: Evana.DiPietro@jhuapl.edu 697 David Linko 698 Johns Hopkins Applied Physics Laboratory 700 Email: David.Linko@jhuapl.edu