share/man/man4/if_bridge.4

   1 .\"     $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $
   2 .\"
   3 .\" Copyright 2001 Wasabi Systems, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed for the NetBSD Project by
  19 .\"     Wasabi Systems, Inc.
  20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  21 .\"    or promote products derived from this software without specific prior
  22 .\"    written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .\" $FreeBSD$
  37 .\"
  38 .Dd January 20, 2007
  39 .Dt IF_BRIDGE 4
  40 .Os
  41 .Sh NAME
  42 .Nm if_bridge
  43 .Nd network bridge device
  44 .Sh SYNOPSIS
  45 To compile this driver into the kernel,
  46 place the following line in your
  47 kernel configuration file:
  48 .Bd -ragged -offset indent
  49 .Cd "device if_bridge"
  50 .Ed
  51 .Pp
  52 Alternatively, to load the driver as a
  53 module at boot time, place the following lines in
  54 .Xr loader.conf 5 :
  55 .Bd -literal -offset indent
  56 if_bridge_load="YES"
  57 bridgestp_load="YES"
  58 .Ed
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 driver creates a logical link between two or more IEEE 802 networks
  63 that use the same (or
  64 .Dq "similar enough" )
  65 framing format.
  66 For example, it is possible to bridge Ethernet and 802.11 networks together,
  67 but it is not possible to bridge Ethernet and Token Ring together.
  68 .Pp
  69 Each
  70 .Nm
  71 interface is created at runtime using interface cloning.
  72 This is
  73 most easily done with the
  74 .Xr ifconfig 8
  75 .Cm create
  76 command or using the
  77 .Va cloned_interfaces
  78 variable in
  79 .Xr rc.conf 5 .
  80 .Pp
  81 The
  82 .Nm
  83 interface randomly chooses a link (MAC) address in the range reserved for
  84 locally administered addresses when it is created.
  85 The address can be changed by assigning the desired link address using
  86 .Xr ifconfig 8 .
  87 .Pp
  88 A bridge can be used to provide several services, such as a simple
  89 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation.
  90 .Pp
  91 A bridge works like a hub, forwarding traffic from one interface
  92 to another.
  93 Multicast and broadcast packets are always forwarded to all
  94 interfaces that are part of the bridge.
  95 For unicast traffic, the bridge learns which MAC addresses are associated
  96 with which interfaces and will forward the traffic selectively.
  97 .Pp
  98 All the bridged member interfaces need to be up in order to pass network traffic.
  99 These can be enabled using
 100 .Xr ifconfig 8
 101 or
 102 .Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up"
 103 in
 104 .Xr rc.conf 5 .
 105 .Pp
 106 The MTU of the first member interface to be added is used as the bridge MTU.
 107 All additional members are required to have exactly the same value.
 108 .Pp
 109 The TXCSUM capability is disabled for any interface added to the bridge, and it
 110 is restored when the interface is removed again.
 111 .Pp
 112 The bridge supports
 113 .Dq monitor mode ,
 114 where the packets are discarded after
 115 .Xr bpf 4
 116 processing, and are not processed or forwarded further.
 117 This can be used to multiplex the input of two or more interfaces into a single
 118 .Xr bpf 4
 119 stream.
 120 This is useful for reconstructing the traffic for network taps
 121 that transmit the RX/TX signals out through two separate interfaces.
 122 .Sh SPANNING TREE
 123 The
 124 .Nm
 125 driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
 126 backwards compatibility with the legacy Spanning Tree Protocol (STP).
 127 Spanning Tree is used to detect and remove loops in a network topology.
 128 .Pp
 129 RSTP provides faster spanning tree convergence than legacy STP, the protocol
 130 will exchange information with neighbouring switches to quickly transition to
 131 forwarding without creating loops.
 132 .Pp
 133 The code will default to RSTP mode but will downgrade any port connected to a
 134 legacy STP network so is fully backward compatible.
 135 A bridge can be forced to operate in STP mode without rapid state transitions
 136 via the
 137 .Va proto
 138 command in
 139 .Xr ifconfig 8 .
 140 .Pp
 141 The bridge can log STP port changes to
 142 .Xr syslog 3
 143 by enabling the
 144 .Va net.link.bridge.log_stp
 145 variable using
 146 .Xr sysctl 8 .
 147 .Pp
 148 .Sh PACKET FILTERING
 149 Packet filtering can be used with any firewall package that hooks in via the
 150 .Xr pfil 9
 151 framework.
 152 When filtering is enabled, bridged packets will pass through the filter
 153 inbound on the originating interface, on the bridge interface and outbound on
 154 the appropriate interfaces.
 155 Either stage can be disabled.
 156 The filtering behaviour can be controlled using
 157 .Xr sysctl 8 :
 158 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
 159 .It Va net.link.bridge.pfil_onlyip
 160 Controls the handling of non-IP packets which are not passed to
 161 .Xr pfil 9 .
 162 Set to
 163 .Li 1
 164 to only allow IP packets to pass (subject to firewall rules), set to
 165 .Li 0
 166 to unconditionally pass all non-IP Ethernet frames.
 167 .It Va net.link.bridge.pfil_member
 168 Set to
 169 .Li 1
 170 to enable filtering on the incoming and outgoing member interfaces, set
 171 to
 172 .Li 0
 173 to disable it.
 174 .It Va net.link.bridge.pfil_bridge
 175 Set to
 176 .Li 1
 177 to enable filtering on the bridge interface, set
 178 to
 179 .Li 0
 180 to disable it.
 181 .It Va net.link.bridge.ipfw
 182 Set to
 183 .Li 1
 184 to enable layer2 filtering with
 185 .Xr ipfirewall 4 ,
 186 set to
 187 .Li 0
 188 to disable it.
 189 This needs to be enabled for
 190 .Xr dummynet 4
 191 support.
 192 When
 193 .Va ipfw
 194 is enabled,
 195 .Va pfil_bridge
 196 and
 197 .Va pfil_member
 198 will be disabled so that IPFW
 199 is not run twice; these can be re-enabled if desired.
 200 .It Va net.link.bridge.ipfw_arp
 201 Set to
 202 .Li 1
 203 to enable layer2 ARP filtering with
 204 .Xr ipfirewall 4 ,
 205 set to
 206 .Li 0
 207 to disable it.
 208 Requires
 209 .Va ipfw
 210 to be enabled.
 211 .El
 212 .Pp
 213 ARP and REVARP packets are forwarded without being filtered and others
 214 that are not IP nor IPv6 packets are not forwarded when
 215 .Va pfil_onlyip
 216 is enabled.
 217 IPFW can filter Ethernet types using
 218 .Cm mac-type
 219 so all packets are passed to
 220 the filter for processing.
 221 .Pp
 222 Note that packets to and from the bridging host will be seen by the
 223 filter on the interface with the appropriate address configured as well
 224 as on the interface on which the packet arrives or departs.
 225 .Sh EXAMPLES
 226 The following when placed in the file
 227 .Pa /etc/rc.conf
 228 will cause a bridge called
 229 .Dq Li bridge0
 230 to be created, and will add the interfaces
 231 .Dq Li ath0
 232 and
 233 .Dq Li fxp0
 234 to the bridge, and then enable packet forwarding.
 235 Such a configuration could be used to implement a simple
 236 802.11-to-Ethernet bridge (assuming the 802.11 interface is
 237 in ad-hoc mode).
 238 .Bd -literal -offset indent
 239 cloned_interfaces="bridge0"
 240 ifconfig_bridge0="addm ath0 addm fxp0 up"
 241 .Ed
 242 .Pp
 243 For the bridge to forward packets all member interfaces and the bridge need
 244 to be up.
 245 The above example would also require:
 246 .Bd -literal -offset indent
 247 ifconfig_ath0="up ssid my_ap mode 11g mediaopt hostap"
 248 ifconfig_fxp0="up"
 249 .Ed
 250 .Pp
 251 Consider a system with two 4-port Ethernet boards.
 252 The following will cause a bridge consisting of all 8 ports with Rapid Spanning
 253 Tree enabled to be created:
 254 .Bd -literal -offset indent
 255 ifconfig bridge0 create
 256 ifconfig bridge0 \e
 257     addm fxp0 stp fxp0 \e
 258     addm fxp1 stp fxp1 \e
 259     addm fxp2 stp fxp2 \e
 260     addm fxp3 stp fxp3 \e
 261     addm fxp4 stp fxp4 \e
 262     addm fxp5 stp fxp5 \e
 263     addm fxp6 stp fxp6 \e
 264     addm fxp7 stp fxp7 \e
 265     up
 266 .Ed
 267 .Pp
 268 The bridge can be used as a regular host interface at the same time as bridging
 269 between its member ports.
 270 In this example, the bridge connects em0 and em1, and will receive its IP
 271 address through DHCP:
 272 .Bd -literal -offset indent
 273 cloned_interfaces="bridge0"
 274 ifconfig_bridge0="addm em0 addm em1 DHCP"
 275 ifconfig_em0="up"
 276 ifconfig_em1="up"
 277 .Ed
 278 .Pp
 279 The bridge can tunnel Ethernet across an IP internet using the EtherIP
 280 protocol.
 281 This can be combined with
 282 .Xr ipsec 4
 283 to provide an encrypted connection.
 284 Create a
 285 .Xr gif 4
 286 interface and set the local and remote IP addresses for the
 287 tunnel, these are reversed on the remote bridge.
 288 .Bd -literal -offset indent
 289 ifconfig gif0 create
 290 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
 291 ifconfig bridge0 create
 292 ifconfig bridge0 addm fxp0 addm gif0 up
 293 .Ed
 294 .Sh SEE ALSO
 295 .Xr gif 4 ,
 296 .Xr ipf 4 ,
 297 .Xr ipfw 4 ,
 298 .Xr pf 4 ,
 299 .Xr ifconfig 8
 300 .Sh HISTORY
 301 The
 302 .Nm
 303 driver first appeared in
 304 .Fx 6.0 .
 305 .Sh AUTHORS
 306 .An -nosplit
 307 The
 308 .Nm bridge
 309 driver was originally written by
 310 .An Jason L. Wright
 311 .Aq jason@thought.net
 312 as part of an undergraduate independent study at the University of
 313 North Carolina at Greensboro.
 314 .Pp
 315 This version of the
 316 .Nm
 317 driver has been heavily modified from the original version by
 318 .An Jason R. Thorpe
 319 .Aq thorpej@wasabisystems.com .
 320 .Pp
 321 Rapid Spanning Tree Protocol (RSTP) support was added by
 322 .An Andrew Thompson
 323 .Aq thompsa@FreeBSD.org .
 324 .Sh BUGS
 325 The
 326 .Nm
 327 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
 328 network devices, with exactly the same interface MTU size as the bridge device.
 329 .Pp
 330 Only wireless interfaces in hostap mode can be bridged due to the 802.11
 331 framing format, bridging a wireless client is not supported yet.