FLOW-NFILTER(1)

💖 FLOW-NFILTER(1) 💖

okay bestie, welcome to flow-nfilter — she's a section 1 manual page and she FILTERS FLOWS. let's get into it, no cap. ✨

---

✨ 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 🦋

okay so flow-nfilter filters flows based on criteria you pick. it's giving choose-your-own-adventure but for network flows. 💅

Filters live in a configuration file, and they're made of two things: primitives and a definition. Definitions contain match lines grouped together to form logical AND and OR operations on the flow, using the primitives you selected. A definition may also contain the invert command, which inverts the result of the evaluation. (iconic, honestly.)

Words in the configuration file of the form @VAR or @{VAR:default} get expanded at run-time by setting variable names with the -v option. variable girlies rise up 🌸

Filter primitives begin with the filter-primitive keyword followed by a symbolic name. Each primitive has a type, defined below. Then a list of permit and or deny keywords followed by an argument get evaluated later to figure out if the flow is permitted or denied. The default action for a primitive is to deny, which you can change 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. versatile queen 💅

🌈 Primitive types

• as — Bucket — Autonomous System Number. e.g. 600,159,3112
• ip-address-prefix-len — Numeric — Integer from 0 to 32. e.g. 16-31
• ip-protocol — Bucket — Integer from 0 to 255. e.g. 6,17,1
• ip-tos — Bucket — Integer from 0 to 255 with mask. e.g. 0xA0/0xE0
• ip-tcp-flags — Bucket — Integer from 0 to 255 with mask. e.g. 0x2/0x2
• ifindex — Bucket — Integer from 0 to 65535. e.g. 0,5,10
• engine — Bucket — Integer from 0 to 255. e.g. 0
• ip-port — Bucket — Integer from 0 to 65535. e.g. 80,8080,23,22
• ip-address — Hash — List of IP Addresses. e.g. 10.0.0.1
• ip-address-mask — List — List of IP address/mask pairs. e.g. 10.1.0.0 255.255.0.0
• ip-address-prefix — Trie — List of IP address/mask pairs. e.g. 10.1/16
• tag — Hash — List of tags. e.g. 0xFF00
• tag-mask — List — List of tags. e.g. 0xF000/0xFF00
• counter — List — List of Integers with qualifier. e.g. lt 32
• time — List — List of relative time specifiers. e.g. gt 5:00
• time-date — List — List of absolute time specifiers. e.g. gt December 12, 2002 5:13:21
• double — List — List of doubles with qualifier. e.g. lt 32.0
• rate — Element — Rate is calculated as 1/rate. e.g. permit 100

💜 Match types

• source-as — Source AS — primitives accepted: as
• destination-as — Destination AS — primitives accepted: as
• ip-source-address — Source IP Address — primitives accepted: ip-address, ip-address-mask, ip-address-prefix
• ip-destination-address — Destination IP Address — primitives accepted: ip-address, ip-address-mask, ip-address-prefix
• ip-exporter-address — Exporter IP Address — primitives accepted: ip-address, ip-address-mask, ip-address-prefix
• ip-nexthop-address — NextHop IP Address — primitives accepted: ip-address, ip-address-mask, ip-address-prefix
• ip-shortcut-address — Shortcut IP Address — primitives accepted: ip-address, ip-address-mask, ip-address-prefix
• ip-protocol — IP Protocol — primitives accepted: ip-protocol
• ip-source-address-prefix-len — Source IP address prefix length — primitives accepted: ip-address-prefix-len
• ip-destination-address-prefix-len — Destination IP address prefix length — primitives accepted: ip-address-prefix-len
• ip-tos — IP Type Of Service — primitives accepted: ip-tos
• ip-marked-tos — IP Type Of Service — primitives accepted: ip-tos
• ip-tcp-flags — IP/TCP Flags — primitives accepted: ip-tcp-flags
• ip-source-port — Source IP Port eg TCP/UDP — primitives accepted: ip-port
• ip-destination-port — Destination IP Port eg TCP/UDP — primitives accepted: ip-port
• input-interface — Source ifIndex eg Input Interface — primitives accepted: ifindex
• output-interface — Destination ifIndex eg Output Interface — primitives accepted: ifindex
• start-time — Start Time of flow — primitives accepted: time, time-date
• end-time — End Time of Flow — primitives accepted: time, time-date
• flows — Number of flows — primitives accepted: counter
• octets — Number of octets — primitives accepted: counter
• packets — Number of packets — primitives accepted: counter
• duration — Duration of flow in ms — primitives accepted: counter
• engine-id — Engine ID — primitives accepted: engine
• engine-type — Engine Type — primitives accepted: engine
• source-tag — Source Tag — primitives accepted: tag, tag-mask
• destination-tag — Destination Tag — primitives accepted: tag, tag-mask
• pps — Packets Per Second — primitives accepted: double
• bps — Bits Per Second — primitives accepted: double
• random-sample — Random Sample — primitives accepted: 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. (she's flexible, we love her 🫶)

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

and then, the moment you've all been waiting for:

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

ate. 🔥

---

🍓 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. (she's perfect, we been knew 💅)

---

🧚 AUTHOR 🧚

Mark Fullmer <maf@splintered.net>

---

💜 SEE ALSO 💜

flow-tools(1)

---

and that's the whole page bestie!! ✨ this was manual page FLOW-NFILTER(1), dated 26 Август 2010, straight outta the flow-tools source. tysm for reading, go filter some flows, mwah 🫶💖