1.\" Copyright (c) 2004 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 September 17, 2004 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., 69plus a single hook named 70.Va export . 71The node reads data on 72.Va iface* 73hooks, and sends export datagrams to the 74.Va export 75hook. 76In normal operation, the 77.Va export 78hook is connected to the 79.Va inet/dgram/udp 80hook of the 81.Xr ng_ksocket 4 82node. 83.Sh CONTROL MESSAGES 84This node type supports the generic control messages, plus the following: 85.Bl -tag -width indent 86.It Dv NGM_NETFLOW_INFO 87Returns some node statistics and the current timeout values in a 88.Vt "struct ng_netflow_info" . 89.It Dv NGM_NETFLOW_IFINFO 90Returns information about the 91.Va iface Ns Ar N 92hook. 93The hook number is passed as an argument. 94.It Dv NGM_NETFLOW_SETDLT 95Sets data link type on the 96.Va iface Ns Ar N 97hook. 98Currently, supported types are raw IP datagrams and Ethernet. 99This messsage type uses 100.Vt "struct ng_netflow_setdlt" 101as an argument: 102.Bd -literal -offset 4n 103struct ng_netflow_setdlt { 104 uint16_t iface; /* which iface to operate on */ 105 uint8_t dlt; /* DLT_XXX from bpf.h */ 106}; 107.Ed 108.Pp 109The requested 110.Va iface Ns Ar N 111hook must already be connected, otherwise message send operation will 112return an error. 113.It Dv NGM_NETFLOW_SETIFINDEX 114In some cases, 115.Nm 116may be unable to determine the input interface index of a packet. 117This can happen if traffic enters the 118.Nm 119node before it comes to the system interface's input queue. 120An example of such a setup is capturing a traffic 121.Em between 122synchronous data line and 123.Xr ng_iface 4 . 124In this case, the input index should be associated with a given hook. 125The interface's index can be determined via 126.Xr if_nametoindex 3 127from userland. 128This message requires 129.Vt "struct ng_netflow_setifindex" 130as an argument: 131.Bd -literal -offset 4n 132struct ng_netflow_setifindex { 133 u_int16_t iface; /* which iface to operate on */ 134 u_int16_t index; /* new index */ 135}; 136.Ed 137.Pp 138The requested 139.Va iface Ns Ar N 140hook must already be connected, otherwise the message 141send operation will return an error. 142.It Dv NGM_NETFLOW_SETTIMEOUTS 143Sets values in seconds for NetFlow active/inactive timeouts. 144This message requires 145.Vt "struct ng_netflow_settimeouts" 146as an argument: 147.Bd -literal -offset 4n 148struct ng_netflow_settimeouts { 149 uint32_t inactive_timeout; 150 uint32_t active_timeout; 151}; 152.Ed 153.It Dv NGM_NETFLOW_SHOW 154This control message asks a node to dump the entire contents of the flow cache. 155It is called from 156.Xr flowctl 8 , 157not directly from 158.Xr ngctl 8 . 159.El 160.Sh ASCII CONTROL MESSAGES 161Most binary control messages have an 162.Tn ASCII 163equivalent. 164The supported 165.Tn ASCII 166commands are: 167.Pp 168.Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact 169.It Dv NGM_NETFLOW_INFO 170.Qq Li info 171.It Dv NGM_NETFLOW_IFINFO 172.Qq Li "ifinfo %u" 173.It Dv NGM_NETFLOW_SETDLT 174.Qq Li "setdlt { iface = %u dlt = %u }" 175.It Dv NGM_NETFLOW_SETIFINDEX 176.Qq Li "setifindex { iface = %u index = %u }" 177.It Dv NGM_NETFLOW_SETTIMEOUTS 178.Qq Li "settimeouts { inactive = %u active = %u }" 179.El 180.Sh SHUTDOWN 181This node shuts down upon receipt of a 182.Dv NGM_SHUTDOWN 183control message, or when all hooks have been disconnected. 184.Sh EXAMPLES 185The simplest possible configuration is one Ethernet interface, where 186flow collecting is enabled. 187.Bd -literal -offset indent 188/usr/sbin/ngctl -f- <<-SEQ 189 mkpeer fxp0: tee lower right 190 connect fxp0: fxp0:lower upper left 191 mkpeer fxp0:lower netflow right2left iface0 192 name fxp0:lower.right2left netflow 193 mkpeer netflow: ksocket export inet/dgram/udp 194 msg netflow:export connect inet/10.0.0.1:4444 195SEQ 196.Ed 197.Pp 198This is a more complicated example of a router with 2 NetFlow-enabled 199interfaces 200.Li fxp0 201and 202.Li ng0 . 203Note that the 204.Va ng0: 205node in this example is connected to 206.Xr ng_tee 4 . 207.Bd -literal -offset indent 208/usr/sbin/ngctl -f- <<-SEQ 209 # connect ng0's tee to iface0 hook 210 mkpeer ng0:inet netflow right2left iface0 211 name ng0:inet.right2left netflow 212 # set DLT to raw mode 213 msg netflow: setdlt { iface=0 dlt=12 } 214 # set interface index (5 in this example) 215 msg netflow: setifindex { iface=0 index=5 } 216 217 # Create tee on fxp0, and connect it to iface1 hook 218 mkpeer fxp0: tee lower right 219 connect fxp0: fxp0:lower upper left 220 name fxp0:lower fxp0_tee 221 connect fxp0_tee: netflow: right2left iface1 222 223 # Create ksocket node on export hook, and configure it 224 # to send exports to proper destination 225 mkpeer netflow: ksocket export inet/dgram/udp 226 msg netflow:export connect inet/10.0.0.1:4444 227SEQ 228.Ed 229.Sh SEE ALSO 230.Xr netgraph 4 , 231.Xr ng_ksocket 4 , 232.Xr ng_tee 4 , 233.Xr ngctl 8 234.Pp 235.Pa http://www.cisco.com/warp/public/cc/pd/iosw/ioft/neflct/tech/napps_wp.htm 236.Sh AUTHORS 237.An -nosplit 238The 239.Nm 240node type was written by 241.An Gleb Smirnoff Aq glebius@FreeBSD.org , 242based on 243.Nm ng_ipacct 244written by 245.An Roman V. Palagin Aq romanp@unshadow.net . 246.Sh BUGS 247The 248.Nm 249node type does not fill in AS numbers. 250This is due to the lack of necessary information in the kernel routing table. 251However, this information can be injected into the kernel from a routing daemon 252such as GNU Zebra. 253This functionality may become available in future releases. 254