/share/man/man4/ng_bridge.4

  1.\" Copyright (c) 2000 Whistle Communications, Inc.
  2.\" All rights reserved.
  3.\"
  4.\" Subject to the following obligations and disclaimer of warranty, use and
  5.\" redistribution of this software, in source or object code forms, with or
  6.\" without modifications are expressly permitted by Whistle Communications;
  7.\" provided, however, that:
  8.\" 1. Any and all reproductions of the source or object code must include the
  9.\"    copyright notice above and the following disclaimer of warranties; and
 10.\" 2. No rights are granted, in any manner or form, to use Whistle
 11.\"    Communications, Inc. trademarks, including the mark "WHISTLE
 12.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
 13.\"    such appears in the above copyright notice or in the software.
 14.\"
 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
 31.\" OF SUCH DAMAGE.
 32.\"
 33.\" Author: Archie Cobbs <archie@FreeBSD.org>
 34.\"
 35.\" $FreeBSD$
 36.\"
 37.Dd May 5, 2010
 38.Dt NG_BRIDGE 4
 39.Os
 40.Sh NAME
 41.Nm ng_bridge
 42.Nd Ethernet bridging netgraph node type
 43.Sh SYNOPSIS
 44.In sys/types.h
 45.In netgraph/ng_bridge.h
 46.Sh DESCRIPTION
 47The
 48.Nm bridge
 49node type performs Ethernet bridging over one or more links.
 50Each link (represented by a connected hook) is used to transmit
 51and receive raw Ethernet frames.
 52As packets are received, the node learns which link each
 53host resides on.
 54Packets unicast to a known host are directed out the appropriate
 55link only, and other links are spared the traffic.
 56This behavior is in contrast to a hub, which always forwards
 57every received packet to every other link.
 58.Sh LOOP DETECTION
 59The
 60.Nm bridge
 61node incorporates a simple loop detection algorithm.
 62A loop is when two ports are connected to the same physical medium.
 63Loops are important to avoid because of packet storms, which severely
 64degrade performance.
 65A packet storm results when the same packet is sent and received
 66over and over again.
 67If a host is detected on link A, and is then detected on link B
 68within a certain time period after first being detected on link A,
 69then link B is considered to be a looped back link.
 70The time period is called the minimum stable time.
 71.Pp
 72A looped back link will be temporarily muted, i.e., all traffic
 73received on that link is ignored.
 74.Sh IPFW PROCESSING
 75Processing of IP packets via the
 76.Xr ipfirewall 4
 77mechanism on a per-link basis is not yet implemented.
 78.Sh HOOKS
 79This node type supports up to
 80.Dv NG_BRIDGE_MAX_LINKS
 81hooks.
 82Each connected hook represents a bridged link.
 83The hooks are named
 84.Dv link0 ,
 85.Dv link1 ,
 86etc.
 87Typically these hooks are connected to the
 88.Dv lower
 89hooks of one or more
 90.Xr ng_ether 4
 91nodes.
 92To connect the host machine to a bridged network, simply connect the
 93.Dv upper
 94hook of an
 95.Xr ng_ether 4
 96node to the bridge node.
 97.Sh CONTROL MESSAGES
 98This node type supports the generic control messages, plus the
 99following:
100.Bl -tag -width foo
101.It Dv NGM_BRIDGE_SET_CONFIG
102Set the node configuration.
103This command takes a
104.Dv "struct ng_bridge_config"
105as an argument:
106.Bd -literal -offset 0n
107/* Node configuration structure */
108struct ng_bridge_config {
109  u_char      ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */
110  u_char      debugLevel;           /* debug level */
111  uint32_t    loopTimeout;          /* link loopback mute time */
112  uint32_t    maxStaleness;         /* max host age before nuking */
113  uint32_t    minStableAge;         /* min time for a stable host */
114};
115.Ed
116.Pp
117The
118.Dv ipfw
119array enables
120.Xr ipfirewall 4
121processing of IP packets received on the corresponding links.
122The
123.Dv debugLevel
124field sets the debug level on the node.
125At level of 2 or greater, detected loops are logged.
126The default level is 1.
127.Pp
128The
129.Dv loopTimeout
130determines how long (in seconds) a looped link is muted.
131The default is 60 seconds.
132The
133.Dv maxStaleness
134parameter determines how long a period of inactivity before
135a host's entry is forgotten.
136The default is 15 minutes.
137The
138.Dv minStableAge
139determines how quickly a host must jump from one link to another
140before we declare a loopback condition.
141The default is one second.
142.Pp
143.It Dv NGM_BRIDGE_GET_CONFIG
144Returns the current configuration as a
145.Dv "struct ng_bridge_config" .
146.It Dv NGM_BRIDGE_RESET
147Causes the node to forget all hosts and unmute all links.
148The node configuration is not changed.
149.It Dv NGM_BRIDGE_GET_STATS
150This command takes a four byte link number as an argument and
151returns a
152.Dv "struct ng_bridge_link_stats"
153containing statistics for the corresponding link, which must be
154currently connected:
155.Bd -literal -offset 0n
156/* Statistics structure (one for each link) */
157struct ng_bridge_link_stats {
158  uint64_t   recvOctets;     /* total octets rec'd on link */
159  uint64_t   recvPackets;    /* total pkts rec'd on link */
160  uint64_t   recvMulticasts; /* multicast pkts rec'd on link */
161  uint64_t   recvBroadcasts; /* broadcast pkts rec'd on link */
162  uint64_t   recvUnknown;    /* pkts rec'd with unknown dest addr */
163  uint64_t   recvRunts;      /* pkts rec'd less than 14 bytes */
164  uint64_t   recvInvalid;    /* pkts rec'd with bogus source addr */
165  uint64_t   xmitOctets;     /* total octets xmit'd on link */
166  uint64_t   xmitPackets;    /* total pkts xmit'd on link */
167  uint64_t   xmitMulticasts; /* multicast pkts xmit'd on link */
168  uint64_t   xmitBroadcasts; /* broadcast pkts xmit'd on link */
169  uint64_t   loopDrops;      /* pkts dropped due to loopback */
170  uint64_t   loopDetects;    /* number of loop detections */
171  uint64_t   memoryFailures; /* times couldn't get mem or mbuf */
172};
173.Ed
174.It Dv NGM_BRIDGE_CLR_STATS
175This command takes a four byte link number as an argument and
176clears the statistics for that link.
177.It Dv NGM_BRIDGE_GETCLR_STATS
178Same as
179.Dv NGM_BRIDGE_GET_STATS ,
180but also atomically clears the statistics as well.
181.It Dv NGM_BRIDGE_GET_TABLE
182Returns the current host mapping table used to direct packets, in a
183.Dv "struct ng_bridge_host_ary" .
184.It Dv NGM_BRIDGE_SET_PERSISTENT
185This command sets the persistent flag on the node, and takes no arguments.
186.El
187.Sh SHUTDOWN
188This node shuts down upon receipt of a
189.Dv NGM_SHUTDOWN
190control message, or when all hooks have been disconnected.  Setting the
191persistent flag via a
192.Dv NGM_BRIDGE_SET_PERSISTENT
193control message disables automatic node shutdown when the last hook gets
194disconnected.
195.Sh FILES
196.Bl -tag -width XXXXXXXX -compact
197.It Pa /usr/share/examples/netgraph/ether.bridge
198Example script showing how to set up a bridging network
199.El
200.Sh SEE ALSO
201.Xr if_bridge 4 ,
202.Xr netgraph 4 ,
203.Xr ng_ether 4 ,
204.Xr ng_hub 4 ,
205.Xr ng_one2many 4 ,
206.Xr ngctl 8
207.Sh HISTORY
208The
209.Nm
210node type was implemented in
211.Fx 4.2 .
212.Sh AUTHORS
213.An Archie Cobbs Aq archie@FreeBSD.org