1<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 2<refentry> 3 4<refmeta> 5<refentrytitle> 6<application>flow-xlate</application> 7</refentrytitle> 8<manvolnum>1</manvolnum> 9</refmeta> 10 11<refnamediv> 12<refname> 13<application>flow-xlate</application> 14</refname> 15<refpurpose> 16Apply translations to selected fields of a flow. 17</refpurpose> 18</refnamediv> 19 20<refsynopsisdiv> 21<cmdsynopsis> 22<command>flow-xlate</command> 23<arg>-hkn</arg> 24<arg>-b<replaceable> big</replaceable>|<replaceable>little</replaceable></arg> 25<arg>-C<replaceable> comment</replaceable></arg> 26<arg>-d<replaceable> debug_level</replaceable></arg> 27<arg>-v<replaceable> variable binding</replaceable></arg> 28<arg>-V<replaceable> flow_version</replaceable></arg> 29<arg>-x<replaceable> xlate_fname</replaceable></arg> 30<arg>-X<replaceable> xlate_definition</replaceable></arg> 31<arg>-z<replaceable> z_level</replaceable></arg> 32</cmdsynopsis> 33</refsynopsisdiv> 34 35 36<refsect1> 37<title>DESCRIPTION</title> 38<para> 39The <command>flow-xlate</command> utility is used to apply translations 40to flows. Translations are defined in a configuration file and are 41composed of actions and a definition to invoke action(s). The definitions 42are in the form of terms, each term can have a filter and multiple actions. 43</para> 44<para> 45Words in the configuration file of the form @VAR or @{VAR:default} will be 46expanded at run-time by setting variable names with the -v option. 47</para> 48<para> 49Translation actions begin with the xlate-action keyword followed by 50a symbolic name. Each action has a type defined below. 51</para> 52<para> 53Translation definitions begin with the xlate-definition keyword followed 54by a symbolic name. Each definition is composed of terms which are 55evaluated in the order of the configuration file. A term may invoke 56a filter to conditionally invoke an action. 57</para> 58 59<screen> 60Action type/sub-commands Description/Example 61------------------------------------------------------------------------ 62ip-source-address-to-network Zero host bits based on mask. 63ip-destination-address-to-network Zero host bits based on mask. 64 65 (no sub-commands) 66 67ip-source-address-to-class-network Zero source host bits to 68 match class. 69ip-destination-address-to-class-network Zero dst host bits to 70 match class. 71 72 (no sub-commands) 73 74ip-source-address-anonymize Anonymize source address. 75ip-destination-address-anonymize Anonymize destination address. 76ip-address-anonymize Anonymize src/dst address. 77 78 79 algorithm Algorithm. cryptopan-aes128 is 80 currently supported. 81 algorithm cryptopan-aes128 82 83 key Key. Key is 128 bits in hex. 84 key 0123456789ABCDEFG 85 86 key-file File to load key from. Key is 87 128 bits in hex. 88 key-file /mfstmp/secret-key 89 90 key-file-refresh How often to check the key file. 91 Interval is in minutes, the 92 optional second argument is 93 hour:min:sec to specify the 94 first refresh. This example 95 will load a new key every day 96 at 12:00:00. 97 14400 12:00:00 98 99 100ip-address-privacy-mask Apply a mask to the source and 101 destination address to remove 102 bits. 103 104ip-port-privacy-mask Apply a mask to the source and 105 destination port to remove 106 bits. 107 108tag-mask Apply mask to the source and 109 destination tag. 110 111 mask Source and Destination mask 112 to apply. 113 mask 0xFFFF 0xFFFF 114 115scale Scale packets and bytes. 116 117 scale Scale to apply. 118 scale 100 119 120replace-source-as0 Replace source AS 0 121replace-destination-as0 Replace destination AS 0 122 123 as AS replacement value. 124 as 3112 125 126</screen> 127 128</refsect1> 129 130<refsect1> 131<title>OPTIONS</title> 132<variablelist> 133 134<varlistentry> 135<term>-b<replaceable> big</replaceable>|<replaceable>little</replaceable</term> 136<listitem> 137<para> 138Byte order of output. 139</para> 140</listitem> 141</varlistentry> 142 143<varlistentry> 144<term>-C<replaceable> Comment</replaceable></term> 145<listitem> 146<para> 147Add a comment. 148</para> 149</listitem> 150</varlistentry> 151 152<varlistentry> 153<term>-d<replaceable> debug_level</replaceable></term> 154<listitem> 155<para> 156Enable debugging. 157</para> 158</listitem> 159</varlistentry> 160 161<varlistentry> 162<term>-h</term> 163<listitem> 164<para> 165Display help. 166</para> 167</listitem> 168</varlistentry> 169 170<varlistentry> 171<term>-k</term> 172<listitem> 173<para> 174Keep time from input. 175</para> 176</listitem> 177</varlistentry> 178 179<varlistentry> 180<term>-n</term> 181<listitem> 182<para> 183Don't load configuration file. Useful only with -V 184</para> 185</listitem> 186</varlistentry> 187 188<varlistentry> 189<term>-v<replaceable> variable binding</replaceable></term> 190<listitem> 191<para> 192Set a variable FOO=bar. 193</para> 194</listitem> 195</varlistentry> 196 197<varlistentry> 198<term>-V<replaceable> pdu_version</replaceable></term> 199<listitem> 200<para> 201Use <replaceable>pdu_version</replaceable> format output. 202<literallayout> 203 1 NetFlow version 1 (No sequence numbers, AS, or mask) 204 5 NetFlow version 5 205 6 NetFlow version 6 (5+ Encapsulation size) 206 7 NetFlow version 7 (Catalyst switches) 207 8.1 NetFlow AS Aggregation 208 8.2 NetFlow Proto Port Aggregation 209 8.3 NetFlow Source Prefix Aggregation 210 8.4 NetFlow Destination Prefix Aggregation 211 8.5 NetFlow Prefix Aggregation 212 8.6 NetFlow Destination (Catalyst switches) 213 8.7 NetFlow Source Destination (Catalyst switches) 214 8.8 NetFlow Full Flow (Catalyst switches) 215 8.9 NetFlow ToS AS Aggregation 216 8.10 NetFlow ToS Proto Port Aggregation 217 8.11 NetFlow ToS Source Prefix Aggregation 218 8.12 NetFlow ToS Destination Prefix Aggregation 219 8.13 NetFlow ToS Prefix Aggregation 220 8.14 NetFlow ToS Prefix Port Aggregation 221 1005 Flow-Tools tagged version 5 222</literallayout> 223</para> 224</listitem> 225</varlistentry> 226 227<varlistentry> 228<term>-x<replaceable> xlate_fname</replaceable></term> 229<listitem> 230<para> 231Translation config file name. Defaults to <filename>/usr/local/etc/flow-tools/xlate.cfg</filename> 232</para> 233</listitem> 234</varlistentry> 235 236<varlistentry> 237<term>-X<replaceable> xlate_definition</replaceable></term> 238<listitem> 239<para> 240Translation definition. Defaults to default. 241</para> 242</listitem> 243</varlistentry> 244 245<varlistentry> 246<term>-z<replaceable> z_level</replaceable></term> 247<listitem> 248<para> 249Configure compression level to <replaceable> z_level</replaceable>. 0 is 250disabled (no compression), 9 is highest compression. 251</para> 252</listitem> 253</varlistentry> 254 255</variablelist> 256</refsect1> 257 258<refsect1> 259<title>EXAMPLES</title> 260 261<informalexample> 262<para> 263Convert the version 7 flows in <filename>flows.v7</filename> to version 5, 264storing the result in <filename>flows.v5</filename>. 265</para> 266<para> 267 <command>flow-xlate -V5 < flows.v7 > flows.v5</command> 268</para> 269</informalexample> 270 271<informalexample> 272<para> 273Set the low 11 bits in the IP addresses to zero unless the address 274is multicast or it belongs to the 192.88.99/24 network. 275 276<literallayout> 277# xlate.cfg 278include-filter filter.cfg 279 280xlate-action MULTICAST-PRIVACY 281 type ip-address-privacy-mask 282 mask 0xFFFFFFFF 0xFFFFFFFF 283 284xlate-action UNICAST-PRIVACY 285 type ip-address-privacy-mask 286 mask 0xFFFFFF00 0xFFFFF800 287 288xlate-definition abilene_privacy 289 term 290 filter mcast 291 action MULTICAST-PRIVACY 292 stop 293 term 294 filter ucast 295 action UNICAST-PRIVACY 296 297</literallayout> 298 299<literallayout> 300# filter.cfg 301filter-primitive MCAST 302 type ip-address-mask 303 permit 224.0.0.0 240.0.0.0 304 305filter-primitive UCAST 306 type ip-address-mask 307 deny 224.0.0.0 240.0.0.0 308 default permit 309 310filter-primitive SKIP 311 type ip-address-mask 312 deny 192.88.99.0 255.255.255.0 313 default permit 314 315filter-definition mcast 316 match ip-destination-address MCAST 317 318filter-definition ucast 319 match ip-destination-address UCAST 320 match ip-destination-address SKIP 321 match ip-source-address SKIP 322</literallayout> 323 324<command>flow-cat <filename>flows</filename> | flow-xlate -xxlate.cfg -Xabilene_privacy | flow-print</command> 325</para> 326</informalexample> 327</refsect1> 328 329<refsect1> 330<title>FILES</title> 331<para> 332 Configuration files: 333 Symbols - <filename>/usr/local/etc/flow-tools/*</filename>. 334 Filter - <filename>/usr/local/etc/flow-tools/filter.cfg</filename>. 335 Xlate - <filename>/usr/local/etc/flow-tools/xlate.cfg</filename>. 336</para> 337</refsect1> 338 339 340<refsect1> 341<title>BUGS</title> 342<para> 343The scale option can overflow the 32 bit flow counters. This could be 344solved by detecting this condition and splitting the flow in two. 345</para> 346<para> 347Translation between aggregated and non aggregated formats is not supported. 348</para> 349</refsect1> 350 351<refsect1> 352<title>AUTHOR</title> 353<para> 354<author> 355<firstname>Mark</firstname> 356<surname>Fullmer</surname> 357</author> 358<email>maf@splintered.net</email> 359</para> 360</refsect1> 361 362<refsect1> 363<title>SEE ALSO</title> 364<para> 365<application>flow-tools</application>(1) 366</para> 367</refsect1> 368 369</refentry> 370