1<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 2<refentry> 3 4<refmeta> 5<refentrytitle> 6<application>flow-capture</application> 7</refentrytitle> 8<manvolnum>1</manvolnum> 9</refmeta> 10 11<refnamediv> 12<refname> 13<application>flow-capture</application> 14</refname> 15<refpurpose> 16Manage storage of flow file archives by expiring old data. 17</refpurpose> 18</refnamediv> 19 20<refsynopsisdiv> 21<cmdsynopsis> 22<command>flow-capture</command> 23<arg>-hu</arg> 24<arg>-b<replaceable> big|little</replaceable></arg> 25<arg>-C<replaceable> comment</replaceable></arg> 26<arg>-c<replaceable> flow_clients</replaceable></arg> 27<arg>-d<replaceable> debug_level</replaceable></arg> 28<arg>-D<replaceable> daemonize</replaceable></arg> 29<arg>-e<replaceable> expire_count</replaceable></arg> 30<arg>-f<replaceable> filter_fname</replaceable></arg> 31<arg>-F<replaceable> filter_definition</replaceable></arg> 32<arg>-E<replaceable> expire_size</replaceable></arg> 33<arg>-n<replaceable> rotations</replaceable></arg> 34<arg>-N<replaceable> nesting_level</replaceable></arg> 35<arg>-p<replaceable> pidfile</replaceable></arg> 36<arg>-R<replaceable> rotate_program</replaceable></arg> 37<arg>-S<replaceable> stat_interval</replaceable></arg> 38<arg>-t<replaceable> tag_fname</replaceable></arg> 39<arg rep="repeat">-T<replaceable> active_def</replaceable>|<replaceable>active_def,active_def</replaceable></arg> 40<arg>-V<replaceable> pdu_version</replaceable></arg> 41<arg>-z<replaceable> z_level</replaceable></arg> 42<arg choice="req">-w<replaceable> workdir</replaceable></arg> 43<arg>-x<replaceable> xlate_fname</replaceable></arg> 44<arg>-X<replaceable> xlate_definition</replaceable></arg> 45<arg choice="req"><replaceable>localip/remoteip/port</replaceable></arg> 46</cmdsynopsis> 47</refsynopsisdiv> 48 49 50<refsect1> 51<title>DESCRIPTION</title> 52<para> 53The <command>flow-capture</command> utility will receive and store 54NetFlow exports to disk. The flow files are rotated <replaceable>rotations 55</replaceable>times per day 56and expiration of old flow files can be configured by number of files 57or total space utilization. Files are stored in <filename>workdir</filename> 58and can optionally be stored in additional levels of directories. Active 59files created by <command>flow-capture</command> begin 60with 'tmp'. Files that are complete begin with 'ft'. 61</para> 62<para> 63When the <replaceable>remoteip</replaceable> is configured only flows 64from that exporter will be processed, this is the most secure and recommended 65configuration. When the <replaceable>localip</replaceable> is configured 66<command>flow-capture</command> will only process flows 67sent to the <replaceable> localip</replaceable> IP address. If 68<replaceable>remoteip</replaceable> is 0 (not configured) flows from any 69source IP address are accepted. Multiple non aggregated PDU versions may 70be accepted at once to support Cisco's Catalyst 6500 NetFlow 71implementation which exports from both the supervisor and MSFC with the 72same IP address and same port but different export versions. In this case 73the exports will be stored in the format specified by <replaceable>pdu_version 74</replaceable> or whichever export type is received first. 75</para> 76<para> 77NetFlow exports are UDP and do not employ congestion control or a 78retransmission mechanism. If the server flow-capture is configured 79on is too busy, or the network is congested or lossy NetFlow exports will 80be lost. An estimate of lost flows is recorded in the flow files, and 81logged via syslog. Most servers will provide a count of dropped packets 82due to full socket buffers via the <command>netstat</command> utility. 83For example <command>netstat -s | grep full</command> will provide a count 84of UDP packets dropped due to full socket buffers. If this is a persistent 85occurrence either <command>flow-capture</command> will need a larger server 86or the compression level should be decreased with -z. 87</para> 88<para> 89A SIGHUP signal will cause <command>flow-capture</command> to close 90the current file and create a new one. 91</para> 92<para> 93A SIGQUIT or SIGTERM signal will cause <command>flow-capture</command> to close 94the current file and exit. 95</para> 96</refsect1> 97 98<refsect1> 99<title>OPTIONS</title> 100<variablelist> 101 102<varlistentry> 103<term>-b<replaceable> big</replaceable>|<replaceable>little</replaceable</term> 104<listitem> 105<para> 106Byte order of output. 107</para> 108</listitem> 109</varlistentry> 110 111<varlistentry> 112<term>-c<replaceable> flow_clients</replaceable></term> 113<listitem> 114<para> 115Enable <replaceable>flow_clients</replaceable> TCP clients. When libwrap 116is available the client must be in a permit list for the service 117flow-capture-client. 118</para> 119</listitem> 120</varlistentry> 121 122<varlistentry> 123<term>-C<replaceable> Comment</replaceable></term> 124<listitem> 125<para> 126Add a comment. 127</para> 128</listitem> 129</varlistentry> 130 131<varlistentry> 132<term>-d<replaceable> debug_level</replaceable></term> 133<listitem> 134<para> 135Enable debugging. 136</para> 137</listitem> 138</varlistentry> 139 140<varlistentry> 141<term>-e<replaceable> expire_count</replaceable></term> 142<listitem> 143<para> 144Retain the maximum number of files so that the total file count is 145less than <replaceable>expire_count</replaceable>. Defaults to 1460 (do not expire). 147</para> 148</listitem> 149</varlistentry> 150 151<varlistentry> 152<term>-E<replaceable> expire_size</replaceable></term> 153<listitem> 154<para> 155Retain the maximum number of files so that the total storage is less 156than <replaceable>expire_size</replaceable>. The letters b,K,M,G can 157be used as multipliers, ie 16 Megabytes is 16M. Default to 0 (do not expire). 158</para> 159</listitem> 160</varlistentry> 161 162<varlistentry> 163<term>-f<replaceable> filter_fname</replaceable></term> 164<listitem> 165<para> 166Filter list filename. Defaults to <filename>/usr/local/etc/flow-tools/filter</filename>. 167</para> 168</listitem> 169</varlistentry> 170 171<varlistentry> 172<term>-F<replaceable> filter_definition</replaceable></term> 173<listitem> 174<para> 175Select the active definition. Defaults to default. 176</para> 177</listitem> 178</varlistentry> 179 180<varlistentry> 181<term>-h</term> 182<listitem> 183<para> 184Display help. 185</para> 186</listitem> 187</varlistentry> 188 189<varlistentry> 190<term>-n<replaceable> rotations</replaceable></term> 191<listitem> 192<para> 193Configure the number of times flow-capture will create a new file per day. 194The default is 95, or every 15 minutes. 195</para> 196</listitem> 197</varlistentry> 198 199<varlistentry> 200<term>-N<replaceable> nesting_level</replaceable></term> 201<listitem> 202<para> 203Configure the nesting level for storing flow files. The default is 0. 204 -3 YYYY/YYYY-MM/YYYY-MM-DD/flow-file 205 -2 YYYY-MM/YYYY-MM-DD/flow-file 206 -1 YYYY-MM-DD/flow-file 207 0 flow-file 208 1 YYYY/flow-file 209 2 YYYY/YYYY-MM/flow-file 210 3 YYYY/YYYY-MM/YYYY-MM-DD/flow-file 211</para> 212</listitem> 213</varlistentry> 214 215<varlistentry> 216<term>-p<replaceable> pidfile</replaceable></term> 217<listitem> 218<para> 219Configure the process ID file. Use - to disable pid file creation. 220</para> 221</listitem> 222</varlistentry> 223 224<varlistentry> 225<term>-R<replaceable> rotate_program</replaceable></term> 226<listitem> 227<para> 228Execute <replaceable>rotate_program</replaceable> with the first argument 229as the flow file name after rotating it. 230</para> 231</listitem> 232</varlistentry> 233 234<varlistentry> 235<term>-S<replaceable> stat_interval</replaceable></term> 236<listitem> 237<para> 238When configured <command>flow-capture</command> will log a timestamped 239message every <replaceable>stat_interval</replaceable> minutes 240indicating counters such as the number of flows received, packets processed, 241and lost flows. 242</para> 243</listitem> 244</varlistentry> 245 246<varlistentry> 247<term>-t<replaceable> tag_fname</replaceable></term> 248<listitem> 249<para> 250Load tags from <filename>tag_name</filename> 251</para> 252</listitem> 253</varlistentry> 254 255<varlistentry> 256<term>-T<replaceable> active_def</replaceable>|<replaceable>active_def,active_def...</replaceable></term> 257<listitem> 258<para> 259Use <replaceable>active_def</replaceable> as the active tag definition(s). 260</para> 261</listitem> 262</varlistentry> 263 264<varlistentry> 265<term>-u</term> 266<listitem> 267<para> 268Preserve inherited umask. By default the umask will be set to 0022. 269</para> 270</listitem> 271</varlistentry> 272 273<varlistentry> 274<term>-V<replaceable> pdu_version</replaceable></term> 275<listitem> 276<para> 277Use <replaceable>pdu_version</replaceable> format output. 278<literallayout> 279 1 NetFlow version 1 (No sequence numbers, AS, or mask) 280 5 NetFlow version 5 281 6 NetFlow version 6 (5+ Encapsulation size) 282 7 NetFlow version 7 (Catalyst switches) 283 8.1 NetFlow AS Aggregation 284 8.2 NetFlow Proto Port Aggregation 285 8.3 NetFlow Source Prefix Aggregation 286 8.4 NetFlow Destination Prefix Aggregation 287 8.5 NetFlow Prefix Aggregation 288 8.6 NetFlow Destination (Catalyst switches) 289 8.7 NetFlow Source Destination (Catalyst switches) 290 8.8 NetFlow Full Flow (Catalyst switches) 291 8.9 NetFlow ToS AS Aggregation 292 8.10 NetFlow ToS Proto Port Aggregation 293 8.11 NetFlow ToS Source Prefix Aggregation 294 8.12 NetFlow ToS Destination Prefix Aggregation 295 8.13 NetFlow ToS Prefix Aggregation 296 8.14 NetFlow ToS Prefix Port Aggregation 297 1005 Flow-Tools tagged version 5 298</literallayout> 299</para> 300</listitem> 301</varlistentry> 302 303<varlistentry> 304<term>-w<replaceable> workdir</replaceable></term> 305<listitem> 306<para> 307Work in <filename>workdir</filename>. 308</para> 309</listitem> 310</varlistentry> 311 312<varlistentry> 313<term>-x<replaceable> xlate_fname</replaceable></term> 314<listitem> 315<para> 316Translation config file name. Defaults to <filename>/usr/local/etc/flow-tools/xlate.c 317fg</filename> 318</para> 319</listitem> 320</varlistentry> 321 322<varlistentry> 323<term>-X<replaceable> xlate_definition</replaceable></term> 324<listitem> 325<para> 326Translation definition. Defaults to default. 327</para> 328</listitem> 329</varlistentry> 330 331 332<varlistentry> 333<term>-z<replaceable> z_level</replaceable></term> 334<listitem> 335<para> 336Configure compression level to <replaceable> z_level</replaceable>. 0 is 337disabled (no compression), 9 is highest compression. 338</para> 339</listitem> 340</varlistentry> 341 342</variablelist> 343</refsect1> 344 345<refsect1> 346<title>EXAMPLES</title> 347 348<informalexample> 349<para> 350Receive flows from the exporter at 10.0.0.1 port 9800. Maintain 5 Gigabytes 351of flow files in /flows/krc4. Mask the source and destination IP addresses 352contained in the flow exports with 255.255.248.0. 353</para> 354<para> 355 <command>flow-capture -w /flows/krc4 -m 255.255.248.0 -E5G 0/10.0.0.1/9800</command> 356</para> 357</informalexample> 358 359<informalexample> 360<para> 361Receive flows from any exporter on port 9800. Do not perform any flow 362file space management. Store the exports in /flows/krc4. Emit a stat 363log message every 5 minutes. 364</para> 365<para> 366 <command>flow-capture -w /flows/krc4 0/0/9800 -S5</command> 367</para> 368</informalexample> 369 370</refsect1> 371 372<refsect1> 373<title>BUGS</title> 374<para> 375Empty directories are not removed. 376</para> 377</refsect1> 378 379<refsect1> 380<title>FILES</title> 381<para> 382 Configuration files: 383 Tag - <filename>/usr/local/etc/flow-tools/tag.cfg</filename>. 384 Filter - <filename>/usr/local/etc/flow-tools/filter.cfg</filename>. 385 Xlate - <filename>/usr/local/etc/flow-tools/xlate.cfg</filename>. 386</para> 387</refsect1> 388 389<refsect1> 390<title>AUTHOR</title> 391<para> 392<author> 393<firstname>Mark</firstname> 394<surname>Fullmer</surname> 395</author> 396<email>maf@splintered.net</email> 397</para> 398</refsect1> 399 400<refsect1> 401<title>SEE ALSO</title> 402<para> 403<application>flow-tools</application>(1) 404</para> 405</refsect1> 406 407</refentry> 408