idnits 2.17.00 (12 Aug 2021) /tmp/idnits47798/draft-irtf-dtnrg-dtnmp-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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 31, 2014) is 2691 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'ACL' is mentioned on line 510, but not defined == Missing Reference: 'SDNV' is mentioned on line 2437, but not defined == Missing Reference: 'BYTE' is mentioned on line 1101, but not defined == Missing Reference: 'VARIED' is mentioned on line 826, but not defined == Missing Reference: 'VAR' is mentioned on line 1101, but not defined == Missing Reference: 'DC' is mentioned on line 1197, but not defined == Missing Reference: 'MID' is mentioned on line 2437, but not defined == Missing Reference: 'MC' is mentioned on line 2437, but not defined == Missing Reference: 'TS' is mentioned on line 2437, but not defined -- Looks like a reference, but probably isn't: '0' on line 1625 == Missing Reference: 'STR' is mentioned on line 2174, but not defined == Missing Reference: 'EXPR' is mentioned on line 1819, but not defined == Missing Reference: 'PRED' is mentioned on line 2344, but not defined == Unused Reference: 'DTNM' is defined on line 2480, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 15 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Delay-Tolerant Networking Research Group E. Birrane 3 Internet-Draft V. Ramachandran 4 Intended status: Experimental Johns Hopkins Applied Physics Laboratory 5 Expires: July 4, 2015 December 31, 2014 7 Delay Tolerant Network Management Protocol 8 draft-irtf-dtnrg-dtnmp-01 10 Abstract 12 This draft describes the Delay/Disruption Tolerant Network Management 13 Protocol (DTNMP). The DTNMP provides monitoring and configuration 14 services between managing devices and managed devices, some of which 15 may operate on the far side of high-delay or high-disruption links. 16 The protocol is designed to minimize the number of transmitted bytes, 17 to operate without sessions or (concurrent) two-way links, and to 18 function autonomously when there is no timely contact with a network 19 operator. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on July 4, 2015. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.2. Technical Notes . . . . . . . . . . . . . . . . . . . . . 4 58 1.3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 1.3.1. Protocol Scope . . . . . . . . . . . . . . . . . . . 5 60 1.3.2. Specification Scope . . . . . . . . . . . . . . . . . 5 61 1.4. Requirements Language . . . . . . . . . . . . . . . . . . 5 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3. System Model . . . . . . . . . . . . . . . . . . . . . . . . 7 64 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2. Roles and Responsibilities . . . . . . . . . . . . . . . 8 66 3.3. Data Flows . . . . . . . . . . . . . . . . . . . . . . . 10 67 3.4. Control Flow by Role . . . . . . . . . . . . . . . . . . 11 68 3.4.1. Notation . . . . . . . . . . . . . . . . . . . . . . 11 69 3.4.2. Serialized Management . . . . . . . . . . . . . . . . 11 70 3.4.3. Multiplexed Management . . . . . . . . . . . . . . . 12 71 3.4.4. Data Fusion . . . . . . . . . . . . . . . . . . . . . 14 72 4. Component Model . . . . . . . . . . . . . . . . . . . . . . . 15 73 4.1. Data Representation . . . . . . . . . . . . . . . . . . . 15 74 4.1.1. Types . . . . . . . . . . . . . . . . . . . . . . . . 15 75 4.1.2. Categories . . . . . . . . . . . . . . . . . . . . . 15 76 4.1.3. Data Model . . . . . . . . . . . . . . . . . . . . . 16 77 4.2. Primitive Types . . . . . . . . . . . . . . . . . . . . . 17 78 4.2.1. Self-Delimiting Numeric Value (SDNV) . . . . . . . . 17 79 4.2.2. Timestamp (TS) . . . . . . . . . . . . . . . . . . . 17 80 4.2.3. Data Collections (DC) . . . . . . . . . . . . . . . . 17 81 4.3. Naming and Identification . . . . . . . . . . . . . . . . 17 82 4.4. Special Types . . . . . . . . . . . . . . . . . . . . . . 21 83 4.4.1. MID Collections (MC) . . . . . . . . . . . . . . . . 21 84 4.4.2. Expressions (EXPR) . . . . . . . . . . . . . . . . . 21 85 4.4.3. Predicate (PRED) . . . . . . . . . . . . . . . . . . 22 86 5. Functional Specification . . . . . . . . . . . . . . . . . . 22 87 5.1. Message Group Format . . . . . . . . . . . . . . . . . . 23 88 5.2. Message Format . . . . . . . . . . . . . . . . . . . . . 24 89 5.3. Register Agent (0x00) . . . . . . . . . . . . . . . . . . 25 90 5.4. Data Report (0x12) . . . . . . . . . . . . . . . . . . . 26 91 5.5. Perform Control (0x20) . . . . . . . . . . . . . . . . . 26 92 6. Appliation Data Model Template . . . . . . . . . . . . . . . 27 93 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 27 94 6.2. ADM Types . . . . . . . . . . . . . . . . . . . . . . . . 27 95 6.3. Template . . . . . . . . . . . . . . . . . . . . . . . . 28 96 6.3.1. ADM Metadata . . . . . . . . . . . . . . . . . . . . 29 97 6.3.2. ADM Information Capture . . . . . . . . . . . . . . . 29 98 7. DTNMP Agent Application Data Model . . . . . . . . . . . . . 30 99 7.1. Data Definitions . . . . . . . . . . . . . . . . . . . . 30 100 7.2. Metadata Definitions . . . . . . . . . . . . . . . . . . 31 101 7.3. Data Definitions . . . . . . . . . . . . . . . . . . . . 31 102 7.3.1. Atomic Data . . . . . . . . . . . . . . . . . . . . . 31 103 7.3.2. Computed Data . . . . . . . . . . . . . . . . . . . . 32 104 7.3.3. Reports . . . . . . . . . . . . . . . . . . . . . . . 32 105 7.4. Operators . . . . . . . . . . . . . . . . . . . . . . . . 33 106 7.5. Controls . . . . . . . . . . . . . . . . . . . . . . . . 35 107 7.5.1. Control Summary . . . . . . . . . . . . . . . . . . . 35 108 7.5.2. Control Specification . . . . . . . . . . . . . . . . 37 109 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 110 9. Security Considerations . . . . . . . . . . . . . . . . . . . 55 111 10. Normative References . . . . . . . . . . . . . . . . . . . . 55 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 114 1. Introduction 116 This document presents the Delay/Disruption Tolerant Network 117 Management Protocol (DTNMP) providing application-layer network 118 management services over links where propagation delays or link 119 disruptions prevent timely communications between a network operator 120 and a managed device.[RFC4838]. 122 1.1. Overview 124 A network management protocol defines the messages that implement 125 management functions amongst managed and managing devices in a 126 network. Management functions include the definition, production, 127 and reporting of performance data, the application of administrative 128 and security policy, and the configuration of behavior based on local 129 time and state measurements. 131 DTNs contain nodes whose communication links are characterized by 132 signal propagation delays and/or transmission disruptions that make 133 timely data exchange difficult or impossible. Management protocols 134 that rely on timely data exchange, such as those that rely on 135 negotiated sessions or other synchronized acknowledgment, do not 136 function in the DTN environment. For example, the Internet approach 137 of network management via closed-loop, synchronous messaging does not 138 work when network disruptions increase in frequency and severity. 139 While no protocol delivers data in the absence of a networking link, 140 protocols that eliminate or drastically reduce overhead and end-point 141 coordination require smaller transmission windows and continue to 142 function when confronted with scaling delays and disruptions in the 143 network. 145 DTNMP accomplishes the network management function using open-loop, 146 intelligent-push, asynchronous mechanisms that better scale as link 147 challenges scale. The protocol is designed to support five desirable 148 properties: 150 Intelligent Push of Information 151 The intelligent push of information eliminates the need for round- 152 trip data exchange in the management protocol. This is a 153 necessary consequence of operating in open-loop systems where 154 reliable round-trip communication may not exist. DTNMP is 155 designed to operate even in uni-directional networks. 157 Small Message Sizes 158 Smaller messages require smaller periods of viable transmission 159 for communication, incur less re-transmission cost, and consume 160 less resources when persistently stored en-route in the network. 161 DTNMP minimizes the size of a message whenever practical, to 162 include packing and unpacking binary data, variable-length fields, 163 and pre-configured data definitions. 165 Fine-grained, Flexible Data Identification 166 Fine-grained identification allows data in the system to be 167 explicitly addressed while flexible data identification allows 168 users to define their own customized, addressed data collections. 169 In both cases, the ability to define precisely the data required 170 removes the need to query and transmit large data sets only to 171 filter/downselect desired data at a receiving device. 173 Asynchronous Operation 174 DTNMP does not rely on session establishment or round-trip data 175 exchange to perform network management functions. Wherever 176 possible, the DTNMP is designed to be stateless. Where state is 177 required, the DTNMP provides mechanisms to support transactions 178 and graceful degredation when nodes in the network fail to 179 synchronize on common definitions. 181 Compatibility with Low-Latency Network Management Protocols 182 DTNMP adopts an identifier approach compatible with the Managed 183 Information Base (MIB) format used by Internet management 184 protocols such as the Simple Network Management Protocol (SNMP), 185 thus enabling management interfaces between DTNs and other types 186 of networks. 188 1.2. Technical Notes 190 All multi-byte values are assumed to be communicated in network-byte 191 order. Bit-fields are specified in Little-Endian format with bit 192 position 0 holding the least-significant bit (LSB). When illustrated 193 in this manuscript, the LSB appears on the right. 195 1.3. Scope 197 1.3.1. Protocol Scope 199 The DTNMP provides data monitoring, administration, and configuration 200 for applications operating above the data link layer of the OSI 201 networking model. While the DTNMP may be configured to support the 202 management of network layer protocols (such as the Internet Protocol 203 and Bundle Protocol) it also uses these protocols stacks to 204 encapsulate and communicate its own DTNMP messages. 206 It is assumed that the protocols used to carry DTNMP messages provide 207 addressing, confidentiality, integrity, security, fragmentation 208 support and other network/session layer functions. Therefore, these 209 items are not discussed in the scope of this document. 211 1.3.2. Specification Scope 213 This document describes the format of the DTNMP messages exchanged 214 amongst managing and managed devices in a DTN. This document further 215 describes the rationale behind key design decisions to the extent 216 that such a description informs the operational deployment and 217 configuration of DTNMP implementations. This document does not 218 address specific data configurations of DTNMP-enabled devices, nor 219 does it discuss the interface between DTNMP and other management 220 protocols, such as SNMP. 222 1.4. Requirements Language 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 226 document are to be interpreted as described in RFC 2119 [RFC2119]. 228 2. Terminology 230 This section identifies those terms critical to understanding the 231 proper operation of the DTNMP. Whenever possible, these terms align 232 in both word selection and meaning with their analogs from other 233 management protocols. 235 Actor 236 A software service running on either managed or managing 237 devices implementing an end-point in the DTNMP. Actors may 238 implement the "Manager" role, "Agent" role, or both. 240 Agent Role 241 A role within the DTNMP, associated with a managed device, 242 responsible for reporting performance data, enforcing 243 administrative policies, and accepting/performing actions. 244 Agents exchange information with DTNMP managers operating 245 either on the same device or on a remote managing device. 247 Application Data Model (ADM) 248 The set of predefined data definitions, reports, literals, 249 operations, and controls given to a DTNMP actor to manage a 250 particular application or protocol. DTNMP actors support 251 multiple ADMs, one for each application/protocol being 252 managed. 254 Atomic Data 255 Globally unique, managed data definitions, similar to those 256 defined in a Management Information Base (MIB), whose 257 definition does not change based on the configuration of a 258 DTNMP actor. Atomic data comprise the "lingua franca" within 259 the DTNMP. All messages in the protocol operate either 260 directly on atomic data or on data derived from atomic data. 262 Computed Data 263 Data items that are computed dynamically by a DTNMP actor 264 from some combination of Atomic Data and other Computed Data. 266 Controls 267 Operations that may be undertaken by a DTNMP actor to change 268 the behavior, configuration, or state of an application 269 managed by the DTNMP. 271 Macros 272 A named, ordered collection of controls. 274 Managed Item Definition (MID) 275 A parameterized structure used to uniquely identify all data 276 and control definitions within the DTNMP. MIDs are a super- 277 set of Object Identifiers (OIDs) and the mechanism by which 278 the DTNMP maintains data compatibility with other management 279 protocols. 281 Manager 282 A role within the DTNMP associated with a managing device 283 responsible for configuring the behavior of, and 284 receiving/processing/visualizing information from, DTNMP 285 agents. DTNMP managers also provide gateways to non-DTNMP 286 management protocols as part of conditioning the data 287 returned from agents. Managers interact with one or more 288 agents located on the same device and/or on remote devices in 289 the network. 291 Report 292 A named, ordered collection of data items gathered by one or 293 more DTNMP agents and provided to one or more DTNMP managers. 294 Reports may contain atomic data, computed data, and other 295 reports. Individual data within a report are not named; the 296 report itself is named to reduce the size of the report 297 message. 299 3. System Model 301 3.1. Overview 303 DTNMP performs the core network management functions of 304 configuration, performance reporting, control, and administration, as 305 follows. 307 Configuration 308 The configuration function synchronizes definitions amongst 309 DTNMP actors in the DTN. Managers and Agents must agree on 310 what ADMs are supported by what nodes. Further, these Actors 311 must agree on the definitions of customized information, such 312 as data production schedules, report definitions, and state- 313 based autonomous actions. 315 Performance Reporting 316 Since DTNMP operates asynchronously, performance *monitoring* 317 is replaced by performance *reporting*. As there is no 318 expectation of closed-loop control of a managed device across 319 a delayed/disrupted link, the best action that a managing 320 device can undertake is to collect and operate on whatever 321 data is received by managed devices. 322 Reporting the performance of a managed device involves the 323 local collection of reports and the communication of those 324 reports to appropriate managing devices. 326 Control 327 Part of the ADM for a supported application/protocol includes 328 a list of controls/commands that may be run by a DTNMP actor 329 based on local time or local state. Controls comprise the 330 basic autonomy mechanism within the DTNMP. 332 Administration 333 The mappings amongst agents and managers within a network may 334 be complex, especially in networks comprising multiple 335 administrative domains. The administrative management 336 function defines what managers may control what agents, for 337 what types of information. 339 3.2. Roles and Responsibilities 341 By definition, DTNMP agents reside on managed devices and DTNMP 342 managers reside on managing devices. These roles naturally map to 343 the transmit and receipt of various DTNMP messages. This section 344 describes how each of these roles participate in the network 345 management functions outlined in the prior section. 347 Agent Responsibilities 349 Local Data Collection 350 Agents MUST collect and report the data defined in 351 all ADMs for which they have been configured for the 352 local managed device. Agents MAY also collect data 353 for network nodes that do not have their own DTNMP 354 agents. In this scenario, the DTNMP agent acts as a 355 proxy agent. 357 Autonomous Control 358 Agents MUST determine, without manager intervention, 359 whether a configured control should be invoked. 360 Agents MUST periodically evaluate the conditions 361 associated with configured controls and invoke those 362 controls based on local state. Agents MAY also 363 invoke controls on other devices within a regional, 364 low-latency network. 366 Data Conditioning 367 DTNMP agents MUST accept computed data definitions 368 that specify how a single data value may be 369 constructed from the transformation of one or more 370 other data values in the system, using the expression 371 syntax specified in this manuscript. Further, agents 372 MUST produce this data when requested by Managers 373 with the appropriate security persmissions. Agents 374 MUST produce the list of computer data definitions 375 when requested by a Manager. Agents MUST detect when 376 a computed data definition references other data 377 definitions that are unknown to the agent and respond 378 in a way consistent with the logging/error-handling 379 configuration of the agent. 381 Report Definition 382 Agents MUST support the ability to accept and store 383 definitions for custom report definitions. Agents 384 MUST conform to the security policies associated with 385 custom reports when determining if a Manager may 386 request a report defined by a different Manager in 387 the network. Agents MUST provide a listing of custom 388 report definitions to appropriate managing devices 389 when requested. Agents MUST detect requests for 390 custom reports that are not configured on the agent, 391 or are not appropriate for the requesting Manager, 392 and respond in a way consistent with the logging/ 393 error-handling configuration of the agent. 395 Consolidate Messages 396 Agents SHOULD produce as few messages as possible 397 when sending information. For example, rather than 398 sending multiple report messages to a manager, an 399 agent SHOULD prefer to send a single message 400 containing multiple reports. 402 Regional Proxy 403 Agents MAY perform any of their responsibilities on 404 behalf of other network nodes that, themselves, do 405 not have a DTNMP agent. In such a configuration, the 406 DTNMP agent acts as a proxy agent for these other 407 network nodes. 409 Manager Responsibilities 411 Agent/ADM Mapping 412 Managers MUST understand what ADMs are supported by 413 the various agents with which they communicate. 414 Managers SHOULD NOT attempt to request, invoke, or 415 refer to ADM information for ADMs unsupported by an 416 agent. 418 Data Collection 419 Managers MUST receive information from agents by 420 asynchronously configuring the production of data 421 reports and then waiting for, and collecting, 422 responses from agents over time. Managers SHOULD 423 implement internal time-outs to detect conditions 424 where agent information has not been received within 425 network-specific timespans. 427 Custom Definitions 428 Managers SHOULD provide the ability to define custom 429 data and report definitions. Any defined custom 430 definitions MUST be transmitted to appropriate agents 431 and these definitions MUST be remembered to interpret 432 the reporting of these custom values from an agent in 433 the future. 435 Data Translation 436 Managers SHOULD provide some interface to other 437 network management protocols, such as the SNMP. 438 Managers MAY accomplish this by accumulating a 439 repository of push-data from high-latency parts of 440 the network from which data may be pulled by low- 441 latency parts of the network. 443 Data Fusion 444 Managers MAY support the fusion of data from multiple 445 agents with the purpose of transmitting fused data 446 results to other managers within the network. 447 Managers MAY receive fused reports from other 448 managers pursuant to appropriate security and 449 administrative configurations. 451 3.3. Data Flows 453 We identify three significant data flows within the DTNMP: control 454 flows from managers to agents, reports flows from agents to managers, 455 and fusion reports from managers to other managers. These data flows 456 are illustrated in Figure 1. 458 DTNMP Data Flows 460 +---------+ +------------------------+ +---------+ 461 | Node A | | Node B | | Node C | 462 | | | | | | 463 |+-------+| |+-------+ +-------+| |+-------+| 464 || ||=====>>|| DTNMP |====>>| DTNMP ||====>>|| || 465 || ||<<=====|| Mgr B |<<====|Agent B||<<====|| || 466 || DTNMP || |+--++---+ +-------+| || DTNMP || 467 || Agent || +---||-------------------+ || Mgr C || 468 || A || || || || 469 || ||<<=========||==========================|| || 470 || ||===========++========================>>|| || 471 |+-------+| |+-------+| 472 +---------+ +---------+ 474 Figure 1 476 In this data flow, the agent on node A receives configurations from 477 managers on nodes B and C, and replies with reports back to these 478 managers. Similarly, the agent on node B interacts with the local 479 manager on node B and the remote manager on node C. Finally, the 480 manager on node B may fuse data reports received from agents at nodes 481 A and B and send these fused reports back to the manager on node C. 482 From this figure, we see many-to-many relationships amongst managers, 483 amongst agents, and between agents and managers. Note that agents 484 and managers are roles, not necessarily differing software 485 applications. Node A may represent a single software application 486 fulfilling only the agent role, whereas node B may have a single 487 software application fulfilling both the agent and manager roles. 488 The specifics of how these roles are realized is an implementation 489 matter. 491 3.4. Control Flow by Role 493 This section describes three common configurations of DTNMP agents 494 and managers and the flow of messages between them. These 495 configurations involve local and remote management and data fusion. 497 3.4.1. Notation 499 The notation outlined in Table 1 describes the types of control 500 messages exchanged between DTNMP agents and managers. 502 +-------------+---------------------------------------+-------------+ 503 | Term | Definition | Example | 504 +-------------+---------------------------------------+-------------+ 505 | AD# | Atomic data definition, from ADM. | AD1 | 506 | | | | 507 | CD# | Custom data definition. | CD1 = AD1 + | 508 | | | CD0. | 509 | | | | 510 | DEF([ACL], | Define id from expression. Allow | DEF([*], | 511 | ID,EXPR) | managers in access control list (ACL) | CD1, AD1 + | 512 | | to request this id. | AD2) | 513 | | | | 514 | PROD(P,ID) | Produce ID according to predicate P. | PROD(1s, | 515 | | P may be a time period (1s) or an | AD1) | 516 | | expression (AD1 > 10). | | 517 | | | | 518 | RPT(ID) | A report identified by ID. | RPT(AD1) | 519 +-------------+---------------------------------------+-------------+ 521 Table 1: Terminology 523 3.4.2. Serialized Management 525 This is a nominal configuration of network management where a 526 managing device interacts with a set of managed devices, with a DTNMP 527 manager installed on the managing device and a DTNMP agent installed 528 on each managed device. The control flows for this are outlined in 529 Figure 2. 531 Serialized Management Control Flow 533 +----------+ +---------+ +---------+ 534 | Manager | | Agent A | | Agent B | 535 +----+-----+ +----+----+ +----+----+ 536 | | | 537 |-----PROD(1s, AD1)---->| |(Step 1) 538 |----------------------------PROD(1s, AD1)--->| 539 | | | 540 | | | 541 |<-------RPT(AD1)-------| |(Step 2) 542 |<-----------------------------RPT(AD1)-------| 543 | | | 544 | | | 545 |<-------RPT(AD1)-------| | 546 |<-----------------------------RPT(AD1)-------| 547 | | | 548 | | | 549 |<-------RPT(AD1)-------| | 550 |<-----------------------------RPT(AD1)-------| 551 | | | 553 In a simple network, a manager interacts with multiple agents. 555 Figure 2 557 In this figure, the manager configures agents A and B to produce 558 atomic data AD1 every second in (Step 1). At some point in the 559 future, upon receiving and configuring this message, agents A and B 560 then build a report containing AD1 and send those reports back to the 561 manager in (Step 2). 563 3.4.3. Multiplexed Management 565 Networks spanning multiple administrative domains may require 566 multiple managing devices (for example, one per domain). When a 567 manager defines custom reports/data to an agent, that definition may 568 be tagged with an access control list (ACL) to limit what other 569 managers will be privy to this information. Managers in such 570 networks SHOULD synchronize with those other managers granted access 571 to their custom data definitions. When agents generate messages, 572 they MUST only send messages to managers according to these ACLs, if 573 present. The control flows in this scenario are outlined in 574 Figure 3. 576 Multiplexed Management Control Flow 578 +-----------+ +-------+ +-----------+ 579 | Manager A | | Agent | | Manager B | 580 +-----+-----+ +---+---+ +-----+-----+ 581 | | | 582 |--DEF(A,CD1,AD1*2)--->|<--DEF(B, CD2, AD2*2)-|(Step 1) 583 | | | 584 |---PROD(1s, CD1)----->|<---PROD(1s, CD2)-----|(Step 2) 585 | | | 586 |<-------RPT(CD1)------| |(Step 3) 587 | |--------RPT(CD2)----->| 588 |<-------RPT(CD1)------| | 589 | |--------RPT(CD2)----->| 590 | | | 591 | |<---PROD(1s, CD1)-----|(Step 4) 592 | | | 593 | |--ERR(CD1 no perm.)-->| 594 | | | 595 |--DEF(*,CD3,AD3*3)--->| |(Step 5) 596 | | | 597 |---PROD(1s, CD3)----->| |(Step 6) 598 | | | 599 | |<---PROD(1s, CD3)-----| 600 | | | 601 |<-------RPT(CD3)------|--------RPT(CD3)----->|(Step 7) 602 |<-------RPT(CD1)------| | 603 | |--------RPT(CD2)----->| 604 |<-------RPT(CD3)------|--------RPT(CD3)----->| 605 |<-------RPT(CD1)------| | 606 | |--------RPT(CD2)----->| 608 Complex networks require multiple managers interfacing with agents. 610 Figure 3 612 In more complex networks, managers may choose to define custom 613 reports and data definitions, and agents may need to accept such 614 definitions from multiple managers. Custom data definitions may 615 include an ACL that describes who may query and otherwise understand 616 the custom definition. In (Step 1), Manager A defines CD1 only for A 617 while Manager B defines CD2 only for B. Managers may, then, request 618 the production of reports containing these custom definitions, as 619 shown in (Step 2). Agents produce different data for different 620 managers in accordance with configured production rules, as shown in 621 (Step 3). If a manager requests an operation, such as a production 622 rule, for a custom data definition for which the manager has no 623 permissions, a response consistent with the configured logging policy 624 on the agent should be implemented, as shown in (Step 4). 625 Alternatively, as shown in (Step 5), a manager may define custom data 626 with no restrictions allowing all other managers to request and use 627 this definition. This allows all managers to request the production 628 of reports containing this definition, shown in (Step 6) and have all 629 managers receive this and other data going forward, as shown in (Step 630 7). 632 3.4.4. Data Fusion 634 In many networks, agents do not want to individually transmit their 635 data to a manager, preferring instead to fuse reporting data with 636 local nodes prior to transmission. This approach reduces the number 637 and size of messages in the network and reduces overall transmission 638 energy expenditure. DTNMP supports fusion of NM reports by co- 639 locating agents and managers on managed devices and offloading fusion 640 activities to the manager. This process is illustrated in Figure 4. 642 Data Fusion Control Flow 644 +-----------+ +-----------+ +---------+ +---------+ 645 | Manager A | | Manager B | | Agent B | | Agent C | 646 +---+-------+ +-----+-----+ +----+----+ +----+----+ 647 | | | | 648 |--DEF(A,CD0,AD1+AD2)->| | |(Step 1) 649 |--PROD(AD1&AD2, CD0)->| | | 650 | | | | 651 | |--PROD(1s,AD1)-->| |(Step 2) 652 | |-------------------PROD(1s, AD2)->| 653 | | | | 654 | |<---RPT(AD1)-----| |(Step 3) 655 | |<-------------------RPT(AD2)------| 656 | | | | 657 |<-----RPT(A,CD0)------| | |(Step 4) 658 | | | | 660 Data fusion in DTNMP accours amongst managers in the network. 662 Figure 4 664 In this example, Manager A requires the production of a computed data 665 set, CD0, from node B, as shown in (Step 1). The manager role 666 understands what data is available from what agents in the subnetwork 667 local to B, understanding that AD1 is available locally and AD2 is 668 available remotely. Production messages are produced in (Step 2) and 669 data collected in (Step 3). This allows the manager at node B to 670 fuse the collected data reports into CD0 and return it in (Step 4). 671 While a trivial example, the mechanism of associating fusion with the 672 manager function rather than the agent function scales with fusion 673 complexity, though it is important to reiterate that agent and 674 manager designations are roles, not individual software components. 675 There may be a single software application running on node B 676 implementing both Manager B and Agent B roles. 678 4. Component Model 680 This section identifies the components that comprise the data 681 communicated within the DTNMP, the way in which these components are 682 named, and those special types associated with DTNMP messages. 684 4.1. Data Representation 686 4.1.1. Types 688 Components within the DTNMP are represented as one of four basic data 689 types: Data, Controls, Literals, and Operators: 691 Data Data consist of values collected by an agent and reported to 692 managers within the DTNMP. This includes definitions from an 693 ADM, derived data as configured from managers, and reports 694 which are collections of data elements. 696 Controls Controls consist of actions that may be invoked on agents 697 and managers to change behavior in response to some external 698 event (such as local state changes or time). Controls 699 include application-specific functions specified as part of 700 an ADM and macros which are collections of these controls. 702 Literals Literals are constant numerical values that may be used in 703 the evaluation of expressions and predicates. 705 Operator Operators are those mathematical functions that operate on 706 series of Data and Literals, such as addition, subtraction, 707 multiplication, and division. 709 4.1.2. Categories 711 Components within the DTNMP can be categorized as Atomic, Computed, 712 or Collection. 714 Atomic 715 Atomic components are those components that are directly 716 implemented by the underlying software/firmware of a network 717 node. Atomic components may also refer to components whose 718 definitions may not be changed. Examples of atomic 719 components are Data, Controls, Literals, and Operators 720 specified by an ADM. Atomic component identifiers MUST be 721 unique and SHOULD be managed by a registration authority, 722 similar to the mechanisms used to assign Object Identifiers 723 (OIDs). Atomic components must be understood by both DTNMP 724 managers and agents in a network. 726 Computed 727 Computed components are those components that are not 728 directly implemented by the underlying software/firmware of a 729 network node. The definition of a computed component MAY be 730 dynamically defined by DTNMP managers and communicated to one 731 or more DTNMP agents in a network. The definition of a 732 computed component may include other computed components or 733 other atomic components. The identifier of a computed 734 component is not guaranteed to be universally unique but 735 SHOULD be unique within the context of a particular network 736 or internetwork. 738 Collection 739 A collection component is a set of other components (to 740 include other collection components). DTNMP implementations 741 MUST prevent circular definitions when implementing 742 collections that include other collections. 744 4.1.3. Data Model 746 Each component of the DTNMP data model can be identified as a 747 combination of type and category, as illustrated in Table 2. In this 748 table type/catgory combinations that are unsupported are listed as N/ 749 A. Specifically, DTNMP does not support user-defined controls, 750 constants, or operations; any value that specifies action on an agent 751 MUST be pre-configured as part of an ADM. 753 +------------+------------------+----------+----------+----------+ 754 | | Data | Controls | Literals | Operator | 755 +------------+------------------+----------+----------+----------+ 756 | Atomic | Measured Value | Control | Constant | Operator | 757 | | | | | | 758 | Computed | Calculated Value | N/A | N/A | N/A | 759 | | | | | | 760 | Collection | Report | Macro | N/A | N/A | 761 +------------+------------------+----------+----------+----------+ 763 Table 2 765 4.2. Primitive Types 767 4.2.1. Self-Delimiting Numeric Value (SDNV) 769 The data type "SDNV" refers to a Self-Delimiting Numerical Value 770 (SDNV) described in [RFC6256]. SDNVs are used in the DTNMP to 771 capture any data items that are expected to be 8 bytes or less in 772 total length. DTNMP actors MAY reject any SDNV value that is greater 773 than 8 bytes in length. 775 4.2.2. Timestamp (TS) 777 For compatibility with a variety of protocols, the use of UTC time is 778 selected to represent all time values in the DTNMP. However, 779 timestamps in DTNMP may represent either absolute or relative time 780 based on the associated epoch. DTNMP uses September 9th, 2012 as the 781 timestamp epoch (UTC time 1348025776). Values less than this value 782 MUST be considered as relative times. Values greater than or equal 783 to this epoch MUST be considered as absolute times. In all cases, 784 the DTNMP timestamp is encoded as an SDNV. 786 4.2.3. Data Collections (DC) 788 A Data collection is comprised of a value identifiying the number of 789 bytes in the collection, followed by each byte, as illustrated in 790 Figure 5. Data collections are used in the DTNMP to capture variable 791 data sets that are too large to place in an SDNV. 793 Data Collection 795 +---------+--------+--------+ +--------+ 796 | # Bytes | BYTE 1 | BYTE 2 | ... | BYTE N | 797 | [SDNV] | [BYTE] | [BYTE] | | [BYTE] | 798 +---------+--------+--------+ +--------+ 800 Figure 5 802 4.3. Naming and Identification 804 While all components within the DTNMP can be uniquely identified by 805 an Object Identifier (OID), several annotations exist to assist with 806 the filtering and access control associated with components beyond 807 what is efficiently represented in the OID structure. These 808 annotations include the type and category of the component, an 809 optional identifier naming the issuer of the component, and an 810 optional tag value holding issuer-specific information about the 811 component. 813 The DTNMP Managed Identifier (MID) provides a single, variable length 814 structure that encapsulates all of the information necessary to 815 identify a DTNMP component and its useful annotations. 817 The MID structure, illustrated in Figure 6, is comprised of up to 818 four fields. In this illustration, each field is named, the type of 819 each field is given in []'s, and the string "(opt.)" indicates that 820 the field is optional, pending on the values found in the flags byte. 822 MID format 824 +--------+--------+--------+--------+ 825 | Flags | Issuer | OID | Tag | 826 | [BYTE] | [SDNV] |[VARIED]| [SDNV] | 827 | | (opt.) | | (opt.) | 828 +--------+--------+--------+--------+ 830 Figure 6 832 The MID fields are defined as follows. 834 Flags 835 Flags are used to describe the type of component identified 836 by the MID, identify which optional fields in the MID are 837 present, and the encoding used to capture the component's 838 OID. The layout of the flag byte is illustrated in Figure 7. 840 MID Flag Format 842 +-----+---+---+-----+------+ 843 | OID |TAG|ISS| CAT | TYPE | 844 +-----+---+---+-----+------+ 845 | 7 6 | 5 | 4 | 3 2 | 1 0 | 846 +-----+---+---+-----+------+ 847 MSB LSB 849 Figure 7 851 MID Type (TYPE) 852 The type of the component encapsulated by the MID, 853 enumerated as data (0), control (1), literal (2), or 854 operator (3). 856 MID Category (CAT) 857 The category of the component encapsulated by the 858 MID, enumerated as atomic (0), computed (1), and 859 collection (2). 861 Issuer Present (ISS) 862 Whether the issuer field is present (1) or not (0) 863 for this MID. If this flag has a value of 1 then the 864 issuer field MUST be present in the MID. Otherwise, 865 the issuer field MUST NOT be present in the MID. 867 Tag Present (TAG) 868 Whether the tag field is present (1) or not (0) for 869 this MID. If this flag has a value of 1 then the tag 870 field MUST be present in the MID. Otherwise, the tag 871 field MUST NOT be present. 873 OID Type (OID) 874 Whether the contained OID field represents an full 875 OID (0), a parameterized OID (1), a compressed full 876 OID (2), or a compressed, parameterized OID (3). 878 For example, a MID flag byte of 0x00 indicates an atomic data 879 value with no issuer or tag field encapsulating a full OID. 880 A MID flag byte of 0x94 indicates a computed data value with 881 an issuer field, but no tag field encapsulating a compressed 882 OID. 884 Issuer 885 This is a binary identifier representing a predetermined 886 issuer name. The DTNMP protocol does not parse or validate 887 this identifier, using it only as a distinguishing bit 888 pattern to assure MID uniqueness. This value, for example, 889 may come from a global registry of organizations, an issuing 890 node address, or some other network-unique marking. 892 OID 893 The core of a MID is its encapsulated Object Identifier 894 (OID). Aside from the flag byte, this is the only other 895 mandatory element within a MID. The DTNMP defines four types 896 of OID references for this part of the MID structure: Full 897 OIDs, Parameterized OIDs, Compressed Full OIDs, and 898 Compressed Parameterized OIDs. 900 Full OID 901 This is a binary representation of the full OID 902 associated with the named value. The OID is encoded 903 using a modified form of the ASN.1 Basic Encoding 904 Rules (BER) for Object Identifiers (type value of 905 0x06). In the standard ASN.1 encoding, four octet 906 sets are defined: identifier octets, length octets, 907 contents octets, and end-of-contents octets. A DTNMP 908 Full OID does not use the identifier, length, or end- 909 of-contents octets. Instead, a DTNMP Full OID is 910 comprised of two fields: the length in bytes of the 911 encoded OID captured in an SDNV followed by the OID 912 contents octets, as illustrated in Figure 8. 914 Full OID Format 916 +------------+--------------------+ 917 | OID Length | OID Content Octets | 918 | [SDNV] | [ASN.1 BER] | 919 +------------+--------------------+ 921 Figure 8 923 Parameterized OID 924 The parameterized OID is represented as the non- 925 parameterized portions of the OID followed by one or 926 more parameters. Parameterized OIDs are used to 927 templatize the specification of data items and 928 otherwise provide parameters to controls without 929 requiring potentially unmanagable growth of a Full 930 OID namespace. The format of a parameterized OID is 931 given in Figure 9. 933 Parameterized OID Format 935 +----------+---------+--------+ +--------+ 936 | Base OID | # Parms | Parm 1 | ... | Parm N | 937 | [VAR] | [SDNV] | [DC] | | [DC] | 938 +----------+---------+--------+ +--------+ 940 Figure 9 942 Compressed Full OID 943 Since many related OIDs share a common and lengthy 944 hierarchy there is opportunity for significant 945 message size savings by defining a shorthand for 946 commonly-used portions of the OID tree. A partial 947 OID is a tuple consisting of a nickname for a pre- 948 defined portion of the OID tree (as an SDNV), 949 followed by a relative OID. 951 Compressed Parameterized OID 952 A compressed, parameterized OID is similar to a 953 compressed OID. In this instance, the tuple 954 contained in this field is the nickname for the pre- 955 defined portion of the OID tree (as an SDNV) followed 956 by a parameterized OID whose hierarchy begins at the 957 place identified by the nickname. 959 Tag 960 A value used to disambiguate multiple MIDs with the same OID/ 961 Issuer combination. The definition of the tag is left to the 962 discretion of the MID issuer. Proper name objects do not 963 require a tag as their OIDs are guaranteed to be globally 964 unique. Options for tag values include an issuer-known 965 version number or a hashing of the data associated with a 966 non-proper-name MIDs. The tag field MUST NOT be present for 967 the atomic category. 969 4.4. Special Types 971 In addition to the primitive data types already mentioned, the 972 following special data types are also defined. 974 4.4.1. MID Collections (MC) 976 A MID collection is comprised of a value identifiying the number of 977 MIDs in the collection, followed by each MID, as illustrated in 978 Figure 10. 980 MID Collection 982 +--------+-------+ +-------+ 983 | # MIDs | MID 1 | ... | MID N | 984 | [SDNV] | [MID] | | [MID] | 985 +--------+-------+ +-------+ 987 Figure 10 989 4.4.2. Expressions (EXPR) 991 Expressions apply operations to data and literal values to generate 992 new data values. The expression type in DTNMP is a collection of 993 MIDs that represent a postfix notation stack of Data, Literal, and 994 Operation types. For example, the infix expression A * (B * C) is 995 represented as the sequence A B C * *. The format of an expression is 996 illustrated in Figure 11. 998 Expression Format 1000 +----------+------------+ 1001 | Priority | Expression | 1002 | [SDNV] | [MC] | 1003 +----------+------------+ 1005 Figure 11 1007 Priority 1008 The priority of this expression relative to any other 1009 expression configured on the DTNMP actor. Priorities are 1010 used when one expression MUST be evaluated before some other 1011 expression is evaluated. This field represents an unsigned 1012 integer value with larger values indicating higher priority. 1013 Unless otherwise specified, a default priority value of 0 1014 SHALL be used for any defined expression. 1016 Expression 1017 An expression is represented in the DTNMP as a MID 1018 collection, where each MID in the ordered collection 1019 represents the data, literals, and operations that comprise 1020 the expression. 1022 4.4.3. Predicate (PRED) 1024 Predicates are expressions whose values are interpretted as a 1025 Boolean. The value of zero MUST be considered "false" and all other 1026 values MUST be considered "true". Similar to an expression, a 1027 predicate is represented as a MID collection. 1029 5. Functional Specification 1031 This section describes the format of the messages that comprise the 1032 DTNMP protocol. When discussing the format/types of data that 1033 comprise message fields, the following conventions are used. 1035 +-----------+---------------------------------+ 1036 | Type Name | Description | 1037 +-----------+---------------------------------+ 1038 | BYTE | Unsigned, 8-bit byte. | 1039 | | | 1040 | DC | Data Collection | 1041 | | | 1042 | EXPR | Expression | 1043 | | | 1044 | MC | MID Collection | 1045 | | | 1046 | MID | Managed Identifier | 1047 | | | 1048 | PRED | Predicate | 1049 | | | 1050 | SDNV | Self-Delimiting Numerical Value | 1051 | | | 1052 | TS | Timestamp | 1053 | | | 1054 | VAR | Variable field. | 1055 +-----------+---------------------------------+ 1057 5.1. Message Group Format 1059 Individual messages within the DTNMP are combined into a single group 1060 for communication with another DTNMP actor. Messages within a group 1061 MUST be received and applied as an atomic unit. The format of a 1062 message group is illustrated in Figure 12. These message groups are 1063 assumed communicated amongst agents and managers as the payloads of 1064 encapsulating protocols, such as the Bundle Protocol or Internet 1065 Protocol, which MAY provide additional security and data integrity 1066 features. 1068 DTNMP Message Group Format 1070 +--------+-----------+-----------+ +-----------+ 1071 | # Msgs | Timestamp | Message 1 | ... | Message N | 1072 | [SDNV] | [TS] | [VAR] | | [VAR] | 1073 +--------+-----------+-----------+ +-----------+ 1075 Figure 12 1077 # Msgs 1078 The number of messages that are together in this message 1079 group. 1081 Timestamp 1082 The creation time for this messaging group. This timestamp 1083 MUST be an absolute time. Individual messages may have their 1084 own creation timestamps based on their type, but the group 1085 timestamp also serves as the default creation timestamp for 1086 every message in the group. 1088 Message N 1089 The Nth message in the group. 1091 5.2. Message Format 1093 Each message identified in the DTNMP specification adheres to a 1094 common message format, illustrated in Figure 13, consisting of a 1095 message header, a message body, and an optional trailer. 1097 DTNMP Message Format 1099 +--------+-------+---------+ 1100 | Header | Body | Trailer | 1101 | [BYTE] | [VAR] | [VAR] | 1102 | | | (opt.) | 1103 +--------+-------+---------+ 1105 Figure 13 1107 Header 1108 The message header byte is shown in Figure 14. The header 1109 identifies a message context and opcode as well as flags that 1110 control whether a report should be generated on message 1111 success (Ack) and whether a report should be generated on 1112 message failure (Nack). 1114 DTNMP Common Message Header 1116 +--------+----+---+---------+-------+ 1117 |ACL Used|Nack|Ack| Context |Opcode | 1118 +--------+----+---+---------+-------+ 1119 | 7 | 6 | 5 | 4 3 | 2 1 0 | 1120 +--------+----+---+---------+-------+ 1121 MSB LSB 1123 Figure 14 1125 Opcode 1126 The opcode field identifies the opcode of the 1127 message, within the associated message context. 1129 ACK Flag 1130 The ACK flag describes whether successfull 1131 application of the message must generate an 1132 ackowledgement back to the message sender. If this 1133 flag is set (1) then the receiving actor MUST 1134 generate a report communicating this status. 1135 Otherwise, the actor MAY generate such a report based 1136 on other criteria. 1138 NACK Flag 1139 The NACK flag describes whether a failure applying 1140 the message must generate an error notice back to the 1141 message sender. If this flag is set (1) then the 1142 receiving actor MUST generate a report communicating 1143 this status. Otherwise, the actor MAY generate such 1144 a report based on other criteria. 1146 ACL Used Flag 1147 The ACL used flag indicates whether the message has a 1148 trailer associated with it that specifies the list of 1149 DTNMP actors that may participate in the actions or 1150 definitions associated with the message. This area 1151 is still under development. 1153 Body 1154 The message body contains the information associated with the 1155 given message. 1157 Trailer 1158 An OPTIONAL access control list (ACL) may be appended as a 1159 trailer to a message. When present, the ACL for a message 1160 identifiers the agents and managers that can be affected by 1161 the definitions and actions contained within the message. 1162 The explicit impact of an ACL is described in the context of 1163 each message below. When an ACL trailer is not present, the 1164 message results may be visible to any DTNMP actor in the 1165 network, pursuant to other security protocol implementations. 1167 5.3. Register Agent (0x00) 1169 The Register Agent message is used to inform a DTNMP manager of the 1170 presence of another agent in the network. 1172 +----------+ 1173 | Agent ID | 1174 | [SDNV] | 1175 +----------+ 1177 Figure 15: Register Agent Message Body 1179 Agent ID 1180 The Agent ID MUST represent the unique address of the agent 1181 in whatever protocol is used to communicate with the agent. 1182 For example, when DTNMP is run over Bundle Protocol, the 1183 Agent ID should be the Endpoint Identifier (EID) of the agent 1184 being added. 1186 5.4. Data Report (0x12) 1188 Data reports include a listing of one or more data items collected 1189 from a managed device. These reports may include atomic data, 1190 computed data, or any report definition known to the generating 1191 device. Each message is a concatenation of ID/Data definitions with 1192 the overall message length assumed to be captured in the underlying 1193 transport container. 1195 +------+------+-------+--------+ +-------+--------+ 1196 | Time | Num | ID 1 | Data 1 | | ID N | Data N | 1197 | [TS] |[SDNV]| [MID] | [DC] |...| [MID] | [DC] | 1198 +------+------+-------+--------+ +-------+--------+ 1200 Figure 16 1202 Time 1203 The time at which the report was generated by the DTNMP 1204 actor. 1206 Num 1207 The number of reports in the data report message. 1209 ID N 1210 The MID identifying the Nth report. 1212 Data N 1213 The contents of the Nth report. 1215 5.5. Perform Control (0x20) 1217 The perform control method causes the receiving DTNMP actor to apply 1218 one or more pre-configured controls. 1220 Predicate Production Message 1222 +-------+-----------+ 1223 | Start | Controls | 1224 | [TS] | [MC] | 1225 +-------+-----------+ 1227 Figure 17 1229 Start 1230 The time at which the control should be run. 1232 Controls 1233 The collection of controls to be applied by the DTNMP actor. 1234 The MID identifying a control will contain the parameters for 1235 the control (if any) through the use of a parameterized OID 1236 captured within the MID. 1238 6. Appliation Data Model Template 1240 6.1. Overview 1242 An application data model (ADM) specifies the set of DTNMP components 1243 associated with a particular application/protocol. The purpose of 1244 the ADM is to provide a guaranteed interface for the management of an 1245 application or protocol over DTNMP that is independent of the nuances 1246 of its software implementation. In this respect, the ADM is 1247 conceptually similar to the Managed Information Base (MIB) used by 1248 SNMP, but contains additional information relating to command opcodes 1249 and more expressive syntax for automated behavior. 1251 Currently, the ADM is an organizing document and not used to 1252 automatically generate software. As such, the ADM template lists the 1253 kind of information that must be present in an ADM definition but 1254 does not address mechanisms for automating implementations. 1256 Each ADM specifies the globally unique identifiers and descriptions 1257 for all data, controls, literals, and operators associated with the 1258 application or protocol maanged by the ADM. Any implementation 1259 claiming compliance with a given ADM must compute all identified 1260 data, perform identified controls, and understand identified literals 1261 and operators. 1263 6.2. ADM Types 1265 ADMs must specify data types when defining data items and parameters. 1266 In addition to the standard DTNMP Types (SDNV, TS, DC, MID, OID, 1267 P_OID, MC, EXPR, and PRED) ADMs support the following additional data 1268 types. 1270 +------------+--------+-----------------------------+---------------+ 1271 | Data Type | ID | Description | Encapsulating | 1272 | | | | DTNMP Type | 1273 +------------+--------+-----------------------------+---------------+ 1274 | Integer | INT | A signed or unsigned | SDNV | 1275 | | | integer up to 64 bits in | | 1276 | | | width encoded using Google | | 1277 | | | Protocol Buffer VARINT | | 1278 | | | rules. Booleans, | | 1279 | | | enumerations, and all | | 1280 | | | integer values are captured | | 1281 | | | using this data type. | | 1282 | | | | | 1283 | Float | FLOAT | A 32-bit fixed-width number | SDNV | 1284 | | | stored according to the | | 1285 | | | IEEE-754 float standard. | | 1286 | | | | | 1287 | Double | DOUBLE | A 64-bit fixed-width number | SDNV | 1288 | | | stored according to the | | 1289 | | | IEEE-754 double standard. | | 1290 | | | | | 1291 | STRING | STR | An array of characters | DC | 1292 | | | preceeded by the character | | 1293 | | | count. Strings are not | | 1294 | | | required to be NULL- | | 1295 | | | terminated. | | 1296 | | | | | 1297 | Binary | BLOB | An undefined series of | DC | 1298 | Large | | user-defined bytes | | 1299 | Object | | preceeded by the length of | | 1300 | | | the binary object. This | | 1301 | | | data type is captured . | | 1302 +------------+--------+-----------------------------+---------------+ 1304 Table 3: ADM Data Types 1306 6.3. Template 1308 ADM definitions specify the metadata, data, controls, literals, and 1309 operators associated with a managed application or protocol. 1311 6.3.1. ADM Metadata 1313 ADM metadata consist of the items necessary to uniquely identify the 1314 ADM itself. The required metadata items include the following. 1316 +-------------+--------+-------------------------------------+------+ 1317 | Item | Type | Description | Req. | 1318 +-------------+--------+-------------------------------------+------+ 1319 | Name | STR | The human-readible name of the ADM. | Y | 1320 | | | | | 1321 | Version | STR | Version of the ADM encoded as a | Y | 1322 | | | string. | | 1323 | | | | | 1324 | OID | OID | ADMs provide an ordered list of | N | 1325 | Nickname N | | nicknames that can be used by other | | 1326 | | | MIDs in the ADM definition to | | 1327 | | | defined compressed OIDs. There can | | 1328 | | | an arbitratry number of nicknames | | 1329 | | | defined for an ADM. | | 1330 +-------------+--------+-------------------------------------+------+ 1332 Table 4: ADM Terminology 1334 6.3.2. ADM Information Capture 1336 The ADM Data Section consist of all components in the "data" category 1337 associated with the managed application or protocol. The information 1338 that must be provided for each of these items is as follows. 1340 Name 1341 Every component in an ADM MUST be given a human-readable, 1342 consistent name that unqiuely identifies the component in the 1343 context of the application or protocol. These names will be used 1344 by human-computer interfaces for manipulating components. 1346 MID 1347 The managed identifier that describes this data item. MIDs in 1348 components identified by an ADM MUST NOT contain an issuer or a 1349 tag value. In cases where a partial OID is specified, the ADM OID 1350 prefix is presumed as the base. In cases where the OID is 1351 parameterized, the parameter values are not included in the MID 1352 definition in the ADM as parameters are provided at runtime by 1353 implementations. 1355 OID 1356 A human-readible version of the OID encapsulated in the MID for 1357 the component (e.g., 1.2.3.4). When a nickname is used to 1358 represent an compressed OID, the nickname enumeration is included 1359 in this field enclosed by square brackets. For example, if OID 1360 nickname 0 refers to the OID prefix 1.2.3.4.5, then the OID 1361 1.2.3.4.5.6 may be listed more compactly as [0].6 1363 Description 1364 Every component in an ADM MUST be given a human-readable, 1365 consistent description that provides a potential user with a 1366 compact, effective summary of the component. 1368 Type 1369 For components that evaluate to a data value, the data type for 1370 that value must be represented. 1372 # Parameters 1373 For components with a parameterized OID, the ADM MUST provide the 1374 expected number of parameters. A value of 0 indicates that the 1375 OID has no parameters and MUST NOT be used for any MID which has a 1376 parameterized OID. When ommitted, the number of parameters is 1377 considered 0. 1379 Parameter N Name 1380 Each parameter of a parameterized component must be given a name. 1382 Parameter N Description 1383 Each parameter of a parameterized component must be given a 1384 summary that describes how the parameter will be used by the 1385 application or protocol. 1387 Parameter N Type 1388 Each parameter of a parameterized component must be given a type 1389 that describes the structre capturing the parameter value. 1390 Notably, while parameters in the OID form something similar to a 1391 function prototype, there is no sense of function call or stack 1392 and therefore all parameters should be considered as pass-by- 1393 value. 1395 7. DTNMP Agent Application Data Model 1397 7.1. Data Definitions 1399 This section provides the ADM for a DTNMP Agent. This ADM may 1400 eventually be removed from the DTNMP specification into its own 1401 standards document. All DTNMP agents MUST support the items 1402 described in this section. 1404 7.2. Metadata Definitions 1406 +-------------+-------+------------+--------------------------------+ 1407 | Item | Type | Value | Comment | 1408 +-------------+-------+------------+--------------------------------+ 1409 | Name | STR | DTNMP | | 1410 | | | Agent ADM | | 1411 | | | | | 1412 | Version | STR | 2014-12-31 | | 1413 | | | | | 1414 | OID | OID | 1.1 | 1.1 is currently used only as | 1415 | Nickname 0 | | | a non-operational example of | 1416 | | | | an ADM base. | 1417 +-------------+-------+------------+--------------------------------+ 1419 Table 5: DTNMP Agent Metadata 1421 7.3. Data Definitions 1423 The DTNMP Agent ADM defines the following atomic data definitions 1424 that represent the set of data that MUST be collected by any DTNMP 1425 agent implementation. 1427 7.3.1. Atomic Data 1428 +------------------+----------+---------+----------------+----------+ 1429 | Name | MID | OID | Description | Type | 1430 +------------------+----------+---------+----------------+----------+ 1431 | DefinedReports | 0x800200 | [0].0.0 | # Reports | INT | 1432 | | | | Defined | | 1433 | | | | | | 1434 | SentReports | 0x800201 | [0].0.1 | # Reports Sent | INT | 1435 | | | | | | 1436 | DefinedTimeRules | 0x800202 | [0].0.2 | # Active Time- | INT | 1437 | | | | Based | | 1438 | | | | Production | | 1439 | | | | Rules | | 1440 | | | | | | 1441 | RunTimeRules | 0x800203 | [0].0.3 | # Run Time- | INT | 1442 | | | | Based | | 1443 | | | | Production | | 1444 | | | | Rules | | 1445 | | | | | | 1446 | DefinedConsts | 0x800204 | [0].0.4 | # Constants | INT | 1447 | | | | Defined | | 1448 | | | | | | 1449 | DefinedCustom | 0x800205 | [0].0.5 | # Computed | INT | 1450 | | | | Data | | 1451 | | | | Definitions | | 1452 | | | | | | 1453 | DefinedMacros | 0x800206 | [0].0.6 | # Macros | INT | 1454 | | | | Defined | | 1455 | | | | | | 1456 | RunMacros | 0x800207 | [0].0.7 | # Macros Run | INT | 1457 | | | | | | 1458 | DefinedCtrls | 0x800208 | [0].0.8 | # Controls | INT | 1459 | | | | Defined | | 1460 | | | | | | 1461 | RunCtrls | 0x800209 | [0].0.9 | # Controls | INT | 1462 | | | | Defined | | 1463 +------------------+----------+---------+----------------+----------+ 1465 Table 6: DTNMP Agent Atomic Data 1467 7.3.2. Computed Data 1469 The DTNMP Agent ADM does not define any computed data items. 1471 7.3.3. Reports 1472 +------------+----------+---------+------------------+--------------+ 1473 | Name | MID | OID | Description | Type | 1474 +------------+----------+---------+------------------+--------------+ 1475 | FullReport | 0x880220 | [0].2.0 | Report of all | DC | 1476 | | | | atomic data | | 1477 | | | | items | | 1478 +------------+----------+---------+------------------+--------------+ 1480 Table 7: DTNMP Agent Reports 1482 7.4. Operators 1484 This section describes the standard set of operators available to all 1485 DTNMP agents. Applications and protocols do not need to redefine 1486 these operators, as they may be used in any expressions evaluated by 1487 any agent. 1489 +------------+-----------+----------+-------------------------------+ 1490 | Name | MID | OID | Description | 1491 +------------+-----------+----------+-------------------------------+ 1492 | + | 0x830260 | [0].6.0 | Addition | 1493 | | | | | 1494 | - | 0x830261 | [0].6.1 | Subtraction | 1495 | | | | | 1496 | * | 0x830262 | [0].6.2 | Multiplication | 1497 | | | | | 1498 | / | 0x830263 | [0].6.3 | Division | 1499 | | | | | 1500 | % | 0x830264 | [0].6.4 | Modulo | 1501 | | | | | 1502 | ^ | 0x830265 | [0].6.5 | Exponentiation | 1503 | | | | | 1504 | & | 0x830266 | [0].6.6 | Bitwise AND | 1505 | | | | | 1506 | | | 0x830267 | [0].6.7 | Bitwise OR | 1507 | | | | | 1508 | # | 0x830268 | [0].6.8 | Bitwise XOR | 1509 | | | | | 1510 | ~ | 0x830269 | [0].6.9 | Bitwise NOT | 1511 | | | | | 1512 | && | 0x83026A | [0].6.A | Logical AND | 1513 | | | | | 1514 | || | 0x83026B | [0].6.B | Logical OR | 1515 | | | | | 1516 | ## | 0x83026C | [0].6.C | Logical XOR | 1517 | | | | | 1518 | ! | 0x83026D | [0].6.D | Logical NOT | 1519 | | | | | 1520 | abs | 0x83026E | [0].6.E | Absolute Value | 1521 | | | | | 1522 | < | 0x83026F | [0].6.F | Less than | 1523 | | | | | 1524 | > | 0x8303610 | [0].6.10 | Greater than | 1525 | | | | | 1526 | <= | 0x8303611 | [0].6.11 | Less than or equal to | 1527 | | | | | 1528 | >= | 0x8303612 | [0].6.12 | Greater than or equal to | 1529 | | | | | 1530 | != | 0x8303613 | [0].6.13 | Not equal | 1531 | | | | | 1532 | == | 0x8303614 | [0].6.14 | Equal to | 1533 +------------+-----------+----------+-------------------------------+ 1535 Table 8: DTNMP Agent Atomic Data 1537 7.5. Controls 1539 This section describes the controls available for use on any DTNMP 1540 agent. Since this section essentially provides a functional 1541 specification for the DTNMP agent, it is presented in two sections. 1542 First, a summary section provides a quick reference for the controls 1543 available on a DTNMP agent. Second, a full control specification 1544 provides detailed information on each individual DTNMP agent control. 1546 7.5.1. Control Summary 1548 +----------------+-----------+----------+---------------------------+ 1549 | Name | MID | OID | Description | 1550 +----------------+-----------+----------+---------------------------+ 1551 | ListADMs | 0x810230 | [0].3.0 | List all ADMs known to | 1552 | | | | the agent. | 1553 | | | | | 1554 | ListAtomicIDs | 0x810231 | [0].3.1 | List all Atomic MIDs | 1555 | | | | known to the agent. | 1556 | | | | | 1557 | DescAtomicData | 0xC10232 | [0].3.2 | Dump information for | 1558 | | | | given Atomic MIDs. | 1559 | | | | | 1560 | AddCompData | 0xC10233 | [0].3.3 | Define a computed data | 1561 | | | | definition on the agent. | 1562 | | | | | 1563 | DelCompData | 0xC10234 | [0].3.4 | Remove a computed data | 1564 | | | | definition from the | 1565 | | | | agent. | 1566 | | | | | 1567 | ListCompData | 0x810235 | [0].3.5 | List known computed data | 1568 | | | | MIDs. | 1569 | | | | | 1570 | DescCompData | 0xC10236 | [0].3.6 | Dump information for | 1571 | | | | given computed data MIDs. | 1572 | | | | | 1573 | AddRptDef | 0xC10237 | [0].3.7 | Define a custom report. | 1574 | | | | | 1575 | DelRptDef | 0xC10238 | [0].3.8 | Forget a custom report. | 1576 | | | | | 1577 | ListRpts | 0x810239 | [0].3.9 | List known custom report | 1578 | | | | MIDs. | 1579 | | | | | 1580 | DescRpts | 0xC1023A | [0].3.A | Dump information for | 1581 | | | | given custom report MIDs. | 1582 | | | | | 1583 | ListOps | 0x81023B | [0].3.B | List known operator IDs. | 1584 | | | | | 1585 | DescOps | 0xC1023C | [0].3.C | Dump information for | 1586 | | | | given operator MIDs. | 1587 | | | | | 1588 | ListCtrls | 0x81023D | [0].3.D | List known custom control | 1589 | | | | MIDs. | 1590 | | | | | 1591 | DescCtrls | 0xC1023E | [0].3.E | Dump information for | 1592 | | | | given controls MIDs. | 1593 | | | | | 1594 | AddMacroDef | 0xC1023F | [0].3.F | Define a custom macro. | 1595 | | | | | 1596 | DelMacroDef | 0xC103310 | [0].3.10 | Forget a custom macro. | 1597 | | | | | 1598 | ListMacros | 0x8103311 | [0].3.11 | List known custom macro | 1599 | | | | MIDs. | 1600 | | | | | 1601 | DescMacros | 0xC103312 | [0].3.12 | Dump information for | 1602 | | | | given custom macro MIDs. | 1603 | | | | | 1604 | AddTimeRule | 0xC103313 | [0].3.13 | Define a time-based prod | 1605 | | | | rule. | 1606 | | | | | 1607 | DelTimeRule | 0xC103314 | [0].3.14 | Forget a time-based prod | 1608 | | | | rule. | 1609 | | | | | 1610 | ListTimeRules | 0x8103315 | [0].3.15 | List known time-based | 1611 | | | | rules. | 1612 | | | | | 1613 | DescTimeRules | 0xC103316 | [0].3.16 | Dump information for | 1614 | | | | given time-based rules. | 1615 | | | | | 1616 | AddStateRule | 0xC103317 | [0].3.17 | Define a state-based prod | 1617 | | | | rule. | 1618 | | | | | 1619 | DelStateRule | 0xC103318 | [0].3.18 | Forget a state-based prod | 1620 | | | | rule. | 1621 | | | | | 1622 | ListStateRules | 0x8103319 | [0].3.19 | List known state-based | 1623 | | | | rules. | 1624 | | | | | 1625 | DescStateRules | 0xC10331A | [0].3.1A | Dump information for | 1626 | | | | given state-based rules. | 1627 +----------------+-----------+----------+---------------------------+ 1629 Table 9: DTNMP Agent Controls Summary 1631 7.5.2. Control Specification 1633 7.5.2.1. ListADMs 1635 This control causes the agent to produce a report detailing the list 1636 of all ADMs configured on the agent and available for use. 1638 This control takes no parameters. 1640 This control causes a report to be generated with the following 1641 format. 1643 ListADMs Report Format 1645 +--------+------------+ +------------+ 1646 | # ADMs | ADM 1 Name | ... | ADM N Name | 1647 | [SDNV] | [STR] | | [STR] | 1648 +--------+------------+ +------------+ 1650 Figure 18 1652 # ADMs 1653 The number of ADMs known to the agent. 1655 ADM [x] Name 1656 For each ADM, it's human readable name. 1658 7.5.2.2. ListAtomicIDs 1660 This control causes the agent to produce a list containing the MID of 1661 every atomic data item understood by the agent. 1663 This control takes no parameters. 1665 This control causes a report to be generated with the following 1666 format. 1668 ListAtomicIDs Report Format 1670 +------------+ 1671 | Atomic IDs | 1672 | [MC] | 1673 +------------+ 1675 Figure 19 1677 Atomic IDs 1678 A MID Collection of the MIDs of each atomic data definition 1679 known to the agent. 1681 7.5.2.3. DescAtomicData 1683 This control causes the agent to produce a detailed description of 1684 the requested atomic data definitions. 1686 This control takes 1 parameter in the following format. 1688 DescAtomicData Parameters 1690 +------------+ 1691 | Atomic IDs | 1692 | [MC] | 1693 +------------+ 1695 Figure 20 1697 Atomic IDs 1698 The list of MIDs identifying the atomic IDs to be described. 1700 This control causes a report to be generated with the following 1701 format. 1703 DescAtomicData Report Format 1705 +--------+----------+----------+ +----------+----------+ 1706 | # IDs | ID1 Name | ID1 Type |... | IDn Name | IDn Type | 1707 | [SDNV] | [STR] | [SDNV] | | [STR] | [SDNV] | 1708 +--------+----------+----------+ +----------+----------+ 1710 Figure 21 1712 # IDs 1713 The number of atomic data descriptions returned. 1715 ID[n] Name 1716 The name of the nth returned atomic data item. 1718 ID[n] Type 1719 Type enumeration for the nth atomic data item. 1721 7.5.2.4. AddCompData 1723 This control configures a new computed data definition on the agent. 1724 A computed data item uses an expression to assign a data value. 1726 This control takes 3 parameters in the following format. 1728 AddCompData Parameters 1730 +--------+--------+--------+ 1731 | Def ID | Def | Type | 1732 | [MID] | [EXPR] | [SDNV] | 1733 +--------+--------+--------+ 1735 Figure 22 1737 Def ID 1738 The MID value identifying the new computed data definition. 1740 Def 1741 The expression used to calculate the value for the new 1742 computed data item. 1744 Type 1745 The data type for the resultant computed data value. 1747 This control causes no report to be produced. 1749 7.5.2.5. DelCompData 1751 This control removes a computed data definition from the agent. 1753 This control takes 1 parameter in the following format. 1755 DelCompData Parameters 1757 +---------------+ 1758 | IDs To Remove | 1759 | [MC] | 1760 +---------------+ 1762 Figure 23 1764 IDs To Remove 1765 The list of computed data items to be removed from the agent. 1767 This control causes no report to be produced. 1769 7.5.2.6. ListCompData 1771 This control causes the agent to produce a list containing the MID of 1772 every computed data definition understood by the agent. 1774 This control takes no parameters. 1776 This control causes a report to be generated with the following 1777 format. 1779 ListCompData Report Format 1781 +------------+ 1782 | Custom IDs | 1783 | [MC] | 1784 +------------+ 1786 Figure 24 1788 Custom IDs 1789 The collection of identifiers for those computed data 1790 definitions known to the agent. 1792 7.5.2.7. DescCompData 1794 This control causes the agent to produce a detailed description of 1795 the requested computed data definitions. 1797 This control takes 1 parameter in the following format. 1799 DescCompData Parameters 1801 +----------+ 1802 | Comp IDs | 1803 | [MC] | 1804 +----------+ 1806 Figure 25 1808 Comp IDs 1809 The MID collection identifying the computed data items to be 1810 described. 1812 This control causes a report to be generated with the following 1813 format. 1815 DescCompData Report Format 1817 +------+-------+--------+---------+ +-------+--------+--------+ 1818 |# IDs | C1 ID | C1 Def | C1 Type |... | Cn ID | Cn Def | Cn Type| 1819 |[SDNV]| [MID] | [EXPR] | [SDNV] | | [MID] | [EXPR] | [SDNV] | 1820 +------+-------+--------+---------+ +-------+--------+--------+ 1822 Figure 26 1824 # IDs 1825 The number of computed data definitions in the report. 1827 C[n] ID 1828 The MID of the nth computed data definition. 1830 C[n] Def 1831 The expression used to calculate the value of the Nth 1832 computed data item. 1834 C[n] Type 1835 The data type of the value of the Nth computed data item. 1837 7.5.2.8. AddRptDef 1839 This control configures a new custom report definition on the agent. 1840 A custom report assigns a single MID value to represent an ordered 1841 collection of other MID values, with some administrative information 1842 that identifies what other nodes in the network may request and 1843 process this report. 1845 This control takes 2 parameters in the following format. 1847 AddRptDef Parameters 1849 +--------+------------+ 1850 | RPT ID | Definition | 1851 | [MID] | [MC] | 1852 +--------+------------+ 1854 Figure 27 1856 Rpt ID 1857 The MID for the new report. 1859 Definition 1860 The ordered set of MIDs representing the contents of the 1861 report. 1863 This control causes no report to be produced. 1865 7.5.2.9. DelRptDef 1867 This control removes a custom report definition from the agent. 1869 This control takes 1 parameters in the following format. 1871 DelRptDef Parameters 1873 +---------------+ 1874 | IDs To Remove | 1875 | [MC] | 1876 +---------------+ 1878 Figure 28 1880 IDs to Remove 1881 The collection of MIDs identifying the report definitions to 1882 remove from the agent. 1884 This control causes no report to be produced. 1886 7.5.2.10. ListRpts 1888 This control causes the agent to produce a list containing the MID of 1889 every report definition understood by the agent. 1891 This control takes no parameters. 1893 This control causes a report to be generated with the following 1894 format. 1896 ListRpts Report Format 1898 +---------+ 1899 | Reports | 1900 | [MC] | 1901 +---------+ 1903 Figure 29 1905 Reports 1906 The collection of MIDs representing custom report IDs known 1907 to the agent. 1909 7.5.2.11. DescRpts 1911 This control causes the agent to produce a detailed description of 1912 the requested report definitions. 1914 This control takes 1 parameter in the following format. 1916 DescRpts Parameters 1918 +------------+ 1919 | Report IDs | 1920 | [MC] | 1921 +------------+ 1923 Figure 30 1925 Report IDs 1926 The collection of MIDs identifying the report definitions to 1927 be described. 1929 This control causes a report to be generated with the following 1930 format. 1932 DescRpts Report Format 1934 +--------+----------+-----------+ +----------+-----------+ 1935 | # IDs | RPT 1 ID | RPT 1 Def | ... | RPT N ID | RPT N Def | 1936 | [SDNV] | [MID] | [MC] | | [MID] | [MC] | 1937 +--------+----------+-----------+ +----------+-----------+ 1939 Figure 31 1941 # IDs 1942 The number of report definitions in this report. 1944 RPT[n] ID 1945 The MID of the nth report definition. 1947 RPT[n] Def 1948 The ordered collection of IDs comprising the Nth report 1949 definition. 1951 7.5.2.12. ListOps 1953 This control causes the agent to produce a list containing the MID of 1954 every operator understood by the agent. 1956 This control takes no parameters. 1958 This control causes a report to be generated with the following 1959 format. 1961 ListOps Report Format 1963 +------+ 1964 | OPS | 1965 | [MC] | 1966 +------+ 1968 Figure 32 1970 OPS 1971 The collection of MIDs for every op known by the agent. 1973 7.5.2.13. DescOps 1975 This control causes the agent to produce a detailed listing of the 1976 requested operator definitions. 1978 This control takes 1 parameter in the following format. 1980 DescOps Parameters 1982 +--------+ 1983 | OP IDs | 1984 | [MC] | 1985 +--------+ 1987 Figure 33 1989 OP IDs 1990 The set of operators to be described. 1992 This control causes a report to be generated with the following 1993 format. 1995 DescOps Report Format 1997 +--------+---------+-----------+ +---------+-----------+ 1998 | # OPs | OP 1 ID | OP 1 Desc | ... | OP N ID | OP N Desc | 1999 | [SDNV] | [MID] | [STR] | | [MID] | [STR] | 2000 +--------+---------+-----------+ +---------+-----------+ 2002 Figure 34 2004 # OPs 2005 The number of operator definitions in the report. 2007 OP[n] ID 2008 The MID of the nth operator definition. 2010 OP[n] Def 2011 The description of the nth operator. 2013 7.5.2.14. ListCtrls 2015 This control causes the agent to produce a list containing the MID of 2016 every control understood by the agent. 2018 This control takes no parameters. 2020 This control causes a report to be generated with the following 2021 format. 2023 ListCtrls Report Format 2025 +-------+ 2026 | CTRLs | 2027 | [MC] | 2028 +-------+ 2030 Figure 35 2032 CTRLs 2033 The collection of MIDs of controls known to the agent. 2035 7.5.2.15. DescCtrls 2037 This control causes the agent to produce a detailed listing of the 2038 requested control definitions. 2040 This control takes 1 parameter in the following format. 2042 DescCtrls Parameters 2044 +----------+ 2045 | CTRL IDs | 2046 | [MC] | 2047 +----------+ 2049 Figure 36 2051 CTRL IDs 2052 The set of controls to be described. 2054 This control causes a report to be generated with the following 2055 format. 2057 DescCtrls Report Format 2059 +---------+----------+------------+ +----------+------------+ 2060 | # CTRLs | CTRL1 ID | CTRL1 Desc | ... | CTRLN ID | CTRLN Desc | 2061 | [SDNV] | [MID] | [STR] | | [MID] | [STR] | 2062 +---------+----------+------------+ +----------+------------+ 2064 Figure 37 2066 # CTRLs 2067 The number of control definitions in the report. 2069 CTRL[n] ID 2070 The MID of the nth control definition. 2072 CTRL[n] Desc 2073 The description of the Nth control definition, to include 2074 information on parameters. 2076 7.5.2.16. AddMacroDef 2078 This control configures a new custom macro definition on the agent. 2079 A macro is a series of controls that should be run in sequence. 2081 This control takes 3 parameters in the following format. 2083 AddMacroDef Parameters 2085 +------------+----------+------+ 2086 | Macro Name | Macro ID | Def | 2087 | [STR] | [MID] | [MC] | 2088 +------------+----------+------+ 2090 Figure 38 2092 Macro Name 2093 The descriptive name for the macro. 2095 Macro ID 2096 The MID value identifying the new macro. 2098 Def 2099 The ordered set of controls/macros that are run sequentially 2100 during macro execution. 2102 This control causes no report to be produced. 2104 7.5.2.17. DelMacroDef 2106 This control removes a custom macro definition from the agent. 2108 This control takes 1 parameters in the following format. 2110 DelMacroDef Parameters 2112 +---------------+ 2113 | IDs To Remove | 2114 | [MC] | 2115 +---------------+ 2117 Figure 39 2119 IDs To Remove 2120 The collection of MIDs identifying the macros to be removed 2121 from the agent. 2123 This control causes no report to be produced. 2125 7.5.2.18. ListMacros 2127 This control causes the agent to produce a list containing the MID of 2128 every custom macro definition understood by the agent. 2130 This control takes no parameters. 2132 This control causes a report to be generated with the following 2133 format. 2135 ListMacros Report Format 2137 +-----------+ 2138 | Macro IDs | 2139 | [MC] | 2140 +-----------+ 2142 Figure 40 2144 Macro IDs 2145 The list of macro definitions known to the agent. 2147 7.5.2.19. DescMacros 2149 This control causes the agent to produce a detailed listing of the 2150 requested macro definitions. 2152 This control takes 1 parameter in the following format. 2154 DescMacros Parameters 2156 +-----------+ 2157 | Macro IDs | 2158 | [MC] | 2159 +-----------+ 2161 Figure 41 2163 Macro IDs 2164 The collection of MIDs identifying the macros to be 2165 described. 2167 This control causes a report to be generated with the following 2168 format. 2170 DescMacros Report Format 2172 +--------+-------+-----+------+ +-------+-----+------+ 2173 |# Macros|M1 Name|M1 ID|M1 Def| ... |Mn Name|Mn ID|Mn Def| 2174 | [SDNV] | [STR] |[MID]| [MC] | | [STR] |[MID]| [MC] | 2175 +--------+-------+-----+------+ +-------+-----+------+ 2177 Figure 42 2179 # Macros 2180 The number of macro definitions in the report. 2182 M[n] Name 2183 The name of the nth macro definition. 2185 M[n] ID 2186 The MID of the nth macro definition. v 2188 M[n] Def 2189 The expression used to calculate the value of the Nth 2190 computed data item. 2192 7.5.2.20. AddTimeRule 2194 This control configures a new time-based production rule on the 2195 agent. A time-based production rule instructs the agent to produce a 2196 report comprising a fixed set of component values periodically over 2197 time. The component values may represent any type of data value, 2198 including atomic data, computed data, or reports. 2200 This control takes 4 parameters in the following format. 2202 AddTimeRule Parameters 2204 +--------+------------+--------+---------+ 2205 | Start | Period (s) | Count | Results | 2206 | [TS] | [SDNV] | [SDNV] | [MC] | 2207 +--------+------------+--------+---------+ 2209 Figure 43 2211 Start 2212 The time at which the production should commence. 2214 Period 2215 The number of seconds to wait between report message 2216 generation. 2218 Count 2219 The number of reports to be generated by this configuration. 2220 The special value of 0 indicates production should continue 2221 indefinitely. 2223 Results 2224 The collection of MIDs to be included in the report. 2226 No report is produced in response to this individual command. THe 2227 configured reports will be produced in accordance to the configured 2228 time period. 2230 7.5.2.21. DelTimeRule 2232 This control removes a time-based production rule from the agent. 2234 This control takes 1 parameters in the following format. 2236 DelTimeRule Parameters 2238 +----------+ 2239 | Rule IDs | 2240 | [MC] | 2241 +----------+ 2243 Figure 44 2245 Rule IDs 2246 The collection of MIDs identifying the rules to be removed 2247 from the agent. 2249 This control causes no report to be produced. 2251 7.5.2.22. ListTimeRules 2253 This control causes the agent to produce a list containing the MID of 2254 every time-based production rule understood by the agent. 2256 This control takes no parameters. 2258 This control causes a report to be generated with the following 2259 format. 2261 ListTimeRules Report Format 2263 +----------+ 2264 | Rule IDs | 2265 | [MC] | 2266 +----------+ 2268 Figure 45 2270 Rule IDs 2271 The collection of MIDs identifying the time-based rules known 2272 to the agent. 2274 7.5.2.23. DescTimeRules 2276 This control causes the agent to produce a detailed listing of the 2277 requested time-based production rules. 2279 This control takes 1 parameter in the following format. 2281 DescTimeRules Parameters 2283 +----------+ 2284 | Rule IDs | 2285 | [MC] | 2286 +----------+ 2288 Figure 46 2290 Rule IDs 2291 The collection of MIDs identifying the time-based rules to be 2292 described. 2294 This control causes a report to be generated with the following 2295 format. 2297 DescTimeRules Report Format 2299 +--------+-------+----------+-----------+----------+-----------+ 2300 |# Rules | R1 ID | R1 START | R1 PERIOD | R1 Count | R1 Result | ... 2301 | [SDNV] | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | 2302 +--------+-------+----------+-----------+----------+-----------+ 2304 Figure 47 2306 # Rules 2307 The number of time-based rule definitions in the report. 2309 R[n] ID 2310 The MID identifier for the nth time-based rule definition. 2312 R[n] Start 2313 The time at which the nth time-based rule production should 2314 commence. 2316 R[n] Period 2317 The number of seconds to wait between running the nth time- 2318 based rule. 2320 R[n] Count 2321 The number of reports to be generated by the nth time-based 2322 report. The special value of 0 indicates production should 2323 continue indefinitely. 2325 R[n] Results 2326 The collection of MIDs to be included in the report generated 2327 by the nth time-based rule. 2329 7.5.2.24. AddStateRule 2331 This control configures a new state-based production rule on the 2332 agent. A state-based production rule instructs the agent to produce 2333 a report comprising a fixed set of component values periodically 2334 whenever the expression evaluates to true. The component values may 2335 represent any type of data value, including atomic data, computed 2336 data, or reports. 2338 This control takes 4 parameters in the following format. 2340 AddStateRule Parameters 2342 +--------+--------+--------+---------+ 2343 | Start | State | Count | Results | 2344 | [TS] | [PRED] | [SDNV] | [MC] | 2345 +--------+--------+--------+---------+ 2347 Figure 48 2349 Start 2350 The time at which the production should commence. 2352 State 2353 The expression which, when non-zero, causes the report to be 2354 generated. 2356 Count 2357 The number of reports to be generated by this configuration. 2358 The special value of 0 indicates production should continue 2359 indefinitely. 2361 Results 2362 The collection of MIDs to be included in the report. 2364 No report is produced in response to this individual command. 2366 7.5.2.25. DelStateRule 2368 This control removes a state-based production rule from the agent. 2370 This control takes 1 parameters in the following format. 2372 DelStateRule Parameters 2374 +----------+ 2375 | Rule IDs | 2376 | [MC] | 2377 +----------+ 2379 Figure 49 2381 Rule IDs 2382 The collection of MIDs identifying the rules to be removed 2383 from the agent. 2385 This control causes no report to be produced. 2387 7.5.2.26. ListStateRules 2389 This control causes the agent to produce a list containing the MID of 2390 every state-based production rule understood by the agent. 2392 This control takes no parameters. 2394 This control causes a report to be generated with the following 2395 format. 2397 ListStateRules Report Format 2399 +----------+ 2400 | Rule IDs | 2401 | [MC] | 2402 +----------+ 2404 Figure 50 2406 Rule IDs 2407 The collection of MIDs identifying the state-based rules 2408 known to the agent. 2410 7.5.2.27. DescStateRules 2412 This control causes the agent to produce a detailed listing of the 2413 requested state-based production rules. 2415 This control takes 1 parameter in the following format. 2417 DescStateRules Parameters 2419 +----------+ 2420 | Rule IDs | 2421 | [MC] | 2422 +----------+ 2424 Figure 51 2426 Rule IDs 2427 The collection of MIDs identifying the state-based rules to 2428 be described. 2430 This control causes a report to be generated with the following 2431 format. 2433 DescStateRules Report Format 2435 +--------+-------+----------+-----------+----------+-----------+ 2436 |# Rules | R1 ID | R1 START | R1 PERIOD | R1 Count | R1 Result | ... 2437 | [SDNV] | [MID] | [TS] | [SDNV] | [SDNV] | [MC] | 2438 +--------+-------+----------+-----------+----------+-----------+ 2440 Figure 52 2442 # Rules 2443 The number of state-based rule definitions in the report. 2445 R[n] ID 2446 The MID identifier for the nth state-based rule definition. 2448 R[n] Start 2449 The time at which the nth state-based rule production should 2450 commence. 2452 R[n] Period 2453 The number of seconds to wait between running the nth state- 2454 based rule. 2456 R[n] Count 2457 The number of reports to be generated by the nth state-based 2458 report. The special value of 0 indicates production should 2459 continue indefinitely. 2461 R[n] Results 2462 The collection of MIDs to be included in the report generated 2463 by the nth state-based rule. 2465 8. IANA Considerations 2467 At this time, this protocol has no fields registered by IANA. 2469 9. Security Considerations 2471 Transport security is handled by the transport layer, for example the 2472 Bundle Security Protocol [RFC6257] when using the Bundle Protocol 2473 [RFC5050]. 2475 Finer grain application security is done via ACLs which are defined 2476 via configuration messages and implementation specific. 2478 10. Normative References 2480 [DTNM] Birrane, E. and H. Kruse, "DTN Network management: The 2481 Definition and Exchange of Infrastructure Information in 2482 High Delay Environments", . 2484 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2485 Requirement Levels", BCP 14, RFC 2119, March 1997. 2487 [RFC4838] Cerf, V., Burleigh, S., Hooke, A., Torgerson, L., Durst, 2488 R., Scott, K., Fall, K., and H. Weiss, "Delay-Tolerant 2489 Networking Architecture", RFC 4838, April 2007. 2491 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 2492 Specification", RFC 5050, November 2007. 2494 [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric 2495 Values in Protocols", RFC 6256, May 2011. 2497 [RFC6257] Symington, S., Farrell, S., Weiss, H., and P. Lovell, 2498 "Bundle Security Protocol Specification", RFC 6257, May 2499 2011. 2501 [tolerance] 2502 Birrane, E., Burleigh, S., and V. Cerf, "Defining 2503 Tolerance: Impacts of Delay and Didruption when Managing 2504 Challenged Networks", 2001. 2506 Authors' Addresses 2508 Edward J. Birrane 2509 Johns Hopkins Applied Physics Laboratory 2511 Email: Edward.Birrane@jhuapl.edu 2512 Vignesh Ramachandran 2513 Johns Hopkins Applied Physics Laboratory 2515 Email: Vinny.Ramachandran@jhuapl.edu