diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index a0d62873b296..80d5acaab4bc 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -183,6 +183,7 @@ MAN= aac.4 \ ng_l2tp.4 \ ng_lmi.4 \ ng_mppc.4 \ + ng_netflow.4 \ ng_one2many.4 \ ng_ppp.4 \ ng_pppoe.4 \ diff --git a/share/man/man4/ng_netflow.4 b/share/man/man4/ng_netflow.4 new file mode 100644 index 000000000000..a03b2e31bc16 --- /dev/null +++ b/share/man/man4/ng_netflow.4 @@ -0,0 +1,247 @@ +.\" Copyright (c) 2004 Gleb Smirnoff +.\" 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 .