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