flow-tag

Langue: en

Version: 262632 (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

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)