1<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 2<refentry> 3 4<refmeta> 5<refentrytitle> 6<application>flow-tag</application> 7</refentrytitle> 8<manvolnum>1</manvolnum> 9</refmeta> 10 11<refnamediv> 12<refname> 13<application>flow-tag</application> 14</refname> 15<refpurpose> 16Apply tags to flow files. 17</refpurpose> 18</refnamediv> 19 20<refsynopsisdiv> 21<cmdsynopsis> 22<command>flow-tag</command> 23<arg>-hk</arg> 24<arg>-b<replaceable> big</replaceable>|<replaceable>little</replaceable></arg> 25<arg>-C<replaceable> comment</replaceable></arg> 26<arg>-d<replaceable> debug_level</replaceable></arg> 27<arg>-t<replaceable> tag_fname</replaceable></arg> 28<arg>-T<replaceable> tag_definition</replaceable></arg> 29<arg>-v<replaceable> variable binding</replaceable></arg> 30</cmdsynopsis> 31</refsynopsisdiv> 32 33<refsect1> 34<title>DESCRIPTION</title> 35<para> 36The <command>flow-tag</command> utility is used to add or modify 37source and destination tags in flow records. Tags are 32 bit 38identifiers derived from rules and fields in a flow record. Tags 39can be used to group flows with common prefixes, autonomous systems, 40next hops, exporter id and/or input/output interface. 41<command>flow-stat</command> can be used with tagged flows to produce 42group based reports. For example, all outbound traffic for a customer 43where the customer is defined by a list of IP prefixes. 44</para> 45</refsect1> 46 47<refsect1> 48<title>OPTIONS</title> 49<variablelist> 50 51<varlistentry> 52<term>-b<replaceable> big</replaceable>|<replaceable>little</replaceable</term> 53<listitem> 54<para> 55Byte order of output. 56</para> 57</listitem> 58</varlistentry> 59 60<varlistentry> 61<term>-C<replaceable> Comment</replaceable></term> 62<listitem> 63<para> 64Add a comment. 65</para> 66</listitem> 67</varlistentry> 68 69<varlistentry> 70<term>-d<replaceable> debug_level</replaceable></term> 71<listitem> 72<para> 73Enable debugging. 74</para> 75</listitem> 76</varlistentry> 77 78<varlistentry> 79<term>-h</term> 80<listitem> 81<para> 82Display help. 83</para> 84</listitem> 85</varlistentry> 86 87<varlistentry> 88<term>-k</term> 89<listitem> 90<para> 91Keep time from input. 92</para> 93</listitem> 94</varlistentry> 95 96<varlistentry> 97<term>-t<replaceable> tag_fname</replaceable></term> 98<listitem> 99<para> 100Load tags from <filename>tag_name</filename>. Defaults to 101<filename>/usr/local/etc/flow-tools/tag</filename> 102</para> 103</listitem> 104</varlistentry> 105 106<varlistentry> 107<term>-T<replaceable> active_def</replaceable>|</term> 108<listitem> 109<para> 110Use <replaceable>active_def</replaceable> as the active tag definition(s). 111</para> 112</listitem> 113</varlistentry> 114 115<varlistentry> 116<term>-v<replaceable> variable binding</replaceable></term> 117<listitem> 118<para> 119Set a variable FOO=bar. 120</para> 121</listitem> 122</varlistentry> 123</variablelist> 124 125<para> 126</para> 127<para> 128The configuration file is a collection of actions and definitions. An 129action is triggered by a definition and a definition is invoked only 130if listed with the <replaceable>-T</replaceable> flag. Lines begining 131with # are treated as comments and ignored. 132</para> 133<para> 134Words in the configuration file of the form @VAR or @{VAR:default} will be 135expanded at run-time by setting variable names with the -v option. 136</para> 137<para> 138<screen> 139tag-action command Description/Example 140---------------------------------------------------------------------- 141tag-action Begin tag-action section 142 tag-action foo 143 144type Configure the type of action, one of 145 source-prefix, destination-prefix, prefix, 146 source-as, destination-as, as, next-hop, 147 tcp-source-port, tcp-destination-port, 148 tcp-port, udp-source-port, 149 udp-destination-port, udp-port, 150 tos, exporter, source-ip-address, 151 destination-ip-address, ip-address, 152 input-interface, output-interface, 153 interface, any. 154 type src-prefix 155 156match Match criteria. The match condition 157 depends on the type. Following the 158 match condition is one of 159 set-destination, set-source, 160 or-destination, or-source to 161 set or logically or a value to the 162 source or destination tag. 163 match 128.146/16 set-destination 0x010001 164 165Multiple actions may match and set tags on the same flow. Note that 166listing many actions will cause tags to be applied in O(actions) time. 167The actions try to run in O(1) time. For example if 10 prefixes are 168listed in a single action it will take about the same CPU as if 100 169prefixes are used. Listing 100 actions will require 100 times the 170CPU as 1 action. 171 172 173tag-action types Description 174---------------------------------------------------------------------- 175 176source-prefix Source Prefix 177 178destination-prefix Destination Prefix 179 180prefix Source or Destination Prefix 181 182source-as Source AS 183 184destination-as Destination AS 185 186as Source or Destination AS 187 188next-hop IP Next Hop 189 190tcp-source-port TCP Source Port 191 192tcp-destination-port TCP Destination Port 193 194tcp-port TCP Source or Destination Port 195 196udp-source-port UDP Source Port 197 198udp-destination-port UDP Destination Port 199 200udp-port UDP Source or Destination Port 201 202tos Type of Service 203 204exporter Exporter IP Address 205 206source-ip-address Source IP Address 207 208destination-ip-address Destination IP Address 209 210ip-address Source or Destination IP Address 211 212input-interface Input Interface 213 214output-interface Output Interface 215 216interface Input or Output Interface 217 218any Match any flows 219 220 221tag-action matches Description 222---------------------------------------------------------------------- 223 224set-destination Set the destination tag, replacing 225 any previous tag. 226 227set-source Set the source tag, replacing any 228 previous tag. 229 230or-destination Logically or this value to the 231 existing destination tag 232 233or-source Logically or this value to the 234 existing source tag 235 236 237</screen> 238</para> 239<para> 240A definition lists a set of actions which are evaluated if the filter 241criteria is met. Each definition is built with terms. A term has 242its action(s) evaluated if the filter is passed. 243<screen> 244definition command Description/Example 245----------------------------------------------------------------------- 246tag-definition Begin tag-defintion secrion 247 tag-definition bar 248 249term Begin a list of actions to be 250 evaluated that match the filter 251 rule. 252 term 253 254input-filter List of input ifIndexes the flow 255 must match. 256 input-filter 1,2,3,4 257 258output-filter List of output ifIndexes the flow 259 must match. 260 output-filter 1,2,3,4 261 262exporter IP address of exporter the flow must 263 match. 264 exporter 1.2.3.4 265 266action Name of action to evaluate. Actions 267 are evaluated in the order they 268 appear in a definition. 269 action foo 270 271</screen> 272</para> 273<para> 274</para> 275</refsect1> 276 277<refsect1> 278<title>EXAMPLES</title> 279<informalexample> 280<para> 281The meaning of a tag is user defined. The following example uses 28216 bits of a tag as a customer ID and 4 bits as a customer type. 283<command>flow-xlate</command> can be used to apply a mask to these 284fields. 285<programlisting> 286# file: gigapop-tags 287# tag format 288# 289# 0 7 15 23 31 290# 0000 0000 0000 0000 0000 0000 0000 0000 (32 bits) 291# RRRRRRRRRRRRRR TTTT NNNNNNNNNNNNNNNNNNN 292# | | | Site name 293# | | Site type 294# | Reserved 295# 296# 297# SITE_NAME_MASK = 0x0000FFFF 298# SITE_TYPE_MASK = 0x00FF0000 299# 300# ID Name 301#--------------------------------- 302# 0x0001 OSU 303# 0x0002 CWRU 304# 0x0003 BGSU 305# ... etc 306# 0x0019 MULTICAST 307# 308# ID Type 309#------------------------ 310# 0x01 Participant 311# 0x02 SEGP 312# 0x03 Sponsored-Participant 313# 0x04 Gigapop 314# 0x05 MULTICAST 315 316tag-action OHIO-GIGAPOP_DST 317 type destination-prefix 318# OSU 319 match 128.146/16 set-destination 0x010001 320 match 164.107/16 set-destination 0x010001 321 match 140.254/16 set-destination 0x010001 322 match 192.153.26/24 set-destination 0x010001 323# CWRU 324 match 129.22/16 set-destination 0x010002 325 match 192.5.110/24 set-destination 0x010002 326# BGSU 327 match 129.1/16 set-destination 0x010003 328# ...etc 329# MULTICAST 330 match 224/4 set-destination 0x050019 331 332tag-action OHIO-GIGAPOP_SRC 333 type source-prefix 334# OSU 335 match 128.146/16 set-source 0x010001 336 match 164.107/16 set-source 0x010001 337 match 140.254/16 set-source 0x010001 338 match 192.153.26/24 set-source 0x010001 339# CWRU 340 match 129.22/16 set-source 0x010002 341 match 192.5.110/24 set-source 0x010002 342# BGSU 343 match 129.1/16 set-source 0x010003 344# ...etc 345 346tag-action OTHER_DST 347 type destination-prefix 348 match 0/0 set-destination 0x0 349 350tag-action OTHER_SRC 351 type source-prefix 352 match 0/0 set-source 0x0 353 354tag-definition OHIO-GIGAPOP 355 term 356# Abilene interface 357 input-filter 25 358# clear tag first -- it defaults to 0, so this may not be necessary. 359 action OTHER_DST 360 action OHIO-GIGAPOP_DST 361 term 362# Abilene interface 363 output-filter 25 364# clear tag first -- it defaults to 0, so this may not be necessary. 365 action OTHER_SRC 366 action OHIO-GIGAPOP_SRC 367 368</programlisting> 369</para> 370<para> 371First populate <filename>/usr/local/etc/flow-tools/tag</filename> for <command>flow-stat</command> to use as symbols. 372<programlisting> 3730x0001 OSU 3740x0002 CWRU 3750x0003 BGSU 3760x0019 MULTICAST 3770x010000 PART 3780x020000 SEGP 3790x030000 SPART 3800x040000 GIGAPOP 3810x050000 MULTICAST 382</programlisting> 383</para> 384<para> 385To generate a report for outgoing traffic to Abilene based on customer ID: 386<programlisting> 387flow-cat <filename>flows</filename> | flow-filter -I25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -t0x0000FFFF | flow-stat -n -f30 -S2 388</programlisting> 389<screen> 390# --- ---- ---- Report Information --- --- --- 391# 392# Fields: Total 393# Symbols: Enabled 394# Sorting: Descending Field 2 395# Name: Source Tag 396# 397# Args: ../flow-stat -n -f30 -S2 398# 399# 400# Src Tag flows octets packets 401# 402OSU 4942230 181326237007 302476793 403CWRU 874883 54358312807 70589318 404BGSU 1008797 7600209852 22060870 405</screen> 406</para> 407<para> 408To generate a report for inbound traffic from Abilene based on customer type: 409<programlisting> 410flow-cat <filename>flows</filename> | flow-filter -i25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -T0xFF0000 | flow-stat -n -f31 -S2 411</programlisting> 412<screen> 413# --- ---- ---- Report Information --- --- --- 414# 415# Fields: Total 416# Symbols: Enabled 417# Sorting: Descending Field 2 418# Name: Destination Tag 419# 420# Args: ../flow-stat -n -f31 -S2 421# 422# 423# Dst Tag flows octets packets 424# 425PART 15923156 663289954569 981163979 426SEGP 4995795 135525076170 196534917 427MULTICAST 45171 49866825003 137798118 428GIGAPOP 942209 26422533266 23199961 429SPART 73998 5170323905 7597985 430</screen> 431</para> 432</informalexample> 433</refsect1> 434 435<refsect1> 436<title>FILES</title> 437<para> 438 Configuration files: 439 Symbols - <filename>/usr/local/etc/flow-tools/*</filename>. 440 Tag - <filename>/usr/local/etc/flow-tools/tag.cfg</filename>. 441</para> 442</refsect1> 443 444 445<refsect1> 446<title>BUGS</title> 447<para> 448None known. 449</para> 450</refsect1> 451 452<refsect1> 453<title>AUTHOR</title> 454<para> 455<author> 456<firstname>Mark</firstname> 457<surname>Fullmer</surname> 458</author> 459<email>maf@splintered.net</email> 460</para> 461</refsect1> 462 463<refsect1> 464<title>SEE ALSO</title> 465<para> 466<application>flow-tools</application>(1) 467</para> 468</refsect1> 469 470</refentry> 471