summaryrefslogtreecommitdiffstats
path: root/share/man/man4/ng_netflow.4
diff options
context:
space:
mode:
Diffstat (limited to 'share/man/man4/ng_netflow.4')
-rw-r--r--share/man/man4/ng_netflow.4356
1 files changed, 356 insertions, 0 deletions
diff --git a/share/man/man4/ng_netflow.4 b/share/man/man4/ng_netflow.4
new file mode 100644
index 0000000..3c710dc
--- /dev/null
+++ b/share/man/man4/ng_netflow.4
@@ -0,0 +1,356 @@
+.\" 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 December 10, 2012
+.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/9 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
+Node supports IPv6 accounting (NetFlow v9 only) and is aware of multiple fibs.
+Different fibs are mapped to different domain_id in NetFlow V9 and different engine_id in NetFlow V5.
+.Sh HOOKS
+This node type supports up to
+.Dv NG_NETFLOW_MAXIFACES
+(default 65536) hooks named
+.Va iface0 , iface1 ,
+etc.,
+and the same number of hooks named
+.Va out0 , out1 ,
+etc.,
+plus two export hooks:
+.Va export
+(for NetFlow version 5) and
+.Va export9
+(for NetFlow version 9). Export can be done simultaneously for all supported
+export hooks. 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 for an export protocol is built it is sent to the
+.Va export
+or
+.Va export9
+hook.
+In normal operation, one (or more) 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 foo
+.It Dv NGM_NETFLOW_INFO Pq Ic info
+Returns some node statistics and the current timeout values in a
+.Vt "struct ng_netflow_info" .
+.It Dv NGM_NETFLOW_IFINFO Pq Ic ifinfo
+Returns information about the
+.Va iface Ns Ar N
+hook.
+The hook number is passed as an argument.
+.It Dv NGM_NETFLOW_SETDLT Pq Ic setdlt
+Sets data link type on the
+.Va iface Ns Ar N
+hook.
+Currently, supported types are
+.Cm DLT_RAW
+(raw IP datagrams) and
+.Cm DLT_EN10MB
+(Ethernet).
+DLT_ definitions can be found in
+.In net/bpf.h
+header.
+Currently used values are 1 for
+.Cm DLT_EN10MB
+and 12 for
+.Cm DLT_RAW .
+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 dlt change */
+ 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 Pq Ic 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 {
+ uint16_t iface; /* which iface index change */
+ uint16_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 Pq Ic 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; /* flow inactive timeout */
+ uint32_t active_timeout; /* flow active timeout */
+};
+.Ed
+.It Dv NGM_NETFLOW_SETCONFIG Pq Ic 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 {
+ uint16_t iface; /* which iface config change */
+ uint32_t conf; /* new config */
+#define NG_NETFLOW_CONF_INGRESS 1
+#define NG_NETFLOW_CONF_EGRESS 2
+#define NG_NETFLOW_CONF_ONCE 4
+#define NG_NETFLOW_CONF_THISONCE 8
+#define NG_NETFLOW_CONF_NOSRCLOOKUP 16
+#define NG_NETFLOW_CONF_NODSTLOOKUP 32
+};
+.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
+.Va NG_NETFLOW_CONF_EGRESS
+enables egress NetFlow (for data coming from outX hook).
+Option
+.Va NG_NETFLOW_CONF_ONCE
+defines that packet should be accounted only once if it several times passes
+via netflow node.
+Option
+.Va NG_NETFLOW_CONF_THISONCE
+defines that packet should be accounted only once if it several times passes
+via exactly this netflow node.
+These two options are important to avoid duplicate accounting when both ingress
+and egress NetFlow are enabled.
+Option
+.Va NG_NETFLOW_CONF_NOSRCLOOKUP
+skips radix lookup on flow source address used to fill in network mask.
+Option
+.Va NG_NETFLOW_CONF_NODSTLOOKUP
+skips radix lookup on destination (which fills egress interface id, destination
+mask and gateway).
+If one doesn't need data provided by lookups, he/she can disable them, to reduce
+load on routers.
+.It Dv NGM_NETFLOW_SETTEMPLATE Pq Ic settemplate
+Sets various timeouts to announce data flow templates
+(NetFlow v9-specific). This message requires
+.Vt "struct ng_netflow_settemplate"
+as an argument:
+.Bd -literal -offset 4n
+struct ng_netflow_settemplate {
+ uint16_t time; /* max time between announce */
+ uint16_t packets; /* max packets between announce */
+};
+.Ed
+.Pp
+Value of time field represents time in seconds to re-announce data templates.
+Value of packets field represents maximum packets count between
+re-announcing data templates.
+.It Dv NGM_NETFLOW_SETMTU Pq Ic setmtu
+Sets export interface MTU to build packets of specified size (NetFlow v9-specific).
+This message requires
+.Vt "struct ng_netflow_setmtu"
+as an argument:
+.Bd -literal -offset 4n
+struct ng_netflow_setemtu {
+ uint16_t mtu; /* MTU for packet */
+};
+.Ed
+.Pp
+Default is 1500 bytes.
+.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 .
+.It Dv NGM_NETFLOW_V9INFO Pq Ic v9info
+Returns some NetFlow v9 related values in a
+.Bd -literal -offset 4n
+struct ng_netflow_v9info {
+ uint16_t templ_packets; /* v9 template packets */
+ uint16_t templ_time; /* v9 template time */
+ uint16_t mtu; /* v9 MTU */
+};
+.Ed
+.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 either 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 setfib 2 ,
+.Xr ng_ether 4 ,
+.Xr ng_iface 4 ,
+.Xr ng_ksocket 4 ,
+.Xr ng_tee 4 ,
+.Xr flowctl 8 ,
+.Xr ngctl 8
+.Rs
+.%A B. Claise, Ed
+.%T "Cisco Systems NetFlow Services Export Version 9"
+.%O RFC 3954
+.Re
+.Pp
+.Pa http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+node type was written by
+.An Gleb Smirnoff Aq glebius@FreeBSD.org ,
+.An Alexander Motin Aq mav@FreeBSD.org ,
+.An Alexander Chernikov Aq melifaro@ipfw.ru .
+The initial code was 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.
OpenPOWER on IntegriCloud