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 February 6, 2021
  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
  47 The
  48 .Nm bridge
  49 node type performs Ethernet bridging over one or more links.
  50 Each link (represented by a connected hook) is used to transmit
  51 and receive raw Ethernet frames.
  52 As packets are received, the node learns which link each
  53 host resides on.
  54 Packets unicast to a known host are directed out the appropriate
  55 link only, and other links are spared the traffic.
  56 This behavior is in contrast to a hub, which always forwards
  57 every received packet to every other link.
  58 .Sh LOOP DETECTION
  59 The
  60 .Nm bridge
  61 node incorporates a simple loop detection algorithm.
  62 A loop is when two ports are connected to the same physical medium.
  63 Loops are important to avoid because of packet storms, which severely
  64 degrade performance.
  65 A packet storm results when the same packet is sent and received
  66 over and over again.
  67 If a host is detected on link A, and is then detected on link B
  68 within a certain time period after first being detected on link A,
  69 then link B is considered to be a looped back link.
  70 The time period is called the minimum stable time.
  71 .Pp
  72 A looped back link will be temporarily muted, i.e., all traffic
  73 received on that link is ignored.
  74 .Sh IPFW PROCESSING
  75 Processing of IP packets via the
  76 .Xr ipfirewall 4
  77 mechanism on a per-link basis is not yet implemented.
  78 .Sh HOOKS
  79 This node type supports an unlimited number of hooks.
  80 Each connected hook represents a bridged link.
  81 The hooks are named
  82 .Dv link0 ,
  83 .Dv link1 ,
  84 etc.
  85 Typically these hooks are connected to the
  86 .Dv lower
  87 hooks of one or more
  88 .Xr ng_ether 4
  89 nodes.
  90 To connect the host machine to a bridged network, simply connect the
  91 .Dv upper
  92 hook of an
  93 .Xr ng_ether 4
  94 node to the bridge node.
  95 .Pp
  96 Instead of naming a hook
  97 .Dv linkX
  98 the hook might be also named
  99 .Dv uplinkX .
 100 The node does not learn MAC addresses on uplink hooks, which keeps
 101 the internal address table small.
 102 This way it is desirable to connect the
 103 .Dv lower
 104 hook of an
 105 .Xr ng_ether 4
 106 node to an
 107 .Dv uplink
 108 hook of the bridge, and ignore the complexity of the outside world.
 109 Frames with unknown MACs are always sent out to
 110 .Dv uplink
 111 hooks, so no functionality is lost.
 112 .Pp
 113 Frames with unknown destination MAC addresses are replicated to any
 114 available hook, unless the first connected hook is an
 115 .Ar uplink
 116 hook.
 117 In this case the node assumes, that all unknown MAC addresses are
 118 located soley on the
 119 .Ar uplink
 120 hooks and only those hooks will be used to send out frames with
 121 unknown destination MACs.
 122 If the first connected hook is an
 123 .Ar link
 124 hook, the node will replicate such frames to all types of hooks,
 125 even if
 126 .Ar uplink
 127 hooks are connected later.
 128 .Sh CONTROL MESSAGES
 129 This node type supports the generic control messages, plus the
 130 following:
 131 .Bl -tag -width foo
 132 .It Dv NGM_BRIDGE_SET_CONFIG Pq Ic setconfig
 133 Set the node configuration.
 134 This command takes a
 135 .Dv "struct ng_bridge_config"
 136 as an argument:
 137 .Bd -literal -offset 0n
 138 /* Node configuration structure */
 139 struct ng_bridge_config {
 140   u_char      debugLevel;           /* debug level */
 141   uint32_t    loopTimeout;          /* link loopback mute time */
 142   uint32_t    maxStaleness;         /* max host age before nuking */
 143   uint32_t    minStableAge;         /* min time for a stable host */
 144 };
 145 .Ed
 146 .Pp
 147 The
 148 .Dv debugLevel
 149 field sets the debug level on the node.
 150 At level of 2 or greater, detected loops are logged.
 151 The default level is 1.
 152 .Pp
 153 The
 154 .Dv loopTimeout
 155 determines how long (in seconds) a looped link is muted.
 156 The default is 60 seconds.
 157 The
 158 .Dv maxStaleness
 159 parameter determines how long a period of inactivity before
 160 a host's entry is forgotten.
 161 The default is 15 minutes.
 162 The
 163 .Dv minStableAge
 164 determines how quickly a host must jump from one link to another
 165 before we declare a loopback condition.
 166 The default is one second.
 167 .It Dv NGM_BRIDGE_GET_CONFIG Pq Ic getconfig
 168 Returns the current configuration as a
 169 .Dv "struct ng_bridge_config" .
 170 .It Dv NGM_BRIDGE_RESET Pq Ic reset
 171 Causes the node to forget all hosts and unmute all links.
 172 The node configuration is not changed.
 173 .It Dv NGM_BRIDGE_GET_STATS Pq Ic getstats
 174 This command takes a four byte link number as an argument and
 175 returns a
 176 .Dv "struct ng_bridge_link_stats"
 177 containing statistics for the corresponding
 178 .Dv link ,
 179 which must be currently connected:
 180 .Bd -literal -offset 0n
 181 /* Statistics structure (one for each link) */
 182 struct ng_bridge_link_stats {
 183   uint64_t   recvOctets;     /* total octets rec'd on link */
 184   uint64_t   recvPackets;    /* total pkts rec'd on link */
 185   uint64_t   recvMulticasts; /* multicast pkts rec'd on link */
 186   uint64_t   recvBroadcasts; /* broadcast pkts rec'd on link */
 187   uint64_t   recvUnknown;    /* pkts rec'd with unknown dest addr */
 188   uint64_t   recvRunts;      /* pkts rec'd less than 14 bytes */
 189   uint64_t   recvInvalid;    /* pkts rec'd with bogus source addr */
 190   uint64_t   xmitOctets;     /* total octets xmit'd on link */
 191   uint64_t   xmitPackets;    /* total pkts xmit'd on link */
 192   uint64_t   xmitMulticasts; /* multicast pkts xmit'd on link */
 193   uint64_t   xmitBroadcasts; /* broadcast pkts xmit'd on link */
 194   uint64_t   loopDrops;      /* pkts dropped due to loopback */
 195   uint64_t   loopDetects;    /* number of loop detections */
 196   uint64_t   memoryFailures; /* times couldn't get mem or mbuf */
 197 };
 198 .Ed
 199 .Pp
 200 Negative numbers refer to the
 201 .Dv uplink
 202 hooks.
 203 So querying for -7 will get the statistics for hook
 204 .Dv uplink7 .
 205 .It Dv NGM_BRIDGE_CLR_STATS Pq Ic clrstats
 206 This command takes a four byte link number as an argument and
 207 clears the statistics for that link.
 208 .It Dv NGM_BRIDGE_GETCLR_STATS Pq Ic getclrstats
 209 Same as
 210 .Dv NGM_BRIDGE_GET_STATS ,
 211 but also atomically clears the statistics as well.
 212 .It Dv NGM_BRIDGE_GET_TABLE Pq Ic gettable
 213 Returns the current host mapping table used to direct packets, in a
 214 .Dv "struct ng_bridge_host_ary" .
 215 .It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ic setpersistent
 216 This command sets the persistent flag on the node, and takes no arguments.
 217 .El
 218 .Sh SHUTDOWN
 219 This node shuts down upon receipt of a
 220 .Dv NGM_SHUTDOWN
 221 control message, or when all hooks have been disconnected.
 222 Setting the persistent flag via a
 223 .Dv NGM_BRIDGE_SET_PERSISTENT
 224 control message disables automatic node shutdown when the last hook gets
 225 disconnected.
 226 .Sh FILES
 227 .Bl -tag -width XXXXXXXX -compact
 228 .It Pa /usr/share/examples/netgraph/ether.bridge
 229 Example script showing how to set up a bridging network
 230 .El
 231 .Sh SEE ALSO
 232 .Xr if_bridge 4 ,
 233 .Xr netgraph 4 ,
 234 .Xr ng_ether 4 ,
 235 .Xr ng_hub 4 ,
 236 .Xr ng_one2many 4 ,
 237 .Xr ngctl 8
 238 .Sh HISTORY
 239 The
 240 .Nm
 241 node type was implemented in
 242 .Fx 4.2 .
 243 .Sh AUTHORS
 244 .An Archie Cobbs Aq Mt archie@FreeBSD.org