1FLOW-NFILTER(1)                                                FLOW-NFILTER(1)
2
3
4

NAME

6       flow-nfilter - Filter flows.
7

SYNOPSIS

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

DESCRIPTION

14       The  flow-nfilter  utility  will  filter flows based on user selectable
15       criteria. Filters are defined in a configuration file and are  composed
16       of primitives and a definition. Definitions contain match lines grouped
17       to form logical AND and OR operations on the flow  using  the  selected
18       primitives.  A  definition  may  contain  the invert command which will
19       invert the result of the evaluation.
20
21       Words in the configuration file of the form @VAR or @{VAR:default} will
22       be expanded at run-time by setting variable names with the -v option.
23
24       Filter primitives begin with the filter-primitive keyword followed by a
25       symbolic name. Each primitive has a type defined below.  A list of per‐
26       mit and or deny keywords followed by an argument are later evaulated to
27       determine if the flow is permitted or denied. The default action for  a
28       primitive  is  to  deny  which may be changed with the default keyword.
29       Symbolic substitutions are done where appropriate.
30
31       The match keyword in a definition selects the criteria to match a prim‐
32       itive.   A  match  type  may allow more than one type of primitive, for
33       example the src-ip-addr match type will accept any of {ip-address,  ip-
34       address-mask, ip-address-prefix} primitive types.
35
36       Primitive type          Type       Description/Example
37       -------------------------------------------------------------------
38       as                      Bucket     Autonomous System Number.
39                                          600,159,3112
40
41       ip-address-prefix-len   Numeric    Integer from 0 to 32.
42                                          16-31
43
44       ip-protocol             Bucket     Integer from 0 to 255.
45                                          6,17,1
46
47       ip-tos                  Bucket     Integer from 0 to 255 with mask.
48                                          0xA0/0xE0
49
50       ip-tcp-flags            Bucket     Integer from 0 to 255 with mask.
51                                          0x2/0x2
52
53       ifindex                 Bucket     Integer from 0 to 65535
54                                          0,5,10
55
56       engine                  Bucket     Integer from 0 to 255.
57                                          0
58
59       ip-port                 Bucket     Integer from 0 to 65535.
60                                          80,8080,23,22
61
62       ip-address              Hash       List of IP Addresses.
63                                          10.0.0.1
64
65       ip-address-mask         List       List of IP address/mask pairs.
66                                          10.1.0.0 255.255.0.0
67
68       ip-address-prefix       Trie       List of IP address/mask pairs.
69                                          10.1/16
70
71       tag                     Hash       List of tags.
72                                          0xFF00
73
74       tag-mask                List       List of tags.
75                                          0xF000/0xFF00
76
77       counter                 List       List of Integers with qualifier.
78                                          lt 32
79
80       time                    List       List of relative time specifiers.
81                                          gt 5:00
82
83       time-date               List       List of absolute time specifiers.
84                                          gt December 12, 2002 5:13:21
85
86       double                  List       List of doubles with qualifier.
87                                          lt 32.0
88
89       rate                    Element    Rate is calculated as 1/rate.
90                                          permit 100
91
92
93
94       Match type              Description             Primitives accepted
95       -------------------------------------------------------------------
96       source-as               Source AS               as
97
98       destination-as          Destination AS          as
99
100       ip-source-address       Source IP Address       ip-address,
101                                                       ip-address-mask,
102                                                       ip-address-prefix
103
104       ip-destination-address  Destination IP Address  ip-address,
105                                                       ip-address-mask,
106                                                       ip-address-prefix
107
108       ip-exporter-address     Exporter IP Address     ip-address,
109                                                       ip-address-mask,
110                                                       ip-address-prefix
111
112       ip-nexthop-address      NextHop IP Address      ip-address,
113                                                       ip-address-mask,
114                                                       ip-address-prefix
115
116       ip-shortcut-address     Shortcut IP Address     ip-address,
117                                                       ip-address-mask,
118                                                       ip-address-prefix
119
120       ip-protocol             IP Protocol             ip-protocol
121
122       ip-source-address-prefix-len
123                               Source IP address       ip-address-prefix-len
124                               prefix length
125
126       ip-destination-address-prefix-len
127                               Destination IP address  ip-address-prefix-len
128                               prefix length
129
130       ip-tos                  IP Type Of Service      ip-tos
131
132       ip-marked-tos           IP Type Of Service      ip-tos
133
134       ip-tcp-flags            IP/TCP Flags            ip-tcp-flags
135
136       ip-source-port          Source IP Port          ip-port
137                               eg TCP/UDP
138
139       ip-destination-port     Destination IP Port     ip-port
140                               eg TCP/UDP
141
142       input-interface         Source ifIndex          ifindex
143                               eg Input Interface
144
145       output-interface        Destination ifIndex     ifindex
146                               eg Output Interface
147
148       start-time              Start Time of flow      time, time-date
149
150       end-time                End Time of Flow        time, time-date
151
152       flows                   Number of flows         counter
153
154       octets                  Number of octets        counter
155
156       packets                 Number of packets       counter
157
158       duration                Duration of flow in ms  counter
159
160       engine-id               Engine ID               engine
161
162       engine-type             Engine Type             engine
163
164       source-tag              Source Tag              tag, tag-mask
165
166       destination-tag         Destination Tag         tag, tag-mask
167
168       pps                     Packets Per Second      double
169
170       bps                     Bits Per Second         double
171
172       random-sample           Random Sample           rate
173
174

OPTIONS

176       -b big|little
177              Byte order of output.
178
179       -C Comment
180              Add a comment.
181
182       -d debug_level
183              Enable debugging.
184
185       -f filter_fname
186              Filter list filename. Defaults to /etc/flow-tools/cfg/filter.
187
188       -F filter_definition
189              Select the active definition. Defaults to default.
190
191       -h     Display help.
192
193       -k     Keep time from input.
194
195       -v variable binding
196              Set a variable FOO=bar.
197
198       -z z_level
199              Configure  compression level to  z_level. 0 is disabled (no com‐
200              pression), 9 is highest compression.
201

TIME/DATE PARSING

203       time-date parsing is implemented with getdate.y, a commonly used  func‐
204       tion to process free-form time date specifications.  Example usage bor‐
205       rowed from cvs: 1 month ago 2 hours ago 400000 seconds  ago  last  year
206       last  Monday yesterday a fortnight ago 3/31/92 10:00:07 PST January 23,
207       1987 10:05pm 22:00 GMT
208

EXAMPLES

210       An example of filter configuration file.
211
212
213       filter-primitive srate
214         type rate
215         permit 100
216
217       filter-primitive test-as
218         type as
219         permit 600,159
220
221       filter-primitive test-prefix-len
222         type ip-address-prefix-len
223         permit 32
224
225       filter-primitive test-protocol
226         type ip-protocol
227         permit tcp
228
229       filter-primitive test-tos
230         type ip-tos
231         mask 0xA0
232         permit 0xE0
233
234       filter-primitive test-tcp-flags
235         type ip-tcp-flags
236         mask 0x2
237         permit 0x2
238
239       filter-primitive test-ifindex
240         type ifindex
241         permit 0,5,10
242
243       filter-primitive test-engine
244         type engine
245         permit 0
246
247       filter-primitive test-port
248         type ip-port
249         permit https
250         permit 80
251         default deny
252
253       filter-primitive test-address
254         type ip-address
255         permit 0.0.0.1
256         permit 0.0.0.2
257         default deny
258
259       filter-primitive test-address-mask
260         type ip-address-mask
261         permit 128.146.197.1 255.255.255.255
262         permit 128.146.197.2 255.255.255.255
263
264       filter-primitive test-prefix
265         type ip-address-prefix
266         permit 128.146.0.0/16
267         default deny
268
269       filter-primitive test-tag
270         type tag
271         permit 0x00
272         permit 0x01
273         permit 0xFF
274
275       filter-primitive test-tag-mask
276         type tag-mask
277         permit OSU 0xFF
278         permit 0xFF 0xFF
279         default deny
280
281       filter-primitive test-counter
282         type counter
283         permit lt 5
284         permit gt 10
285         default deny
286
287       filter-primitive test-time-date
288         type time-date
289         permit gt December 12, 2002 5:13:21
290
291       filter-primitive test-time
292         type time-date
293         permit gt 12:15:00
294
295       filter-definition sample-1-in-100
296         match random-sample srate
297
298       filter-definition t1
299         match engine-type test-engine
300         or
301         match destination-tag test-tag-mask
302
303
304       Display all flows with a destination port of 80 or source  port  of  25
305       (smtp) starting after Dec 12, 2001. The file test is populated with the
306       following:
307
308       filter-primitive port80
309         type ip-port
310         permit 80
311
312       filter-primitive port25
313         type ip-port
314         permit smtp
315
316       filter-primitive dec12
317         type time-date
318         permit gt Dec 12, 2001
319
320       filter-definition foo
321         match ip-source-port port80
322         match start-time dec12
323         or
324         match ip-destination-port port25
325         match start-time dec12
326
327       flow-cat flows | flow-nfilter -ftest -Ffoo | flow-print
328

FILES

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

BUGS

334       None known.
335

AUTHOR

337       Mark Fullmer <maf@splintered.net>
338

SEE ALSO

340       flow-tools(1)
341
342
343
344                                26 Август 2010                 FLOW-NFILTER(1)
Impressum