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 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
  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 By default (ingress NetFlow enabled) node does NetFlow accounting of data
  75 received on
  76 .Va iface*
  77 hooks.
  78 If corresponding
  79 .Va out
  80 hook is connected, unmodified data is bypassed to it, otherwise data is freed.
  81 If data is received on
  82 .Va out
  83 hook, it is bypassed to corresponding
  84 .Va iface
  85 hook without any processing (egress NetFlow disabled by default).
  86 When full export datagram is built it is sent to the
  87 .Va export
  88 hook.
  89 In normal operation, the
  90 .Va export
  91 hook is connected to the
  92 .Va inet/dgram/udp
  93 hook of the
  94 .Xr ng_ksocket 4
  95 node.
  96 .Sh CONTROL MESSAGES
  97 This node type supports the generic control messages, plus the following:
  98 .Bl -tag -width indent
  99 .It Dv NGM_NETFLOW_INFO
 100 Returns some node statistics and the current timeout values in a
 101 .Vt "struct ng_netflow_info" .
 102 .It Dv NGM_NETFLOW_IFINFO
 103 Returns information about the
 104 .Va iface Ns Ar N
 105 hook.
 106 The hook number is passed as an argument.
 107 .It Dv NGM_NETFLOW_SETDLT
 108 Sets data link type on the
 109 .Va iface Ns Ar N
 110 hook.
 111 Currently, supported types are raw IP datagrams and Ethernet.
 112 This message type uses
 113 .Vt "struct ng_netflow_setdlt"
 114 as an argument:
 115 .Bd -literal -offset 4n
 116 struct 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
 122 The requested
 123 .Va iface Ns Ar N
 124 hook must already be connected, otherwise message send operation will
 125 return an error.
 126 .It Dv NGM_NETFLOW_SETIFINDEX
 127 In some cases,
 128 .Nm
 129 may be unable to determine the input interface index of a packet.
 130 This can happen if traffic enters the
 131 .Nm
 132 node before it comes to the system interface's input queue.
 133 An example of such a setup is capturing a traffic
 134 .Em between
 135 synchronous data line and
 136 .Xr ng_iface 4 .
 137 In this case, the input index should be associated with a given hook.
 138 The interface's index can be determined via
 139 .Xr if_nametoindex 3
 140 from userland.
 141 This message requires
 142 .Vt "struct ng_netflow_setifindex"
 143 as an argument:
 144 .Bd -literal -offset 4n
 145 struct 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
 151 The requested
 152 .Va iface Ns Ar N
 153 hook must already be connected, otherwise the message
 154 send operation will return an error.
 155 .It Dv NGM_NETFLOW_SETTIMEOUTS
 156 Sets values in seconds for NetFlow active/inactive timeouts.
 157 This message requires
 158 .Vt "struct ng_netflow_settimeouts"
 159 as an argument:
 160 .Bd -literal -offset 4n
 161 struct ng_netflow_settimeouts {
 162         uint32_t        inactive_timeout;
 163         uint32_t        active_timeout;
 164 };
 165 .Ed
 166 .It Dv NGM_NETFLOW_SETCONFIG
 167 Sets configuration for the specified interface.
 168 This message requires
 169 .Vt "struct ng_netflow_setconfig"
 170 as an argument:
 171 .Bd -literal -offset 4n
 172 struct 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
 182 Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS
 183 enabled by default enables ingress NetFlow generation (for data coming from
 184 ifaceX hook). Option NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data
 185 coming from outX hook). Option NG_NETFLOW_CONF_ONCE defines that packet should
 186 be accounted only once if it several times passes via netflow node. Option
 187 NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once
 188 if it several times passes via exactly this netflow node. Last two options are
 189 important to avoid duplicate accounting when both ingress and egress NetFlow
 190 are enabled.
 191 .It Dv NGM_NETFLOW_SHOW
 192 This control message asks a node to dump the entire contents of the flow cache.
 193 It is called from
 194 .Xr flowctl 8 ,
 195 not directly from
 196 .Xr ngctl 8 .
 197 See also
 198 .Sx BUGS
 199 section.
 200 .El
 201 .Sh ASCII CONTROL MESSAGES
 202 Most binary control messages have an
 203 .Tn ASCII
 204 equivalent.
 205 The supported
 206 .Tn ASCII
 207 commands 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
 224 This node shuts down upon receipt of a
 225 .Dv NGM_SHUTDOWN
 226 control message, or when all hooks have been disconnected.
 227 .Sh EXAMPLES
 228 The simplest possible configuration is one Ethernet interface, where
 229 flow 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
 237 SEQ
 238 .Ed
 239 .Pp
 240 This is a more complicated example of a router with 2 NetFlow-enabled
 241 interfaces
 242 .Li fxp0
 243 and
 244 .Li ng0 .
 245 Note that the
 246 .Va ng0:
 247 node in this example is connected to
 248 .Xr ng_tee 4 .
 249 The latter sends us a copy of IP packets, which we analyze and free.
 250 On
 251 .Va fxp0:
 252 we 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
 271 SEQ
 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
 285 The
 286 .Nm
 287 node type was written by
 288 .An Gleb Smirnoff Aq glebius@FreeBSD.org ,
 289 based on
 290 .Nm ng_ipacct
 291 written by
 292 .An Roman V. Palagin Aq romanp@unshadow.net .
 293 .Sh BUGS
 294 Cache snapshot obtained via
 295 .Dv NGM_NETFLOW_SHOW
 296 command may lack some percentage of entries under severe load.
 297 .Pp
 298 The
 299 .Nm
 300 node type does not fill in AS numbers.
 301 This is due to the lack of necessary information in the kernel routing table.
 302 However, this information can be injected into the kernel from a routing daemon
 303 such as GNU Zebra.
 304 This functionality may become available in future releases.