idnits 2.17.1 draft-birrane-dtn-adm-bp-03.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 -- The document date (March 11, 2019) is 1870 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == 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 == Outdated reference: A later version (-31) exists of draft-ietf-dtn-bpbis-12 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 Bundle Protocol Agent Application Data Model 9 draft-birrane-dtn-adm-bp-03 11 Abstract 13 This document describes the Application Data Model (ADM) for a Bundle 14 Protocol Agent (BPA) 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 . . . . . . . . . . . . . . . . . . 3 57 3.1. Namespace and Nicknames . . . . . . . . . . . . . . . . . 4 58 4. BP Agent ADM JSON Encoding . . . . . . . . . . . . . . . . . 5 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 61 6.1. Informative References . . . . . . . . . . . . . . . . . 14 62 6.2. Normative References . . . . . . . . . . . . . . . . . . 14 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 Bundle Protocol Agents (BPAs) are software instances that implement 75 functionality required by the Bundle Protocol ([I-D.ietf-dtn-bpbis]). 76 The BPA ADM provides the set of information necessary to remotely 77 manage such agents. 79 1.1. Technical Notes 81 o This document describes Version 0.1 of the BP ADM. 83 o The AMM Resource Identifier (ARI) for this ADM is NOT correctly 84 set. A sample ARI is used in this version of the specification 85 and MAY change in future versions of this ADM until an ARI 86 registry is established. This notice will be removed at that 87 time. 89 o Agent applications MAY choose to ignore the name, description, or 90 other annotative information associated with the component 91 definitions within this ADM where such items are only used to 92 provide human-readable information or are otherwise not necessary 93 to manage a device. 95 1.2. Scope 97 This ADM specifies those components of the Asynchronous Management 98 Model (AMM) common to the management of any instance of a BPA. 100 Any Manager software implementing this ADM MUST perform the 101 responsibilities of an AMA Manager as outlined in 102 [I-D.birrane-dtn-adm] as they relate to the objects included in this 103 document. 105 Any Agent software implementing this ADM MUST perform the 106 responsibilities of an AMA Agent as outlined in [I-D.birrane-dtn-adm] 107 as they relate to the objects included in this document. 109 1.3. Requirements Language 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [RFC2119]. 115 2. Structure and Design of this ADM 117 The BP Agent ADM's structure is in accordance to 118 [I-D.birrane-dtn-adm]. This ADM contains metadata, edd, report 119 templates, and controls. Externally Defined Data (EDD) are values 120 that are calculated external to the ADM system. Report Templates are 121 ordered sets of data descriptions that show how values will be 122 represented in a corresponding report. Controls are predefined and 123 sometimes parameterized opcodes that can be run on an Agent. 124 Controls are preconfigured in Agents and Managers as part of ADM 125 support. There are no variables, table templates, macros, constants, 126 or operators in this ADM at this time. The contents of this ADM are 127 derived from the main functions and data that are needed to configure 128 and manage bundle protocol operations on an ION node. 130 All ADMs have metadata that includes the name, namespace, and version 131 of the ADM as well as the name of the organization that is issuing 132 that particular ADM. This is important for identification purposes 133 of the ADMs and to ensure version control. The main elements of BP 134 that are discussed in this ADM are endpoints, the priority of 135 bundles/bytes, and whether or not the bundles/bytes were transferred 136 successfully. 138 3. Naming and Identification 140 This section outlines the namespaces used to uniquely identify ADM 141 objects in this specification. 143 3.1. Namespace and Nicknames 145 In accordance with [I-D.birrane-dtn-adm], every ADM is assigned a 146 moderated Namespace. In accordance with [I-D.birrane-dtn-amp], these 147 namespaces may be enumerated for compactness. The namespace and ADM 148 identification for these objects is defined as follows. 150 +-----------------+--------------+ 151 | Identifier | Value | 152 +-----------------+--------------+ 153 | Namespace | DTN/bp_agent | 154 | | | 155 | ADM Enumeration | 2 | 156 +-----------------+--------------+ 158 Table 1: Namespace Information 160 Given the above ADM enumeration, in accordance with 161 [I-D.birrane-dtn-amp], the following AMP nicknames are defined. 163 +----------+------------------------------+ 164 | Nickname | Collection | 165 +----------+------------------------------+ 166 | 40 | DTN/bp_agent/Const | 167 | | | 168 | 41 | DTN/bp_agent/Ctrl | 169 | | | 170 | 42 | DTN/bp_agent/Edd | 171 | | | 172 | 43 | DTN/bp_agent/Mac | 173 | | | 174 | 44 | DTN/bp_agent/Oper | 175 | | | 176 | 45 | DTN/bp_agent/Rptt | 177 | | | 178 | 47 | DTN/bp_agent/Tblt | 179 | | | 180 | 49 | DTN/bp_agent/Var | 181 | | | 182 | 50 | DTN/bp_agent/Mdat | 183 | | | 184 | 51-59 | DTN/bp_agent/Reserved | 185 +----------+------------------------------+ 187 Table 2: BP Agent ADM Nicknames 189 4. BP Agent ADM JSON Encoding 191 The following is the JSON encoding for the Bundle Protocol Agent ADM: 193 { 194 "Mdat": [{ 195 "name": "name", 196 "type": "STR", 197 "value": "bp_agent", 198 "description": "The human-readable name of the ADM." 199 }, 200 { 201 "name": "namespace", 202 "type": "STR", 203 "value": "DTN/bp_agent", 204 "description": "The namespace of the ADM." 205 }, 206 { 207 "name": "version", 208 "type": "STR", 209 "value": "v0.1", 210 "description": "The version of the ADM" 211 }, 212 { 213 "name": "organization", 214 "type": "STR", 215 "value": "JHUAPL", 216 "description": "The name of the issuing organization of the 217 ADM." 218 } 219 ], 221 "Edd": [{ 222 "name": "bp_node_id", 223 "type": "STR", 224 "description": "The node administration endpoint" 225 }, 226 { 227 "name": "bp_node_version", 228 "type": "STR", 229 "description": "The latest version of the BP supported by this 230 node" 231 }, 232 { 233 "name": "available_storage", 234 "type": "UVAST", 235 "description": "Bytes available for bundle storage" 236 }, 237 { 238 "name": "last_reset_time", 239 "type": "UVAST", 240 "description": "The last time that BP counters were reset, 241 either due to execution of a reset control or 242 a restart of the node itself" 243 }, 244 { 245 "name": "num_registrations", 246 "type": "UINT", 247 "description": "number of registrations" 248 }, 249 { 250 "name": "num_pend_fwd", 251 "type": "UINT", 252 "description": "number of bundles pending forwarding" 253 }, 254 { 255 "name": "num_pend_dis", 256 "type": "UINT", 257 "description": "number of bundles awaiting dispatch" 258 }, 259 { 260 "name": "num_in_cust", 261 "type": "UINT", 262 "description": "number of bundles" 263 }, 264 { 265 "name": "num_pend_reassembly", 266 "type": "UINT", 267 "description": "number of bundles pending reassembly" 268 }, 269 { 270 "name": "bundles_by_priority", 271 "type": "UINT", 272 "parmspec": [{ 273 "type": "UINT", 274 "name": "mask" 275 }], 276 "description": "Number of bundles for the given priority. 277 Priority is given as a priority mask where 278 Bulk=0x1, normal=0x2, express=0x4. Any bundles 279 matching any of the masked priorities will be 280 included in the returned count" 281 }, 282 { 283 "name": "bytes_by_priority", 284 "type": "UINT", 285 "parmspec": [{ 286 "type": "UINT", 287 "name": "mask" 288 }], 289 "description": "Number of bytes of the given priority. Priority 290 is given as a priority mask where bulk=0x1, 291 normal=0x2, express=0x4. Any bundles matching 292 any of the masked priorities will be included 293 in the returned count." 294 }, 295 { 296 "name": "src_bundles_by_priority", 297 "type": "UINT", 298 "parmspec": [{ 299 "type": "UINT", 300 "name": "mask" 301 }], 302 "description": "Number of bundles sourced by this node of the 303 given priority. Priority is given as a priority 304 mask where bulk=0x1, normal=0x2, express=0x4. 305 Any bundles sourced by this node and matching 306 any of the masked priorities will be included 307 in the returned count." 308 }, 309 { 310 "name": "src_bytes_by_priority", 311 "type": "UINT", 312 "parmspec": [{ 313 "type": "UINT", 314 "name": "mask" 315 }], 316 "description": "Number of bytes sourced by this node of the 317 given priority. Priority is given as a priority 318 mask where bulk=0x1, normal=0x2, express=0x4. 319 Any bundles sourced by this node and matching 320 any of the masked priorities will be included 321 in the returned count" 322 }, 323 { 324 "name": "num_fragmented_bundles", 325 "type": "UINT", 326 "description": "number of fragmented bundles" 327 }, 328 { 329 "name": "num_fragments_produced", 330 "type": "UINT", 331 "description": "Number of bundles with fragmentary payloads 332 produced by this node" 334 }, 335 { 336 "name": "num_failed_by_reason", 337 "type": "UINT", 338 "parmspec": [{ 339 "type": "UINT", 340 "name": "mask" 341 }], 342 "description": "Number of bundles failed for any of the given 343 reasons. (noInfo=0x1, Expired=0x2, UniFwd=0x4, 344 Cancelled=0x8, NoStorage=0x10, BadEID=0x20, 345 NoRoute=0x40, NoContact=0x80, BadBlock=0x100)" 346 }, 347 { 348 "name": "num_bundles_deleted", 349 "type": "UINT", 350 "description": "number of bundles deleted by this node" 351 }, 352 { 353 "name": "failed_custody_bundles", 354 "type": "UINT", 355 "description": "number of bundle fails at this node" 356 }, 357 { 358 "name": "failed_custody_bytes", 359 "type": "UINT", 360 "description": "number bytes of fails at this node" 361 }, 362 { 363 "name": "failed_forward_bundles", 364 "type": "UINT", 365 "description": "number bundles not forwarded by this node" 366 }, 367 { 368 "name": "failed_forward_bytes", 369 "type": "UINT", 370 "description": "number of bytes not forwaded by this node" 371 }, 372 { 373 "name": "abandoned_bundles", 374 "type": "UINT", 375 "description": "number of bundles abandoned by this node" 376 }, 377 { 378 "name": "abandoned_bytes", 379 "type": "UINT", 380 "description": "number of bytes abandoned by this node" 381 }, 382 { 383 "name": "discarded_bundles", 384 "type": "UINT", 385 "description": "number of bundles discarded by this node" 386 }, 387 { 388 "name": "discarded_bytes", 389 "type": "UINT", 390 "description": "number of bytes discarded by this node" 391 }, 392 { 393 "name": "endpoint_names", 394 "type": "STR", 395 "description": "CSV list of endpoint names for this node" 396 }, 397 { 398 "name": "endpoint_active", 399 "type": "UINT", 400 "parmspec": [{ 401 "type": "STR", 402 "name": "endpoint_name" 403 }], 404 "description": "is the given endpoint active? (0=no)" 405 }, 406 { 407 "name": "endpoint_singleton", 408 "type": "UINT", 409 "parmspec": [{ 410 "type": "STR", 411 "name": "endpoint_name" 412 }], 413 "description": "is the given endpoint singleton? (0=no)" 414 }, 415 { 416 "name": "endpoint_policy", 417 "type": "UINT", 418 "parmspec": [{ 419 "type": "STR", 420 "name": "endpoint_name" 421 }], 422 "description": "Does the endpoint abandon on fail (0=no)" 423 } 424 ], 426 "Rptt": [{ 427 "name": "full_report", 428 "definition": [ 429 { 431 "ns": "DTN/bp_agent", 432 "nm": "Mdat.name" 433 }, 434 { 435 "ns": "DTN/bp_agent", 436 "nm": "Mdat.version" 437 }, 438 { 439 "ns": "DTN/bp_agent", 440 "nm": "Edd.bp_node_id" 441 }, 442 { 443 "ns": "DTN/bp_agent", 444 "nm": "Edd.bp_node_version" 445 }, 446 { 447 "ns": "DTN/bp_agent", 448 "nm": "Edd.available_storage" 449 }, 450 { 451 "ns": "DTN/bp_agent", 452 "nm": "Edd.last_reset_time" 453 }, 454 { 455 "ns": "DTN/bp_agent", 456 "nm": "Edd.num_registrations" 457 }, 458 { 459 "ns": "DTN/bp_agent", 460 "nm": "Edd.num_pend_fwd" 461 }, 462 { 463 "ns": "DTN/bp_agent", 464 "nm": "Edd.num_pend_dis" 465 }, 466 { 467 "ns": "DTN/bp_agent", 468 "nm": "Edd.num_in_cust" 469 }, 470 { 471 "ns": "DTN/bp_agent", 472 "nm": "Edd.num_pend_reassembly" 473 }, 474 { 475 "ns": "DTN/bp_agent", 476 "nm": "Edd.bundles_by_priority(1)" 477 }, 478 { 480 "ns": "DTN/bp_agent", 481 "nm": "Edd.bundles_by_priority(2)" 482 }, 483 { 484 "ns": "DTN/bp_agent", 485 "nm": "Edd.bundles_by_priority(4)" 486 }, 487 { 488 "ns": "DTN/bp_agent", 489 "nm": "Edd.bytes_by_priority(1)" 490 }, 491 { 492 "ns": "DTN/bp_agent", 493 "nm": "Edd.bytes_by_priority(2)" 494 }, 495 { 496 "ns": "DTN/bp_agent", 497 "nm": "Edd.bytes_by_priority(4)" 498 }, 499 { 500 "ns": "DTN/bp_agent", 501 "nm": "Edd.src_bundles_by_priority(1)" 502 }, 503 { 504 "ns": "DTN/bp_agent", 505 "nm": "Edd.src_bundles_by_priority(2)" 506 }, 507 { 508 "ns": "DTN/bp_agent", 509 "nm": "Edd.src_bundles_by_priority(4)" 510 }, 511 { 512 "ns": "DTN/bp_agent", 513 "nm": "Edd.src_bytes_by_priority(1)" 514 }, 515 { 516 "ns": "DTN/bp_agent", 517 "nm": "Edd.src_bytes_by_priority(2)" 518 }, 519 { 520 "ns": "DTN/bp_agent", 521 "nm": "Edd.src_bytes_by_priority(4)" 522 }, 523 { 524 "ns": "DTN/bp_agent", 525 "nm": "Edd.num_fragmented_bundles" 526 }, 527 { 529 "ns": "DTN/bp_agent", 530 "nm": "Edd.num_fragments_produced" 531 }, 532 { 533 "ns": "DTN/bp_agent", 534 "nm": "Edd.num_failed_by_reason(1)" 535 }, 536 { 537 "ns": "DTN/bp_agent", 538 "nm": "Edd.num_failed_by_reason(2)" 539 }, 540 { 541 "ns": "DTN/bp_agent", 542 "nm": "Edd.num_failed_by_reason(4)" 543 }, 544 { 545 "ns": "DTN/bp_agent", 546 "nm": "Edd.num_failed_by_reason(8)" 547 }, 548 { 549 "ns": "DTN/bp_agent", 550 "nm": "Edd.num_failed_by_reason(16)" 551 }, 552 { 553 "ns": "DTN/bp_agent", 554 "nm": "Edd.num_failed_by_reason(32)" 555 }, 556 { 557 "ns": "DTN/bp_agent", 558 "nm": "Edd.num_failed_by_reason(64)" 559 }, 560 { 561 "ns": "DTN/bp_agent", 562 "nm": "Edd.num_failed_by_reason(128)" 563 }, 564 { 565 "ns": "DTN/bp_agent", 566 "nm": "Edd.num_failed_by_reason(256)" 567 }, 568 { 569 "ns": "DTN/bp_agent", 570 "nm": "Edd.num_bundles_deleted" 571 }, 572 { 573 "ns": "DTN/bp_agent", 574 "nm": "Edd.failed_custody_bundles" 575 }, 576 { 578 "ns": "DTN/bp_agent", 579 "nm": "Edd.failed_custody_bytes" 580 }, 581 { 582 "ns": "DTN/bp_agent", 583 "nm": "Edd.failed_forward_bundles" 584 }, 585 { 586 "ns": "DTN/bp_agent", 587 "nm": "Edd.failed_forward_bytes" 588 }, 589 { 590 "ns": "DTN/bp_agent", 591 "nm": "Edd.abandoned_bundles" 592 }, 593 { 594 "ns": "DTN/bp_agent", 595 "nm": "Edd.discarded_bundles" 596 }, 597 { 598 "ns": "DTN/bp_agent", 599 "nm": "Edd.discarded_bytes" 600 }, 601 { 602 "ns": "DTN/bp_agent", 603 "nm": "Edd.endpoint_names" 604 } 605 ], 606 "description": "This is all known meta-data, EDD, and VAR 607 values known by the agent." 608 }, 609 { 610 "name": "endpoint_report", 611 "parmspec": [{ 612 "type": "STR", 613 "name": "endpoint_id" 614 }], 615 "definition": [{ 616 "ns": "DTN/bp_agent", 617 "nm": "edd.endpoint_active", 618 "ap": [{ 619 "type": "ParmName", 620 "value": "endpoint_id" 621 }] 622 }, 623 { 624 "ns": "DTN/bp_agent", 625 "nm": "edd.endpoint_singleton", 626 "ap": [{ 627 "type": "ParmName", 628 "value": "endpoint_id" 629 }] 630 }, 631 { 632 "ns": "DTN/bp_agent", 633 "nm": "edd.endpoint_policy", 634 "ap": [{ 635 "type": "ParmName", 636 "value": "endpoint_id" 637 }] 638 } 639 ], 640 "description": "This is all known endpoint information" 641 } 642 ], 644 "Ctrl": [{ 645 "name": "reset_all_counts", 646 "description": "This control causes the Agent to reset all counts 647 associated with bundle or byte statistics and to 648 set the last reset time of the BP primitive data 649 to the time when the control was run." 650 }] 651 } 653 5. IANA Considerations 655 At this time, this protocol has no fields registered by IANA. 657 6. References 659 6.1. Informative References 661 [I-D.birrane-dtn-ama] 662 Birrane, E., "Asynchronous Management Architecture", 663 draft-birrane-dtn-ama-07 (work in progress), June 2018. 665 6.2. Normative References 667 [I-D.birrane-dtn-adm] 668 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 669 Data Model", draft-birrane-dtn-adm-02 (work in progress), 670 June 2018. 672 [I-D.birrane-dtn-amp] 673 Birrane, E., "Asynchronous Management Protocol", draft- 674 birrane-dtn-amp-04 (work in progress), June 2018. 676 [I-D.ietf-dtn-bpbis] 677 Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol 678 Version 7", draft-ietf-dtn-bpbis-12 (work in progress), 679 November 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 693 Evana DiPietro 694 Johns Hopkins Applied Physics Laboratory 696 Email: Evana.DiPietro@jhuapl.edu 698 David Linko 699 Johns Hopkins Applied Physics Laboratory 701 Email: David.Linko@jhuapl.edu