diff options
Diffstat (limited to 'static/freebsd/man4/ng_netflow.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_netflow.4 3.html | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_netflow.4 3.html b/static/freebsd/man4/ng_netflow.4 3.html new file mode 100644 index 00000000..e2f9e217 --- /dev/null +++ b/static/freebsd/man4/ng_netflow.4 3.html @@ -0,0 +1,304 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_NETFLOW(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_NETFLOW(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">ng_netflow</code> — + <span class="Nd">Cisco's NetFlow implementation</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">netinet/in.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netgraph/netflow/ng_netflow.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">ng_netflow</code> node implements Cisco's + NetFlow export protocol on a router running <span class="Ux">FreeBSD</span>. + The <code class="Nm">ng_netflow</code> 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:</p> +<ul class="Bl-dash"> + <li>RST or FIN TCP segment.</li> + <li>Active timeout. Flows cannot live more than the specified period of time. + The default is 1800 seconds (30 minutes).</li> + <li>Inactive timeout. A flow was inactive for the specified period of time. + The default is 15 seconds.</li> +</ul> +<p class="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.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">This node type supports up to + <code class="Dv">NG_NETFLOW_MAXIFACES</code> (default 65536) hooks named + <var class="Va">iface0</var>, <var class="Va">iface1</var>, etc., and the + same number of hooks named <var class="Va">out0</var>, + <var class="Va">out1</var>, etc., plus two export hooks: + <var class="Va">export</var> (for NetFlow version 5) and + <var class="Va">export9</var> (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 + <var class="Va">iface*</var> hooks. If corresponding + <var class="Va">out</var> hook is connected, unmodified data is bypassed to + it, otherwise data is freed. If data is received on + <var class="Va">out</var> hook, it is bypassed to corresponding + <var class="Va">iface</var> hook without any processing (egress NetFlow + disabled by default). When full export datagram for an export protocol is + built it is sent to the <var class="Va">export</var> or + <var class="Va">export9</var> hook. In normal operation, one (or more) + export hook is connected to the <var class="Va">inet/dgram/udp</var> hook of + the <a class="Xr">ng_ksocket(4)</a> node.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL + MESSAGES</a></h1> +<p class="Pp">This node type supports the generic control messages, plus the + following:</p> +<dl class="Bl-tag"> + <dt id="NGM_NETFLOW_INFO"><a class="permalink" href="#NGM_NETFLOW_INFO"><code class="Dv">NGM_NETFLOW_INFO</code></a> + (<code class="Ic">info</code>)</dt> + <dd>Returns some node statistics and the current timeout values in a + <var class="Vt">struct ng_netflow_info</var>.</dd> + <dt id="NGM_NETFLOW_IFINFO"><a class="permalink" href="#NGM_NETFLOW_IFINFO"><code class="Dv">NGM_NETFLOW_IFINFO</code></a> + (<code class="Ic">ifinfo</code>)</dt> + <dd>Returns information about the + <var class="Va">iface</var><var class="Ar">N</var> hook. The hook number + is passed as an argument.</dd> + <dt id="NGM_NETFLOW_SETDLT"><a class="permalink" href="#NGM_NETFLOW_SETDLT"><code class="Dv">NGM_NETFLOW_SETDLT</code></a> + (<code class="Ic">setdlt</code>)</dt> + <dd>Sets data link type on the + <var class="Va">iface</var><var class="Ar">N</var> hook. Currently, + supported types are <code class="Cm">DLT_RAW</code> (raw IP datagrams) and + <code class="Cm">DLT_EN10MB</code> (Ethernet). DLT_ definitions can be + found in <code class="In"><<a class="In">net/bpf.h</a>></code> + header. Currently used values are 1 for <code class="Cm">DLT_EN10MB</code> + and 12 for <code class="Cm">DLT_RAW</code>. This message type uses + <var class="Vt">struct ng_netflow_setdlt</var> as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_setdlt { + uint16_t iface; /* which iface dlt change */ + uint8_t dlt; /* DLT_XXX from bpf.h */ +};</pre> + </div> + <p class="Pp">The requested + <var class="Va">iface</var><var class="Ar">N</var> hook must already be + connected, otherwise message send operation will return an error.</p> + </dd> + <dt id="NGM_NETFLOW_SETIFINDEX"><a class="permalink" href="#NGM_NETFLOW_SETIFINDEX"><code class="Dv">NGM_NETFLOW_SETIFINDEX</code></a> + (<code class="Ic">setifindex</code>)</dt> + <dd>In some cases, <code class="Nm">ng_netflow</code> may be unable to + determine the input interface index of a packet. This can happen if + traffic enters the <code class="Nm">ng_netflow</code> node before it comes + to the system interface's input queue. An example of such a setup is + capturing a traffic + <a class="permalink" href="#between"><i class="Em" id="between">between</i></a> + synchronous data line and <a class="Xr">ng_iface(4)</a>. In this case, the + input index should be associated with a given hook. The interface's index + can be determined via <a class="Xr">if_nametoindex(3)</a> from userland. + This message requires <var class="Vt">struct ng_netflow_setifindex</var> + as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_setifindex { + uint16_t iface; /* which iface index change */ + uint16_t index; /* new index */ +};</pre> + </div> + <p class="Pp">The requested + <var class="Va">iface</var><var class="Ar">N</var> hook must already be + connected, otherwise the message send operation will return an + error.</p> + </dd> + <dt id="NGM_NETFLOW_SETTIMEOUTS"><a class="permalink" href="#NGM_NETFLOW_SETTIMEOUTS"><code class="Dv">NGM_NETFLOW_SETTIMEOUTS</code></a> + (<code class="Ic">settimeouts</code>)</dt> + <dd>Sets values in seconds for NetFlow active/inactive timeouts. This message + requires <var class="Vt">struct ng_netflow_settimeouts</var> as an + argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_settimeouts { + uint32_t inactive_timeout; /* flow inactive timeout */ + uint32_t active_timeout; /* flow active timeout */ +};</pre> + </div> + </dd> + <dt id="NGM_NETFLOW_SETCONFIG"><a class="permalink" href="#NGM_NETFLOW_SETCONFIG"><code class="Dv">NGM_NETFLOW_SETCONFIG</code></a> + (<code class="Ic">setconfig</code>)</dt> + <dd>Sets configuration for the specified interface. This message requires + <var class="Vt">struct ng_netflow_setconfig</var> as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>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 +};</pre> + </div> + <p class="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 + <var class="Va">NG_NETFLOW_CONF_EGRESS</var> enables egress NetFlow (for + data coming from outX hook). Option + <var class="Va">NG_NETFLOW_CONF_ONCE</var> defines that packet should be + accounted only once if it several times passes via netflow node. Option + <var class="Va">NG_NETFLOW_CONF_THISONCE</var> 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 + <var class="Va">NG_NETFLOW_CONF_NOSRCLOOKUP</var> skips radix lookup on + flow source address used to fill in network mask. Option + <var class="Va">NG_NETFLOW_CONF_NODSTLOOKUP</var> 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.</p> + </dd> + <dt id="NGM_NETFLOW_SETTEMPLATE"><a class="permalink" href="#NGM_NETFLOW_SETTEMPLATE"><code class="Dv">NGM_NETFLOW_SETTEMPLATE</code></a> + (<code class="Ic">settemplate</code>)</dt> + <dd>Sets various timeouts to announce data flow templates (NetFlow + v9-specific). This message requires <var class="Vt">struct + ng_netflow_settemplate</var> as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_settemplate { + uint16_t time; /* max time between announce */ + uint16_t packets; /* max packets between announce */ +};</pre> + </div> + <p class="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.</p> + </dd> + <dt id="NGM_NETFLOW_SETMTU"><a class="permalink" href="#NGM_NETFLOW_SETMTU"><code class="Dv">NGM_NETFLOW_SETMTU</code></a> + (<code class="Ic">setmtu</code>)</dt> + <dd>Sets export interface MTU to build packets of specified size (NetFlow + v9-specific). This message requires <var class="Vt">struct + ng_netflow_setmtu</var> as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_setemtu { + uint16_t mtu; /* MTU for packet */ +};</pre> + </div> + <p class="Pp">Default is 1500 bytes.</p> + </dd> + <dt id="NGM_NETFLOW_SHOW"><a class="permalink" href="#NGM_NETFLOW_SHOW"><code class="Dv">NGM_NETFLOW_SHOW</code></a></dt> + <dd>This control message asks a node to dump the entire contents of the flow + cache. It is called from <a class="Xr">flowctl(8)</a>, not directly from + <a class="Xr">ngctl(8)</a>.</dd> + <dt id="NGM_NETFLOW_V9INFO"><a class="permalink" href="#NGM_NETFLOW_V9INFO"><code class="Dv">NGM_NETFLOW_V9INFO</code></a> + (<code class="Ic">v9info</code>)</dt> + <dd>Returns some NetFlow v9 related values in a + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_netflow_v9info { + uint16_t templ_packets; /* v9 template packets */ + uint16_t templ_time; /* v9 template time */ + uint16_t mtu; /* v9 MTU */ +};</pre> + </div> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1> +<p class="Pp">This node shuts down upon receipt of a + <code class="Dv">NGM_SHUTDOWN</code> control message, or when all hooks have + been disconnected.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The simplest possible configuration is one Ethernet interface, + where flow collecting is enabled.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>/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</pre> +</div> +<p class="Pp">This is a more complicated example of a router with 2 + NetFlow-enabled interfaces <code class="Li">fxp0</code> and + <code class="Li">ng0</code>. Note that the <var class="Va">ng0:</var> node + in this example is connected to <a class="Xr">ng_tee(4)</a>. The latter + sends us a copy of IP packets, which we analyze and free. On + <var class="Va">fxp0:</var> we do not use tee, but send packets back to + either node.</p> +<div class="Bd Pp Bd-indent Li"> +<pre>/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</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">setfib(2)</a>, <a class="Xr">netgraph(4)</a>, + <a class="Xr">ng_ether(4)</a>, <a class="Xr">ng_iface(4)</a>, + <a class="Xr">ng_ksocket(4)</a>, <a class="Xr">ng_tee(4)</a>, + <a class="Xr">flowctl(8)</a>, <a class="Xr">ngctl(8)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">B. Claise, Ed</span>, + <span class="RsT">Cisco Systems NetFlow Services Export Version 9</span>, + <span class="RsO">RFC 3954</span>.</cite></p> +<p class="Pp"><span class="Pa">http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">ng_netflow</code> node type was written by + <span class="An">Gleb Smirnoff</span> + <<a class="Mt" href="mailto:glebius@FreeBSD.org">glebius@FreeBSD.org</a>>, + <span class="An">Alexander Motin</span> + <<a class="Mt" href="mailto:mav@FreeBSD.org">mav@FreeBSD.org</a>>, + <span class="An">Alexander Chernikov</span> + <<a class="Mt" href="mailto:melifaro@ipfw.ru">melifaro@ipfw.ru</a>>. + The initial code was based on <code class="Nm">ng_ipacct</code> written by + <span class="An">Roman V. Palagin</span> + <<a class="Mt" href="mailto:romanp@unshadow.net">romanp@unshadow.net</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Cache snapshot obtained via + <code class="Dv">NGM_NETFLOW_SHOW</code> command may lack some percentage of + entries under severe load.</p> +<p class="Pp">The <code class="Nm">ng_netflow</code> 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.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 10, 2012</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |