A man page for Netflow node.

English lessons by:	julian
mdoc(7) lessons by:	ru
Approved by:		julian (mentor)

1 files changed, 247 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..a03b2e3
--- /dev/null
+++ b/share/man/man4/ng_netflow.4
@@ -0,0 +1,247 @@
+.\" Copyright (c) 2004 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 September 17, 2004
+.Os
+.Dt NG_NETFLOW 4
+.Sh NAME
+.Nm ng_netflow
+.Nd Cisco's Netflow implementation
+.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.
+.It
+Inactive timeout.
+A flow was inactive for the specified period of time.
+.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.,
+plus a single hook named
+.Va export .
+The node reads data on
+.Va iface*
+hooks, and sends export datagrams 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 messsage 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 */
+	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 */
+	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_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 .
+.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
+.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 }"
+.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: tee lower right
+	connect fxp0: fxp0:lower upper left
+	mkpeer fxp0:lower netflow right2left iface0
+	name fxp0:lower.right2left netflow
+	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 .
+.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 }
+
+	# Create tee on fxp0, and connect it to iface1 hook
+	mkpeer fxp0: tee lower right
+	connect fxp0: fxp0:lower upper left
+	name fxp0:lower fxp0_tee
+	connect fxp0_tee: netflow: right2left iface1
+
+	# 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 BUGS
+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.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ng_ksocket 4 ,
+.Xr ng_tee 4 ,
+.Xr ngctl 8
+.Pp
+.Pa http://www.cisco.com/warp/public/cc/pd/iosw/ioft/neflct/tech/napps_wp.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 .