Provided by: flow-tools_0.68-12.1build1_amd64 bug

flow-tag(1)                          General Commands Manual                          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
       tag_definition]  [-v variable binding]

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 /etc/flow-tools/cfg/tag

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

       -v variable binding
                 Set a variable FOO=bar.

       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.

       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.

       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

       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.

       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

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 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 populate /etc/flow-tools/sym/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 | 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 | 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.

AUTHOR

       Mark Fullmer maf@splintered.net

SEE ALSO

       flow-tools(1)

                                                                                      flow-tag(1)