aa12cea2cc
Although groff_mdoc(7) gives another impression, this is the ordering most widely used and also required by mdocml/mandoc. Reviewed by: ru Approved by: philip, ed (mentors)
305 lines
8.8 KiB
Groff
305 lines
8.8 KiB
Groff
.\" Copyright (c) 2004-2005 Gleb Smirnoff <glebius@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 8, 2008
|
|
.Dt NG_NETFLOW 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ng_netflow
|
|
.Nd Cisco's NetFlow implementation
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In netinet/in.h
|
|
.In netgraph/netflow/ng_netflow.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
node implements Cisco's NetFlow export protocol on a router running
|
|
.Fx .
|
|
The
|
|
.Nm
|
|
node listens for incoming traffic and identifies unique flows in it.
|
|
Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers,
|
|
ToS and input interface.
|
|
Expired flows are exported out of the node in NetFlow version 5 UDP datagrams.
|
|
Expiration reason can be one of the following:
|
|
.Bl -dash
|
|
.It
|
|
RST or FIN TCP segment.
|
|
.It
|
|
Active timeout.
|
|
Flows cannot live more than the specified period of time.
|
|
The default is 1800 seconds (30 minutes).
|
|
.It
|
|
Inactive timeout.
|
|
A flow was inactive for the specified period of time.
|
|
The default is 15 seconds.
|
|
.El
|
|
.Pp
|
|
Export information is stored in NetFlow version 5 datagrams.
|
|
.Sh HOOKS
|
|
This node type supports up to
|
|
.Dv NG_NETFLOW_MAXIFACES
|
|
hooks named
|
|
.Va iface0 , iface1 ,
|
|
etc.,
|
|
and the same number of hooks named
|
|
.Va out0 , out1 ,
|
|
etc.,
|
|
plus a single hook named
|
|
.Va export .
|
|
By default (ingress NetFlow enabled) node does NetFlow accounting of data
|
|
received on
|
|
.Va iface*
|
|
hooks.
|
|
If corresponding
|
|
.Va out
|
|
hook is connected, unmodified data is bypassed to it, otherwise data is freed.
|
|
If data is received on
|
|
.Va out
|
|
hook, it is bypassed to corresponding
|
|
.Va iface
|
|
hook without any processing (egress NetFlow disabled by default).
|
|
When full export datagram is built it is sent to the
|
|
.Va export
|
|
hook.
|
|
In normal operation, the
|
|
.Va export
|
|
hook is connected to the
|
|
.Va inet/dgram/udp
|
|
hook of the
|
|
.Xr ng_ksocket 4
|
|
node.
|
|
.Sh CONTROL MESSAGES
|
|
This node type supports the generic control messages, plus the following:
|
|
.Bl -tag -width indent
|
|
.It Dv NGM_NETFLOW_INFO
|
|
Returns some node statistics and the current timeout values in a
|
|
.Vt "struct ng_netflow_info" .
|
|
.It Dv NGM_NETFLOW_IFINFO
|
|
Returns information about the
|
|
.Va iface Ns Ar N
|
|
hook.
|
|
The hook number is passed as an argument.
|
|
.It Dv NGM_NETFLOW_SETDLT
|
|
Sets data link type on the
|
|
.Va iface Ns Ar N
|
|
hook.
|
|
Currently, supported types are raw IP datagrams and Ethernet.
|
|
This message type uses
|
|
.Vt "struct ng_netflow_setdlt"
|
|
as an argument:
|
|
.Bd -literal -offset 4n
|
|
struct ng_netflow_setdlt {
|
|
uint16_t iface; /* which iface to operate on */
|
|
uint8_t dlt; /* DLT_XXX from bpf.h */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The requested
|
|
.Va iface Ns Ar N
|
|
hook must already be connected, otherwise message send operation will
|
|
return an error.
|
|
.It Dv NGM_NETFLOW_SETIFINDEX
|
|
In some cases,
|
|
.Nm
|
|
may be unable to determine the input interface index of a packet.
|
|
This can happen if traffic enters the
|
|
.Nm
|
|
node before it comes to the system interface's input queue.
|
|
An example of such a setup is capturing a traffic
|
|
.Em between
|
|
synchronous data line and
|
|
.Xr ng_iface 4 .
|
|
In this case, the input index should be associated with a given hook.
|
|
The interface's index can be determined via
|
|
.Xr if_nametoindex 3
|
|
from userland.
|
|
This message requires
|
|
.Vt "struct ng_netflow_setifindex"
|
|
as an argument:
|
|
.Bd -literal -offset 4n
|
|
struct ng_netflow_setifindex {
|
|
u_int16_t iface; /* which iface to operate on */
|
|
u_int16_t index; /* new index */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The requested
|
|
.Va iface Ns Ar N
|
|
hook must already be connected, otherwise the message
|
|
send operation will return an error.
|
|
.It Dv NGM_NETFLOW_SETTIMEOUTS
|
|
Sets values in seconds for NetFlow active/inactive timeouts.
|
|
This message requires
|
|
.Vt "struct ng_netflow_settimeouts"
|
|
as an argument:
|
|
.Bd -literal -offset 4n
|
|
struct ng_netflow_settimeouts {
|
|
uint32_t inactive_timeout;
|
|
uint32_t active_timeout;
|
|
};
|
|
.Ed
|
|
.It Dv NGM_NETFLOW_SETCONFIG
|
|
Sets configuration for the specified interface.
|
|
This message requires
|
|
.Vt "struct ng_netflow_setconfig"
|
|
as an argument:
|
|
.Bd -literal -offset 4n
|
|
struct ng_netflow_setconfig {
|
|
u_int16_t iface;
|
|
u_int32_t conf;
|
|
#define NG_NETFLOW_CONF_INGRESS 1
|
|
#define NG_NETFLOW_CONF_EGRESS 2
|
|
#define NG_NETFLOW_CONF_ONCE 4
|
|
#define NG_NETFLOW_CONF_THISONCE 8
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Configuration is a bitmask of several options. Option NG_NETFLOW_CONF_INGRESS
|
|
enabled by default enables ingress NetFlow generation (for data coming from
|
|
ifaceX hook). Option NG_NETFLOW_CONF_EGRESS enables egress NetFlow (for data
|
|
coming from outX hook). Option NG_NETFLOW_CONF_ONCE defines that packet should
|
|
be accounted only once if it several times passes via netflow node. Option
|
|
NG_NETFLOW_CONF_THISONCE defines that packet should be accounted only once
|
|
if it several times passes via exactly this netflow node. Last two options are
|
|
important to avoid duplicate accounting when both ingress and egress NetFlow
|
|
are enabled.
|
|
.It Dv NGM_NETFLOW_SHOW
|
|
This control message asks a node to dump the entire contents of the flow cache.
|
|
It is called from
|
|
.Xr flowctl 8 ,
|
|
not directly from
|
|
.Xr ngctl 8 .
|
|
See also
|
|
.Sx BUGS
|
|
section.
|
|
.El
|
|
.Sh ASCII CONTROL MESSAGES
|
|
Most binary control messages have an
|
|
.Tn ASCII
|
|
equivalent.
|
|
The supported
|
|
.Tn ASCII
|
|
commands are:
|
|
.Pp
|
|
.Bl -tag -width ".Dv NGM_NETFLOW_SETTIMEOUTS" -compact
|
|
.It Dv NGM_NETFLOW_INFO
|
|
.Qq Li info
|
|
.It Dv NGM_NETFLOW_IFINFO
|
|
.Qq Li "ifinfo %u"
|
|
.It Dv NGM_NETFLOW_SETDLT
|
|
.Qq Li "setdlt { iface = %u dlt = %u }"
|
|
.It Dv NGM_NETFLOW_SETIFINDEX
|
|
.Qq Li "setifindex { iface = %u index = %u }"
|
|
.It Dv NGM_NETFLOW_SETTIMEOUTS
|
|
.Qq Li "settimeouts { inactive = %u active = %u }"
|
|
.It Dv NGM_NETFLOW_SETCONFIG
|
|
.Qq Li "setconfig { iface = %u conf = %u }"
|
|
.El
|
|
.Sh SHUTDOWN
|
|
This node shuts down upon receipt of a
|
|
.Dv NGM_SHUTDOWN
|
|
control message, or when all hooks have been disconnected.
|
|
.Sh EXAMPLES
|
|
The simplest possible configuration is one Ethernet interface, where
|
|
flow collecting is enabled.
|
|
.Bd -literal -offset indent
|
|
/usr/sbin/ngctl -f- <<-SEQ
|
|
mkpeer fxp0: netflow lower iface0
|
|
name fxp0:lower netflow
|
|
connect fxp0: netflow: upper out0
|
|
mkpeer netflow: ksocket export inet/dgram/udp
|
|
msg netflow:export connect inet/10.0.0.1:4444
|
|
SEQ
|
|
.Ed
|
|
.Pp
|
|
This is a more complicated example of a router with 2 NetFlow-enabled
|
|
interfaces
|
|
.Li fxp0
|
|
and
|
|
.Li ng0 .
|
|
Note that the
|
|
.Va ng0:
|
|
node in this example is connected to
|
|
.Xr ng_tee 4 .
|
|
The latter sends us a copy of IP packets, which we analyze and free.
|
|
On
|
|
.Va fxp0:
|
|
we do not use tee, but send packets back to ether node.
|
|
.Bd -literal -offset indent
|
|
/usr/sbin/ngctl -f- <<-SEQ
|
|
# connect ng0's tee to iface0 hook
|
|
mkpeer ng0:inet netflow right2left iface0
|
|
name ng0:inet.right2left netflow
|
|
# set DLT to raw mode
|
|
msg netflow: setdlt { iface=0 dlt=12 }
|
|
# set interface index (5 in this example)
|
|
msg netflow: setifindex { iface=0 index=5 }
|
|
|
|
# Connect fxp0: to iface1 and out1 hook
|
|
connect fxp0: netflow: lower iface1
|
|
connect fxp0: netflow: upper out1
|
|
|
|
# Create ksocket node on export hook, and configure it
|
|
# to send exports to proper destination
|
|
mkpeer netflow: ksocket export inet/dgram/udp
|
|
msg netflow:export connect inet/10.0.0.1:4444
|
|
SEQ
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr netgraph 4 ,
|
|
.Xr ng_ether 4 ,
|
|
.Xr ng_iface 4 ,
|
|
.Xr ng_ksocket 4 ,
|
|
.Xr ng_tee 4 ,
|
|
.Xr flowctl 8 ,
|
|
.Xr ngctl 8
|
|
.Pp
|
|
.Pa http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/netflsol/\:nfwhite.htm
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
node type was written by
|
|
.An Gleb Smirnoff Aq glebius@FreeBSD.org ,
|
|
based on
|
|
.Nm ng_ipacct
|
|
written by
|
|
.An Roman V. Palagin Aq romanp@unshadow.net .
|
|
.Sh BUGS
|
|
Cache snapshot obtained via
|
|
.Dv NGM_NETFLOW_SHOW
|
|
command may lack some percentage of entries under severe load.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
node type does not fill in AS numbers.
|
|
This is due to the lack of necessary information in the kernel routing table.
|
|
However, this information can be injected into the kernel from a routing daemon
|
|
such as GNU Zebra.
|
|
This functionality may become available in future releases.
|