share/man/man4/bridge.4

   1 .\" Copyright 2001 Wasabi Systems, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed for the NetBSD Project by
  17 .\"     Wasabi Systems, Inc.
  18 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  19 .\"    or promote products derived from this software without specific prior
  20 .\"    written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  24 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  26 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  27 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  28 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  29 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  30 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  31 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  32 .\" POSSIBILITY OF SUCH DAMAGE.
  33 .\"
  34 .\" $NetBSD: bridge.4,v 1.7 2005/06/23 12:47:38 peter Exp $
  35 .\" $DragonFly: src/share/man/man4/bridge.4,v 1.10 2007/07/29 17:27:45 swildner Exp $
  36 .\"
  37 .Dd August 30, 2006
  38 .Dt BRIDGE 4
  39 .Os
  40 .Sh NAME
  41 .Nm bridge
  42 .Nd network bridge device
  43 .Sh SYNOPSIS
  44 .Cd "pseudo-device bridge"
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 driver creates a logical link between two or more IEEE 802 networks
  49 that use the same (or
  50 .Dq similar enough )
  51 framing format.
  52 For example, it is possible to bridge Ethernet and 802.11 networks together,
  53 but it is not possible to bridge Ethernet and Token Ring together.
  54 .Pp
  55 To use
  56 .Nm ,
  57 the administrator must first create the interface and configure
  58 the bridge parameters.
  59 The bridge is created using the
  60 .Xr ifconfig 8
  61 .Cm create
  62 subcommand.
  63 See the
  64 .Xr ifconfig 8
  65 manual page for further information on configuring bridges.
  66 .Pp
  67 A bridge can be used to provide several services, such as a simple
  68 802.11-to-Ethernet bridge for wireless hosts, and traffic isolation.
  69 .Pp
  70 A bridge works like a hub, forwarding traffic from one interface
  71 to another.
  72 Multicast and broadcast packets are always forwarded to all
  73 interfaces that are part of the bridge.
  74 For unicast traffic, the bridge learns which MAC addresses are associated
  75 with which interfaces and will forward the traffic selectively.
  76 .Pp
  77 The bridge operates in a safe mode by default, setting the MAC source in
  78 the link header on outgoing packets to the outgoing interface MAC.
  79 This reduces the chance that the layer-2 switching in your switches
  80 will become confused.
  81 To operate the bridge in transparent MAC mode you must set the
  82 .Cm link0
  83 flag on the bridge interface via
  84 .Xr ifconfig 8
  85 and then carefully check that your network is still fully operational.
  86 .Pp
  87 If your network becomes glitchy, with long pauses in tcp sessions, then
  88 transparent bridging mode is likely the cause.  This mode should only be
  89 used when you are bridging networks with devices that do MAC-based security
  90 or firewalling (for example, the supremely braindead at&t uverse router),
  91 or which impose severe limitations on MAC:IP assignments.
  92 .Pp
  93 The
  94 .Nm
  95 driver implements the IEEE 802.1D Spanning Tree protocol (STP).
  96 Spanning Tree is used to detect and remove loops in a network topology.
  97 .Pp
  98 Packet filtering can be used with any firewall package that hooks in via the
  99 .Xr pfil 9
 100 framework.
 101 When filtering is enabled, bridged packets will pass through the filter
 102 inbound on the originating interface, on the bridge interface and outbound on
 103 the appropriate interfaces.
 104 Either stage can be disabled, this behaviour can be controlled using
 105 .Xr sysctl 8 :
 106 Set
 107 .Va net.link.bridge.pfil_member
 108 to
 109 .Li 1
 110 to enable filtering on the incoming and outgoing member interfaces
 111 and set
 112 .Va net.link.bridge.pfil_bridge
 113 to
 114 .Li 1
 115 to enable filtering on the bridge interface.
 116 .Pp
 117 ARP and REVARP packets are forwarded without being filtered and others
 118 that are not IP nor IPv6 packets are not forwarded when filtering is
 119 enabled.
 120 .Pp
 121 Note that packets to and from the bridging host will be seen by the
 122 filter on the interface with the appropriate address configured as well
 123 as on the interface on which the packet arrives or departs.
 124 .Pp
 125 The MTU of the first member interface to be added is used as the bridge MTU,
 126 all additional members are required to have exactly the same value.
 127 .Sh SEE ALSO
 128 .Xr pf 4 ,
 129 .Xr ifconfig 8
 130 .Sh HISTORY
 131 The
 132 .Nm
 133 driver first appeared in
 134 .Ox 2.5
 135 and found its way into
 136 .Dx 1.3 .
 137 Transparent bridging (link0) was added in
 138 .Dx 2.9
 139 in 2011.
 140 .Sh AUTHORS
 141 .An -nosplit
 142 The
 143 .Nm
 144 driver was originally written by
 145 .An Jason L. Wright
 146 .Aq jason@thought.net
 147 as part of an undergraduate independent study at the University of
 148 North Carolina at Greensboro.
 149 .Pp
 150 This version of the
 151 .Nm
 152 driver has been heavily modified from the original version by
 153 .An Jason R. Thorpe
 154 .Aq thorpej@wasabisystems.com .
 155 .Sh BUGS
 156 The
 157 .Nm
 158 driver currently supports only Ethernet and Ethernet-like (e.g. 802.11)
 159 network devices, with exactly the same interface MTU size as the bridge device.