FLOW-TAG(1)

okay so bestie, pull up a chair, we're learning flow-tag(1) today and honestly? it's giving main character energy. this is the tool that slaps tags on your flow files so everything downstream can be cute and organized. let's go 💖

---

🌸 NAME 🌸

flow-tag — apply tags to flow files. no cap, that's the whole job. 💅

---

✨ SYNOPSIS ✨

flow-tag [ -hk ]  [ -b big|little ]  [ -C comment ]  [ -d debug_level ]
[ -t tag_fname ]  [ -T tag_definition ]  [ -v variable binding ]

---

🦋 DESCRIPTION 🦋

so the flow-tag utility is what you use to add or modify source and destination tags inside flow records. and what even is a tag? bestie, a tag is a 32 bit identifier derived from rules and fields in a flow record. periodt.

tags let you group flows that share stuff in common — prefixes, autonomous systems, next hops, exporter id and/or input/output interface. and then flow-stat can be used with tagged flows to produce group based reports. like, imagine: all outbound traffic for a customer, where the customer is defined by a list of IP prefixes. iconic. 👑

---

💅 OPTIONS 💅

• -b big|little — byte order of the output. pick your fighter.
• -C Comment — add a comment. drop a little note, why not.
• -d debug_level — enable debugging. turn the volume up on the inner workings.
• -h — display help. when in doubt, ask the tool itself 🫶
• -k — keep time from input. don't touch the timestamps, they're fine as they are.
• -t tag_fname — load tags from tag_name. defaults to /etc/flow-tools/cfg/tag. that's the default, memorise it iykyk.
• -T active_def| — use active_def as the active tag definition(s).
• -v variable binding — set a variable FOO=bar. yes, that exact shape.

---

💫 OPTIONS, part 2: the configuration file 💫

the config file is literally just a collection of actions and definitions. here's the tea:

• an action is triggered by a definition
• a definition is invoked only if it's listed with the -T flag
• lines that start with # are treated as comments and ignored, bye ✌️

words in the configuration file shaped like @VAR or @{VAR:default} get expanded at run-time, and you set those variable names with the -v option. cute, right?

---

🎀 tag-action commands 🎀

• tag-action command — begin tag-action section. example: tag-action foo
• type — configure the type of action, one of: source-prefix, destination-prefix, prefix, source-as, destination-as, as, next-hop, tcp-source-port, tcp-destination-port, tcp-port, udp-source-port, udp-destination-port, udp-port, tos, exporter, source-ip-address, destination-ip-address, ip-address, input-interface, output-interface, interface, any. example: type src-prefix
• match — match criteria. the match condition depends on the type. following the match condition is one of set-destination, set-source, or-destination, or-source, to set or logically or a value to the source or destination tag. example: match 128.146/16 set-destination 0x010001

heads up bestie: multiple actions may match and set tags on the same flow. and the way that listing many actions will cause tags to be applied in O(actions) time… the actions try to run in O(1) time. for example, if 10 prefixes are listed in a single action it will take about the same CPU as if 100 prefixes are used. listing 100 actions will require 100 times the CPU as 1 action. so like… group them, queen. 🔥

---

🌈 tag-action types 🌈

• source-prefix — Source Prefix
• destination-prefix — Destination Prefix
• prefix — Source or Destination Prefix
• source-as — Source AS
• destination-as — Destination AS
• as — Source or Destination AS
• next-hop — IP Next Hop
• tcp-source-port — TCP Source Port
• tcp-destination-port — TCP Destination Port
• tcp-port — TCP Source or Destination Port
• udp-source-port — UDP Source Port
• udp-destination-port — UDP Destination Port
• udp-port — UDP Source or Destination Port
• tos — Type of Service
• exporter — Exporter IP Address
• source-ip-address — Source IP Address
• destination-ip-address — Destination IP Address
• ip-address — Source or Destination IP Address
• input-interface — Input Interface
• output-interface — Output Interface
• interface — Input or Output Interface
• any — Match any flows

---

🦋 tag-action matches 🦋

• set-destination — set the destination tag, replacing any previous tag. out with the old 🫶
• set-source — set the source tag, replacing any previous tag.
• or-destination — logically or this value to the existing destination tag
• or-source — logically or this value to the existing source tag

---

🧚 definitions (the plot thickens) 🧚

a definition lists a set of actions which are evaluated if the filter criteria is met. each definition is built with terms. a term has its action(s) evaluated if the filter is passed. slay.

📓 definition commands 📓

• tag-definition command — begin tag-defintion secrion. example: tag-definition bar
• term — begin a list of actions to be evaluated that match the filter rule. example: term
• input-filter — list of input ifIndexes the flow must match. example: input-filter 1,2,3,4
• output-filter — list of output ifIndexes the flow must match. example: output-filter 1,2,3,4
• exporter — IP address of exporter the flow must match. example: exporter 1.2.3.4
• action — name of action to evaluate. actions are evaluated in the order they appear in a definition. example: action foo

The meaning of a tag is, and I cannot stress this enough, completely up to you. It's your tag, your rules, bestie. 💅

The example below uses 16 bits of a tag as a customer ID and 4 bits as a customer type. And flow-xlate can be used to apply a mask to these fields. Slay.

# file: gigapop-tags
# tag format
#
# 0       7         15        23        31
# 0000 0000 0000 0000 0000 0000 0000 0000 (32 bits)
# RRRRRRRRRRRRRR TTTT NNNNNNNNNNNNNNNNNNN
#              |    |                   | Site name
#              |    | Site type
#              | Reserved
#
#
# SITE_NAME_MASK = 0x0000FFFF
# SITE_TYPE_MASK = 0x00FF0000
#
# ID             Name
#---------------------------------
# 0x0001         OSU
# 0x0002         CWRU
# 0x0003         BGSU
# ... etc
# 0x0019         MULTICAST
#
# ID             Type
#------------------------
# 0x01         Participant
# 0x02         SEGP
# 0x03         Sponsored-Participant
# 0x04         Gigapop
# 0x05         MULTICAST

tag-action OHIO-GIGAPOP_DST
 type destination-prefix
# OSU
 match 128.146/16 set-destination     0x010001
 match 164.107/16 set-destination     0x010001
 match 140.254/16 set-destination     0x010001
 match 192.153.26/24 set-destination  0x010001
# CWRU
 match 129.22/16 set-destination      0x010002
 match 192.5.110/24 set-destination   0x010002
# BGSU
 match 129.1/16 set-destination       0x010003
# ...etc
# MULTICAST
 match 224/4 set-destination 0x050019

tag-action OHIO-GIGAPOP_SRC
 type source-prefix
# OSU
 match 128.146/16 set-source     0x010001
 match 164.107/16 set-source     0x010001
 match 140.254/16 set-source     0x010001
 match 192.153.26/24 set-source  0x010001
# CWRU
 match 129.22/16 set-source      0x010002
 match 192.5.110/24 set-source   0x010002
# BGSU
 match 129.1/16 set-source       0x010003
# ...etc

tag-action OTHER_DST
 type destination-prefix
 match 0/0 set-destination 0x0

tag-action OTHER_SRC
 type source-prefix
 match 0/0 set-source 0x0

tag-definition OHIO-GIGAPOP
 term
# Abilene interface
 input-filter 25
# clear tag first -- it defaults to 0, so this may not be necessary.
 action OTHER_DST
 action OHIO-GIGAPOP_DST
 term
# Abilene interface
 output-filter 25
# clear tag first -- it defaults to 0, so this may not be necessary.
 action OTHER_SRC
 action OHIO-GIGAPOP_SRC

First, go populate /etc/flow-tools/sym/tag so that flow-stat has some symbols to use. 🎀

0x0001 OSU
0x0002 CWRU
0x0003 BGSU
0x0019 MULTICAST
0x010000 PART
0x020000 SEGP
0x030000 SPART
0x040000 GIGAPOP
0x050000 MULTICAST

---

Wanna generate a report for outgoing traffic to Abilene based on customer ID? Say less. 👑

flow-cat flows | flow-filter -I25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -t0x0000FFFF | flow-stat -n -f30 -S2

And that gives you, literally:

#  --- ---- ---- Report Information --- --- ---
#
# Fields:    Total
# Symbols:   Enabled
# Sorting:   Descending Field 2
# Name:      Source Tag
#
# Args:      ../flow-stat -n -f30 -S2
#
#
# Src Tag   flows                 octets                packets
#
OSU         4942230               181326237007          302476793
CWRU        874883                54358312807           70589318
BGSU        1008797               7600209852            22060870

---

Now for inbound traffic from Abilene based on customer type? Obsessed with this one, fr fr. 🦋

flow-cat flows | flow-filter -i25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -T0xFF0000 | flow-stat -n -f31 -S2

#  --- ---- ---- Report Information --- --- ---
#
# Fields:    Total
# Symbols:   Enabled
# Sorting:   Descending Field 2
# Name:      Destination Tag
#
# Args:      ../flow-stat -n -f31 -S2
#
#
# Dst Tag   flows                 octets                packets
#
PART        15923156              663289954569          981163979
SEGP        4995795               135525076170          196534917
MULTICAST   45171                 49866825003           137798118
GIGAPOP     942209                26422533266           23199961
SPART       73998                 5170323905            7597985

---

📁 FILES 📁

• Configuration files: Symbols — /etc/flow-tools/sym/*.
• Tag — /etc/flow-tools/cfg/tag.cfg.

---

🐛 BUGS 🐛

None known. Not a single one, bestie. We are thriving. ✨

---

👑 AUTHOR 👑

Mark Fullmer <maf@splintered.net> — an absolute legend, no cap. 🫶

---

🔮 SEE ALSO 🔮

• flow-tools(1)

---

Okay that's the whole page, you made it, I'm so proud of you. 🎀 This beauty is flow-tools, and it's dated 26 Август 2010. Go forth and tag your flows, main character. 💖🌈⭐