idnits 2.17.1 draft-ietf-rtfm-ruleset-language-06.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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 2) being 95 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 22 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 327 has weird spacing: '...decimal e.g. ...' == Line 329 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 (December 1999) is 8892 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) ** Obsolete normative reference: RFC 2063 (ref. '1') (Obsoleted by RFC 2722) ** Obsolete normative reference: RFC 2064 (ref. '2') (Obsoleted by RFC 2720) -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 1700 (ref. '4') (Obsoleted by RFC 3232) ** Obsolete normative reference: RFC 2373 (ref. '5') (Obsoleted by RFC 3513) Summary: 8 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force Nevil Brownlee 2 INTERNET-DRAFT The University of Auckland 3 June 1999 4 Expires December 1999 6 SRL: A Language for Describing Traffic Flows 7 and Specifying Actions for Flow Groups 9 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with all 14 provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering Task 17 Force (IETF), its areas, and its working groups. Note that other groups 18 may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference material 23 or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet Draft is a product of the Realtime Traffic Flow 32 Measurement Working Group of the IETF. 34 Abstract 36 This document describes a language for specifying rulesets, i.e. 37 configuration files which may be loaded into a traffic flow meter so as 38 to specify which traffic flows are measured by the meter, and the 39 information it will store for each flow. 41 Contents 43 1 Purpose and Scope 2 44 1.1 RTFM Meters and Traffic Flows . . . . . . . . . . . . . . . . 2 45 1.2 SRL Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 47 2 SRL Language Description 4 48 2.1 Define Directive . . . . . . . . . . . . . . . . . . . . . . . 4 49 2.2 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 50 2.3 Declaration . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 3 Statement 5 53 3.1 IF_statement . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 3.1.1 expression . . . . . . . . . . . . . . . . . . . . . . . . 6 55 3.1.2 term . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 3.1.3 factor . . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 3.1.4 operand_list . . . . . . . . . . . . . . . . . . . . . . . 6 58 3.1.5 operand . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 3.1.6 Test Part . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.1.7 Action Part . . . . . . . . . . . . . . . . . . . . . . . 8 61 3.1.8 ELSE Clause . . . . . . . . . . . . . . . . . . . . . . . 8 62 3.2 Compound_statement . . . . . . . . . . . . . . . . . . . . . . 8 63 3.3 Imperative_statement . . . . . . . . . . . . . . . . . . . . . 9 64 3.3.1 SAVE Statement . . . . . . . . . . . . . . . . . . . . . . 9 65 3.3.2 COUNT Statement . . . . . . . . . . . . . . . . . . . . . 10 66 3.3.3 EXIT Statement . . . . . . . . . . . . . . . . . . . . . . 10 67 3.3.4 IGNORE Statement . . . . . . . . . . . . . . . . . . . . . 11 68 3.3.5 NOMATCH Statement . . . . . . . . . . . . . . . . . . . . 11 69 3.3.6 STORE Statement . . . . . . . . . . . . . . . . . . . . . 11 70 3.3.7 RETURN Statement . . . . . . . . . . . . . . . . . . . . . 11 71 3.4 Subroutine_declaration . . . . . . . . . . . . . . . . . . . . 12 72 3.5 CALL_statement . . . . . . . . . . . . . . . . . . . . . . . . 12 74 4 Example Programs 13 75 4.1 Classify IP Port Numbers . . . . . . . . . . . . . . . . . . . 13 76 4.2 Classify Traffic into Groups of Networks . . . . . . . . . . . 14 78 5 Security Considerations 16 80 6 IANA Considerations 16 82 7 APPENDICES 16 83 7.1 Appendix A: SRL Syntax in BNF . . . . . . . . . . . . . . . . 16 84 7.2 Appendix B: Syntax for Values and Masks . . . . . . . . . . . 18 85 7.3 Appendix C: RTFM Attribute Information . . . . . . . . . . . . 19 87 8 Acknowledgments 21 89 9 References 21 91 10 Author's Address 21 92 1 Purpose and Scope 94 A ruleset for an RTFM Meter is a sequence of instructions to be executed 95 by the meter's Pattern Matching Engine (PME). The form of these 96 instructions is described in detail in the 'RTFM Architecture' and 'RTFM 97 Meter MIB' documents [1], [2], but most users - at least initially - 98 find them confusing and difficult to write, mainly because the effect of 99 each instruction is strongly dependent on the state of the meter's 100 Packet Matching Engine at the moment of its execution. 102 SRL (the Simple Ruleset Language) is a procedural language for creating 103 RTFM rulesets. It has been designed to be simple for people to 104 understand, using statements which help to clarify the execution context 105 in which they operate. SRL programs will be compiled into rulesets 106 which can then be downloaded to RTFM meters. 108 An SRL compiler is available as part of NeTraMet (a free-software 109 implementation of the RTFM meter and manager), version 4.2 [3]. 111 1.1 RTFM Meters and Traffic Flows 113 The RTFM Architecture [1] defines a set of 'attributes' which apply to 114 network traffic. Among the attributes are 'address attributes,' such as 115 PeerType, PeerAddress, TransType and TransAddress, which have meaning 116 for many protocols, e.g. for IPv4 traffic (PeerType == 1) PeerAddress 117 is an IP address, TransType is TCP(6), UDP(17), ICMP(1), etc., and 118 TransAddress is usually an IP port number. 120 An 'RTFM Traffic Flow' is simply a stream of packets observed by a meter 121 as they pass across a network between two end points (or to/from a 122 single end point). Each 'end point' of a flow is specified by the set 123 of values of its address attributes. 125 An 'RTFM Meter' is a measuring device - e.g. a program running on a 126 Unix or PC host - which observes passing packets and builds 'Flow Data 127 Records' for the flows of interest. 129 RTFM traffic flows have another important property - they are 130 bi-directional. This means that each flow data record in the meter has 131 two sets of counters, one for packets travelling from source to 132 destination, the other for returning packets. Within the RTFM 133 architecture such counters appear as further attributes of the flow. 135 An RTFM meter must be configured by the user, which means creating a 136 'Ruleset' so as to specify which flows are to be measured, and how much 137 information (i.e. which attributes) should be stored for each of them. 138 A ruleset is effectively a program for a minimal virtual machine, the 139 'Packet Matching Engine (PME),' which is described in detail in [1]. An 140 RTFM meter may run multiple rule sets, with every passing packet being 141 processed by each of the rulesets. The rule 'actions' in this document 142 are described as though only a single ruleset were running. 144 In the past creating a ruleset has meant writing machine code for the 145 PME, which has proved rather difficult to do. SRL provides a high-level 146 language which should enable users to create effective rulesets without 147 having to understand the details of the PME. 149 The language may be useful in other applications, being suitable for any 150 application area which involves selecting traffic flows from a stream of 151 packets. 153 1.2 SRL Overview 155 An SRL program is executed from the beginning for each new packet 156 arriving at the meter. It has two essential goals. 158 (a) Decide whether the current packet is part of a flow which is of 159 interest and, if necessary, determine its direction (i.e. decide 160 which of its end-points is considered to be its source). Other 161 packets will be ignored. 163 (b) SAVE whatever information is required to identify the flow and 164 accumulate (COUNT) quantitative information for that flow. 166 At execution, the meter's Packet Matching Engine (PME) begins by using 167 source and destination attributes as they appear 'on the wire.' If the 168 attributes do not match those of a flow to be recorded, the PME will 169 normally execute the program again, this time with the source and 170 destination addresses interchanged. Because of this bi-directional 171 matching, an RTFM meter is able to build up tables of flows with two 172 sets of counters - one for forward packets, the other for backward 173 packets. The programmer can, if required, suppress the 174 reverse-direction matching and assign 'forward' and 'backward' 175 directions which conform to the conventions of the external context. 177 Goal (a) is achieved using IF statements which perform comparisons on 178 information from the packet or from SRL variables. Goal (b) is achieved 179 using one or more SAVE statements to store the flow's identification 180 attributes; a COUNT statement then increments the statistical data 181 accumulating for it. 183 2 SRL Language Description 185 The SRL language is explained below using 'railway diagrams' to describe 186 the syntax. Flow through a diagram is from left to right. The only 187 exception to this is that lines carrying a left arrow may only be 188 traversed right to left. In the diagrams, keywords are written in 189 capital letters; in practice an SRL compiler must be insensitive to 190 case. Lower-case identifiers are explained in the text, or they refer 191 to another diagram. 193 The tokens of an SRL program obey the following rules: 195 - Comments may appear on any line of an SRL program, following a # 196 - White space is used to separate tokens 197 - Semicolon is used as the terminator for most statements 198 - Identifiers (e.g. for defines and labels) must start with a letter 199 - Identifiers may contain letters, digits and underscores 200 - The case of letters is not significant 201 - Reserved words (shown in upper case in this documents) 202 may not be used as identifiers 204 2.1 Define Directive 206 --- DEFINE -- defname ---- = ---- defined_text ------------------ ; 208 Simple parameterless defines are supported via the syntax above. The 209 define name, defname, is an identifier. The defined text starts after 210 the equal sign, and continues up to (but not including) the closing 211 semicolon. If a semicolon is required within the defined text it must 212 be preceded by a backslash, i.e. \; in an SRL define produces ; in the 213 text. 215 Wherever defname appears elsewhere in the program, it will be replaced 216 by the defined text. 218 For example, 220 DEFINE ftp = (20, 21); # Well-known Port numbers from [4] 221 DEFINE telnet = 23; 222 DEFINE www = 80; 224 2.2 Program 226 ------------+-------+-------- Statement -------+-------+----------- 227 | | | | 228 | +------- Declaration ------+ | 229 | | 230 +---------------------<--------------------+ 232 An SRL program is a sequence of statements or declarations. It does not 233 have any special enclosing symbols. Statements and declarations 234 terminate with a semicolon, except for compound statements, which 235 terminate with a right brace. 237 2.3 Declaration 239 ---------------------- Subroutine_declaration --------------------- 241 SRL's only explicit declaration is the subroutine declaration. Other 242 implicit declarations are labels (declared where they appear in front of 243 a statement) and subroutine parameters (declared in the subroutine 244 header). 246 3 Statement 248 ----------------+---- IF_statement ----------------+--------------- 249 | | 250 +---- Compound_statement ----------+ 251 | | 252 +---- Imperative_statement --------+ 253 | | 254 +---- CALL_statement --------------+ 256 An SRL program is a sequence of SRL statements. There are four kinds of 257 statements, as follows. 259 3.1 IF_statement 261 Test Part Action Part 262 ............. ............... 264 --- IF --- expression ---+------------+---- Statement ----+---> 265 | | | 266 +-- SAVE , --+ | 267 | | 268 +-- SAVE ; ----------------------+ 270 >-----------+-----------------------------+----------------- 271 | | 272 +-----ELSE --- Statement -----+ 274 3.1.1 expression 276 -------- term --------+------------------------+------------------- 277 | | 278 +--<-- term ----- || ----+ logical OR 280 3.1.2 term 282 ------- factor -------+------------------------+------------------- 283 | | 284 +--<-- factor --- && ----+ logical AND 286 3.1.3 factor 288 ------------+-------- attrib == operand_list --------+----------- 289 | | 290 +------------ ( expression ) --------------+ 292 3.1.4 operand_list 294 ----------+------------------ operand -----------------+----------- 295 | | 296 +-- ( operand ---+-------------------+-- ) --+ 297 | | 298 +-<-- operand , ---+ 300 3.1.5 operand 302 ------------- value ---------+----------------------+-------------- 303 | | 304 +------- / width ------+ 305 | | 306 +------- & mask -------+ 308 3.1.6 Test Part 310 The IF statement evaluates a logical expression. If the expression 311 value is TRUE, the action indicated in the 'Action Part' of the diagram 312 is executed. If the value is FALSE and the IF has an ELSE clause, that 313 ELSE clause is executed (see below). 315 The simplest form of expression is a test for equality (== operator); in 316 this an RTFM attribute value (from the packet or from an SRL variable) 317 is ANDed with a mask and compared with a value. A list of RTFM 318 attributes is given in Appendix C. More complicated expressions may be 319 built up using parentheses and the && (logical AND) and || (logical OR) 320 operators. 322 Operand values may be specified as dotted decimal, hexadecimal or as a 323 character constant (enclosed in apostrophes). The syntax for operand 324 values is given in Appendix B. 326 Masks may be specified as numbers, 327 dotted decimal e.g. &255.255 328 or hexadecimal e.g. &FF-FF 329 or as a width in bits e.g. /16 331 If a mask is not specified, an all-ones mask is used. 333 In SRL a value is always combined with a mask; this combination is 334 referred to as an operand. For example, if we were interested in flows 335 originating from IP network 130.216, we might write: 337 IF SourcePeerAddress == 130.216.0.0 & 255.255.0.0 SAVE; 339 or equivalently 341 IF SourcePeerAddress == 130.216/16 SAVE; 343 A list of values enclosed in parentheses may also be specified; the test 344 succeeds if the masked attribute equals any of the values in the list. 345 For example 347 IF SourcePeerAddress == ( 130.216.7/24, 130.216.34/24 ) SAVE; 349 As this last example indicates, values are right-padded with zeroes, 350 i.e. the given numbers specify the leading bytes of masks and values. 352 The operand values and masks used in an IF statement must be consistent 353 with the attribute being tested. For example, a four-byte value is 354 acceptable as a peer address, but would not be accepted as a transport 355 address (which may not be longer than two bytes). 357 3.1.7 Action Part 359 A SAVE action (i.e. SAVE , or SAVE ;) saves attribute(s), mask(s) and 360 value(s) as given in the statement. If the IF expression tests more 361 than one attribute, the masks and values are saved for all the matched 362 attributes. For each value_list in the statement the value saved is the 363 one which the packet actually matched. See below for further 364 description of SAVE statements. 366 Other actions are described in detail under "Imperative statements" 367 below. Note that the RETURN action is valid only within subroutines. 369 3.1.8 ELSE Clause 371 An ELSE Clause provides a statement which will be executed if the IF's 372 test fails. The statement following ELSE will often be another IF 373 statement, providing SRL's version of a 'select' statement. Note that 374 an ELSE clause always matches the immediately preceding IF. 376 3.2 Compound_statement 378 -------+-------------+----- { ---+---- Statement ----+--- } ------- 379 | | | | 380 +-- label : --+ +--------<----------+ 382 A compound statement is a sequence of statements enclosed in braces. 383 Each statement will terminate with a semicolon, unless it is another 384 compound statement (which terminates with a right brace). 386 A compound statement may be labelled, i.e. preceded by an identifier 387 followed by a semi-colon. Each statement inside the braces is executed 388 in sequence unless an EXIT statement is performed, as explained below. 390 Labels have a well-defined scope, within which they must be unique. 391 Labels within a subroutine (i.e. between a SUBROUTINE and its matching 392 ENDSUB) are local to that subroutine and are not visible outside it. 393 Labels outside subroutines are part of a program's outer block. 395 3.3 Imperative_statement 397 ------+---------------------------------------------------+------ ; 398 | | 399 +-- SAVE attrib --+--+-----------+--+---------------+ 400 | | | | | | 401 | | +- / width -+ | | 402 | | | | | | 403 | | +- & mask --+ | | 404 | | | | 405 | +--- = operand ---+ | 406 | | 407 +-- COUNT ------------------------------------------+ 408 | | 409 +-- EXIT label ------------------------------------+ 410 | | 411 +-- IGNORE -----------------------------------------+ 412 | | 413 +-- NOMATCH ----------------------------------------+ 414 | | 415 +-- RETURN --+-------+------------------------------+ 416 | | | | 417 | +-- n --+ | 418 | | 419 +-- STORE variable := value ------------------------+ 421 3.3.1 SAVE Statement 423 The SAVE statement saves information which will (later) identify the 424 flow in the meter's flow table. It does not actually record anything in 425 the table; this is done when a subsequent COUNT statement executes. 427 SAVE has two possible forms: 429 SAVE attrib = operand ; 430 saves the attribute, mask and value as given in the statement. 431 This form of the SAVE statement is similar to that allowed 432 in an IF statement, except that - since imperative statements 433 do not perform a test - you may save an arbitrary value. 435 SAVE attrib ; 436 SAVE attrib / width ; 437 SAVE attrib & mask ; 438 saves the attribute and mask from the statement, and the 439 value resulting from their application to the current packet. 440 This is most useful when used to save a value with a wider 441 mask than than was used to select the packet. For example 443 IF DestPeerAddress == 130.216/16 444 NOMATCH; 445 ELSE IF SourcePeerAddress == 130.216/16 { 446 SAVE SourcePeerAddress /24; 447 COUNT; 448 } 449 ELSE IGNORE; 451 3.3.2 COUNT Statement 453 The COUNT statement appears after all testing and saving is complete; it 454 instructs the PME to build the flow identifier from the attributes which 455 have been SAVEd, find it in the meter's flow table (creating a new entry 456 if this is the first packet observed for the flow), and increment its 457 counters. The meter then moves on to examine the next incoming packet. 459 3.3.3 EXIT Statement 461 The EXIT statement exits a labelled compound statement. The next 462 statement to be executed will be the one following that compound 463 statement. This provides a well-defined way to jump to a clearly 464 identified point in a program. For example 466 outer: { 467 ... 468 if SourcePeerAddress == 192.168/16 469 exit outer; # exits the statement labelled 'outer' 470 ... 471 } 472 # execution resumes here 474 In practice the language provides sufficient logical structure that one 475 seldom - if ever - needs to use the EXIT statement. 477 3.3.4 IGNORE Statement 479 The IGNORE statement terminates examination of the current packet 480 without saving any information from it. The meter then moves on to 481 examine the next incoming packet, beginning again at the first statement 482 of its program. 484 3.3.5 NOMATCH Statement 486 The NOMATCH statement indicates that matching has failed for this 487 execution of the program. If it is executed when a packet is being 488 processed with its addresses in 'on the wire' order, the PME will 489 perform the program again from the beginning with source and destination 490 addresses interchanged. If it is executed following such an 491 interchange, the packet will be IGNOREd. 493 NOMATCH is illustrated in the SAVE example (section 3.3.1), where it is 494 used to ensure that flows having 130.216/16 as an end-point are counted 495 as though 130.216 had been those flows' source peer (IP) address. 497 3.3.6 STORE Statement 499 The STORE statement assigns a value to an SRL variable and SAVEs it. 500 There are six SRL variables: 502 SourceClass SourceKind 503 DestClass DestKind 504 FlowClass FlowKind 506 Their names have no particular significance; they were arbitrarily 507 chosen as likely RTFM attributes but can be used to store any 508 single-byte integer values. Their values are set to zero each time 509 examination of a new packet begins. For example 511 STORE SourceClass := 3; 512 STORE FlowKind := 'W' 514 3.3.7 RETURN Statement 516 The RETURN statement is used to return from subroutines and can be used 517 only within the context of a subroutine. It is described in detail 518 below (CALL statement). 520 3.4 Subroutine_declaration 522 -- SUBROUTINE subname ( --+-----------------------------+-- ) --> 523 | | 524 +--+-- ADDRESS --- pname --+--+ 525 | | 526 +-- VARIABLE -- pname --+ 527 | | 528 +------<------- , ------+ 530 >------+-------- Statement ---------+----- ENDSUB -------- ; 531 | | 532 +-------------<--------------+ 534 A Subroutine declaration has three parts: 536 the subname is an identifier, used to name the subroutine. 538 the parameter list specifies the subroutine's parameters. 539 Each parameter is preceded with a keyword indicating its 540 type - VARIABLE indicates an SRL variable (see the STORE 541 statement above), ADDRESS indicates any other RTFM attribute. 542 A parameter name may be any identifier, and its scope is 543 limited to the subroutine's body. 545 the body specifies what processing the subroutine will perform. 546 This is simply a sequence of Statements, terminated by the 547 ENDSUB keyword. 549 Note that EXITs in a subroutine may not refer to labels outside it. The 550 only way to leave a subroutine is via a RETURN statement. 552 3.5 CALL_statement 554 ---- CALL subname ( --+---------------------+-- ) ----> 555 | | 556 +--+-- parameter --+--+ 557 | | 558 +----<--- , ----+ 560 >---+-------------------------------------+--- ENDCALL ---- ; 561 | | 562 +---+--+-- n : --+--- Statement --+---+ 563 | | | | 564 | +----<----+ | 565 | | 566 +--------------<--------------+ 568 The CALL statement invokes an SRL subroutine. The parameters are SRL 569 variables or other RTFM attributes, and their types must match those in 570 the subroutine declaration. Following the parameters is a sequence of 571 statements, each preceded by an integer label. These labels will 572 normally be 1:, 2:, 3:, etc, but they do not have to be contiguous, nor 573 in any particular order. They are referred to in RETURN statements 574 within the subroutine body. 576 e.g. RETURN 2; would return to the statement labelled 2: 577 within in the CALL statement. 579 Execution of the labelled statement completes the CALL. 581 If the return statement does not specify a return label, the first 582 statement executed after RETURN will be the statement immediately 583 following ENDCALL. 585 4 Example Programs 587 4.1 Classify IP Port Numbers 589 # 590 # Classify IP port numbers 591 # 592 define IPv4 = 1; # Address Family number from [4] 593 # 594 define ftp = (20, 21); # Well-Known Port numbers from [4] 595 define telnet = 23; 596 define www = 80; 597 # 598 define tcp = 6; # Protocol numbers from [4] 599 define udp = 17; 600 # 601 if SourcePeerType == IPv4 save; 602 else ignore; # Not an IPv4 packet 603 # 604 if (SourceTransType == tcp __ SourceTransType == udp) save, { 605 if SourceTransAddress == (www, ftp, telnet) nomatch; 606 # We want the well-known port as Dest 607 # 608 if DestTransAddress == telnet 609 save, store FlowKind := 'T'; 610 else if DestTransAddress == www 611 save, store FlowKind := 'W'; 612 else if DestTransAddress == ftp 613 save, store FlowKind := 'F'; 614 else { 615 save DestTransAddress; 616 store FlowKind := '?'; 617 } 618 } 619 else save SourceTransType = 0; 620 # 621 save SourcePeerAddress /32; 622 save DestPeerAddress /32; 623 count; 624 # 626 This program counts only IP packets, saving SourceTransType (tcp, udp or 627 0), Source- and DestPeerAddress (32-bit IP addresses) and FlowKind ('W' 628 for www, 'F' for ftp, 'T' for telnet, '?' for unclassified). The 629 program uses a NOMATCH action to specify the packet direction - its 630 resulting flows will have the well-known ports as their destination. 632 4.2 Classify Traffic into Groups of Networks 634 # 635 # SRL program to classify traffic into network groups 636 # 637 define my_net = 130.216/16; 638 define k_nets = ( 130.217/16, 130.123/16, 130.195/16, 639 132.181/16, 138.75/16, 139.80/16 ); 640 # 641 call net_kind (SourcePeerAddress, SourceKind) 642 endcall; 643 call net_kind (DestPeerAddress, DestKind) 644 endcall; 645 count; 646 # 647 subroutine net_kind (address addr, variable net) 648 if addr == my_net save, { 649 store net := 10; return 1; 650 } 651 else if addr == k_nets save, { 652 store net := 20; return 2; 653 } 654 save addr/24; # Not my_net or in k_nets 655 store net := 30; return 3; 656 endsub; 657 # 659 The net_kind subroutine determines whether addr is my network (130.216), 660 one of the Kawaihiko networks (in the k_nets list), or some other 661 network. It saves the network address from addr (16 bits for my_net and 662 the k_net networks, 24 bits for others), stores a value of 10, 20 or 30 663 in net, and returns to 1:, 2: or 3:. Note that the network numbers 664 used are contained within the two DEFINEs, making them easy to change. 666 net_kind is called twice, saving Source- and DestPeerAddress and Source- 667 and DestKind; the COUNT statement produces flows identified by these 668 four RTFM attributes, with no particular source-dest ordering. 670 In the program no use is made of return numbers and they could have been 671 omitted. However, we might wish to re-use the subroutine in another 672 program doing different things for different return numbers, as in the 673 version below. 675 call net_kind (DestPeerAddress, DestKind) 676 1: nomatch; # We want my_net as source 677 endcall; 678 call net_kind (SourcePeerAddress, SourceKind) 679 1: count; # my_net -> other networks 680 endcall; 681 save SourcePeerAddress /24; 682 save DestPeerAddress /24; 683 count; 685 This version uses a NOMATCH statement to ensure that its resulting flows 686 have my_net as their source. The NOMATCH also rejects my_net -> my_net 687 traffic. Traffic which doesn't have my_net as source or destination 688 saves 24 bits of its peer addresses (the subroutine might only have 689 saved 16) before counting such an unusual flow. 691 5 Security Considerations 693 SRL is a language for creating rulesets (i.e. configuration files) for 694 RTFM Traffic Meters - it does not present any security issues in itself. 696 On the other hand, flow data gathered using such rulesets may well be 697 valuable. It is therefore important to take proper precautions to 698 ensure that access to the meter and its data is secure. Ways to achieve 699 this are discussed in detail in the Architecture and Meter MIB documents 700 [1,2]. 702 6 IANA Considerations 704 Appendix C below lists the RTFM attributes by name. Since SRL only 705 refers to attributes by name, SRL users do not have to know the 706 attribute numbers. 708 The size (in bytes) of the various attribute values is also listed in 709 Appendix C. These sizes reflect the object sizes for the attribute 710 values as they are stored in the RTFM Meter MIB [2]. 712 IANA considerations for allocating new attributes are discussed in 713 detail in the RTFM Architecture document [1]. 715 7 APPENDICES 717 7.1 Appendix A: SRL Syntax in BNF 719 ::= | 721 ::= | 723 ::= 725 ::= | 726 | 727 | 728 730 ::= IF 732 ::= SAVE ; | 733 SAVE , | 734 736 ::= | 737 ELSE 739 ::= | || 741 ::= | && 743 ::= == | 744 ( ) 746 ::= | ( ) 748 ::= | 749 , 751 ::= | 752 / | 753 & 755 ::= { } 757 ::= | 758 : 760 ::= | 762 ::= ; | 763 SAVE ; | 764 COUNT ; | 765 EXIT