flow-nfilter

Langue: en

Version: 250929 (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

NAME

flow-nfilter --- Filter flows.

SYNOPSIS

flow-nfilter [-hk] [-b big|little] [-C comment] [-d debug_level] [-f filter_fname] [-F filter_definition] [-v variable binding] [-z z_level]

DESCRIPTION

The flow-nfilter 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.

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.

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.

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.

  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
 

OPTIONS

-b big|little
Byte order of output.
-C Comment
Add a comment.
-d debug_level
Enable debugging.
-f filter_fname
Filter list filename. Defaults to /etc/flow-tools/cfg/filter.
-F filter_definition
Select the active definition. Defaults to default.
-h
Display help.
-k
Keep time from input.
-v variable binding
Set a variable FOO=bar.
-z z_level
Configure compression level to z_level. 0 is disabled (no compression), 9 is highest compression.

TIME/DATE parsing

time-date parsing is implemented with getdate.y, a commonly used function to process free-form time date specifications. Example usage borrowed from cvs:
    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

EXAMPLES

An example of filter configuration file.

  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
 

Display all flows with a destination port of 80 or source port of 25 (smtp) starting after Dec 12, 2001. The file test is populated with the following:

 filter-primitive port80
   type ip-port
   permit 80
 
 filter-primitive port25
   type ip-port
   permit smtp
 
 filter-primitive dec12
   type time-date
   permit gt Dec 12, 2001
 
 filter-definition foo
   match ip-source-port port80
   match start-time dec12
   or
   match ip-destination-port port25
   match start-time dec12
 

  flow-cat flows | flow-nfilter -ftest -Ffoo | flow-print

FILES


  Configuration files:
    Symbols - /etc/flow-tools/sym/*.
    Tag - /etc/flow-tools/cfg/tag.cfg.
    Filter - /etc/flow-tools/cfg/filter.cfg.

BUGS

None known.

AUTHOR

Mark Fullmer maf@splintered.net

SEE ALSO

flow-tools(1)