idnits 2.17.1 draft-birrane-dtn-adm-bp-02.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 (July 2, 2018) is 2118 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-11 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: January 3, 2019 Johns Hopkins Applied Physics Laboratory 6 July 2, 2018 8 Bundle Protocol Agent Application Data Model 9 draft-birrane-dtn-adm-bp-02 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 January 3, 2019. 34 Copyright Notice 36 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . 11 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 61 6.1. Informative References . . . . . . . . . . . . . . . . . 11 62 6.2. Normative References . . . . . . . . . . . . . . . . . . 11 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 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 { 196 "name": "name", 197 "type": "STR", 198 "value": "bp", 199 "description": "The human-readable name of the ADM." 200 }, 201 { 202 "name": "namespace", 203 "type": "STR", 204 "value": "DTN/bp_agent", 205 "description": "The namespace of the ADM." 206 }, 207 { 208 "name": "version", 209 "type": "STR", 210 "value": "v0.1", 211 "description": "The version of the ADM" 212 }, 213 { 214 "name": "organization", 215 "type": "STR", 216 "value": "JHUAPL", 217 "description": "The name of the issuing organization of the ADM." 218 } 219 ], 221 "Edd": [ 222 { 223 "name": "bp_node_id", 224 "type": "STR", 225 "description": "The node administration endpoint" 226 }, 227 { 228 "name": "bp_node_version", 229 "type": "STR", 230 "description": "The latest version of the BP supported 231 by this node" 232 }, 233 { 234 "name": "available_storage", 235 "type": "UVAST", 236 "description": "Bytes available for bundle storage" 238 }, 239 { 240 "name": "last_reset_time", 241 "type": "UVAST", 242 "description": "The last time that BP counters were reset, either 243 due to execution of a reset control or a restart of 244 the node itself" 245 }, 246 { 247 "name": "num_registrations", 248 "type": "UINT", 249 "description": "number of registrations" 250 }, 251 { 252 "name": "num_pend_fwd", 253 "type": "UINT", 254 "description": "number of bundles pending forwarding" 255 }, 256 { 257 "name": "num_pend_dis", 258 "type": "UINT", 259 "description": "number of bundles awaiting dispatch" 260 }, 261 { 262 "name": "num_in_cust", 263 "type": "UINT", 264 "description": "number of bundles" 265 }, 266 { 267 "name": "num_pend_reassembly", 268 "type": "UINT", 269 "description": "number of bundles pending reassembly" 270 }, 271 { 272 "name": "bundles_by_priority", 273 "type": "UINT", 274 "parmspec": [{"type":"UINT","name":"mask"}], 275 "description": "number of bundles for the given priority. Priority 276 is given as a priority mask where Bulk=0x1, normal=0x2, 277 express=0x4. Any bundles matching any of the masked priorities 278 will be included in the returned count" 279 }, 280 { 281 "name": "bytes_by_priority", 282 "type": "UINT", 283 "parmspec": [{"type":"UINT","name":"mask"}], 284 "description": "number of bytes of the given priority. Priority is 285 given as a priority mask where bulk=0x1, normal=0x2, 286 express=0x4. Any bundles matching any of the masked priorities 287 will be included in the returned count." 288 }, 289 { 290 "name": "src_bundles_by_priority", 291 "type": "UINT", 292 "parmspec": [{"type":"UINT","name":"mask"}], 293 "description":"number of bundles sourced by this node of the given 294 priority. Priority is given as a priority mask where bulk=0x1, 295 normal=0x2, express=0x4. Any bundles sourced by this node and 296 matching any of the masked priorities will be included in the 297 returned count." 298 }, 299 { 300 "name": "src_bytes_by_priority", 301 "type": "UINT", 302 "parmspec": [{"type":"UINT","name":"mask"}], 303 "description": "number of bytes sourced by this node of the given 304 priority. Priority is given as a priority mask where bulk=0x1, 305 normal=0x2, express=0x4. Any bundles sourced by this node and 306 matching any of the masked priorities will be included in the 307 returned count" 308 }, 309 { 310 "name": "num_fragmented_bundles", 311 "type": "UINT", 312 "description": "number of fragmented bundles" 313 }, 314 { 315 "name": "num_fragments_produced", 316 "type": "UINT", 317 "description": "number of bundles with fragmentary payloads 318 produced by this node" 319 }, 320 { 321 "name": "num_failed_by_reason", 322 "type": "UINT", 323 "parmspec": [{"type":"UINT","name":"mask"}], 324 "description": "number of bundles failed for any of the given 325 reasons. (noInfo=0x1, Expired=0x2, UniFwd=0x4, Cancelled=0x8, 326 NoStorage=0x10, BadEID=0x20, NoRoute=0x40, NoContact=0x80, 327 BadBlock=0x100)" 328 }, 329 { 330 "name": "num_bundles_deleted", 331 "type": "UINT", 332 "description": "number of bundles deleted by this node" 333 }, 334 { 335 "name": "failed_custody_bundles", 336 "type": "UINT", 337 "description": "number of bundle fails at this node" 338 }, 339 { 340 "name": "failed_custody_bytes", 341 "type": "UINT", 342 "description": "number bytes of fails at this node" 343 }, 344 { 345 "name": "failed_forward_bundles", 346 "type": "UINT", 347 "description": "number bundles not forwarded by this node" 348 }, 349 { 350 "name": "failed_forward_bytes", 351 "type": "UINT", 352 "description": "number of bytes not forwaded by this node" 353 }, 354 { 355 "name": "abandoned_bundles", 356 "type": "UINT", 357 "description": "number of bundles abandoned by this node" 358 }, 359 { 360 "name": "abandoned_bytes", 361 "type": "UINT", 362 "description": "number of bytes abandoned by this node" 363 }, 364 { 365 "name": "discarded_bundles", 366 "type": "UINT", 367 "description": "number of bundles discarded by this node" 368 }, 369 { 370 "name": "discarded_bytes", 371 "type": "UINT", 372 "description": "number of bytes discarded by this node" 373 }, 374 { 375 "name": "endpoint_names", 376 "type": "STR", 377 "description": "CSV list of endpoint names for this node" 378 }, 379 { 380 "name": "endpoint_active", 381 "type": "UINT", 382 "parmspec": [{"type":"STR","name":"endpoint_name"}], 383 "description": "is the given endpoint active? (0=no)" 384 }, 385 { 386 "name": "endpoint_singleton", 387 "type": "UINT", 388 "parmspec": [{"type":"STR","name":"endpoint_name"}], 389 "description": "is the given endpoint singleton? (0=no)" 390 }, 391 { 392 "name": "endpoint_policy", 393 "type": "UINT", 394 "parmspec": [{"type":"STR","name":"endpoint_name"}], 395 "description": "Does the endpoint abandon on fail (0=no)" 396 } 397 ], 399 "Rptt": [ 400 { 401 "name": "full_report", 402 "definition": [ 403 "DTN/bp_agent/Mdat.name", 404 "DTN/bp_agent/Mdat.version", 405 "DTN/bp_agent/Edd.bp_node_id", 406 "DTN/bp_agent/Edd.bp_node_version", 407 "DTN/bp_agent/Edd.available_storage", 408 "DTN/bp_agent/Edd.last_reset_time", 409 "DTN/bp_agent/Edd.num_registrations", 410 "DTN/bp_agent/Edd.num_pend_fwd", 411 "DTN/bp_agent/Edd.num_pend_dis", 412 "DTN/bp_agent/Edd.num_in_cust", 413 "DTN/bp_agent/Edd.num_pend_reassembly", 414 "DTN/bp_agent/Edd.bundles_by_priority(0)", 415 "DTN/bp_agent/Edd.bundles_by_priority(1)", 416 "DTN/bp_agent/Edd.bundles_by_priority(2)", 417 "DTN/bp_agent/Edd.bytes_by_priority(0)", 418 "DTN/bp_agent/Edd.bytes_by_priority(1)", 419 "DTN/bp_agent/Edd.bytes_by_priority(2)", 420 "DTN/bp_agent/Edd.src_bundles_by_priority(0)", 421 "DTN/bp_agent/Edd.src_bundles_by_priority(1)", 422 "DTN/bp_agent/Edd.src_bundles_by_priority(2)", 423 "DTN/bp_agent/Edd.src_bytes_by_priority(0)", 424 "DTN/bp_agent/Edd.src_bytes_by_priority(1)", 425 "DTN/bp_agent/Edd.src_bytes_by_priority(2)", 426 "DTN/bp_agent/Edd.num_fragmented_bundles", 427 "DTN/bp_agent/Edd.num_fragments_produced", 428 "DTN/bp_agent/Edd.num_failed_by_reason(0)", 429 "DTN/bp_agent/Edd.num_failed_by_reason(1)", 430 "DTN/bp_agent/Edd.num_failed_by_reason(2)", 431 "DTN/bp_agent/Edd.num_bundles_deleted", 432 "DTN/bp_agent/Edd.failed_custody_bundles", 433 "DTN/bp_agent/Edd.failed_custody_bytes", 434 "DTN/bp_agent/Edd.failed_forward_bundles", 435 "DTN/bp_agent/Edd.failed_forward_bytes", 436 "DTN/bp_agent/Edd.abandoned_bundles", 437 "DTN/bp_agent/Edd.discarded_bundles", 438 "DTN/bp_agent/Edd.discarded_bytes", 439 "DTN/bp_agent/Edd.endpoint_names" 440 ], 441 "description": "This is all known meta-data, EDD, and VAR values 442 known by the agent." 443 }, 444 { 445 "name": "endpoint_report", 446 "parmspec": [{"type":"STR","name":"endpoint_id"}], 447 "definition": [ 448 { 449 "ns":"DTN/bp_agent", 450 "nm":"edd.endpoint_active", 451 "ap":[{"type":"PARMNAME","value":"endpoint_id"}] 452 }, 453 { 454 "ns":"DTN/bp_agent", 455 "nm":"edd.endpoint_singleton", 456 "ap":[{"type":"PARMNAME","value":"endpoint_id"}] 457 }, 458 { 459 "ns":"DTN/bp_agent", 460 "nm":"edd.endpoint_policy", 461 "ap":[{"type":"PARMNAME","value":"endpoint_id"}] 462 } 463 ], 464 "description": "This is all known endpoint information" 465 } 466 ], 468 "Ctrl": [ 469 { 470 "name": "reset_all_counts", 471 "description": "This control causes the Agent to reset all counts 472 associated with bundle or byte statistics and to set the last 473 reset time of the BP primitive data to the time when the 474 control was run" 475 } 476 ] 477 } 479 5. IANA Considerations 481 At this time, this protocol has no fields registered by IANA. 483 6. References 485 6.1. Informative References 487 [I-D.birrane-dtn-ama] 488 Birrane, E., "Asynchronous Management Architecture", 489 draft-birrane-dtn-ama-07 (work in progress), June 2018. 491 6.2. Normative References 493 [I-D.birrane-dtn-adm] 494 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 495 Data Model", draft-birrane-dtn-adm-02 (work in progress), 496 June 2018. 498 [I-D.birrane-dtn-amp] 499 Birrane, E., "Asynchronous Management Protocol", draft- 500 birrane-dtn-amp-04 (work in progress), June 2018. 502 [I-D.ietf-dtn-bpbis] 503 Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol 504 Version 7", draft-ietf-dtn-bpbis-11 (work in progress), 505 May 2018. 507 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 508 Requirement Levels", BCP 14, RFC 2119, 509 DOI 10.17487/RFC2119, March 1997, 510 . 512 Authors' Addresses 514 Edward J. Birrane 515 Johns Hopkins Applied Physics Laboratory 517 Email: Edward.Birrane@jhuapl.edu 519 Evana DiPietro 520 Johns Hopkins Applied Physics Laboratory 522 Email: Evana.DiPietro@jhuapl.edu 523 David Linko 524 Johns Hopkins Applied Physics Laboratory 526 Email: David.Linko@jhuapl.edu