1 .\" Copyright (c) 2004-2005 Gleb Smirnoff <glebius@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd Cisco's NetFlow implementation
36 .In netgraph/netflow/ng_netflow.h
40 node implements Cisco's NetFlow export protocol on a router running
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/9 UDP datagrams.
48 Expiration reason can be one of the following:
51 RST or FIN TCP segment.
54 Flows cannot live more than the specified period of time.
55 The default is 1800 seconds (30 minutes).
58 A flow was inactive for the specified period of time.
59 The default is 15 seconds.
62 Node supports IPv6 accounting (NetFlow v9 only) and is aware of multiple fibs.
63 Different fibs are mapped to different domain_id in NetFlow V9 and different engine_id in NetFlow V5.
66 This node type supports up to
67 .Dv NG_NETFLOW_MAXIFACES
68 (default 65536) hooks named
71 and the same number of hooks named
74 plus two export hooks:
76 (for NetFlow version 5) and
78 (for NetFlow version 9). Export can be done simultaneously for all supported
79 export hooks. By default (ingress NetFlow enabled) node does NetFlow accounting of data
85 hook is connected, unmodified data is bypassed to it, otherwise data is freed.
86 If data is received on
88 hook, it is bypassed to corresponding
90 hook without any processing (egress NetFlow disabled by default).
91 When full export datagram for an export protocol is built it is sent to the
96 In normal operation, one (or more) export hook is connected to the
102 This node type supports the generic control messages, plus the following:
103 .Bl -tag -width indent
104 .It Dv NGM_NETFLOW_INFO
105 Returns some node statistics and the current timeout values in a
106 .Vt "struct ng_netflow_info" .
107 .It Dv NGM_NETFLOW_IFINFO
108 Returns information about the
111 The hook number is passed as an argument.
112 .It Dv NGM_NETFLOW_SETDLT
113 Sets data link type on the
116 Currently, supported types are raw IP datagrams and Ethernet.
117 This message type uses
118 .Vt "struct ng_netflow_setdlt"
120 .Bd -literal -offset 4n
121 struct ng_netflow_setdlt {
122 uint16_t iface; /* which iface to operate on */
123 uint8_t dlt; /* DLT_XXX from bpf.h */
129 hook must already be connected, otherwise message send operation will
131 .It Dv NGM_NETFLOW_SETIFINDEX
134 may be unable to determine the input interface index of a packet.
135 This can happen if traffic enters the
137 node before it comes to the system interface's input queue.
138 An example of such a setup is capturing a traffic
140 synchronous data line and
142 In this case, the input index should be associated with a given hook.
143 The interface's index can be determined via
146 This message requires
147 .Vt "struct ng_netflow_setifindex"
149 .Bd -literal -offset 4n
150 struct ng_netflow_setifindex {
151 u_int16_t iface; /* which iface to operate on */
152 u_int16_t index; /* new index */
158 hook must already be connected, otherwise the message
159 send operation will return an error.
160 .It Dv NGM_NETFLOW_SETTIMEOUTS
161 Sets values in seconds for NetFlow active/inactive timeouts.
162 This message requires
163 .Vt "struct ng_netflow_settimeouts"
165 .Bd -literal -offset 4n
166 struct ng_netflow_settimeouts {
167 uint32_t inactive_timeout;
168 uint32_t active_timeout;
171 .It Dv NGM_NETFLOW_SETCONFIG
172 Sets configuration for the specified interface.
173 This message requires
174 .Vt "struct ng_netflow_setconfig"
176 .Bd -literal -offset 4n
177 struct ng_netflow_setconfig {
180 #define NG_NETFLOW_CONF_INGRESS 1
181 #define NG_NETFLOW_CONF_EGRESS 2
182 #define NG_NETFLOW_CONF_ONCE 4
183 #define NG_NETFLOW_CONF_THISONCE 8
187 Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS
188 enabled by default enables ingress NetFlow generation (for data coming from
189 ifaceX hook). Option NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data
190 coming from outX hook). Option NG_NETFLOW_CONF_ONCE defines that packet should
191 be accounted only once if it several times passes via netflow node. Option
192 NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once
193 if it several times passes via exactly this netflow node. Last two options are
194 important to avoid duplicate accounting when both ingress and egress NetFlow
196 .It Dv NGM_NETFLOW_SETTEMPLATE
197 Sets various timeouts to announce data flow templates
198 (NetFlow v9-specific). This message requires
199 .Vt "struct ng_netflow_settemplate"
201 .Bd -literal -offset 4n
202 struct ng_netflow_settemplate {
208 Value of time field represents time in seconds to re-announce data templates.
209 Value of packets field represents maximum packets count between
210 re-announcing data templates.
211 .It Dv NGM_NETFLOW_SETMTU
212 Sets export interface MTU to build packets of specified size (NetFlow v9-specific).
213 This message requires
214 .Vt "struct ng_netflow_setmtu"
216 .Bd -literal -offset 4n
217 struct ng_netflow_settemtu {
222 Default is 1500 bytes
223 .It Dv NGM_NETFLOW_SHOW
224 This control message asks a node to dump the entire contents of the flow cache.
233 .Sh ASCII CONTROL MESSAGES
234 Most binary control messages have an
241 .Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact
242 .It Dv NGM_NETFLOW_INFO
244 .It Dv NGM_NETFLOW_IFINFO
246 .It Dv NGM_NETFLOW_SETDLT
247 .Qq Li "setdlt { iface = %u dlt = %u }"
248 .It Dv NGM_NETFLOW_SETIFINDEX
249 .Qq Li "setifindex { iface = %u index = %u }"
250 .It Dv NGM_NETFLOW_SETTIMEOUTS
251 .Qq Li "settimeouts { inactive = %u active = %u }"
252 .It Dv NGM_NETFLOW_SETCONFIG
253 .Qq Li "setconfig { iface = %u conf = %u }"
254 .It Dv NGM_NETFLOW_SETTEMPLATE
255 .Qq Li "settemplate { time = %u packets = %u }"
256 .It Dv NGM_NETFLOW_SETMTU
257 .Qq Li "setmtu { mtu = %u }"
260 This node shuts down upon receipt of a
262 control message, or when all hooks have been disconnected.
264 The simplest possible configuration is one Ethernet interface, where
265 flow collecting is enabled.
266 .Bd -literal -offset indent
267 /usr/sbin/ngctl -f- <<-SEQ
268 mkpeer fxp0: netflow lower iface0
269 name fxp0:lower netflow
270 connect fxp0: netflow: upper out0
271 mkpeer netflow: ksocket export inet/dgram/udp
272 msg netflow:export connect inet/10.0.0.1:4444
276 This is a more complicated example of a router with 2 NetFlow-enabled
283 node in this example is connected to
285 The latter sends us a copy of IP packets, which we analyze and free.
288 we do not use tee, but send packets back to ether node.
289 .Bd -literal -offset indent
290 /usr/sbin/ngctl -f- <<-SEQ
291 # connect ng0's tee to iface0 hook
292 mkpeer ng0:inet netflow right2left iface0
293 name ng0:inet.right2left netflow
294 # set DLT to raw mode
295 msg netflow: setdlt { iface=0 dlt=12 }
296 # set interface index (5 in this example)
297 msg netflow: setifindex { iface=0 index=5 }
299 # Connect fxp0: to iface1 and out1 hook
300 connect fxp0: netflow: lower iface1
301 connect fxp0: netflow: upper out1
303 # Create ksocket node on export hook, and configure it
304 # to send exports to proper destination
305 mkpeer netflow: ksocket export inet/dgram/udp
306 msg netflow:export connect inet/10.0.0.1:4444
320 .%T "Cisco Systems NetFlow Services Export Version 9"
324 .Pa http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html
329 node type was written by
330 .An Gleb Smirnoff Aq glebius@FreeBSD.org ,
331 .An Alexander Motin Aq mav@FreeBSD.org ,
332 .An Alexander Chernikov Aq melifaro@ipfw.ru .
333 The initial code was based on
336 .An Roman V. Palagin Aq romanp@unshadow.net .
338 Cache snapshot obtained via
340 command may lack some percentage of entries under severe load.
341 IPv6 flows are not shown.
345 node type does not fill in AS numbers.
346 This is due to the lack of necessary information in the kernel routing table.
347 However, this information can be injected into the kernel from a routing daemon
349 This functionality may become available in future releases.