<HTML
><HEAD
><TITLE
>flow-nfilter</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.73
"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
><SPAN
CLASS="APPLICATION"
>flow-nfilter</SPAN
></A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN6"
></A
><H2
>Name</H2
><SPAN
CLASS="APPLICATION"
>flow-nfilter</SPAN
>&nbsp;--&nbsp;Filter flows.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN10"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>flow-nfilter</B
>  [-hk] [-b<TT
CLASS="REPLACEABLE"
><I
> big</I
></TT
>|<TT
CLASS="REPLACEABLE"
><I
>little</I
></TT
>] [-C<TT
CLASS="REPLACEABLE"
><I
> comment</I
></TT
>] [-d<TT
CLASS="REPLACEABLE"
><I
> debug_level</I
></TT
>] [-f<TT
CLASS="REPLACEABLE"
><I
> filter_fname</I
></TT
>] [-F<TT
CLASS="REPLACEABLE"
><I
> filter_definition</I
></TT
>] [-v<TT
CLASS="REPLACEABLE"
><I
> variable binding</I
></TT
>] [-z<TT
CLASS="REPLACEABLE"
><I
> z_level</I
></TT
>]</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN29"
></A
><H2
>DESCRIPTION</H2
><P
>The <B
CLASS="COMMAND"
>flow-nfilter</B
> utility will filter flows based on
user selectable criteria.  Filters are defined in a configuration file
and are composed of primitives and a definition.  Definitions contain
match lines grouped to form logical AND and OR operations on the flow
using the selected primitives.  A definition may contain the invert
command which will invert the result of the evaluation.</P
><P
>Words in the configuration file of the form @VAR or @{VAR:default} will be
expanded at run-time by setting variable names with the -v option.</P
><P
>Filter primitives begin with the filter-primitive keyword followed by
a symbolic name.  Each primitive has a type defined below.
A list of permit and or deny keywords followed
by an argument are later evaulated to determine if the flow is permitted or
denied.  The default action for a primitive is to deny which may be 
changed with the default keyword.  Symbolic substitutions are done where
appropriate.</P
><P
></P
><P
>The match keyword in a definition selects the criteria to match a primitive.
A match type may allow more than one type of primitive, for example the
src-ip-addr match type will accept any of {ip-address, ip-address-mask,
ip-address-prefix} primitive types.</P
><P
><PRE
CLASS="SCREEN"
>&#13;Primitive type          Type       Description/Example
-------------------------------------------------------------------
as                      Bucket     Autonomous System Number.
                                   600,159,3112

ip-address-prefix-len   Numeric    Integer from 0 to 32.
                                   16-31

ip-protocol             Bucket     Integer from 0 to 255. 
                                   6,17,1

ip-tos                  Bucket     Integer from 0 to 255 with mask.
                                   0xA0/0xE0

ip-tcp-flags            Bucket     Integer from 0 to 255 with mask.
                                   0x2/0x2

ifindex                 Bucket     Integer from 0 to 65535
                                   0,5,10

engine                  Bucket     Integer from 0 to 255.
                                   0

ip-port                 Bucket     Integer from 0 to 65535.
                                   80,8080,23,22

ip-address              Hash       List of IP Addresses.
                                   10.0.0.1

ip-address-mask         List       List of IP address/mask pairs.
                                   10.1.0.0 255.255.0.0

ip-address-prefix       Trie       List of IP address/mask pairs.
                                   10.1/16

tag                     Hash       List of tags.
                                   0xFF00

tag-mask                List       List of tags.
                                   0xF000/0xFF00

counter                 List       List of Integers with qualifier.
                                   lt 32

time                    List       List of relative time specifiers.
                                   gt 5:00

time-date               List       List of absolute time specifiers.
                                   gt December 12, 2002 5:13:21

double                  List       List of doubles with qualifier.
                                   lt 32.0

rate                    Element    Rate is calculated as 1/rate.
                                   permit 100



Match type              Description             Primitives accepted
-------------------------------------------------------------------
source-as               Source AS               as

destination-as          Destination AS          as

ip-source-address       Source IP Address       ip-address,
                                                ip-address-mask,
                                                ip-address-prefix

ip-destination-address  Destination IP Address  ip-address,
                                                ip-address-mask,
                                                ip-address-prefix

ip-exporter-address     Exporter IP Address     ip-address,
                                                ip-address-mask,
                                                ip-address-prefix

ip-nexthop-address      NextHop IP Address      ip-address,
                                                ip-address-mask,
                                                ip-address-prefix

ip-shortcut-address     Shortcut IP Address     ip-address,
                                                ip-address-mask,
                                                ip-address-prefix

ip-protocol             IP Protocol             ip-protocol

ip-source-address-prefix-len
                        Source IP address       ip-address-prefix-len
                        prefix length

ip-destination-address-prefix-len
                        Destination IP address  ip-address-prefix-len
                        prefix length
           
ip-tos                  IP Type Of Service      ip-tos

ip-marked-tos           IP Type Of Service      ip-tos

ip-tcp-flags            IP/TCP Flags            ip-tcp-flags

ip-source-port          Source IP Port          ip-port
                        eg TCP/UDP

ip-destination-port     Destination IP Port     ip-port
                        eg TCP/UDP

input-interface         Source ifIndex          ifindex
                        eg Input Interface

output-interface        Destination ifIndex     ifindex
                        eg Output Interface

start-time              Start Time of flow      time, time-date

end-time                End Time of Flow        time, time-date

flows                   Number of flows         counter

octets                  Number of octets        counter

packets                 Number of packets       counter

duration                Duration of flow in ms  counter

engine-id               Engine ID               engine

engine-type             Engine Type             engine

source-tag              Source Tag              tag, tag-mask

destination-tag         Destination Tag         tag, tag-mask

pps                     Packets Per Second      double

bps                     Bits Per Second         double

random-sample           Random Sample           rate&#13;</PRE
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN39"
></A
><H2
>OPTIONS</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>-b<TT
CLASS="REPLACEABLE"
><I
> big</I
></TT
>|<TT
CLASS="REPLACEABLE"
><I
>little</I
></TT
></DT
><DD
><P
>Byte order of output.</P
></DD
><DT
>-C<TT
CLASS="REPLACEABLE"
><I
> Comment</I
></TT
></DT
><DD
><P
>Add a comment. </P
></DD
><DT
>-d<TT
CLASS="REPLACEABLE"
><I
> debug_level</I
></TT
></DT
><DD
><P
>Enable debugging.</P
></DD
><DT
>-f<TT
CLASS="REPLACEABLE"
><I
> filter_fname</I
></TT
></DT
><DD
><P
>Filter list filename.  Defaults to <TT
CLASS="FILENAME"
>@localstatedir@/cfg/filter</TT
>.</P
></DD
><DT
>-F<TT
CLASS="REPLACEABLE"
><I
> filter_definition</I
></TT
></DT
><DD
><P
>Select the active definition.  Defaults to default.</P
></DD
><DT
>-h</DT
><DD
><P
>Display help.</P
></DD
><DT
>-k</DT
><DD
><P
>Keep time from input.</P
></DD
><DT
>-v<TT
CLASS="REPLACEABLE"
><I
> variable binding</I
></TT
></DT
><DD
><P
>Set a variable FOO=bar.</P
></DD
><DT
>-z<TT
CLASS="REPLACEABLE"
><I
> z_level</I
></TT
></DT
><DD
><P
>Configure compression level to <TT
CLASS="REPLACEABLE"
><I
> z_level</I
></TT
>.  0 is
disabled (no compression), 9 is highest compression.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN88"
></A
><H2
>TIME/DATE parsing</H2
><P
>time-date parsing is implemented with <TT
CLASS="FILENAME"
>getdate.y</TT
>,
a commonly used function to process free-form time date specifications.
Example usage borrowed from <B
CLASS="COMMAND"
>cvs</B
>:
    1 month ago
    2 hours ago
    400000 seconds ago
    last year
    last Monday
    yesterday
    a fortnight ago
    3/31/92 10:00:07 PST
    January 23, 1987 10:05pm
    22:00 GMT</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN93"
></A
><H2
>EXAMPLES</H2
><DIV
CLASS="INFORMALEXAMPLE"
><A
NAME="AEN95"
></A
><P
></P
><P
>An example of filter configuration file.
<PRE
CLASS="SCREEN"
>&#13;filter-primitive srate
  type rate
  permit 100

filter-primitive test-as
  type as
  permit 600,159

filter-primitive test-prefix-len
  type ip-address-prefix-len
  permit 32

filter-primitive test-protocol
  type ip-protocol
  permit tcp

filter-primitive test-tos
  type ip-tos
  mask 0xA0
  permit 0xE0

filter-primitive test-tcp-flags
  type ip-tcp-flags
  mask 0x2
  permit 0x2

filter-primitive test-ifindex
  type ifindex
  permit 0,5,10

filter-primitive test-engine
  type engine
  permit 0

filter-primitive test-port
  type ip-port
  permit https
  permit 80
  default deny

filter-primitive test-address
  type ip-address
  permit 0.0.0.1
  permit 0.0.0.2
  default deny

filter-primitive test-address-mask
  type ip-address-mask
  permit 128.146.197.1 255.255.255.255
  permit 128.146.197.2 255.255.255.255

filter-primitive test-prefix
  type ip-address-prefix
  permit 128.146.0.0/16
  default deny

filter-primitive test-tag
  type tag
  permit 0x00
  permit 0x01
  permit 0xFF

filter-primitive test-tag-mask
  type tag-mask  
  permit OSU 0xFF
  permit 0xFF 0xFF
  default deny

filter-primitive test-counter
  type counter
  permit lt 5 
  permit gt 10
  default deny

filter-primitive test-time-date
  type time-date
  permit gt December 12, 2002 5:13:21

filter-primitive test-time
  type time-date
  permit gt 12:15:00

filter-definition sample-1-in-100
  match random-sample srate

filter-definition t1
  match engine-type test-engine
  or
  match destination-tag test-tag-mask</PRE
></P
><P
></P
></DIV
><DIV
CLASS="INFORMALEXAMPLE"
><A
NAME="AEN98"
></A
><P
></P
><P
>Display all flows with a destination port of 80 or source port of 25 (smtp)
starting after Dec 12, 2001.  The file <TT
CLASS="FILENAME"
>test</TT
> is
populated with the following:

<P
CLASS="LITERALLAYOUT"
>filter-primitive&nbsp;port80<br>
&nbsp;&nbsp;type&nbsp;ip-port<br>
&nbsp;&nbsp;permit&nbsp;80<br>
<br>
filter-primitive&nbsp;port25<br>
&nbsp;&nbsp;type&nbsp;ip-port<br>
&nbsp;&nbsp;permit&nbsp;smtp<br>
<br>
filter-primitive&nbsp;dec12<br>
&nbsp;&nbsp;type&nbsp;time-date<br>
&nbsp;&nbsp;permit&nbsp;gt&nbsp;Dec&nbsp;12,&nbsp;2001<br>
<br>
filter-definition&nbsp;foo<br>
&nbsp;&nbsp;match&nbsp;ip-source-port&nbsp;port80<br>
&nbsp;&nbsp;match&nbsp;start-time&nbsp;dec12<br>
&nbsp;&nbsp;or<br>
&nbsp;&nbsp;match&nbsp;ip-destination-port&nbsp;port25<br>
&nbsp;&nbsp;match&nbsp;start-time&nbsp;dec12</P
>

<B
CLASS="COMMAND"
>flow-cat <TT
CLASS="FILENAME"
>flows</TT
> | flow-nfilter -ftest -Ffoo | flow-print</B
>&#13;</P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN104"
></A
><H2
>FILES</H2
><P
>  Configuration files:
    Symbols - <TT
CLASS="FILENAME"
>@localstatedir@/sym/*</TT
>.
    Tag - <TT
CLASS="FILENAME"
>@localstatedir@/cfg/tag.cfg</TT
>.
    Filter - <TT
CLASS="FILENAME"
>@localstatedir@/cfg/filter.cfg</TT
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN110"
></A
><H2
>BUGS</H2
><P
>None known.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN113"
></A
><H2
>AUTHOR</H2
><P
>Mark Fullmer
<TT
CLASS="EMAIL"
>&#60;<A
HREF="mailto:maf@splintered.net"
>maf@splintered.net</A
>&#62;</TT
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN120"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="APPLICATION"
>flow-tools</SPAN
>(1)</P
></DIV
></BODY
></HTML
>