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 August 13, 2006
  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 A bridge can be used to provide several services, such as a simple
  82 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation.
  83 .Pp
  84 A bridge works like a hub, forwarding traffic from one interface
  85 to another.
  86 Multicast and broadcast packets are always forwarded to all
  87 interfaces that are part of the bridge.
  88 For unicast traffic, the bridge learns which MAC addresses are associated
  89 with which interfaces and will forward the traffic selectively.
  90 .Pp
  91 The
  92 .Nm
  93 driver implements the IEEE 802.1D Spanning Tree protocol (STP).
  94 Spanning Tree is used to detect and remove loops in a network topology.
  95 The bridge can log STP port changes to
  96 .Xr syslog 3
  97 by enabling the
  98 .Va net.link.bridge.log_stp
  99 variable using
 100 .Xr sysctl 8 .
 101 .Pp
 102 All the bridged member interfaces need to be up in order to pass network traffic.
 103 These can be enabled using
 104 .Xr ifconfig 8
 105 or
 106 .Va ifconfig_ Ns Ao Ar interface Ac Ns Va ="up"
 107 in
 108 .Xr rc.conf 5 .
 109 .Pp
 110 The MTU of the first member interface to be added is used as the bridge MTU.
 111 All additional members are required to have exactly the same value.
 112 .Pp
 113 The TXCSUM capability is disabled for any interface added to the bridge, and it
 114 is restored when the interface is removed again.
 115 .Pp
 116 The bridge supports
 117 .Dq monitor mode ,
 118 where the packets are discarded after
 119 .Xr bpf 4
 120 processing, and are not processed or forwarded further.
 121 This can be used to multiplex the input of two or more interfaces into a single
 122 .Xr bpf 4
 123 stream.
 124 This is useful for reconstructing the traffic for network taps
 125 that transmit the RX/TX signals out through two separate interfaces.
 126 .Sh PACKET FILTERING
 127 .Pp
 128 Packet filtering can be used with any firewall package that hooks in via the
 129 .Xr pfil 9
 130 framework.
 131 When filtering is enabled, bridged packets will pass through the filter
 132 inbound on the originating interface, on the bridge interface and outbound on
 133 the appropriate interfaces.
 134 Either stage can be disabled.
 135 The filtering behaviour can be controlled using
 136 .Xr sysctl 8 :
 137 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
 138 .It Va net.link.bridge.pfil_onlyip
 139 Controls the handling of non-IP packets which are not passed to
 140 .Xr pfil 9 .
 141 Set to
 142 .Li 1
 143 to only allow IP packets to pass (subject to firewall rules), set to
 144 .Li 0
 145 to unconditionally pass all non-IP Ethernet frames.
 146 .It Va net.link.bridge.pfil_member
 147 Set to
 148 .Li 1
 149 to enable filtering on the incoming and outgoing member interfaces, set
 150 to
 151 .Li 0
 152 to disable it.
 153 .It Va net.link.bridge.pfil_bridge
 154 Set to
 155 .Li 1
 156 to enable filtering on the bridge interface, set
 157 to
 158 .Li 0
 159 to disable it.
 160 .It Va net.link.bridge.ipfw
 161 Set to
 162 .Li 1
 163 to enable layer2 filtering with
 164 .Xr ipfirewall 4 ,
 165 set to
 166 .Li 0
 167 to disable it.
 168 This needs to be enabled for
 169 .Xr dummynet 4
 170 support.
 171 When
 172 .Va ipfw
 173 is enabled,
 174 .Va pfil_bridge
 175 and
 176 .Va pfil_member
 177 will be disabled so that IPFW
 178 is not run twice; these can be re-enabled if desired.
 179 .El
 180 .Pp
 181 ARP and REVARP packets are forwarded without being filtered and others
 182 that are not IP nor IPv6 packets are not forwarded when
 183 .Va pfil_onlyip
 184 is enabled.
 185 IPFW can filter Ethernet types using
 186 .Cm mac-type
 187 so all packets are passed to
 188 the filter for processing.
 189 .Pp
 190 Note that packets to and from the bridging host will be seen by the
 191 filter on the interface with the appropriate address configured as well
 192 as on the interface on which the packet arrives or departs.
 193 .Sh EXAMPLES
 194 The following when placed in the file
 195 .Pa /etc/rc.conf
 196 will cause a bridge called
 197 .Dq Li bridge0
 198 to be created, and will add the interfaces
 199 .Dq Li ath0
 200 and
 201 .Dq Li fxp0
 202 to the bridge, and then enable packet forwarding.
 203 Such a configuration could be used to implement a simple
 204 802.11-to-Ethernet bridge (assuming the 802.11 interface is
 205 in ad-hoc mode).
 206 .Bd -literal -offset indent
 207 cloned_interfaces="bridge0"
 208 ifconfig_bridge0="addm ath0 addm fxp0 up"
 209 .Ed
 210 .Pp
 211 For the bridge to forward packets all member interfaces and the bridge need
 212 to be up.
 213 The above example would also require:
 214 .Bd -literal -offset indent
 215 ifconfig_ath0="up ssid my_ap mode 11g mediaopt hostap"
 216 ifconfig_fxp0="up"
 217 .Ed
 218 .Pp
 219 Consider a system with two 4-port Ethernet boards.
 220 The following will cause a bridge consisting of all 8 ports with Spanning Tree
 221 enabled to be created:
 222 .Bd -literal -offset indent
 223 ifconfig bridge0 create
 224 ifconfig bridge0 \e
 225     addm fxp0 stp fxp0 \e
 226     addm fxp1 stp fxp1 \e
 227     addm fxp2 stp fxp2 \e
 228     addm fxp3 stp fxp3 \e
 229     addm fxp4 stp fxp4 \e
 230     addm fxp5 stp fxp5 \e
 231     addm fxp6 stp fxp6 \e
 232     addm fxp7 stp fxp7 \e
 233     up
 234 .Ed
 235 .Pp
 236 The bridge can tunnel Ethernet across an IP internet using the EtherIP
 237 protocol.
 238 This can be combined with
 239 .Xr ipsec 4
 240 to provide an encrypted connection.
 241 Create a
 242 .Xr gif 4
 243 interface and set the local and remote IP addresses for the
 244 tunnel, these are reversed on the remote bridge.
 245 .Bd -literal -offset indent
 246 ifconfig gif0 create
 247 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
 248 ifconfig bridge0 create
 249 ifconfig bridge0 addm fxp0 addm gif0 up
 250 .Ed
 251 .Sh SEE ALSO
 252 .Xr gif 4 ,
 253 .Xr ipf 4 ,
 254 .Xr ipfw 4 ,
 255 .Xr pf 4 ,
 256 .Xr ifconfig 8
 257 .Sh HISTORY
 258 The
 259 .Nm
 260 driver first appeared in
 261 .Fx 6.0 .
 262 .Sh AUTHORS
 263 .An -nosplit
 264 The
 265 .Nm bridge
 266 driver was originally written by
 267 .An Jason L. Wright
 268 .Aq jason@thought.net
 269 as part of an undergraduate independent study at the University of
 270 North Carolina at Greensboro.
 271 .Pp
 272 This version of the
 273 .Nm
 274 driver has been heavily modified from the original version by
 275 .An Jason R. Thorpe
 276 .Aq thorpej@wasabisystems.com .
 277 .Sh BUGS
 278 The
 279 .Nm
 280 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
 281 network devices, with exactly the same interface MTU size as the bridge device.
 282 .Pp
 283 Only wireless interfaces in hostap mode can be bridged due to the 802.11
 284 framing format, bridging a wireless client is not supported yet.
 285 .Pp
 286 The bridge implements version IEEE 802.1D 1998 of the Spanning Tree Protocol so
 287 newer features in IEEE 802.1D 2004 such as RSTP are not available.