6/share/man/man4/bridge.4

   1 .\"
   2 .\" $FreeBSD$
   3 .\"
   4 .Dd September 27, 2005
   5 .Dt BRIDGE 4
   6 .Os
   7 .Sh NAME
   8 .Nm bridge
   9 .Nd bridging support
  10 .Sh SYNOPSIS
  11 .Cd "options BRIDGE"
  12 .Sh DESCRIPTION
  13 .Bf -symbolic
  14 This bridge implementation is made obsolete by:
  15 .Ef
  16 .Xr if_bridge 4
  17 .Bf -symbolic
  18 and will be removed from future releases.
  19 .Ef
  20 .Pp
  21 .Fx
  22 supports bridging on Ethernet-type interfaces, including VLANs.
  23 Bridging support can be either compiled into the kernel, or loaded
  24 at runtime as a kernel module.
  25 .Pp
  26 A single
  27 .Fx
  28 host can do bridging on independent sets of interfaces,
  29 which are called
  30 .Dq clusters .
  31 Each cluster connects a set of interfaces, and is
  32 identified by a
  33 .Dq cluster-ID
  34 which is a number in the range 1..65535.
  35 A cluster in fact is very similar to what commercial switches call
  36 a
  37 .Dq VLAN .
  38 Note however that there is no relation whatsoever
  39 between the cluster-ID and the IEEE 802.1q VLAN-ID which appears
  40 in the header of packets transmitted on the wire.
  41 In fact, in most cases there is no relation between the
  42 so-called
  43 .Dq "VLAN identifier"
  44 used in most commercial switches, and
  45 the IEEE 802.1q VLAN-ID.
  46 .Pp
  47 By putting both physical and logical
  48 .Pq Xr vlan 4
  49 interfaces in the same cluster, a
  50 .Fx
  51 box can also implement what in commercial terms is called a
  52 .Dq trunk
  53 interface.
  54 This means that packets
  55 coming from one of the interfaces in a cluster
  56 will appear on the wire of the
  57 .Dq parent
  58 interface of any VLAN interface in a cluster,
  59 with the proper VLAN tag.
  60 Similarly, packets
  61 coming from a parent interface of any VLAN interface in a cluster
  62 will have the VLAN tag stripped,
  63 and will be forwarded to other interfaces in a cluster.
  64 See the
  65 .Sx EXAMPLES
  66 section for more details.
  67 .Pp
  68 Runtime operation of the
  69 .Nm
  70 is controlled by several
  71 .Xr sysctl 8
  72 variables, as follows.
  73 .Bl -tag -width indent
  74 .It Va net.link.ether.bridge.enable
  75 Set to
  76 .Li 1
  77 to enable bridging, set to
  78 .Li 0
  79 to disable it.
  80 .It Va net.link.ether.bridge.ipfw
  81 Set to
  82 .Li 1
  83 to enable
  84 .Xr ipfw 8
  85 processing of bridged packets.
  86 Note that
  87 .Xr ipfw 8
  88 rules only apply
  89 to IP packets.
  90 Non-IP packets are accepted by default.
  91 See the
  92 .Sx BUGS
  93 section and the
  94 .Xr ipfw 8
  95 manpage for more details on the interaction of bridging
  96 and the firewall.
  97 .It Va net.link.ether.bridge.ipf
  98 Set to
  99 .Li 1
 100 to enable
 101 .Xr ipf 8
 102 processing of bridged packets.
 103 Note that
 104 .Xr ipf 8
 105 rules only apply
 106 to IP packets.
 107 Non-IP packets are accepted by default.
 108 .It Va net.link.ether.bridge.config
 109 Set to the list of interfaces to bridge.
 110 Interfaces are separated by spaces, commas or tabs.
 111 Each interface
 112 can be optionally followed by a colon and an integer indicating the
 113 cluster it belongs to (defaults to 1 if the cluster-ID is missing), e.g.\&
 114 .Dq Li "dc0:1,dc1,vlan0:3 dc2:3"
 115 will put
 116 .Li dc0
 117 and
 118 .Li dc1
 119 in cluster number 1, and
 120 .Li vlan0
 121 and
 122 .Li dc2
 123 in cluster
 124 number 3.
 125 See the
 126 .Sx EXAMPLES
 127 section for more examples.
 128 .Pp
 129 The list of interfaces is rescanned every time the list is
 130 modified, bridging is enabled, or new interfaces are created or
 131 destroyed.
 132 An explicit request to refresh the
 133 .Nm
 134 configuration can also
 135 be done by writing any value to
 136 .Va net.link.ether.bridge.refresh .
 137 Interfaces that are in the list but cannot be used
 138 for bridging (because they are non-existing, or not Ethernet or VLAN)
 139 are not used and a warning message is generated.
 140 .El
 141 .Pp
 142 Bridging requires interfaces to be put in promiscuous mode,
 143 and transmit packets with Ethernet source addresses different
 144 than their own.
 145 Some interfaces (e.g.\&
 146 .Xr wi 4 )
 147 do not support this functionality.
 148 Also, bridging is not compatible with interfaces which
 149 use hardware loopback, because there is no way to tell locally
 150 generated packets from externally generated ones.
 151 .Sh FILES
 152 .Bl -tag -width ".Pa /boot/kernel/bridge.ko" -compact
 153 .It Pa /boot/kernel/bridge.ko
 154 .Nm
 155 loadable module.
 156 .El
 157 .Sh EXAMPLES
 158 A simple
 159 .Nm
 160 configuration with three interfaces in the same
 161 cluster can be set as follows.
 162 No cluster-ID is specified here, which
 163 will cause the interfaces to appear as part of cluster #1.
 164 .Pp
 165 .Dl "sysctl net.link.ether.bridge.config=dc0,dc1,fxp1"
 166 .Pp
 167 If you do not know what actual interfaces will be present on
 168 your system, you can just put all existing interfaces in the
 169 configuration, as follows:
 170 .Pp
 171 .Dl sysctl net.link.ether.bridge.config="`ifconfig -l`"
 172 .Pp
 173 This will result in a space-separated list of interfaces.
 174 Out of the list, only Ethernet and VLAN interfaces will be
 175 used for bridging, whereas for others the kernel will produce
 176 a warning message.
 177 .Pp
 178 More complex configurations can be used to create multiple
 179 clusters, e.g.\&
 180 .Pp
 181 .Dl "sysctl net.link.ether.bridge.config=dc0:3,dc1:3,fxp0:4,fxp1:4"
 182 .Pp
 183 will create two completely independent clusters.
 184 .Pp
 185 Finally, interesting configurations involve VLANs and parent interfaces.
 186 As an example, the following configuration will use interface
 187 .Li dc0
 188 as a
 189 .Dq trunk
 190 interface, and pass packets
 191 for 802.1q VLANs 10 and 20 to physical interfaces
 192 .Li dc1
 193 and
 194 .Li dc2 ,
 195 respectively:
 196 .Bd -literal -offset indent
 197 sysctl net.link.ether.bridge.config=vlan0:34,dc1:34,vlan1:56,dc2:56
 198 ifconfig vlan0 vlan 10 vlandev dc0
 199 ifconfig vlan1 vlan 20 vlandev dc0
 200 .Ed
 201 .Pp
 202 Note how there is no relation between the 802.1q VLAN identifiers
 203 (10 and 20) and the cluster-ID's (34 and 56) used in
 204 the
 205 .Va bridge.config
 206 variable.
 207 .Pp
 208 Note also that the trunk interface
 209 does not even appear in the
 210 .Va bridge.config ,
 211 as VLAN tag insertion/removal
 212 is performed by the
 213 .Xr vlan 4
 214 devices.
 215 When using VLAN devices, care must be taken by not creating loops
 216 between these devices and their parent interfaces.
 217 .Sh SEE ALSO
 218 .Xr ip 4 ,
 219 .Xr ng_bridge 4 ,
 220 .Xr vlan 4 ,
 221 .Xr ipf 8 ,
 222 .Xr ipfw 8 ,
 223 .Xr sysctl 8
 224 .Sh HISTORY
 225 Bridging was introduced in
 226 .Fx 2.2.8
 227 by
 228 .An Luigi Rizzo Aq luigi@iet.unipi.it .
 229 .Sh BUGS
 230 Care must be taken not to construct loops in the
 231 .Nm
 232 topology.
 233 The kernel supports only a primitive form of loop detection, by disabling
 234 some interfaces when a loop is detected.
 235 No support for a daemon running the
 236 spanning tree algorithm is currently provided.
 237 .Pp
 238 With bridging active, interfaces are in promiscuous mode,
 239 thus causing some load on the system to receive and filter
 240 out undesired traffic.
 241 .Pp
 242 When passing bridged packets to
 243 .Xr ipfw 8 ,
 244 remember that only IP packets are passed to the firewall, while
 245 other packets are silently accepted.
 246 Also remember that bridged packets are accepted after the
 247 first pass through the firewall irrespective of the setting
 248 of the sysctl variable
 249 .Va net.inet.ip.fw.one_pass ,
 250 and that some
 251 .Xr ipfw 8
 252 actions such as
 253 .Cm divert
 254 do not apply to bridged packets.
 255 It might be useful to have a rule of the form
 256 .Pp
 257 .Dl "skipto 20000 ip from any to any bridged"
 258 .Pp
 259 near the beginning of your ruleset to implement specific rulesets
 260 for bridged packets.