This document describes a language for specifying rulesets, i.e configuration files which may be loaded into a traffic flow meter
as to specify which traffic flows are measured by the meter, and information it will store for each flow
A ruleset for an RTFM Meter is a sequence of instructions to
executed by the meter's Pattern Matching Engine (PME). The form
these instructions is described in detail in the 'RTFM Architecture
and 'RTFM Meter MIB' documents [RTFM-ARC, RTFM-MIB], but most users -
at least initially - find them confusing and difficult to write
mainly because the effect of each instruction is strongly
on the state of the meter's Packet Matching Engine at the moment
its execution
SRL (the Simple Ruleset Language) is a procedural language
creating RTFM rulesets. It has been designed to be simple for
to understand, using statements which help to clarify the
context in which they operate. SRL programs will be compiled
rulesets which can then be downloaded to RTFM meters
The RTFM Architecture [RTFM-ARC] defines a set of 'attributes'
apply to network traffic. Among the attributes are '
attributes,' such as PeerType, PeerAddress, TransType
TransAddress, which have meaning for many protocols, e.g. for IPv
RFC 2723 SRL: A Traffic Flow Language October 1999
traffic (PeerType == 1) PeerAddress is an IP address, TransType
TCP(6), UDP(17), ICMP(1), etc., and TransAddress is usually an
port number
An 'RTFM Traffic Flow' is simply a stream of packets observed by
meter as they pass across a network between two end points (
to/from a single end point). Each 'end point' of a flow is
by the set of values of its address attributes
An 'RTFM Meter' is a measuring device - e.g. a program running on
Unix or PC host - which observes passing packets and builds '
Data Records' for the flows of interest
RTFM traffic flows have another important property - they are bi
directional. This means that each flow data record in the meter
two sets of counters, one for packets travelling from source destination, the other for returning packets. Within the architecture such counters appear as further attributes of the flow
An RTFM meter must be configured by the user, which means creating
'Ruleset' so as to specify which flows are to be measured, and
much information (i.e. which attributes) should be stored for each
them. A ruleset is effectively a program for a minimal
machine, the 'Packet Matching Engine (PME),' which is described
detail in [RTFM-ARC]. An RTFM meter may run multiple rule sets,
every passing packet being processed by each of the rulesets.
rule 'actions' in this document are described as though only a
ruleset were running
In the past creating a ruleset has meant writing machine code for
PME, which has proved rather difficult to do. SRL provides a high
level language which should enable users to create effective
without having to understand the details of the PME
An SRL program is executed from the beginning for each new
arriving at the meter. It has two essential goals
(a) Decide whether the current packet is part of a flow which is
interest and, if necessary, determine its direction (i.e.
which of its end-points is considered to be its source).
packets will be ignored
RFC 2723 SRL: A Traffic Flow Language October 1999
(b) SAVE whatever information is required to identify the flow
accumulate (COUNT) quantitative information for that flow
At execution, the meter's Packet Matching Engine (PME) begins
using source and destination attributes as they appear 'on the wire.'
If the attributes do not match those of a flow to be recorded,
PME will normally execute the program again, this time with
source and destinationaddresses interchanged. Because of this bi
directional matching, an RTFM meter is able to build up tables
flows with two sets of counters - one for forward packets, the
for backward packets. The programmer can, if required, suppress
reverse-directionmatching and assign 'forward' and 'backward
directions which conform to the conventions of the external context
Goal (a) is achieved using IF statements which perform comparisons information from the packet or from SRL variables. Goal (b)
achieved using one or more SAVE statements to store the flow' identification attributes; a COUNT statement then increments
statistical data accumulating for it
The SRL language is explained below using 'railway diagrams' describe the syntax. Flow through a diagram is from left to right
The only exception to this is that lines carrying a left arrow
only be traversed right to left. In the diagrams, keywords
written in capital letters; in practice an SRL compiler must
insensitive to case. Lower-case identifiers are explained in
text, or they refer to another diagram
The tokens of an SRL program obey the following rules
- Comments may appear on any line of an SRL program, following a #
- White space is used to separate
- Semicolon is used as the terminator for most
- Identifiers (e.g. for defines and labels) must start with a
- Identifiers may contain letters, digits and
- The case of letters is not
- Reserved words (shown in upper case in this document) may not
used as
Simple parameterless defines are supported via the syntax above.
define name, defname, is an identifier. The defined text
after the equal sign, and continues up to (but not including)
An SRL program is a sequence of statements or declarations. It
not have any special enclosing symbols. Statements and terminate with a semicolon, except for compound statements, terminate with a right brace
RFC 2723 SRL: A Traffic Flow Language October 1999
3.1.6 Test
The IF statement evaluates a logical expression. If the
value is TRUE, the action indicated in the 'Action Part' of
diagram is executed. If the value is FALSE and the IF has an
clause, that ELSE clause is executed (see below).
The simplest form of expression is a test for equality (== operator);
in this an RTFM attribute value (from the packet or from an variable) is ANDed with a mask and compared with a value. A list
RTFM attributes is given in Appendix C. More complicated
may be built up using parentheses and the && (logical AND) and ||
(logical OR) operators
Masks may be specified as numbers
dotted decimal e.g. &255.255
or hexadecimal e.g. &FF-
or as a width in bits e.g. /16
If a mask is not specified, an all-ones mask is used
In SRL a value is always combined with a mask; this combination
referred to as an operand. For example, if we were interested
flows originating from IP network 130.216, we might write
IF SourcePeerAddress == 130.216.0.0 & 255.255.0.0 SAVE
or
IF SourcePeerAddress == 130.216/16 SAVE
A list of values enclosed in parentheses may also be specified;
test succeeds if the masked attribute equals any of the values in
list. For example
IF SourcePeerAddress == ( 130.216.7/24, 130.216.34/24 ) SAVE
As this last example indicates, values are right-padded with zeroes
i.e. the given numbers specify the leading bytes of masks and values
The operand values and masks used in an IF statement must
consistent with the attribute being tested. For example, a four-
value is acceptable as a peer address, but would not be accepted as transport address (which may not be longer than two bytes).
RFC 2723 SRL: A Traffic Flow Language October 1999
3.1.7 Action
A SAVE action (i.e. SAVE , or SAVE ;) saves attribute(s), mask(s)
value(s) as given in the statement. If the IF expression tests
than one attribute, the masks and values are saved for all
matched attributes. For each value_list in the statement the
saved is the one which the packet actually matched. See below
further description of SAVE statements
Other actions are described in detail under "Imperative statements
below. Note that the RETURN action is valid only within subroutines
A compound statement may be labelled, i.e. preceded by an followed by a semi-colon. Each statement inside the braces
executed in sequence unless an EXIT statement is performed,
explained below
Labels have a well-defined scope, within which they must be unique
Labels within a subroutine (i.e. between a SUBROUTINE and matching ENDSUB) are local to that subroutine and are not
outside it. Labels outside subroutines are part of a program's
block
The SAVE statement saves information which will (later) identify
flow in the meter's flow table. It does not actually record
in the table; this is done when a subsequent COUNT
executes
SAVE attrib = operand ; saves the attribute, mask and value as
in the statement. This form of the SAVE statement is similar
that allowed in an IF statement, except that - since
statements do not perform a test - you may save an
value
SAVE attrib ;
SAVE attrib / width ;
SAVE attrib & mask ; saves the attribute and mask from the statement
and the value resulting from their application to the
packet. This is most useful when used to save a value with
wider mask than than was used to select the packet.
example
RFC 2723 SRL: A Traffic Flow Language October 1999
IF DestPeerAddress == 130.216/16
NOMATCH
ELSE IF SourcePeerAddress == 130.216/16 {
SAVE SourcePeerAddress /24;
COUNT
}
ELSE IGNORE
3.3.2 COUNT
The COUNT statement appears after all testing and saving is complete
it instructs the PME to build the flow identifier from the
which have been SAVEd, find it in the meter's flow table (creating
new entry if this is the first packet observed for the flow), increment its counters. The meter then moves on to examine the incoming packet
3.3.3 EXIT
The EXIT statement exits a labelled compound statement. The statement to be executed will be the one following that statement. This provides a well-defined way to jump to a
identified point in a program. For example
outer: {
...
if SourcePeerAddress == 192.168/16
exit outer; # exits the statement labelled 'outer
...
}
# execution resumes
The IGNORE statement terminates examination of the current
without saving any information from it. The meter then moves on
examine the next incoming packet, beginning again at the statement of its program
3.3.5 NOMATCH
The NOMATCH statementindicates that matching has failed for
execution of the program. If it is executed when a packet is
processed with its addresses in 'on the wire' order, the PME
RFC 2723 SRL: A Traffic Flow Language October 1999
perform the program again from the beginning with source destinationaddresses interchanged. If it is executed following
an interchange, the packet will be IGNOREd
NOMATCH is illustrated in the SAVE example (section 3.3.1), where
is used to ensure that flows having 130.216/16 as an end-point
counted as though 130.216 had been those flows' source peer (IP
address
Their names have no particularsignificance; they were
chosen as likely RTFM attributes but can be used to store
single-byte integer values. Their values are set to zero each
examination of a new packet begins. For example
STORE SourceClass := 3;
STORE FlowKind := 'W
3.3.7 RETURN
The RETURN statement is used to return from subroutines and can
used only within the context of a subroutine. It is described
detail below (CALL statement).
#
# Classify IP port
#
define IPv4 = 1; # Address Family number from [ASG-NBR
#
define ftp = (20, 21); # Well-Known Port numbers from [ASG-NBR
define telnet = 23;
define www = 80;
#
define tcp = 6; # Protocol numbers from [ASG-NBR
define udp = 17;
#
if SourcePeerType == IPv4 save
else ignore; # Not an IPv4
#
if (SourceTransType == tcp || SourceTransType == udp) save, {
if SourceTransAddress == (www, ftp, telnet) nomatch
# We want the well-known port as
#
if DestTransAddress ==
save, store FlowKind := 'T';
else if DestTransAddress ==
save, store FlowKind := 'W';
else if DestTransAddress ==
save, store FlowKind := 'F';
else {
save DestTransAddress
store FlowKind := '?';
}
}
else save SourceTransType = 0;
#
save SourcePeerAddress /32;
save DestPeerAddress /32;
count
#
RFC 2723 SRL: A Traffic Flow Language October 1999
This program counts only IP packets, saving SourceTransType (tcp,
or 0), Source- and DestPeerAddress (32-bit IP addresses) and
('W' for www, 'F' for ftp, 'T' for telnet, '?' for unclassified).
The program uses a NOMATCH action to specify the packet direction -
its resulting flows will have the well-known ports as destination
4.2 Classify Traffic into Groups of
#
# SRL program to classify traffic into network
#
define my_net = 130.216/16;
define k_nets = ( 130.217/16, 130.123/16, 130.195/16,
132.181/16, 138.75/16, 139.80/16 );
#
call net_kind (SourcePeerAddress, SourceKind
endcall
call net_kind (DestPeerAddress, DestKind
endcall
count
# subroutine net_kind (address addr, variable net
if addr == my_net save, {
store net := 10; return 1;
}
else if addr == k_nets save, {
store net := 20; return 2;
}
save addr/24; # Not my_net or in k_
store net := 30; return 3;
endsub
#
The net_kind subroutine determines whether addr is my
(130.216), one of the Kawaihiko networks (in the k_nets list),
some other network. It saves the network address from addr (16
for my_net and the k_net networks, 24 bits for others), stores
value of 10, 20 or 30 in net, and returns to 1:, 2: or 3:.
that the network numbers used are contained within the two DEFINEs
making them easy to change
net_kind is called twice, saving Source- and DestPeerAddress
Source- and DestKind; the COUNT statement produces flows
by these four RTFM attributes, with no particular source- ordering
RFC 2723 SRL: A Traffic Flow Language October 1999
In the program no use is made of return numbers and they could
been omitted. However, we might wish to re-use the subroutine
another program doing different things for different return numbers
as in the version below
call net_kind (DestPeerAddress, DestKind
1: nomatch; # We want my_net as
endcall
call net_kind (SourcePeerAddress, SourceKind
1: count; # my_net -> other
endcall
save SourcePeerAddress /24;
save DestPeerAddress /24;
count
This version uses a NOMATCH statement to ensure that its
flows have my_net as their source. The NOMATCH also rejects my_
-> my_net traffic. Traffic which doesn't have my_net as source destination saves 24 bits of its peer addresses (the subroutine
only have saved 16) before counting such an unusual flow
SRL is a language for creating rulesets (i.e. configuration files
for RTFM Traffic Meters - it does not present any security issues
itself
On the other hand, flow data gathered using such rulesets may well
valuable. It is therefore important to take proper precautions
ensure that access to the meter and its data is secure. Ways
achieve this are discussed in detail in the Architecture and
MIB documents [RTFM-ARC, RTFM-MIB].
6 IANA
Appendix C below lists the RTFM attributes by name. Since SRL
refers to attributes by name, SRL users do not have to know attribute numbers
The size (in bytes) of the various attribute values is also listed Appendix C. These sizes reflect the object sizes for the
values as they are stored in the RTFM Meter MIB [RTFM-MIB].
