diff options
Diffstat (limited to 'static/freebsd/man4/ng_bridge.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_bridge.4 3.html | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_bridge.4 3.html b/static/freebsd/man4/ng_bridge.4 3.html new file mode 100644 index 00000000..4aa25e0b --- /dev/null +++ b/static/freebsd/man4/ng_bridge.4 3.html @@ -0,0 +1,230 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_BRIDGE(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_BRIDGE(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_bridge</code> — + <span class="Nd">Ethernet bridging netgraph node type</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">netgraph/ng_bridge.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">bridge</code> node type performs Ethernet + bridging over one or more links. Each link (represented by a connected hook) + is used to transmit and receive raw Ethernet frames. As packets are + received, the node learns which link each host resides on. Packets unicast + to a known host are directed out the appropriate link only, and other links + are spared the traffic. This behavior is in contrast to a hub, which always + forwards every received packet to every other link.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="LOOP_DETECTION"><a class="permalink" href="#LOOP_DETECTION">LOOP + DETECTION</a></h1> +<p class="Pp">The <code class="Nm">bridge</code> node incorporates a simple loop + detection algorithm. A loop is when two ports are connected to the same + physical medium. Loops are important to avoid because of packet storms, + which severely degrade performance. A packet storm results when the same + packet is sent and received over and over again. If a host is detected on + link A, and is then detected on link B within a certain time period after + first being detected on link A, then link B is considered to be a looped + back link. The time period is called the minimum stable time.</p> +<p class="Pp">A looped back link will be temporarily muted, i.e., all traffic + received on that link is ignored.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IPFW_PROCESSING"><a class="permalink" href="#IPFW_PROCESSING">IPFW + PROCESSING</a></h1> +<p class="Pp">Processing of IP packets via the <a class="Xr">ipfirewall(4)</a> + mechanism on a per-link basis is not yet implemented.</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 an unlimited number of hooks. Each + connected hook represents a bridged link. The hooks are named + <var class="Ar">link0</var>, <var class="Ar">link1</var>, etc. Typically + these hooks are connected to the <var class="Ar">lower</var> hooks of one or + more <a class="Xr">ng_ether(4)</a> nodes. To connect the host machine to a + bridged network, simply connect the <var class="Ar">upper</var> hook of an + <a class="Xr">ng_ether(4)</a> node to the bridge node.</p> +<p class="Pp">Instead of naming a hook <var class="Ar">linkX</var> the hook + might be also named <var class="Ar">uplinkX</var>. The node does not learn + MAC addresses on uplink hooks, which keeps the internal address table small. + This way it is desirable to connect the <var class="Ar">lower</var> hook of + an <a class="Xr">ng_ether(4)</a> node to an <var class="Ar">uplink</var> + hook of the bridge, and ignore the complexity of the outside world. Frames + with unknown MACs are always sent out to <var class="Ar">uplink</var> hooks, + so no functionality is lost. The <var class="Ar">uplink0</var> hook is not + allowed.</p> +<p class="Pp">The <var class="Ar">linkX</var> and <var class="Ar">uplinkX</var> + hook numbers can be autoassigned. If a new hook name was specified as + <var class="Ar">link</var> or <var class="Ar">uplink</var> the node will + append lowest available valid number to the name of the new hook.</p> +<p class="Pp">Frames with unknown destination MAC addresses are replicated to + any available hook, unless the first connected hook is an + <var class="Ar">uplink</var> hook. In this case the node assumes, that all + unknown MAC addresses are located solely on the <var class="Ar">uplink</var> + hooks and only those hooks will be used to send out frames with unknown + destination MACs. If the first connected hook is an + <var class="Ar">link</var> hook, the node will replicate such frames to all + types of hooks, even if <var class="Ar">uplink</var> hooks are connected + later.</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_BRIDGE_SET_CONFIG"><a class="permalink" href="#NGM_BRIDGE_SET_CONFIG"><code class="Dv">NGM_BRIDGE_SET_CONFIG</code></a> + (<var class="Ar">setconfig</var>)</dt> + <dd>Set the node configuration. This command takes a <var class="Vt">struct + ng_bridge_config</var> as an argument: + <div class="Bd Pp Bd-indent Li"> + <pre>/* Node configuration structure */ +struct ng_bridge_config { + u_char debugLevel; /* debug level */ + uint32_t loopTimeout; /* link loopback mute time */ + uint32_t maxStaleness; /* max host age before nuking */ + uint32_t minStableAge; /* min time for a stable host */ +};</pre> + </div> + <p class="Pp">The <var class="Va">debugLevel</var> field sets the debug + level on the node. At level of 2 or greater, detected loops are logged. + The default level is 1.</p> + <p class="Pp">The <var class="Va">loopTimeout</var> determines how long (in + seconds) a looped link is muted. The default is 60 seconds. The + <var class="Va">maxStaleness</var> parameter determines how long a + period of inactivity before a host's entry is forgotten. The default is + 15 minutes. The <var class="Va">minStableAge</var> determines how + quickly a host must jump from one link to another before we declare a + loopback condition. The default is one second.</p> + </dd> + <dt id="NGM_BRIDGE_GET_CONFIG"><a class="permalink" href="#NGM_BRIDGE_GET_CONFIG"><code class="Dv">NGM_BRIDGE_GET_CONFIG</code></a> + (<var class="Ar">getconfig</var>)</dt> + <dd>Returns the current configuration as a <var class="Vt">struct + ng_bridge_config</var>.</dd> + <dt id="NGM_BRIDGE_RESET"><a class="permalink" href="#NGM_BRIDGE_RESET"><code class="Dv">NGM_BRIDGE_RESET</code></a> + (<var class="Ar">reset</var>)</dt> + <dd>Causes the node to forget all hosts and unmute all links. The node + configuration is not changed.</dd> + <dt id="NGM_BRIDGE_GET_STATS"><a class="permalink" href="#NGM_BRIDGE_GET_STATS"><code class="Dv">NGM_BRIDGE_GET_STATS</code></a> + (<var class="Ar">getstats</var>)</dt> + <dd>This command takes a four byte link number as an argument and returns a + <var class="Vt">struct ng_bridge_link_stats</var> containing statistics + for the corresponding <var class="Ar">link</var>, which must be currently + connected: + <div class="Bd Pp Bd-indent Li"> + <pre>/* Statistics structure (one for each link) */ +struct ng_bridge_link_stats { + uint64_t recvOctets; /* total octets rec'd on link */ + uint64_t recvPackets; /* total pkts rec'd on link */ + uint64_t recvMulticasts; /* multicast pkts rec'd on link */ + uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ + uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ + uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ + uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ + uint64_t xmitOctets; /* total octets xmit'd on link */ + uint64_t xmitPackets; /* total pkts xmit'd on link */ + uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ + uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ + uint64_t loopDrops; /* pkts dropped due to loopback */ + uint64_t loopDetects; /* number of loop detections */ + uint64_t memoryFailures; /* times couldn't get mem or mbuf */ +};</pre> + </div> + <p class="Pp">Negative numbers refer to the <var class="Ar">uplink</var> + hooks. So querying for -7 will get the statistics for hook + <var class="Ar">uplink7</var>.</p> + </dd> + <dt id="NGM_BRIDGE_CLR_STATS"><a class="permalink" href="#NGM_BRIDGE_CLR_STATS"><code class="Dv">NGM_BRIDGE_CLR_STATS</code></a> + (<var class="Ar">clrstats</var>)</dt> + <dd>This command takes a four byte link number as an argument and clears the + statistics for that link.</dd> + <dt id="NGM_BRIDGE_GETCLR_STATS"><a class="permalink" href="#NGM_BRIDGE_GETCLR_STATS"><code class="Dv">NGM_BRIDGE_GETCLR_STATS</code></a> + (<var class="Ar">getclrstats</var>)</dt> + <dd>Same as <code class="Dv">NGM_BRIDGE_GET_STATS</code>, but also atomically + clears the statistics as well.</dd> + <dt id="NGM_BRIDGE_GET_TABLE"><a class="permalink" href="#NGM_BRIDGE_GET_TABLE"><code class="Dv">NGM_BRIDGE_GET_TABLE</code></a> + (<var class="Ar">gettable</var>)</dt> + <dd>Returns the current host mapping table used to direct packets, in a + <var class="Vt">struct ng_bridge_host_ary</var>.</dd> + <dt id="NGM_BRIDGE_SET_PERSISTENT"><a class="permalink" href="#NGM_BRIDGE_SET_PERSISTENT"><code class="Dv">NGM_BRIDGE_SET_PERSISTENT</code></a> + (<var class="Ar">setpersistent</var>)</dt> + <dd>This command sets the persistent flag on the node, and takes no + arguments.</dd> + <dt id="NGM_BRIDGE_MOVE_HOST"><a class="permalink" href="#NGM_BRIDGE_MOVE_HOST"><code class="Dv">NGM_BRIDGE_MOVE_HOST</code></a> + (<var class="Ar">movehost</var>)</dt> + <dd>This command takes a <var class="Vt">struct ng_bridge_move_host</var> as + an argument. It assigns the MAC <var class="Va">addr</var> to the + <var class="Va">hook</var>. If the <var class="Va">hook</var> is the empty + string, the incoming hook of the control message is used as fallback. + <p class="Pp">If necessary, the MAC is removed from the currently assigned + hook and moved to the new one. If the MAC is moved faster than + <var class="Va">minStableAge</var>, the hook is considered as a loop and + will block traffic for <var class="Va">loopTimeout</var> seconds.</p> + <div class="Bd Pp Bd-indent Li"> + <pre>struct ng_bridge_move_host { + u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ + char hook[NG_HOOKSIZ]; /* link where addr can be found */ +};</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. Setting the persistent flag via a + <code class="Dv">NGM_BRIDGE_SET_PERSISTENT</code> control message disables + automatic node shutdown when the last hook gets disconnected.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/usr/share/examples/netgraph/ether.bridge</span></dt> + <dd>Example script showing how to set up a bridging network</dd> +</dl> +</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">if_bridge(4)</a>, <a class="Xr">netgraph(4)</a>, + <a class="Xr">ng_ether(4)</a>, <a class="Xr">ng_hub(4)</a>, + <a class="Xr">ng_one2many(4)</a>, <a class="Xr">ngctl(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ng_bridge</code> node type was implemented in + <span class="Ux">FreeBSD 4.2</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Archie Cobbs</span> + <<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">The <code class="Nm">ng_bridge</code> node refuses to create the + <var class="Ar">uplink0</var> hook to avoid later ambiguity with the + <code class="Dv">NGM_BRIDGE_GET_STATS</code> message.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 8, 2024</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |