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 [email protected]