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 October 8, 2008 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 . 74By default (ingress NetFlow enabled) node does NetFlow accounting of data 75received on 76.Va iface* 77hooks. 78If corresponding 79.Va out 80hook is connected, unmodified data is bypassed to it, otherwise data is freed. 81If data is received on 82.Va out 83hook, it is bypassed to corresponding 84.Va iface 85hook without any processing (egress NetFlow disabled by default). 86When full export datagram is built it is sent to the 87.Va export 88hook. 89In normal operation, the 90.Va export 91hook is connected to the 92.Va inet/dgram/udp 93hook of the 94.Xr ng_ksocket 4 95node. 96.Sh CONTROL MESSAGES 97This node type supports the generic control messages, plus the following: 98.Bl -tag -width indent 99.It Dv NGM_NETFLOW_INFO 100Returns some node statistics and the current timeout values in a 101.Vt "struct ng_netflow_info" . 102.It Dv NGM_NETFLOW_IFINFO 103Returns information about the 104.Va iface Ns Ar N 105hook. 106The hook number is passed as an argument. 107.It Dv NGM_NETFLOW_SETDLT 108Sets data link type on the 109.Va iface Ns Ar N 110hook. 111Currently, supported types are raw IP datagrams and Ethernet. 112This message type uses 113.Vt "struct ng_netflow_setdlt" 114as an argument: 115.Bd -literal -offset 4n 116struct ng_netflow_setdlt { 117 uint16_t iface; /* which iface to operate on */ 118 uint8_t dlt; /* DLT_XXX from bpf.h */ 119}; 120.Ed 121.Pp 122The requested 123.Va iface Ns Ar N 124hook must already be connected, otherwise message send operation will 125return an error. 126.It Dv NGM_NETFLOW_SETIFINDEX 127In some cases, 128.Nm 129may be unable to determine the input interface index of a packet. 130This can happen if traffic enters the 131.Nm 132node before it comes to the system interface's input queue. 133An example of such a setup is capturing a traffic 134.Em between 135synchronous data line and 136.Xr ng_iface 4 . 137In this case, the input index should be associated with a given hook. 138The interface's index can be determined via 139.Xr if_nametoindex 3 140from userland. 141This message requires 142.Vt "struct ng_netflow_setifindex" 143as an argument: 144.Bd -literal -offset 4n 145struct ng_netflow_setifindex { 146 u_int16_t iface; /* which iface to operate on */ 147 u_int16_t index; /* new index */ 148}; 149.Ed 150.Pp 151The requested 152.Va iface Ns Ar N 153hook must already be connected, otherwise the message 154send operation will return an error. 155.It Dv NGM_NETFLOW_SETTIMEOUTS 156Sets values in seconds for NetFlow active/inactive timeouts. 157This message requires 158.Vt "struct ng_netflow_settimeouts" 159as an argument: 160.Bd -literal -offset 4n 161struct ng_netflow_settimeouts { 162 uint32_t inactive_timeout; 163 uint32_t active_timeout; 164}; 165.Ed 166.It Dv NGM_NETFLOW_SETCONFIG 167Sets configuration for the specified interface. 168This message requires 169.Vt "struct ng_netflow_setconfig" 170as an argument: 171.Bd -literal -offset 4n 172struct ng_netflow_setconfig { 173 u_int16_t iface; 174 u_int32_t conf; 175#define NG_NETFLOW_CONF_INGRESS 1 176#define NG_NETFLOW_CONF_EGRESS 2 177#define NG_NETFLOW_CONF_ONCE 4 178#define NG_NETFLOW_CONF_THISONCE 8 179}; 180.Ed 181.Pp 182Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS 183enabled by default enables ingress NetFlow generation (for data coming from 184ifaceX hook). Option NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data 185coming from outX hook). Option NG_NETFLOW_CONF_ONCE defines that packet should 186be accounted only once if it several times passes via netflow node. Option 187NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once 188if it several times passes via exactly this netflow node. Last two options are 189important to avoid duplicate accounting when both ingress and egress NetFlow 190are enabled. 191.It Dv NGM_NETFLOW_SHOW 192This control message asks a node to dump the entire contents of the flow cache. 193It is called from 194.Xr flowctl 8 , 195not directly from 196.Xr ngctl 8 . 197See also 198.Sx BUGS 199section. 200.El 201.Sh ASCII CONTROL MESSAGES 202Most binary control messages have an 203.Tn ASCII 204equivalent. 205The supported 206.Tn ASCII 207commands are: 208.Pp 209.Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact 210.It Dv NGM_NETFLOW_INFO 211.Qq Li info 212.It Dv NGM_NETFLOW_IFINFO 213.Qq Li "ifinfo %u" 214.It Dv NGM_NETFLOW_SETDLT 215.Qq Li "setdlt { iface = %u dlt = %u }" 216.It Dv NGM_NETFLOW_SETIFINDEX 217.Qq Li "setifindex { iface = %u index = %u }" 218.It Dv NGM_NETFLOW_SETTIMEOUTS 219.Qq Li "settimeouts { inactive = %u active = %u }" 220.It Dv NGM_NETFLOW_SETCONFIG 221.Qq Li "setconfig { iface = %u conf = %u }" 222.El 223.Sh SHUTDOWN 224This node shuts down upon receipt of a 225.Dv NGM_SHUTDOWN 226control message, or when all hooks have been disconnected. 227.Sh EXAMPLES 228The simplest possible configuration is one Ethernet interface, where 229flow collecting is enabled. 230.Bd -literal -offset indent 231/usr/sbin/ngctl -f- <<-SEQ 232 mkpeer fxp0: netflow lower iface0 233 name fxp0:lower netflow 234 connect fxp0: netflow: upper out0 235 mkpeer netflow: ksocket export inet/dgram/udp 236 msg netflow:export connect inet/10.0.0.1:4444 237SEQ 238.Ed 239.Pp 240This is a more complicated example of a router with 2 NetFlow-enabled 241interfaces 242.Li fxp0 243and 244.Li ng0 . 245Note that the 246.Va ng0: 247node in this example is connected to 248.Xr ng_tee 4 . 249The latter sends us a copy of IP packets, which we analyze and free. 250On 251.Va fxp0: 252we do not use tee, but send packets back to ether node. 253.Bd -literal -offset indent 254/usr/sbin/ngctl -f- <<-SEQ 255 # connect ng0's tee to iface0 hook 256 mkpeer ng0:inet netflow right2left iface0 257 name ng0:inet.right2left netflow 258 # set DLT to raw mode 259 msg netflow: setdlt { iface=0 dlt=12 } 260 # set interface index (5 in this example) 261 msg netflow: setifindex { iface=0 index=5 } 262 263 # Connect fxp0: to iface1 and out1 hook 264 connect fxp0: netflow: lower iface1 265 connect fxp0: netflow: upper out1 266 267 # Create ksocket node on export hook, and configure it 268 # to send exports to proper destination 269 mkpeer netflow: ksocket export inet/dgram/udp 270 msg netflow:export connect inet/10.0.0.1:4444 271SEQ 272.Ed 273.Sh SEE ALSO 274.Xr netgraph 4 , 275.Xr ng_ether 4 , 276.Xr ng_iface 4 , 277.Xr ng_ksocket 4 , 278.Xr ng_tee 4 , 279.Xr flowctl 8 , 280.Xr ngctl 8 281.Pp 282.Pa http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/netflsol/\:nfwhite.htm 283.Sh AUTHORS 284.An -nosplit 285The 286.Nm 287node type was written by 288.An Gleb Smirnoff Aq glebius@FreeBSD.org , 289based on 290.Nm ng_ipacct 291written by 292.An Roman V. Palagin Aq romanp@unshadow.net . 293.Sh BUGS 294Cache snapshot obtained via 295.Dv NGM_NETFLOW_SHOW 296command may lack some percentage of entries under severe load. 297.Pp 298The 299.Nm 300node type does not fill in AS numbers. 301This is due to the lack of necessary information in the kernel routing table. 302However, this information can be injected into the kernel from a routing daemon 303such as GNU Zebra. 304This functionality may become available in future releases. 305