1.\" Copyright (c) 2004-2005 Gleb Smirnoff <glebius@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd March 2, 2006 28.Os 29.Dt NG_NETFLOW 4 30.Sh NAME 31.Nm ng_netflow 32.Nd Cisco's NetFlow implementation 33.Sh SYNOPSIS 34.In sys/types.h 35.In netinet/in.h 36.In netgraph/netflow/ng_netflow.h 37.Sh DESCRIPTION 38The 39.Nm 40node implements Cisco's NetFlow export protocol on a router running 41.Fx . 42The 43.Nm 44node listens for incoming traffic and identifies unique flows in it. 45Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers, 46ToS and input interface. 47Expired flows are exported out of the node in NetFlow version 5 UDP datagrams. 48Expiration reason can be one of the following: 49.Bl -dash 50.It 51RST or FIN TCP segment. 52.It 53Active timeout. 54Flows cannot live more than the specified period of time. 55The default is 1800 seconds (30 minutes). 56.It 57Inactive timeout. 58A flow was inactive for the specified period of time. 59The default is 15 seconds. 60.El 61.Pp 62Export information is stored in NetFlow version 5 datagrams. 63.Sh HOOKS 64This node type supports up to 65.Dv NG_NETFLOW_MAXIFACES 66hooks named 67.Va iface0 , iface1 , 68etc., 69and the same number of hooks named 70.Va out0 , out1 , 71etc., 72plus a single hook named 73.Va export . 74The node does NetFlow accounting of data received on 75.Va iface* 76hooks. 77If corresponding 78.Va out 79hook is connected, unmodified data is bypassed to it, otherwise data is freed. 80If data is received on 81.Va out 82hook, it is bypassed to corresponding 83.Va iface 84hook without any processing. 85When full export datagram is built it is sent to the 86.Va export 87hook. 88In normal operation, the 89.Va export 90hook is connected to the 91.Va inet/dgram/udp 92hook of the 93.Xr ng_ksocket 4 94node. 95.Sh CONTROL MESSAGES 96This node type supports the generic control messages, plus the following: 97.Bl -tag -width indent 98.It Dv NGM_NETFLOW_INFO 99Returns some node statistics and the current timeout values in a 100.Vt "struct ng_netflow_info" . 101.It Dv NGM_NETFLOW_IFINFO 102Returns information about the 103.Va iface Ns Ar N 104hook. 105The hook number is passed as an argument. 106.It Dv NGM_NETFLOW_SETDLT 107Sets data link type on the 108.Va iface Ns Ar N 109hook. 110Currently, supported types are raw IP datagrams and Ethernet. 111This message type uses 112.Vt "struct ng_netflow_setdlt" 113as an argument: 114.Bd -literal -offset 4n 115struct ng_netflow_setdlt { 116 uint16_t iface; /* which iface to operate on */ 117 uint8_t dlt; /* DLT_XXX from bpf.h */ 118}; 119.Ed 120.Pp 121The requested 122.Va iface Ns Ar N 123hook must already be connected, otherwise message send operation will 124return an error. 125.It Dv NGM_NETFLOW_SETIFINDEX 126In some cases, 127.Nm 128may be unable to determine the input interface index of a packet. 129This can happen if traffic enters the 130.Nm 131node before it comes to the system interface's input queue. 132An example of such a setup is capturing a traffic 133.Em between 134synchronous data line and 135.Xr ng_iface 4 . 136In this case, the input index should be associated with a given hook. 137The interface's index can be determined via 138.Xr if_nametoindex 3 139from userland. 140This message requires 141.Vt "struct ng_netflow_setifindex" 142as an argument: 143.Bd -literal -offset 4n 144struct ng_netflow_setifindex { 145 u_int16_t iface; /* which iface to operate on */ 146 u_int16_t index; /* new index */ 147}; 148.Ed 149.Pp 150The requested 151.Va iface Ns Ar N 152hook must already be connected, otherwise the message 153send operation will return an error. 154.It Dv NGM_NETFLOW_SETTIMEOUTS 155Sets values in seconds for NetFlow active/inactive timeouts. 156This message requires 157.Vt "struct ng_netflow_settimeouts" 158as an argument: 159.Bd -literal -offset 4n 160struct ng_netflow_settimeouts { 161 uint32_t inactive_timeout; 162 uint32_t active_timeout; 163}; 164.Ed 165.It Dv NGM_NETFLOW_SHOW 166This control message asks a node to dump the entire contents of the flow cache. 167It is called from 168.Xr flowctl 8 , 169not directly from 170.Xr ngctl 8 . 171See also 172.Sx BUGS 173section. 174.El 175.Sh ASCII CONTROL MESSAGES 176Most binary control messages have an 177.Tn ASCII 178equivalent. 179The supported 180.Tn ASCII 181commands are: 182.Pp 183.Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact 184.It Dv NGM_NETFLOW_INFO 185.Qq Li info 186.It Dv NGM_NETFLOW_IFINFO 187.Qq Li "ifinfo %u" 188.It Dv NGM_NETFLOW_SETDLT 189.Qq Li "setdlt { iface = %u dlt = %u }" 190.It Dv NGM_NETFLOW_SETIFINDEX 191.Qq Li "setifindex { iface = %u index = %u }" 192.It Dv NGM_NETFLOW_SETTIMEOUTS 193.Qq Li "settimeouts { inactive = %u active = %u }" 194.El 195.Sh SHUTDOWN 196This node shuts down upon receipt of a 197.Dv NGM_SHUTDOWN 198control message, or when all hooks have been disconnected. 199.Sh EXAMPLES 200The simplest possible configuration is one Ethernet interface, where 201flow collecting is enabled. 202.Bd -literal -offset indent 203/usr/sbin/ngctl -f- <<-SEQ 204 mkpeer fxp0: netflow lower iface0 205 name fxp0:lower netflow 206 connect fxp0: netflow: upper out0 207 mkpeer netflow: ksocket export inet/dgram/udp 208 msg netflow:export connect inet/10.0.0.1:4444 209SEQ 210.Ed 211.Pp 212This is a more complicated example of a router with 2 NetFlow-enabled 213interfaces 214.Li fxp0 215and 216.Li ng0 . 217Note that the 218.Va ng0: 219node in this example is connected to 220.Xr ng_tee 4 . 221The latter sends us a copy of IP packets, which we analyze and free. 222On 223.Va fxp0: 224we do not use tee, but send packets back to ether node. 225.Bd -literal -offset indent 226/usr/sbin/ngctl -f- <<-SEQ 227 # connect ng0's tee to iface0 hook 228 mkpeer ng0:inet netflow right2left iface0 229 name ng0:inet.right2left netflow 230 # set DLT to raw mode 231 msg netflow: setdlt { iface=0 dlt=12 } 232 # set interface index (5 in this example) 233 msg netflow: setifindex { iface=0 index=5 } 234 235 # Connect fxp0: to iface1 and out1 hook 236 connect fxp0: netflow: lower iface1 237 connect fxp0: netflow: upper out1 238 239 # Create ksocket node on export hook, and configure it 240 # to send exports to proper destination 241 mkpeer netflow: ksocket export inet/dgram/udp 242 msg netflow:export connect inet/10.0.0.1:4444 243SEQ 244.Ed 245.Sh SEE ALSO 246.Xr netgraph 4 , 247.Xr ng_ether 4 , 248.Xr ng_iface 4 , 249.Xr ng_ksocket 4 , 250.Xr ng_tee 4 , 251.Xr flowctl 8 , 252.Xr ngctl 8 253.Pp 254.Pa http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/netflsol/\:nfwhite.htm 255.Sh AUTHORS 256.An -nosplit 257The 258.Nm 259node type was written by 260.An Gleb Smirnoff Aq glebius@FreeBSD.org , 261based on 262.Nm ng_ipacct 263written by 264.An Roman V. Palagin Aq romanp@unshadow.net . 265.Sh BUGS 266Cache snapshot obtained via 267.Dv NGM_NETFLOW_SHOW 268command may lack some percentage of entries under severe load. 269.Pp 270The 271.Nm 272node type does not fill in AS numbers. 273This is due to the lack of necessary information in the kernel routing table. 274However, this information can be injected into the kernel from a routing daemon 275such as GNU Zebra. 276This functionality may become available in future releases. 277