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

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

<refnamediv>
<refname>
<application>flow-xlate</application>
</refname>
<refpurpose>
Apply translations to selected fields of a flow.
</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>flow-xlate</command>
<arg>-hkn</arg>
<arg>-b<replaceable> big</replaceable>|<replaceable>little</replaceable></arg>
<arg>-C<replaceable> comment</replaceable></arg>
<arg>-d<replaceable> debug_level</replaceable></arg>
<arg>-v<replaceable> variable binding</replaceable></arg>
<arg>-V<replaceable> flow_version</replaceable></arg>
<arg>-x<replaceable> xlate_fname</replaceable></arg>
<arg>-X<replaceable> xlate_definition</replaceable></arg>
<arg>-z<replaceable> z_level</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>


<refsect1>
<title>DESCRIPTION</title>
<para>
The <command>flow-xlate</command> utility is used to apply translations
to flows.  Translations are defined in a configuration file and are
composed of actions and a definition to invoke action(s).  The definitions
are in the form of terms, each term can have a filter and multiple actions.
</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>
Translation actions begin with the xlate-action keyword followed by
a symbolic name.  Each action has a type defined below.
</para>
<para>
Translation definitions begin with the xlate-definition keyword followed
by a symbolic name.  Each definition is composed of terms which are
evaluated in the order of the configuration file.  A term may invoke
a filter to conditionally invoke an action.
</para>

<screen>
Action type/sub-commands                Description/Example
------------------------------------------------------------------------
ip-source-address-to-network            Zero host bits based on mask.
ip-destination-address-to-network       Zero host bits based on mask.

  (no sub-commands)

ip-source-address-to-class-network      Zero source host bits to
                                        match class.
ip-destination-address-to-class-network Zero dst host bits to
                                        match class.
                                      
  (no sub-commands)

ip-source-address-anonymize             Anonymize source address.
ip-destination-address-anonymize        Anonymize destination address.
ip-address-anonymize                    Anonymize src/dst address.


    algorithm                           Algorithm.  cryptopan-aes128 is
                                        currently supported.
                                         algorithm cryptopan-aes128

    key                                 Key.  Key is 128 bits in hex.
                                         key 0123456789ABCDEFG

    key-file                            File to load key from.  Key is
                                        128 bits in hex.
                                         key-file /mfstmp/secret-key

    key-file-refresh                    How often to check the key file.
                                        Interval is in minutes, the
                                        optional second argument is
                                        hour:min:sec to specify the
                                        first refresh.  This example
                                        will load a new key every day
                                        at 12:00:00.
                                         14400 12:00:00


ip-address-privacy-mask                 Apply a mask to the source and
                                        destination address to remove
                                        bits.

ip-port-privacy-mask                    Apply a mask to the source and
                                        destination port to remove
                                        bits.

tag-mask                                Apply mask to the source and
                                        destination tag.

    mask                                Source and Destination mask
                                        to apply.
                                         mask 0xFFFF 0xFFFF

scale                                   Scale packets and bytes.

  scale                                 Scale to apply.
                                         scale 100

replace-source-as0                      Replace source AS 0
replace-destination-as0                 Replace destination AS 0

  as                                    AS replacement value.
                                         as 3112

</screen>

</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>-n</term>
<listitem>
<para>
Don't load configuration file.  Useful only with -V
</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term>-V<replaceable> pdu_version</replaceable></term>
<listitem>
<para>
Use <replaceable>pdu_version</replaceable> format output.
<literallayout>
    1    NetFlow version 1 (No sequence numbers, AS, or mask)
    5    NetFlow version 5
    6    NetFlow version 6 (5+ Encapsulation size)
    7    NetFlow version 7 (Catalyst switches)
    8.1  NetFlow AS Aggregation
    8.2  NetFlow Proto Port Aggregation
    8.3  NetFlow Source Prefix Aggregation
    8.4  NetFlow Destination Prefix Aggregation
    8.5  NetFlow Prefix Aggregation
    8.6  NetFlow Destination (Catalyst switches)
    8.7  NetFlow Source Destination (Catalyst switches)
    8.8  NetFlow Full Flow (Catalyst switches)
    8.9  NetFlow ToS AS Aggregation
    8.10 NetFlow ToS Proto Port Aggregation
    8.11 NetFlow ToS Source Prefix Aggregation
    8.12 NetFlow ToS Destination Prefix Aggregation
    8.13 NetFlow ToS Prefix Aggregation
    8.14 NetFlow ToS Prefix Port Aggregation
    1005 Flow-Tools tagged version 5
</literallayout>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-x<replaceable> xlate_fname</replaceable></term>
<listitem>
<para>
Translation config file name.  Defaults to <filename>@localstatedir@/cfg/xlate.cfg</filename>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-X<replaceable> xlate_definition</replaceable></term>
<listitem>
<para>
Translation definition.  Defaults to default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>-z<replaceable> z_level</replaceable></term>
<listitem>
<para>
Configure compression level to <replaceable> z_level</replaceable>.  0 is
disabled (no compression), 9 is highest compression.
</para>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1>
<title>EXAMPLES</title>

<informalexample>
<para>
Convert the version 7 flows in <filename>flows.v7</filename> to version 5,
storing the result in <filename>flows.v5</filename>.
</para>
<para>
  <command>flow-xlate -V5 &lt flows.v7 &gt flows.v5</command>
</para>
</informalexample>

<informalexample>
<para>
Set the low 11 bits in the IP addresses to zero unless the address
is multicast or it belongs to the 192.88.99/24 network.

<literallayout>
# xlate.cfg
include-filter filter.cfg

xlate-action MULTICAST-PRIVACY
  type ip-address-privacy-mask
  mask 0xFFFFFFFF 0xFFFFFFFF  
  
xlate-action UNICAST-PRIVACY
  type ip-address-privacy-mask
  mask 0xFFFFFF00 0xFFFFF800

xlate-definition abilene_privacy
  term
    filter mcast
    action MULTICAST-PRIVACY
    stop
  term
    filter ucast
    action UNICAST-PRIVACY

</literallayout>

<literallayout>
# filter.cfg
filter-primitive MCAST
  type ip-address-mask
  permit 224.0.0.0 240.0.0.0

filter-primitive UCAST
  type ip-address-mask
  deny 224.0.0.0 240.0.0.0
  default permit

filter-primitive SKIP
  type ip-address-mask
  deny 192.88.99.0 255.255.255.0
  default permit

filter-definition mcast
  match ip-destination-address MCAST

filter-definition ucast
  match ip-destination-address UCAST
  match ip-destination-address SKIP
  match ip-source-address SKIP
</literallayout>

<command>flow-cat <filename>flows</filename> | flow-xlate -xxlate.cfg -Xabilene_privacy | flow-print</command>
</informalexample>
</refsect1>

<refsect1>
<title>FILES</title>
<para>
  Configuration files:
    Symbols - <filename>@localstatedir@/sym/*</filename>.
    Filter - <filename>@localstatedir@/cfg/filter.cfg</filename>.
    Xlate - <filename>@localstatedir@/cfg/xlate.cfg</filename>.
</para>
</refsect1>


<refsect1>
<title>BUGS</title>
<para>
The scale option can overflow the 32 bit flow counters.  This could be
solved by detecting this condition and splitting the flow in two.
</para>
<para>
Translation between aggregated and non aggregated formats is not supported.
</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>
