idnits 2.17.1 draft-ietf-rtfm-ruleset-language-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-18) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 Introduction section. ** The document seems to lack a Security Considerations section. ** 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.) ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 258 has weird spacing: '...decimal e.g. ...' == Line 260 has weird spacing: '...in bits e.g....' -- 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 (September 1998) is 9347 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 664 looks like a reference -- Missing reference section? '2' on line 669 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force Nevil Brownlee 3 INTERNET-DRAFT The University of Auckland 4 March 1998 5 Expires September 1998 7 SRL: A Simple Ruleset Language 9 11 Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its Areas, and 15 its Working Groups. Note that other groups may also distribute working 16 documents as Internet-Drafts. This Internet Draft is a product of the 17 Realtime Traffic Flow Measurement Working Group of the IETF. 19 Internet Drafts are draft documents valid for a maximum of six months. 20 Internet Drafts may be updated, replaced, or obsoleted by other 21 documents at any time. It is not appropriate to use Internet Drafts as 22 reference material or to cite them other than as a "working draft" or 23 "work in progress." 25 To view the entire list of current Internet-Drafts, please check the 26 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 27 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 28 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 29 ftp.isi.edu (US West Coast). 31 Abstract 33 This document describes a language for specifying rulesets, i.e. 34 configuration files which may be loaded into an traffic flow meter so as 35 to determine which traffic flows are measured by the meter, and the 36 information it will store for each flow. Although the language is 37 primarily intended for RTFM traffic flows, it may also be useful in 38 other areas as a general way of specifying flows to be measured or 39 collected. 41 Contents 43 1 Purpose and Scope 3 44 1.1 RTFM Meters and Traffic Flows . . . . . . . . . . . . . . . . 3 45 1.2 SRL Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 47 2 SRL Language Description 4 48 2.1 Define Directive . . . . . . . . . . . . . . . . . . . . . . . 5 50 3 Statement 5 51 3.1 IF_Statement . . . . . . . . . . . . . . . . . . . . . . . . . 6 52 3.1.1 operand_list . . . . . . . . . . . . . . . . . . . . . . . 6 53 3.1.2 operand . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 3.1.3 Test Part . . . . . . . . . . . . . . . . . . . . . . . . 6 55 3.1.4 Action Part . . . . . . . . . . . . . . . . . . . . . . . 7 56 3.2 Imperative_Statement . . . . . . . . . . . . . . . . . . . . . 8 57 3.2.1 GOTO Statement . . . . . . . . . . . . . . . . . . . . . . 8 58 3.2.2 SAVE Statement . . . . . . . . . . . . . . . . . . . . . . 8 59 3.2.3 COUNT Statement . . . . . . . . . . . . . . . . . . . . . 9 60 3.2.4 IGNORE Statement . . . . . . . . . . . . . . . . . . . . . 9 61 3.2.5 NOMATCH Statement . . . . . . . . . . . . . . . . . . . . 9 62 3.2.6 STORE Statement . . . . . . . . . . . . . . . . . . . . . 10 63 3.2.7 RETURN Statement . . . . . . . . . . . . . . . . . . . . . 10 64 3.3 SUBROUTINE_declaration . . . . . . . . . . . . . . . . . . . . 10 65 3.4 CALL_Statement . . . . . . . . . . . . . . . . . . . . . . . . 11 67 4 Example Programs 12 68 4.1 Classify IP Port Numbers . . . . . . . . . . . . . . . . . . . 12 69 4.2 Classify Traffic into Groups of Networks . . . . . . . . . . . 13 71 5 APPENDICES 14 72 5.1 Appendix A: SRL Syntax in BNF . . . . . . . . . . . . . . . . 14 74 6 Acknowledgments 16 76 7 References 16 78 8 Author's Addresses 16 80 1 Purpose and Scope 82 A ruleset for an RTFM Meter is a sequence of instructions to be executed 83 by the meter's Pattern Matching Engine (PME). The form of these 84 instructions is described in detail in RFCs 2063 and 2064 [1], [2], but 85 most users - at least inititially - find them confusing and difficult to 86 write, mainly because the effect of each instruction is strongly 87 dependent on the state of the meter's Packet Matching Engine at the 88 moment of its execution. 90 SRL is a procedural language for creating RTFM rulesets. It has been 91 designed to be simple for people to understand, using statements which 92 help to clarify the execution context in which they operate. SRL 93 programs will be compiled into rulesets, which can then be downloaded to 94 RTFM meters. 96 1.1 RTFM Meters and Traffic Flows 98 The RTFM Architecture [1] defines a set of 'attributes' which apply to 99 network traffic. Among the attributes are 'address attributes,' such as 100 PeerType, PeerAddress, TransType and TransAddress, which have meaning 101 for many protocols, but for IP traffic (PeerType = IP) PeerAddress is an 102 IP address, TransType is TCP, UDP, ICMP, etc., and TransAddress is 103 usually an IP port number. 105 An 'RTFM Traffic Flow' is simply a stream of packets observed by a meter 106 as they pass across a network between two end points (or from a single 107 end point). Each 'end point' of a flow is determined by the set of 108 values of its address attributes. 110 An 'RTFM Meter' is a measuring device - e.g. a program running on a 111 Unix or PC host - which observes passing packets and builds 'Flow Data 112 Records' for the flows of interest. 114 RTFM traffic flows have another important property - they are 115 bi-directional. This means that each flow data record in the meter has 116 two sets of counters, one for packets travelling from source to 117 destination, the other for returning packets. Within the RTFM 118 architecture such counters appear as further attributes of the flow. 120 An RTFM meter must be configured by the user, which means creating a 121 'Ruleset' so as to specify which flows are to be measured, and how much 122 information (i.e. which attributes) should be stored for each of them. 123 A rulset is effectively a program for a minimal virtual machine, the 124 'Packet Matching Engine (PME),' which is described in detail in [1]. 126 In the past creating a ruleset has meant writing machine code for the 127 PME, which has proved rather difficult to do. SRL provides a high-level 128 language which should enable users to create effective rulesets without 129 having to understand the PME in detail. 131 1.2 SRL Overview 133 An SRL program is executed from the beginning for each new packet 134 arriving at the meter. It has two essential goals. 136 (a) Decide whether the current packet is part of a flow which is of 137 interest and if necessary, determine its direction (i.e. decide 138 which of its end-points is considered to be its source). Other 139 flows will be ignored. 141 (b) SAVE whatever information is required to identify the flow and 142 accumulate (COUNT) quantitative information for that flow. 144 At execution, the meter's Packet Matching Engine (PME) begins by using 145 source and destination attributes as they appear 'on the wire.' If the 146 attributes do not match those of a flow to be recorded, the PME will 147 normally execute the program again, this time with the source and 148 destination addresses interchanged. Because of this bi- directional 149 matching, an RTFM meter is able to build up tables of flows with two 150 sets of counters - one for forward packets, the other for backward 151 packets. The programmer can if required suppress the reverse-direction 152 matching and assign 'forward' and 'backward' directions which conform to 153 the conventions of the external context. 155 Goal (a) is achieved using IF statements which perform comparisons on 156 information from the packet or from SRL variables. Goal (b) is achieved 157 using one or more SAVE statements to store the flow's identification 158 attributes; a COUNT statement then increments the statistical data 159 accumulating for it. 161 2 SRL Language Description 163 The SRL language is explained below using 'railway diagrams' to describe 164 the syntax. Flow through a diagram is from left to right. The only 165 exception to this is that lines carrying a left arrow may only be 166 traversed right to left. In the diagrams, keywords are written in 167 capital letters; in practice an SRL compiler will be insensitive to case 168 in keywords. Lower-case identifiers are explained in the text, or they 169 refer to another diagram. 171 Comments may appear on any line of an SRL program, following a #. 173 2.1 Define Directive 175 --- DEFINE -- defname ---- = ---- defined_text ------------------ ; 177 Simple, parameterless, defines are supported, via the syntax above. The 178 define name, defname, is an identifier made up of letters, digits and 179 underscores. The defined text starts after the equal sign, and 180 continues up to (but not including) the closing semicolon. (If a 181 semicolon is required within define text, it must be preceded by a 182 backslash). Whereever defname appears elsewhere in the program, it will 183 be replaced by the defined text. 185 For example, 187 DEFINE telnet = 23; 188 DEFINE smtp = 25; 189 DEFINE http = {80, 8080}; 191 3 Statement 193 ----+-------------+-----+--- IF_statement -------------------+--- ; 194 | | | | 195 +-- label : --+ +--- Imperative_statement -----------+ 196 | | | | 197 +------<------+ +--- Subroutine_declaration ---------+ 198 | | 199 +--- CALL_statement -----------------+ 201 An SRL program is a sequence of SRL statements, each one terminated by a 202 semicolon. There are four kinds of statements, as follows. 204 Each statement may be labelled, i.e. preceded by a sequence of one or 205 more labels. A label may contain letters, digits and underscores 206 followed by a semi-colon. Each statement is executed in sequence, 207 unless one of them performs a GOTO, in which case execution transfers to 208 the statement bearing the given label. 210 Labels are global; each must be unique within an SRL program. 212 3.1 IF_Statement 214 Test Part Action Part 215 ............. ............... 217 --- IF attrib --- = operand_list ------+-------- GOTO label -+--- ; 218 | | 219 +- SAVE , GOTO label -+ 220 | | 221 +- SAVE --------------+ 222 | | 223 +- IGNORE ------------+ 224 | | 225 +- NOMATCH -----------+ 226 | | 227 +- RETURN --+-------+-+ 228 | | 229 +-- n --+ 231 3.1.1 operand_list 233 ------------+-------------- operand -----------------+------------- 234 | | 235 +--- { operand--+---------------+-- } ---+ 236 | | 237 +-- , operand --+ 238 | | 239 +-------<-------+ 241 3.1.2 operand 243 ------------- value ---------+----------------------+-------------- 244 | | 245 +------- / width ------+ 246 | | 247 +------- & mask -------+ 249 3.1.3 Test Part 251 The IF statement takes an RTFM Attribute value (from the packet or from 252 an SRL variable), ANDs it with a mask and compares it with a value. If 253 this test succeeds, the action indicated by the keyword on the right of 254 the diagram is executed. If the test fails, the following statement is 255 executed. 257 Masks may be specified as numbers, 258 dotted decimal e.g. &255.255.0.0 259 or hexadecimal e.g. &FF-FF-00-00 260 or as a width in bits e.g. /16 262 If a mask is not specified, an all-ones mask is used. 264 Values may be specified as dotted decimal,hexadecimal or as a character 265 constant (enclosed in apostrophes). 267 In SRL a value is always combined with a mask; this combination is 268 referred to as an operand.For example, if we were interested in flows 269 originating from IP network 130.216, we might write: 271 IF SourcePeerAddress = 130.216.0.0 & 255.255.0.0 272 GOTO my_network; 274 or equivalently 276 IF SourcePeerAddress = 130.216/16 GOTO my_network; 278 A list of values enclosed in braces may also be specified; the test 279 succeeds if the masked attribute equals any of the values in the list. 280 For example 282 IF SourcePeerAddress = { 130.216.7/24, 130.216.34/24 } 283 GOTO special_network; 285 As this last example indicates, values are right-padded with zeroes, 286 i.e. the given numbers specify the leading bytes of masks and values. 288 3.1.4 Action Part 290 A SAVE action saves attribute, mask and value as given in the statement. 291 If the statement has a value_list, the value saved is the value which the 292 packet actually matched. See below for further description of SAVE 293 statements. 295 Other actions are described in detail under "Imperative statements" 296 below. Note that the RETURN action is valid only within subroutines. 298 3.2 Imperative_Statement 300 --+------------------------------------------- GOTO label ----+-- ; 301 | | 302 +-- SAVE attrib --+--+-----------+--+---+----------------+--+ 303 | | | | | | | | 304 | | +- / width -+ | +- , GOTO label -+ | 305 | | | | | | 306 | | +- & mask --+ | | 307 | | | | 308 | +--- = operand ---+ | 309 | | 310 +-- COUNT --------------------------------------------------+ 311 | | 312 +-- IGNORE -------------------------------------------------+ 313 | | 314 +-- NOMATCH ------------------------------------------------+ 315 | | 316 +-- RETURN --+-------+--------------------------------------+ 317 | | | | 318 | +-- n --+ | 319 | | 320 +-- STORE variable := value ------------+----------------+--+ 321 | | 322 +- , GOTO label -+ 324 3.2.1 GOTO Statement 326 The GOTO statement (either on its own or as the last part of a larger 327 statement) specifies the label of the statement to be executed next. 329 3.2.2 SAVE Statement 331 The SAVE statement saves information which will (later) identify the 332 flow in the meter's flow table. It does not actually record anything in 333 the table; this is done when a subsequent COUNT statement executes. 335 SAVE has two possible forms: 337 SAVE attrib = operand 338 saves the attribute, mask and value as given in the statement. 339 This form of the SAVE statement is similar to that allowed 340 in an IF statement, except that - since imperative statements 341 do not perform a test - you may save an arbitrary value. 343 SAVE attrib 344 SAVE attrib / width 345 SAVE attrib & mask 346 saves the attribute and mask from the statement, and the 347 value resulting from their application to the current packet. 348 This is most useful when used to save a value with a wider 349 mask than than was used to select the packet. For example 351 IF DestPeerAddress = 130.216/16 352 NOMATCH; 353 IF SourcePeerAddress = 130.216/16 354 GOTO my_network; 355 IGNORE; # Executes only if preceding 356 # IF statements both fail. 357 my_network: SAVE SourcePeerAddress /24; 358 COUNT; 360 3.2.3 COUNT Statement 362 The COUNT statement appears after all testing and saving is complete; it 363 instructs the PME to build the flow identifier from the attributes which 364 have been Saved, find it in the meter's flow table (creating a new entry 365 if this is the first packet observed for the flow), and increment its 366 counters. The meter then moves on to examine the next incoming packet. 368 3.2.4 IGNORE Statement 370 The IGNORE statement terminates examination of the current packet 371 without saving any information from it; the meter moves on to examine 372 the next incoming packet, beginning again at the first statement of its 373 program. 375 3.2.5 NOMATCH Statement 377 The NOMATCH statement indicates that matching has failed for this 378 execution of the program (i.e. this packet). If it is executed when a 379 packet is being processed with its addresses in 'on the wire' order, the 380 PME will perform the program again from the beginning with source and 381 destination addresses interchanged. If it is executed following such an 382 interchange, the packet will be ignored. NOMATCH is illustrated in the 383 above example, where it is used to ensure that flows having 130.216/16 384 as an end-point are counted as though 130.216 had been their source peer 385 (IP) address. 387 3.2.6 STORE Statement 389 The STORE statement assigns a value to an SRL variable and SAVEs it. 390 There are six SRL variables: 392 SourceClass SourceKind 393 DestClass DestKind 394 FlowClass FlowKind 396 Their names have no particular significance; they were arbitrarily 397 chosen as likely RTFM attributes but can be used to store any integer 398 values. Their values are set to zero each time examination of a new 399 packet begins. 401 3.2.7 RETURN Statement 403 The RETURN statement is used to return from subroutines and can be used 404 only within the context of a subroutine. It is described in detail 405 below (CALL statement). 407 3.3 SUBROUTINE_declaration 409 -- SUBROUTINE subname ( -+--+---ADDRESS ----pname---+--+- ) --> 410 | | | | 411 | +-- VARIABLE -- pname --+ | 412 | | | | 413 | +------<------- , ------+ | 414 | | 415 +-----------------------------+ 417 >------+--- Imperative_statement ---+----- ENDSUB -------- ; 418 | | 419 +----IF_statement -----------+ 420 | | 421 +----CALL_statement ---------+ 422 | | 423 +-------------<--------------+ 425 A Subroutine declaration has three parts: 427 the Name is like a label, it may have letters, digits 428 and underscores. 430 the Parameter list specifies the subroutine's parameters. 431 Each parameter is preceded with a keyword indicating its 432 type - VARIABLE indicates an SRL variable (see the STORE 433 statement above), ADDRESS indicates any other RTFM attribute. 434 The parameter name (pname in the diagram) must be the name of 435 a meter 'parameter' variable, i.e. P1, P2, P3, P4 or P5. 436 The meter implements these as global variables, which means 437 that the SRL programmer must be careful to avoid conflicts 438 when calling one subroutine from another. 440 the Body specifies what processing the subroutine will perform. 441 This is simply a sequence of Imperative, IF and CALL statements, 442 terminated by the ENDSUB keyword. 444 3.4 CALL_Statement 446 --- CALL subname ( -+--+-- parameter --+--+- ) --> 447 | | | | 448 | +---<---- , ----+ | 449 | | 450 +---------------------+ 452 >---+--- n: Imperative_statement ---+---- ENDCALL -------- ; 453 | | 454 +---------------<---------------+ 456 The CALL statement invokes an SRL subroutine. The parameters are SRL 457 variables or other RTFM attributes, and their types must match those in 458 the subroutine declaration. Following the parameters is a sequence of 459 statements, each preceded by an integer label. These labels will 460 normally be 1:, 2:, 3:, etc, but they do not have to be contiguous. 461 They are referred to in RETURN statements. 463 e.g. RETURN 2; would return to the statement labelled 2: 464 in the subroutine call. 466 If this statement does not execute a GOTO, execution 467 will then continue with the first statement after ENDCALL. 469 If the return statement does not specify a return label, the first 470 statement executed after RETURN will be the statement immediately 471 following ENDCALL. 473 4 Example Programs 475 4.1 Classify IP Port Numbers 477 # SRL program to classify IP port numbers 478 # 479 IF SourcePeerType = IP SAVE, GOTO IP_pkt; 480 IGNORE; # Not an IP packet 481 # 482 IP_pkt: 483 IF SourceTransType = { tcp, udp } SAVE, GOTO tcp_udp; 484 GOTO fin; # Not tcp or udp (probably doesn't have ports) 485 # 486 tcp_udp: 487 IF SourceTransAddress = { www, ftp, telnet } NOMATCH; 488 # 489 IF DestTransAddress = www GOTO c_www; 490 IF DestTransAddress = ftp GOTO c_ftp; 491 IF DestTransAddress = telnet GOTO c_telnet; 492 # 493 GOTO fin; # Count as 'unknown' 494 # 495 c_www: 496 STORE FlowKind := 'W', GOTO fin; 497 c_ftp: 498 STORE FlowKind := 'F', GOTO fin; 499 c_telnet: 500 STORE FlowKind := 'T', GOTO fin; 501 # 502 fin: 503 SAVE SourcePeerAddress /32; 504 SAVE DestPeerAddress /32; 505 COUNT; 507 This program counts only IP packets, saving SourceTransType (tcp, udp or 508 0), Source- and DestPeerAddress (32-bit IP addresses) and FlowKind ('W' 509 for www, 'F' for ftp, 'T' for telnet, 0 for inclassified). The program 510 uses NOMATCH actions to specify the packet direction - its resulting 511 flows will have the well-known ports as their destination. 513 4.2 Classify Traffic into Groups of Networks 515 # SRL program to classify traffic into network groups 516 # 517 CALL net_kind (SourcePeerAddress, SourceKind) 518 ENDCALL; 519 CALL net_kind (DestPeerAddress, DestKind) 520 ENDCALL; 521 COUNT; 522 # 523 SUBROUTINE net_kind (ADDRESS p1, VARIABLE p2) 524 IF p1 = 130.216/16 525 SAVE, GOTO nk_mysite; 526 IF p1 = { 130.217/16, 130.123/16, 130.195/16, 527 132.181/16, 138.75/16, 139.80/16 } 528 SAVE, GOTO nk_mynetwork; 529 SAVE p1 /24; # Not my site or my network 530 STORE p2 := 30; RETURN 3; 531 nk_mysite: 532 STORE p2 := 10; RETURN 1; 533 nk_mynetwork: 534 STORE p2 := 20; RETURN 2; 535 ENDSUB; 537 The net_kind subroutine determines whether p1 is my network (130.216), 538 one of the networks in my network (one of the networks in the list), or 539 some other network. It saves the network address from p1 (16 bits for 540 my site and my network, 24 bits for others), stores a value of 10, 20 or 541 30 in p2, and returns to 1:, 2: or 3:. 543 net_kind is called twice, saving Source- and DestPeerAddress and Source- 544 and DestKind; the COUNT statement produces flows identified by these 545 four RTFM attributes, with no particular source-dest ordering. 547 In the program no use is made of return numbers amd they could have been 548 omitted. However, we might wish to re-use the subroutine in another 549 program doing different things for different return numbers, as in the 550 version below. 552 CALL net_kind (DestPeerAddress, DestKind) 553 1: NOMATCH; 554 ENDCALL; 555 CALL net_kind (SourcePeerAddress, SourceKind) 556 1: COUNT; # site -> network or other 557 ENDCALL; 558 SAVE SourcePeerAddress /24; 559 SAVE DestPeerAddress /24; 560 COUNT; 562 This version uses a NOMATCH statement to ensure that site -> network or 563 other flows have site as their source. The NOMATCH also rejects site -> 564 site traffic. Traffic which doesn't have site as source or destination 565 saves 24 bits of its addresses (the subroutine might only have saved 16) 566 before counting such an unusual flow. 568 5 APPENDICES 570 5.1 Appendix A: SRL Syntax in BNF 572 ::= | 574 ::=