diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 193563e56d0d..32f37ce7b045 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -78,6 +78,7 @@ MAN4= adv.4 \ ng_UI.4 \ ng_async.4 \ ng_bpf.4 \ + ng_bridge.4 \ ng_cisco.4 \ ng_echo.4 \ ng_ether.4 \ diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4 index f11ab53f9f14..3543612a6a20 100644 --- a/share/man/man4/bridge.4 +++ b/share/man/man4/bridge.4 @@ -73,6 +73,7 @@ and interfaces. .Sh SEE ALSO .Xr ip 4 , +.Xr ng_bridge 4 , .Xr ipfw 8 , .Xr sysctl 8 . .Sh HISTORY diff --git a/share/man/man4/ng_bridge.4 b/share/man/man4/ng_bridge.4 new file mode 100644 index 000000000000..7869d1247453 --- /dev/null +++ b/share/man/man4/ng_bridge.4 @@ -0,0 +1,199 @@ +.\" Copyright (c) 2000 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.\" $FreeBSD$ +.\" +.Dd August 31, 2000 +.Dt NG_BRIDGE 4 +.Os FreeBSD +.Sh NAME +.Nm ng_bridge +.Nd Ethernet bridging netgraph node type +.Sh SYNOPSIS +.Fd #include +.Sh DESCRIPTION +The +.Nm bridge +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. +.Sh LOOP DETECTION +The +.Nm bridge +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. +.Pp +A looped back link will be temporarily muted, i.e., all traffic +received on that link is ignored. +.Sh IPFW PROCESSING +Processing of IP packets via the +.Xr ipfirewall 4 +mechanism on a per-link basis is not yet implemented. +.Sh HOOKS +This node type supports up to +.Dv NG_BRIDGE_MAX_LINKS +hooks. +Each connected hook represents a bridged link. +The hooks are named +.Dv link0 , +.Dv link1 , +etc. +Typically these hooks are connected to the +.Dv lower +hooks of one or more +.Xr ng_ether +nodes. +To connect the host machine to a bridged network, simply connect the +.Dv upper +hook of an +.Xr ng_ether +node to the bridge node. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_BRIDGE_SET_CONFIG +Set the node configuration. +This command takes a +.Dv "struct ng_bridge_config" +as an argument: +.Bd -literal -offset 0 +/* Node configuration structure */ +struct ng_bridge_config { + u_char ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */ + u_char debugLevel; /* debug level */ + u_int32_t loopTimeout; /* link loopback mute time */ + u_int32_t maxStaleness; /* max host age before nuking */ + u_int32_t minStableAge; /* min time for a stable host */ +}; +.Ed +.Pp +The +.Dv ipfw +array enables +.Xr ipfirewall 4 +processing of IP packets received on the corresponding links. +The +.Dv debugLevel +field sets the debug level on the node. +At level of 2 or greater, detected loops are logged. +The default level is 1. +.Pp +The +.Dv loopTimeout +determines how long (in seconds) a looped link is muted. +The default is 60 seconds. +The +.Dv maxStaleness +parameter determines how long a period of inactivity before +a host's entry is forgotten. +The default is 15 minutes. +The +.Dv minStableAge +determines how quickly a host must jump from one link to another +before we declare a loopback condition. +The default is one second. +.Pp +.It Dv NGM_BRIDGE_GET_CONFIG +Returns the current configuration as a +.Dv "struct ng_bridge_config" . +.It Dv NGM_BRIDGE_RESET +Causes the node to forget all hosts and unmute all links. +The node configuration is not changed. +.It Dv NGM_BRIDGE_GET_STATS +This command takes a four byte link number as an argument and +returns a +.Dv "struct ng_bridge_link_stats" +containing statistics for the corresponding link, which must be +currently connected: +.Bd -literal -offset 0 +/* Statistics structure (one for each link) */ +struct ng_bridge_link_stats { + u_int64_t recvOctets; /* total octets rec'd on link */ + u_int64_t recvPackets; /* total pkts rec'd on link */ + u_int64_t recvMulticasts; /* multicast pkts rec'd on link */ + u_int64_t recvBroadcasts; /* broadcast pkts rec'd on link */ + u_int64_t recvUnknown; /* pkts rec'd with unknown dest addr */ + u_int64_t recvRunts; /* pkts rec'd less than 14 bytes */ + u_int64_t recvInvalid; /* pkts rec'd with bogus source addr */ + u_int64_t xmitOctets; /* total octets xmit'd on link */ + u_int64_t xmitPackets; /* total pkts xmit'd on link */ + u_int64_t xmitMulticasts; /* multicast pkts xmit'd on link */ + u_int64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ + u_int64_t loopDrops; /* pkts dropped due to loopback */ + u_int64_t loopDetects; /* number of loop detections */ + u_int64_t memoryFailures; /* times couldn't get mem or mbuf */ +}; +.Ed +.It Dv NGM_BRIDGE_CLR_STATS +This command takes a four byte link number as an argument and +clears the statistics for that link. +.It Dv NGM_BRIDGE_GETCLR_STATS +Same as +.Dv NGM_BRIDGE_GET_STATS , +but also atomically clears the statistics as well. +.It Dv NGM_BRIDGE_GET_TABLE +Returns the current host mapping table used to direct packets, in a +.Dv "struct ng_bridge_host_ary" . +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr bridge 4 , +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.2 . +.Sh AUTHORS +.An Archie Cobbs Aq archie@freebsd.org