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