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 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 Export information is stored in NetFlow version 5 datagrams.
64 This node type supports up to
65 .Dv NG_NETFLOW_MAXIFACES
69 and the same number of hooks named
72 plus a single hook named
74 By default (ingress NetFlow enabled) node does NetFlow accounting of data
80 hook is connected, unmodified data is bypassed to it, otherwise data is freed.
81 If data is received on
83 hook, it is bypassed to corresponding
85 hook without any processing (egress NetFlow disabled by default).
86 When full export datagram is built it is sent to the
89 In normal operation, the
91 hook is connected to the
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
106 The hook number is passed as an argument.
107 .It Dv NGM_NETFLOW_SETDLT
108 Sets data link type on the
111 Currently, supported types are raw IP datagrams and Ethernet.
112 This message type uses
113 .Vt "struct ng_netflow_setdlt"
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 */
124 hook must already be connected, otherwise message send operation will
126 .It Dv NGM_NETFLOW_SETIFINDEX
129 may be unable to determine the input interface index of a packet.
130 This can happen if traffic enters the
132 node before it comes to the system interface's input queue.
133 An example of such a setup is capturing a traffic
135 synchronous data line and
137 In this case, the input index should be associated with a given hook.
138 The interface's index can be determined via
141 This message requires
142 .Vt "struct ng_netflow_setifindex"
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 */
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"
160 .Bd -literal -offset 4n
161 struct ng_netflow_settimeouts {
162 uint32_t inactive_timeout;
163 uint32_t active_timeout;
166 .It Dv NGM_NETFLOW_SETCONFIG
167 Sets configuration for the specified interface.
168 This message requires
169 .Vt "struct ng_netflow_setconfig"
171 .Bd -literal -offset 4n
172 struct ng_netflow_setconfig {
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
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
191 .It Dv NGM_NETFLOW_SHOW
192 This control message asks a node to dump the entire contents of the flow cache.
201 .Sh ASCII CONTROL MESSAGES
202 Most binary control messages have an
209 .Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact
210 .It Dv NGM_NETFLOW_INFO
212 .It Dv NGM_NETFLOW_IFINFO
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 }"
224 This node shuts down upon receipt of a
226 control message, or when all hooks have been disconnected.
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
240 This is a more complicated example of a router with 2 NetFlow-enabled
247 node in this example is connected to
249 The latter sends us a copy of IP packets, which we analyze and free.
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 }
263 # Connect fxp0: to iface1 and out1 hook
264 connect fxp0: netflow: lower iface1
265 connect fxp0: netflow: upper out1
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
282 .Pa http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/netflsol/\:nfwhite.htm
287 node type was written by
288 .An Gleb Smirnoff Aq glebius@FreeBSD.org ,
292 .An Roman V. Palagin Aq romanp@unshadow.net .
294 Cache snapshot obtained via
296 command may lack some percentage of entries under severe load.
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
304 This functionality may become available in future releases.