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