flow-tag(1)

NAME
flow-tag — Apply tags to flow files.

SYNOPSIS

flow-tag [-hk] [-b big|little] [-C comment] [-d debug_level] [-t tag_fname] [-T active_def|active_def,active_def ...]

DESCRIPTION

The flow-tag utility is used to add or modify source and destination tags in flow records. Tags are 32 bit identifiers derived from rules and fields in a flow record. Tags can be used to group flows with common prefixes, autonomous systems, next hops, exporter id and/or input/output interface. flow-stat can be used with tagged flows to produce group based reports. For example, all outbound traffic for a customer where the customer is defined by a list of IP prefixes.

OPTIONS

-b big|little
    Byte order of output.

-C Comment
    Add a comment.

-d debug_level
    Enable debugging.

-h  Display help.

-k  Keep time from input.

-t tag_fname
    Load tags from tag_name. Defaults to /usr/local/etc/flow-tools/tag

-T active_def|active_def,active_def...
    Use active_def as the active tag definition(s).

The configuration file is a collection of actions and definitions. An action is triggered by a definition and a definition is invoked only if listed with the -T flag. Lines begining with # are treated as comments and ignored.

tag-action command                  Description
----------------------------------------------------------------------
tag-action                          Begin tag-action section
                                    tag-action foo
type                                Configure the type of action, one of
                                    src-prefix, dst-prefix, prefix,
                                    src-as, dst-as, as, next-hop.
                                    type src-prefix
match                               Match criteria.  The match condition
                                    depends on the type.  Following the
                                    match condition is one of
                                    set-dst, set-src, or-dst, or-src to
                                    set or logically or a value to the
                                    source or destination tag.
                                    match 128.146/16 set-dst 0x010001

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 actions evaluated if the filter is passed.

definition command                  Description
-----------------------------------------------------------------------
tag-definition                      Begin tag-defintion secrion
                                    tag-definition bar
term                                Begin a list of actions to be
                                    evaluated that match the filter
                                    rule.
                                    term
input-filter                        List of input ifIndexes the flow
                                    must match.
                                    input-filter 1,2,3,4
output-filter                       List of output ifIndexes the flow
                                    must match.
                                    output-filter 1,2,3,4
exporter                            IP address of exporter the flow must
                                    match.
                                    exporter 1.2.3.4
action                              Name of action to evaluate.  Actions
                                    are evaluated in the order they
                                    appear in a definition.
                                    action foo

EXAMPLES

The meaning of a tag is user defined. The following example uses 16 bits of a tag as a customer ID and 4 bits as a customer type. flow-xlate can be used to apply a mask to these fields.

# 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 dst-prefix
# OSU
 match 128.146/16 set-dst     0x010001
 match 164.107/16 set-dst     0x010001
 match 140.254/16 set-dst     0x010001
 match 192.153.26/24 set-dst  0x010001
# CWRU
 match 129.22/16 set-dst      0x010002
 match 192.5.110/24 set-dst   0x010002
# BGSU
 match 129.1/16 set-dst       0x010003
# ...etc
# MULTICAST
 match 224/4 set-dst 0x050019
tag-action OHIO-GIGAPOP_SRC
 type src-prefix
# OSU
 match 128.146/16 set-src     0x010001
 match 164.107/16 set-src     0x010001
 match 140.254/16 set-src     0x010001
 match 192.153.26/24 set-src  0x010001
# CWRU
 match 129.22/16 set-src      0x010002
 match 192.5.110/24 set-src   0x010002
# BGSU
 match 129.1/16 set-src       0x010003
# ...etc
tag-action OTHER_DST
 type dst-prefix
 match 0/0 set-dst 0x0

tag-action OTHER_SRC
 type src-prefix
 match 0/0 set-src 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 populate /usr/local/share/flow-tools/tag for flow-stat to use as symbols.

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

To generate a report for outgoing traffic to Abilene based on customer ID:

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

#  --- ---- ---- 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

To generate a report for inbound traffic from Abilene based on customer type:

flow-cat flows | flow-filter -i25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP_DST | 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

BUGS

None known.

AUTHOR

Mark Fullmer maf@splintered.net

SEE ALSO

flow-tools(1)