share/man/man4/bridge.4

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