idnits 2.17.1 draft-quittek-rtfm-generic-interface-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. == 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: ---------------------------------------------------------------------------- == Line 457 has weird spacing: '...inds of wildc...' == Line 459 has weird spacing: '...packets diffe...' == Line 461 has weird spacing: '... each occur...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (13 October 2000) is 8589 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC-SRL' is mentioned on line 287, but not defined == Missing Reference: '-32' is mentioned on line 465, but not defined -- Looks like a reference, but probably isn't: '32' on line 465 == Unused Reference: 'RTFM-SRL' is defined on line 754, but no explicit reference was found in the text == Unused Reference: 'RTFM-MIB' is defined on line 758, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 2722 (ref. 'RTFM-ARC') ** Downref: Normative reference to an Informational RFC: RFC 2723 (ref. 'RTFM-SRL') ** Downref: Normative reference to an Experimental RFC: RFC 2724 (ref. 'RTFM-NEW') ** Downref: Normative reference to an Informational RFC: RFC 2753 Summary: 8 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft J. Quittek 3 NEC Europe Ltd. 4 Expires: April 2001 5 M. Pias 6 University College London 8 13 October 2000 10 A high-level application-oriented interface 11 to the traffic flow measurement architecture 13 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that other 22 groups may also distribute working documents as Internet-Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 Abstract 37 This memo specifies a high-level application-oriented interface to 38 the Realtime Traffic Flow Measurement (RTFM) Architecture. The 39 abstract interface models the RTFM architecture while hiding many of 40 the details not relevant to an application programmer who want to 41 integrate IP traffic measurements into an application. Particularly 42 the interaction between manager, reader, and meter is hidden by the 43 interface, and rule sets used for traffic measurement specification 44 are replaced by simpler data structures. Furthermore, the RTFM 45 interface supports complex actions like modifying a traffic 46 measurement specification while it is already being applied. The 47 interface is defined in an abstract way. It can be implemented by an 48 application programming interface as well as by a network protocol. 50 Table of Contents 52 1. Introduction 53 2. RTFM Interface Overview 54 2.1. Motivation 55 2.1.1. Scenario 1: Accounting and Charging for QoS 56 2.1.2. Scenario 2: Policy-based Network Management 57 2.2. Requirements 58 2.3. Applications and the RTFM Arch Integration 59 2.4. Declarative Flow Model 60 3. Notation of the API Specification 61 4. API Specification 62 4.1. FlowDescription 63 4.2. FlowAttribute 64 4.3. Manager 65 4.4. Reader 66 4.5. Meter 67 5. Required Extensions 68 6. Security Considerations 69 7. Acknowledgments 70 8. References 71 9. Authors' Addresses 72 Appendix A: C mapping of API specification 73 Appendix B: Java mapping of API specification 75 1. Introduction 77 This memo specifies an experimental application programming interface 78 (API) to the Realtime Traffic Flow Measurement (RTFM) Architecture 79 [RTFM-ARC]. 81 This memo uses terminology from the RTFM architecture document [RTFM- 82 ARC] and the description of new attributes for traffic flow 83 measurements [RTFM-NEW] 85 Comments should be made directly to the RTFM mailing list at 86 rtfm@auckland.ac.nz. 88 2. RTFM interface overview 90 The need for a high-level interface to the RTFM architecture arose 91 independently in different projects relying on traffic flow 92 measurements. For these projects it appeared to be advantageous to 93 access components of the RTFM architecture, namely managers, meters, 94 and readers, via an abstract interface hiding many of the components' 95 details. 97 In particular, several details concerning the overhead required for 98 coordination of managers, meters and readers, and details concerning 99 the specification of flows by rule sets appeared to be not relevant 100 for the applications and have been hidden by the interface. 102 The attempt made by this memo is to unify different interfaces to the 103 RTFM architecture, which have been developed so far. The unified 104 iterfaces aims to be generic in order to cover any application 105 willing to use the RTFM architecture. 107 The RTFM interface is defined in a way that it can be implemented as 108 an application programming interface (API) as well as a network 109 protocol. Appendices A and B define mappings of the RTFM interface 110 to a C API and to a Java API, respectively. A network protocol 111 implementing the interface is not defined by this memo. 113 2.1. Motivation 115 The motivation for the RTFM interface is illustrated by two 116 application scenarios. The first one deals with accounting and 117 charging for QoS. The subject of the second scenario is policy-based 118 network management. 120 2.1.1. Scenario 1: Accounting and Charging for QoS 122 In the scenario illustrated by Figure 1, a service provider 123 multicasts tariff objects to all accounting modules for his customers 124 customers (1). Once a customer accounting module has received a 125 tariff, it loads dynamically a module called Tariff Translator (TT) 126 in order to perform a translation to appropriate Meter Policies (MP) 127 (2,3). Thus, the MP is a set of ECA (Event-Condition-Action) generic 128 policies derived from the tariff. It specifies 129 explicitly/implicitly accounting/metering requirements. After that, 130 the MP is transformed to Meter specific control and uploaded into a 131 Meter (4). For the RTFM architecture, the meter control is a rule set 132 as described in [RTFM-ARC]. 134 +----------------+ 135 | RTFM Meter | 136 +----------------+ 137 5.Data ^ ^ 138 (Pull Mode) | | 4. Control (Ruleset) 139 v | / 140 +------------+ 2.Tariff +-----------+ / ..... 141 +------| Customer A |--------->| Tariff | \ / ...... 142 | +------------+ | Translator| \/ 143 | 6.Data / ^ +-----------+ \ / 144 | (unicast) / | 3.Meter Policies | \/ 145 | / +-------------------+ / 146 v / / 147 +--------+ / 1. Tariff Multicast / 148 |Provider|----------------------------------------------------------- 149 +--------+ \ \ 150 \ \ 151 \ /\ 152 \ / \/ 153 \ \ 154 +------------+ Tariff +-----------+ . . . 155 +--------------| Customer B |-------->| Tariff | . . . 156 | +------------+ | Translator| 157 | ^ ^ +-----------+ 158 | Control | Data | | 159 | (Meter "x" | (Push +------------------+ 160 | specific) | Mode) Meter Policies 161 | +----------------+ 162 +--------->| Meter "x" | 163 +----------------+ 165 Figure 1: QoS Charging Scenario 167 The Provider/Customer collect the accounting data from Meters either 168 using one of the following modes (5): 170 (a) Pull Mode or Proactive: a Reader polls the meter periodically 171 in order to gather metered data, usually through a 172 request/reply mechanism. 174 (b) Push Mode or Reactive: a Meter pushes out data to a set of 175 Readers/Collectors registered as listeners when a pre-defined 176 event occurs. We have identified so far some categories of 177 events as follows: 178 - packet-related (e.g. set of packets arrival), 179 - temporal (e.g. clock timeout), 180 - protocol-related (specific TCP stream)... 182 Finally, the bill is generated using the logic within the Tariff. The 183 translation performed in steps 2,3 has derived the accounting 184 requirements. Therefore, the collected data from the meters is one 185 form of input to calculate the usage charge. Other inputs might be 186 derived from the marketing and business strategies of the service 187 provider. 189 Each customer accounting module makes use of an API in order to cope 190 with configuration and data collection. All the logic of those both 191 processes are encapsulated by the implementation of two partial 192 interfaces which composes this API. One for control and another for 193 data. 195 The interface defines an abstract programming model for the RTFM 196 architecture, which hides several details not easy understandable by 197 application programmers. An implementation of the interface 198 establishes an abstraction layer between the application and the RTFM 199 architecture. 201 +------------------------------+ 202 | Application | 203 +------------------------------+ 204 ^ ^ 205 | Control | Data 206 | (Meter | (Pull or Push mode) 207 v Policies) v 208 +------------------------------+ 209 | RTFM interface | 210 +------------------------------+ 211 ^ ^ 212 | Control | Data 213 | (ruleset) | (Pull mode) 214 v v 215 +------------------------------+ 216 | RTFM Architecture | 217 +------------------------------+ 219 Figure 2: RTFM Interface Abstraction Layer 221 2.1.2. Scenario 2: Policy-based Network Management 223 Subject of the second scenario is policy-based network management. 224 Core components of a policy-based network management system are 225 policy decision points (PDPs) and policy enforcement points (PEPs) 226 [RFC2753]. 228 ________________ Policy server 229 | | _____ 230 | Network Node | | |-------------> 231 | _____ | | | May use LDAP,SNMP,... for accessing 232 | | | | | | policy database, authentication,etc. 233 | | PEP |<-----|----->| PDP |-------------> 234 | |_____| | |_____| 235 | | | May monitor the network 236 |________________| <-----+----------------> 238 Figure 3: Policy Server Scenario 240 The PEP is located at a network node and enforces policy decision 241 made by the PDP. Decisions of the PDP are based on policy rules 242 stored at policy databases and on the current state of the managed 243 network. Policy decisions may be triggered by requests of a PEP, by 244 user interaction, or by other events in the monitored network. 246 This includes two cases where traffic measurement functionality is 247 required: 249 (a) A policy may depend on current traffic information, e.g. the 250 the decision on whether a user is allowed to open a new 251 connection may depend on the traffic volume he already 252 produced. In this case, the policy server must be able to 253 retrieve accounting information for that particular user. 255 The requirement of the PDP application is similar to mode (a) 256 in the first scenario. Loading a policy depending on 257 transferred data volume from the policy database corresponds 258 to the Tariff multicast. After parsing the policy, the PDP 259 must initiate traffic measurements for all users affected the 260 policy, in order to have measured data available when needed. 261 Therefore it configures one or more traffic meters. When a 262 decision has to be made, the PDP collects traffic data in pull 263 mode. 265 (b) The second case corresponds to case (b) in the first scenario. 266 A policy decision of the PDP, e.g. to reconfigure resource 267 reservations, is triggered by traffic events, e.g. if the 268 bandwidth or volume of a particular user exceeds a given 269 limit. 271 In this case, the PDP receives traffic information in push 272 mode. An active entity monitoring traffic must notify the PDP. 274 Also for this scenario an interface establishing an abstract layer 275 between the application (the PDP) and the RTFM architecture appears 276 to be desirable. As in the first scenario, the interface hides 277 details of traffic measurements, and offers functions for control and 278 push/pull data transfer. 280 2.2. Applications and the RTFM Architecture Integration 282 In a general view, there exist two kinds of applications using the 283 RTFM architecture: 285 (a) Plain (standalone) traffic measurement: this kind of 286 applications is well supported by the architecture. The rule 287 sets are created manually or with SRL [RFC-SRL] to be uploaded 288 into the Meter. The metered data is collected by the Readers 289 and stored (e.g. in a file) for further processing. 291 (b) Applications with integrated traffic measurement: envisaged 292 by the applications described in section 1.1. This kind of 293 applications require to generate rulesets automatically and to 294 gather traffic measurement data for immediate processing. The 295 support by the RTFM architecture for this kind is not 296 sufficient. Therefore, we understand that using a library is 297 the suitable approach for the integration of application and 298 RTFM architecture. 300 2.3. Requirements 302 The following requirements were identified and are addressed in this 303 document: 305 (a) Applications should be able to control traffic measurements 306 at a high level of abstraction from the RTFM architecture. 307 The level of abstraction should be as high as possible, but at 308 the same time it should be as low as necessary for providing 309 sufficient functionality. 311 (b) Applications should be able to gather measured traffic data 312 in pull and push mode at a high level of abstraction. Again, 313 the level of abstraction should be as high as possible and as 314 low as necessary. 316 (c) The functionality provided at the interface should be 317 sufficiently generic to support different kinds of traffic 318 measurement applications including Accounting and Charging, 319 QoS monitoring as well as plain traffic measurement 320 applications. 322 2.4. Declarative Flow Model 323 One issue arising from requirement (a) of section 1.3 is the 324 specification of flows to be measured. Controlling traffic 325 measurements includes specify the flows to be measured. 327 A specification by rulesets as defined by the RTFM architecture is 328 rather complicated and error-prone, because it is a procedural 329 specification. Rulesets are sequences of instructions to be executed 330 by the pattern matching engine within the meter. A flow is specified 331 by the set of all results of the execution of this procedure for all 332 possible packet headers passing the meter. 334 This is not well suited for an application, that would have to 335 generate rulesets automatically. For the RTFM interface specified by 336 this memo, a declarative specification of flows have been chosen. A 337 flows specification consists of a list of attribute constraints which 338 may be exact, wild-carded or generic. The latter one may generate 339 more than one flow table entry out of a single flow description. 341 Implementations of the RTFM interface have to provide the 342 functionality of translating declarative flow specifications to 343 procedural rulesets. 345 2.5. Modifying Active Traffic Measurements 347 To be done. 349 3. Notation of the API Specification 351 The interface specification is open to be implemented as API or as 352 network protocol. Procedural API implementations, e.g. in C, are 353 supported as well as object-oriented implementations. Therefore, we 354 define data structures separated from functions on these data 355 structures, supporting non-object-oriented approaches. However, we 356 group data structures and functions in a way that reflects the 357 grouping of attributes and methods by classes in object-oriented 358 approaches. An object-oriented application is should define a class 359 for each group (FlowDescription, FlowAttribute, Manager, Reader, 360 Meter). 362 How this specification can be mapped to implementations in 363 programming languages is illustrated by appendices A and B. Appendix 364 A shows a mapping of the API Specification to C data structures and 365 function declarations, Appendix B contains a mapping to Java 366 interfaces. Implementation of the interface by a network protocol is 367 not discussed further in this document. 369 The specification of each groups contains two sections: Data 370 Structure and Functions. In the first section, the data structure(s) 371 of this group is described as a list of fields. For each field, a 372 name and a type are specified. The semantics of each field is 373 explained. If a field is defined as a data structure of another 374 group, the name of that particular group is used to specify the 375 field's type. Applications using the API may read and set fields of 376 the data structure, and pass and receive the data structure to or 377 from function calls. 379 In the second section all functions on the data structure are listed 380 and described. The description includes parameters passed to the 381 functions, return values and the functions' semantics. In order to 382 comply with object-oriented paradigms, fields of a data structure may 383 be modified only by functions belonging to the same group as the data 384 structure. However, data structures may be passed to and returned by 385 any function. 387 The definitions use some basic data types: IPAddressType, 388 SignedIntegerX and UnsignedIntegerX with X=8 or X=16. These types 389 have to be defined more precisely by a mapping of the abstract 390 specification in this document to an API or a network protocol. The 391 IPAddressType may also be different for IPv4 and IPv6 392 implementations. 394 4. RTFM Interface Specification 396 The RTFM interface consists of six groups, FlowDescription, 397 FlowAttribute, Manager, Reader, and Meter. Each group contains a data 398 structure and a set of functions on these data structures. For 399 FlowDescription and FlowAttribute the data structures are the more 400 relevant part, while for Manager, Reader, and Meter the offered 401 functions are of more importance. 403 The FlowDescription data structure serves to specify a single flow or 404 a set of different flows to be metered. The FlowAttribute data 405 structure serves to describe a single attribute of a flow by type and 406 value. Within the interface definition, mostly sets of FlowAttribute 407 data structures are used. The FlowData The groups Manager, Reader, 408 and Meter model well known components of the RTFM architecture. 410 4.1. FlowDescription 412 Instances of the FlowDescription data structure serve to specify a 413 single flow or a set of different flows. Different to rule sets, the 414 specification is declarative and not procedural. 416 A FlowDescription leaves much less choices of specifying a flow than 417 rule sets do, but the reduction of flexibility comes in line with an 418 increase of simplicity. Still, the remaining flexibility is expected 419 to be sufficient for most of the applications requiring traffic flow 420 measurements. 422 An implementation of the interface has to translate the 423 FlowDescription data structure (and further input) into RTFM rule 424 sets 426 4.1.1. Data Structure 428 The FlowDescription data structure specifies a flow by nine fields: 430 +----------------------+-----------------------+ 431 | Name | Type | 432 +----------------------+-----------------------+ 433 | sourceIPAddress | IPAddressType | 434 | destinationIPAddress | IPAddressType | 435 | sourceIPMask | SignedInteger8 | 436 | destinationIPMask | SignedInteger8 | 437 | transportType | UnsignedInteger8 | 438 | sourcePort | UnsignedInteger8 | 439 | destinationPort | UnsignedInteger8 | 440 | direction | UnsignedInteger8 | 441 | futherAttributeSet | Set of FlowAtteribute | 442 +----------------------+-----------------------+ 444 4.1.1.1 sourceIPAddress and destIPAddress 446 The sourceIPAddress field and the destinationIPAddress field both 447 have the type of an IP address. This may be different for IPv4 and 448 IPv6 networks. The fields define which source and destination IP 449 addresses must be contained in a packet, if it is assigned to the 450 specified flow(s). How many bits of sourceIPMask and 451 destinationIPMask are relevant is specified by sourceIPMask and 452 destinationIPMask. 454 4.1.1.2 sourceIPMask and destinationIPMask 456 For the IP addresses, these masks specify which bits of the address 457 are wildcards. There are two kinds of wildcards: distinctive and 458 non-distinctive. If wildcards are specified as non-distinctive, all 459 packets differing in just these wildcards are counted in the same 460 account. For distinctive wildcards, a new account is generated for 461 each occurring bit pattern matching the wildcard. 463 The sourceIPMask field and the destinationIPMask field specify the 464 number of wildcard bits in the respective IP address starting with 465 the least significant bit. The range of this field is [-32,32]. 0 466 means no wildcards, i.e. the respective IP address must be matched 467 exactly. 32 or -32 are complete wildcards, i.e. any address matches. 468 Positive bit numbers are used for non-distinctive wildcards, negative 469 numbers for distinctive ones. 471 As an example we take the IP address 134.45.123.56. If the 472 corresponding mask has a value of 16, then all IP addresses 473 134.45.X.Y match and are assigned to the same flow. If the mask value 474 is -8, then all addresses 134.45.123.X match, but each occurring 475 value of X, is assigned to a different flow. 477 4.1.1.3 transportType 479 This field specifies the value of the transport type, an IP packet 480 must contain in order to be assigned to the specified flow(s). Only 481 the following predefined values are valid for this field: 483 0 - any transport type matches (non-distinctive) 484 1 - TCP or UDP matches (non-distinctive) 485 2 - only TCP matches 486 3 - only UDP matches 487 4 - only ICMP matches 488 5 - only IGMP matches 490 4.1.1.4 sourcePort and destinationPort 492 The sourcePort and destinationPort fields specify which respective 493 port number an IP packet must contain in order to be assigned to the 494 specified flow(s). A value of 0 is used as a non-distinctive wildcard 495 matching any port number. These fields are only considered, when the 496 transport type of the IP packet is TCP or UDP. 498 4.1.1.5 direction 500 This fields serves to distinguish directed an undirected flows. It 501 has 4 valid values: 503 0 - direction independent (non-distinctive) 504 As described as the default case in [RTFM-ARC], a value of 0 505 indicates, that packets either matching the forward direction 506 or the backward direction are assigned to the same flow(s). 508 1 - forward direction 509 A value of 1 indicates that only packets matching exactly the 510 specified source and destination are to be assigned to the 511 specified flow(s). 513 2 - backward direction 514 A value of 2 indicates that only packets matching the backward 515 direction, i.e. the specified source matches the packet's 516 destination and the specified destination matches the packet's 517 source, are to be assigned to the specified flow(s). 519 3 - direction dependent (distinctive) 520 A value of 3 indicates, that packets matching the forward 521 direction and packets matching the backward direction are 522 assigned to different flows. 524 4.1.1.6 futherAttributeSet 526 This field contains a set of FlowAttribute. The set may be 527 implemented as an array or list or other container. Alternatively, 528 the field may just be a reference to a set of FlowAttribute. 530 The set may be empty. In this case it has no influence on the 531 assignment of packets to flows. If it is non-empty, each element of 532 the list has to be matched exactly by an IP packet, if it is assigned 533 to the specified flow(s). 535 The set must not contain COUNT attributes. 537 4.1.2. Functions 539 The functions on the FlowDescription data structure are restricted to 540 get and set functions. For each field xxxXxxx there exists two 541 functions getXxxXxxx() and setXxxXxxx(), e.g. getSourceIPAddress() 542 and setSourceIPAddress(). Function getXxxXxxx() takes no argument and 543 returns a value of the respective type, function setXxxXxxx() takes a 544 parameter of the respective type and returns nothing. 546 4.2. FlowAttribute 548 A FlowAttribute is a simple pair of an attribute type and an 549 attribute value. 551 4.2.1. Data Structure 553 +----------------------+-----------------------------+ 554 | Name | Type | 555 +----------------------+-----------------------------+ 556 | attributeType | UnsignedInteger8 | 557 | attributeValue | (depends on attribute type) | 558 +----------------------+-----------------------------+ 560 4.2.1.1 attributeType 562 The attributeType field contains a number indicating the type of the 563 attribute. Valid numbers for this field are defined by [RTFM-ARC] and 564 [RTFM-NEW]. 566 4.2.1.2 AttributeValue 568 This field contains the value of the attribute. Its type depends on 569 the attribute type. 571 4.2.2. Functions 573 The funtions on the FlowDescription data structure are restricted to 574 get and set functions. For each field xxxXxxx there exists two 575 functions getXxxXxxx() and setXxxXxxx(), e.g. getAttributeType() and 576 setAttributeType(). Function getXxxXxxx() takes no argument and 577 returns a value of the respective type, function setXxxXxxx() takes a 578 parameter of the respective type and returns nothing. 580 4.3. Manager 582 The Manager provides functionality of an RTFM manager as specified in 583 [RTFM-ARC]. However, most of its functionality is hidden by the 584 interface, although the implementation must provide it. 586 4.3.1. Data Structure 588 To be done, may be empty. 590 4.3.2. Functions 592 So far there is only one function defined. Further ones need to be 593 added. 595 4.3.2.1. measureFlow() 597 Parameters 598 name: flowDescription 599 type: FlowDescription 600 desc: Specification of the flow to be measured 602 name: flowAttributes 603 type: Set of FlowAttribute 604 desc: List of Attributes to be measured. 605 Here, just the attribute types are of interest. 606 Attribute values in this list are ignored. 608 name: meter 609 type: Meter 610 desc: The meter to be used for measurements 611 name: firstTimeInterpretation 612 type: UnsignedInteger8 613 desc: Interpretation of the start time timestamp of a flow 615 name: collectTimeInterval 616 type: UnsignedInteger16 617 desc: The readers interval of collecting flow data given in seconds 619 The function's result is of type Reader. 621 The function translates the passed FlowDescription into an RTFM rule 622 set. Parameter flowAttributes specifies which attributes of the flow 623 are to be measured. Only the attribute types are of this list of 624 attributes are processed. Attribute values within parameter 625 flowAttributes are ignored. 627 The rule set is installed at the specified Meter and the Reader which 628 is returned as result is configured to collect data from the Meter 629 regularly. After the function is completed, the user of the interface 630 may read measured flow data from the returned Reader. An invalid 631 (null) Reader is returned, if the function failed. 633 The interpretation of a flows start time can be modified by parameter 634 startTimeInterpretation. Three valid values are defined for this 635 parameter: 636 0 - ABSOLUTE: start time corresponds to the definition of 637 attribute FirstTime in [RTFM-ARC]. 638 1 - RELATIVE: start time is equal to the time at which this 639 function is called. 640 2 - RELATIVE_INCREMENTAL: start ime is equal to the last time, 641 flow data has been read. The initial value of FirstTime is the 642 time at which this function is called. 644 To be done: description of collectTimeInterval 646 The following example illustrates the difference between the three 647 possible ways for interpreting the FirstTime attribute. 649 +-------------------------------------+ 650 | Packets received from host X | 651 +-------------------------+----------+----------+---------------+ 652 | Timestamp | ABSOLUTE | RELATIVE | RELATIVE_INCR | 653 +-------------------------+----------+----------+---------------+ 654 | t1. 2000-01-13 17:00:00 | 300 | | | 655 | | | | | 656 | t2. 2000-01-13 17:30:00 | 350 | 0 | 0 | 657 | | | | | 658 | t3. 2000-01-13 18:00:00 | 500 | 150 | 150 | 659 | | | | | 660 | t4. 2000-01-13 18:30:00 | 515 | 165 | 15 | 661 | | | | | 662 | t5. 2000-01-13 19:00:00 | 670 | 320 | 155 | 663 | ....... | ... | ... | ... | 664 | ....... | ... | ... | ... | 665 +-------------------------+----------+----------+---------------+ 667 4.4. Reader group 669 4.4.1. Data Structure 671 4.4.2. Functions 673 This section needs to be elaborated. 675 4.4.2.2. getFlowDesc() 677 4.4.2.3. readFlowData() 679 4.4.2.4. installFlowDataListener() 681 Add this Reader as a new FlowData Listener in the the list of 682 Listeners. 684 4.4.2.5. deleteFlowDataListener() 686 Delete this Reader from the list of Listeners. 688 4.5 Meter 690 The Meter data structure and functions serve just to identify a real 691 meter. The functions do not give access to metering functionality. 692 Meter data structures are passed to Managers and readers for 693 specifying which Meter to manage or read. 695 4.5.1 Data Structure 696 +-----------+------------------+ 697 | Name | Type | 698 +-----------+------------------+ 699 | host | IPAddressType | 700 | port | UnsignedInteger8 | 701 | community | String | 702 +-----------+------------------+ 704 4.5.1.1. host 706 The host field specifies the IP address at which the Meter can be 707 contacted. 709 4.5.1.2. port 711 The UDP port at which the Meter can be contacted at the host. 713 4.5.1.3. community 715 The community string which is required to access the Meter. 717 4.5.2. Functions 719 The funtions on the FlowDescription data structure are restricted to 720 get and set functions. For each field xxxx there exists two functions 721 getXxxx() and setXxxx(), e.g. getHost() and setHost(). Function 722 getXxxx() takes no argument and returns a value of the respective 723 type, function setXxxx() takes a parameter of the respective type and 724 returns nothing. 726 5. Required Extensions 728 To be done: Extensions of the RTFM architecture or the Meter MIB 729 required for the implementation of the RTFM interface. 731 6. Security Considerations 733 This document contains a generic specification of an RTFM interface. 734 To API implementations of the interface the same general security 735 considerations apply than to other libraries for network management 736 applications. API implementation might use network protocols, for 737 example SNMP, for accessing real instances of a Meter. In such a 738 case, the security considerations concerning the particular protocol 739 apply. 741 If the RTFM interface is implemented by a network protocol, several 742 security issues have to be investigated. But this discussion is not 743 subject of this memo. 745 7. Acknowledgments 747 To be done. 749 8. References 751 [RTFM-ARC] Brownlee, N., Mills, C. and Ruth, G., "Traffic Flow 752 Measurement: Architecture", RFC 2722, October 1999. 754 [RTFM-SRL] Brownlee, N., "SRL: A Language for Describing Traffic 755 Flows and Specifying Actions for Flow Groups, RFC 2723, 756 October 1999. 758 [RTFM-MIB] Brownlee, N., "Traffic Flow Measurement: Meter MIB", 759 RFC 2720, October 1999. 761 [RTFM-NEW] Handelman, S., Stibler, S., Brownlee, N. and G. Ruth, 762 "RTFM: New Attributes for Traffic Flow Measurement", RFC 763 2724, October 1999. 765 [RFC2753] R. Yavatkar and D. Pendarakis, R. Guerin, "A Framework 766 for Policy-based Admission Control", RFC 2753, January 767 2000. 769 9. Authors' Addresses 771 Juergen Quittek 772 NEC Europe Ltd. 773 C&C Research Laboratories 774 Adenauerplatz 6 775 69115 Heidelberg 776 Germany 778 Phone: +49 6221 90511-15 779 EMail: quittek@ccrle.nec.de 781 Marcelo Pias 782 University College London (UCL) 783 Department of Computer Science 784 Gower Street 785 London WC1E 6BT 786 UK 788 Phone: +44 171 387 1397 789 EMail: m.pias@cs.ucl.ac.uk 791 Appendix A: C mapping of the RTFM interface specification 792 To be done. 794 Appendix B: Java mapping of the RTFM interface specification 796 To be done.