share/man/man4/ng_netflow.4

   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
  38 The
  39 .Nm
  40 node implements Cisco's NetFlow export protocol on a router running
  41 .Fx .
  42 The
  43 .Nm
  44 node listens for incoming traffic and identifies unique flows in it.
  45 Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers,
  46 ToS and input interface.
  47 Expired flows are exported out of the node in NetFlow version 5 UDP datagrams.
  48 Expiration reason can be one of the following:
  49 .Bl -dash
  50 .It
  51 RST or FIN TCP segment.
  52 .It
  53 Active timeout.
  54 Flows cannot live more than the specified period of time.
  55 The default is 1800 seconds (30 minutes).
  56 .It
  57 Inactive timeout.
  58 A flow was inactive for the specified period of time.
  59 The default is 15 seconds.
  60 .El
  61 .Pp
  62 Export information is stored in NetFlow version 5 datagrams.
  63 .Sh HOOKS
  64 This node type supports up to
  65 .Dv NG_NETFLOW_MAXIFACES
  66 hooks named
  67 .Va iface0 , iface1 ,
  68 etc.,
  69 and the same number of hooks named
  70 .Va out0 , out1 ,
  71 etc.,
  72 plus a single hook named
  73 .Va export .
  74 The node does NetFlow accounting of data received on
  75 .Va iface*
  76 hooks.
  77 If corresponding
  78 .Va out
  79 hook is connected, unmodified data is bypassed to it, otherwise data is freed.
  80 If data is received on
  81 .Va out
  82 hook, it is bypassed to corresponding
  83 .Va iface
  84 hook without any processing.
  85 When full export datagram is built it is sent to the
  86 .Va export
  87 hook.
  88 In normal operation, the
  89 .Va export
  90 hook is connected to the
  91 .Va inet/dgram/udp
  92 hook of the
  93 .Xr ng_ksocket 4
  94 node.
  95 .Sh CONTROL MESSAGES
  96 This node type supports the generic control messages, plus the following:
  97 .Bl -tag -width indent
  98 .It Dv NGM_NETFLOW_INFO
  99 Returns some node statistics and the current timeout values in a
 100 .Vt "struct ng_netflow_info" .
 101 .It Dv NGM_NETFLOW_IFINFO
 102 Returns information about the
 103 .Va iface Ns Ar N
 104 hook.
 105 The hook number is passed as an argument.
 106 .It Dv NGM_NETFLOW_SETDLT
 107 Sets data link type on the
 108 .Va iface Ns Ar N
 109 hook.
 110 Currently, supported types are raw IP datagrams and Ethernet.
 111 This messsage type uses
 112 .Vt "struct ng_netflow_setdlt"
 113 as an argument:
 114 .Bd -literal -offset 4n
 115 struct 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
 121 The requested
 122 .Va iface Ns Ar N
 123 hook must already be connected, otherwise message send operation will
 124 return an error.
 125 .It Dv NGM_NETFLOW_SETIFINDEX
 126 In some cases,
 127 .Nm
 128 may be unable to determine the input interface index of a packet.
 129 This can happen if traffic enters the
 130 .Nm
 131 node before it comes to the system interface's input queue.
 132 An example of such a setup is capturing a traffic
 133 .Em between
 134 synchronous data line and
 135 .Xr ng_iface 4 .
 136 In this case, the input index should be associated with a given hook.
 137 The interface's index can be determined via
 138 .Xr if_nametoindex 3
 139 from userland.
 140 This message requires
 141 .Vt "struct ng_netflow_setifindex"
 142 as an argument:
 143 .Bd -literal -offset 4n
 144 struct 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
 150 The requested
 151 .Va iface Ns Ar N
 152 hook must already be connected, otherwise the message
 153 send operation will return an error.
 154 .It Dv NGM_NETFLOW_SETTIMEOUTS
 155 Sets values in seconds for NetFlow active/inactive timeouts.
 156 This message requires
 157 .Vt "struct ng_netflow_settimeouts"
 158 as an argument:
 159 .Bd -literal -offset 4n
 160 struct ng_netflow_settimeouts {
 161         uint32_t        inactive_timeout;
 162         uint32_t        active_timeout;
 163 };
 164 .Ed
 165 .It Dv NGM_NETFLOW_SHOW
 166 This control message asks a node to dump the entire contents of the flow cache.
 167 It is called from
 168 .Xr flowctl 8 ,
 169 not directly from
 170 .Xr ngctl 8 .
 171 See also
 172 .Sx BUGS
 173 section.
 174 .El
 175 .Sh ASCII CONTROL MESSAGES
 176 Most binary control messages have an
 177 .Tn ASCII
 178 equivalent.
 179 The supported
 180 .Tn ASCII
 181 commands 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
 196 This node shuts down upon receipt of a
 197 .Dv NGM_SHUTDOWN
 198 control message, or when all hooks have been disconnected.
 199 .Sh EXAMPLES
 200 The simplest possible configuration is one Ethernet interface, where
 201 flow 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
 209 SEQ
 210 .Ed
 211 .Pp
 212 This is a more complicated example of a router with 2 NetFlow-enabled
 213 interfaces
 214 .Li fxp0
 215 and
 216 .Li ng0 .
 217 Note that the
 218 .Va ng0:
 219 node in this example is connected to
 220 .Xr ng_tee 4 .
 221 The latter sends us a copy of IP packets, which we analyze and free.
 222 On
 223 .Va fxp0:
 224 we 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
 243 SEQ
 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
 257 The
 258 .Nm
 259 node type was written by
 260 .An Gleb Smirnoff Aq glebius@FreeBSD.org ,
 261 based on
 262 .Nm ng_ipacct
 263 written by
 264 .An Roman V. Palagin Aq romanp@unshadow.net .
 265 .Sh BUGS
 266 Cache snapshot obtained via
 267 .Dv NGM_NETFLOW_SHOW
 268 command may lack some percentage of entries under severe load.
 269 .Pp
 270 The
 271 .Nm
 272 node type does not fill in AS numbers.
 273 This is due to the lack of necessary information in the kernel routing table.
 274 However, this information can be injected into the kernel from a routing daemon
 275 such as GNU Zebra.
 276 This functionality may become available in future releases.