<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<refentry>

<refmeta>
<refentrytitle>
<application>flow-tag</application>
</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>
<application>flow-tag</application>
</refname>
<refpurpose>
Apply tags to flow files.
</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>flow-tag</command>
<arg>-hk</arg>
<arg>-b<replaceable> big</replaceable>|<replaceable>little</replaceable></arg>
<arg>-C<replaceable> comment</replaceable></arg>
<arg>-d<replaceable> debug_level</replaceable></arg>
<arg>-t<replaceable> tag_fname</replaceable></arg>
<arg>-T<replaceable> tag_definition</replaceable></arg>
<arg>-v<replaceable> variable binding</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
<title>DESCRIPTION</title>
<para>
The <command>flow-tag</command> 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.
<command>flow-stat</command> 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.
</para>
</refsect1>

<refsect1>
<title>OPTIONS</title>
<variablelist>

<varlistentry>
<term>-b<replaceable> big</replaceable>|<replaceable>little</replaceable</term>
<listitem>
<para>
Byte order of output.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-C<replaceable> Comment</replaceable></term>
<listitem>
<para>
Add a comment.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-d<replaceable> debug_level</replaceable></term>
<listitem>
<para>
Enable debugging.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-h</term>
<listitem>
<para>
Display help.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-k</term>
<listitem>
<para>
Keep time from input.
</para>
</listitem>  
</varlistentry>

<varlistentry>
<term>-t<replaceable> tag_fname</replaceable></term>
<listitem>
<para>
Load tags from <filename>tag_name</filename>.  Defaults to 
<filename>@localstatedir@/cfg/tag</filename>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-T<replaceable> active_def</replaceable>|</term>
<listitem>
<para>
Use <replaceable>active_def</replaceable> as the active tag definition(s).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-v<replaceable> variable binding</replaceable></term>
<listitem>
<para>
Set a variable FOO=bar.
</para>                       
</listitem>
</varlistentry>
</variablelist>

<para>
</para>
<para>
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 <replaceable>-T</replaceable> flag.  Lines begining
with # are treated as comments and ignored.
</para>
<para>
Words in the configuration file of the form @VAR or @{VAR:default} will be
expanded at run-time by setting variable names with the -v option.
</para>
<para>
<screen>
tag-action command            Description/Example
----------------------------------------------------------------------
tag-action                    Begin tag-action section
                              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.
                              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.
                              match 128.146/16 set-destination 0x010001

Multiple actions may match and set tags on the same flow.  Note 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.


tag-action types                    Description
----------------------------------------------------------------------

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

set-destination                     Set the destination tag, replacing
                                    any previous tag.

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


</screen>
</para>
<para>
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.
<screen>
definition command                  Description/Example
-----------------------------------------------------------------------
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

</screen>
</para>
<para>
</para>
</refsect1>

<refsect1>
<title>EXAMPLES</title>
<informalexample>
<para>
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.
<command>flow-xlate</command> can be used to apply a mask to these
fields.
<programlisting>
# 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

</programlisting>
</para>
<para>
First populate <filename>@localstatedir@/sym/tag</filename> for <command>flow-stat</command> to use as symbols.
<programlisting>
0x0001 OSU
0x0002 CWRU
0x0003 BGSU
0x0019 MULTICAST
0x010000 PART
0x020000 SEGP
0x030000 SPART
0x040000 GIGAPOP
0x050000 MULTICAST
</programlisting>
</para>
<para>
To generate a report for outgoing traffic to Abilene based on customer ID:
<programlisting>
flow-cat <filename>flows</filename> | flow-filter -I25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -t0x0000FFFF | flow-stat -n -f30 -S2
</programlisting>
<screen>
#  --- ---- ---- 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
</screen>
</para>
<para>
To generate a report for inbound traffic from Abilene based on customer type:
<programlisting>
flow-cat <filename>flows</filename> | flow-filter -i25 | flow-tag -t gigapop-tags -TOHIO-GIGAPOP | flow-xlate -T0xFF0000 | flow-stat -n -f31 -S2
</programlisting>
<screen>
#  --- ---- ---- 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
</screen>
</para>
</informalexample>
</refsect1>

<refsect1>
<title>FILES</title>
<para>
  Configuration files:
    Symbols - <filename>@localstatedir@/sym/*</filename>.
    Tag - <filename>@localstatedir@/cfg/tag.cfg</filename>.
</para>
</refsect1>


<refsect1>
<title>BUGS</title>
<para>
None known.
</para>
</refsect1>

<refsect1>
<title>AUTHOR</title>
<para>
<author>
<firstname>Mark</firstname>
<surname>Fullmer</surname>
</author>
<email>maf@splintered.net</email>
</para>
</refsect1>

<refsect1>
<title>SEE ALSO</title>
<para>
<application>flow-tools</application>(1)
</para>
</refsect1>

</refentry>
