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 FILES
 144 .Bl -tag -width ".Pa /boot/kernel/bridge.ko" -compact
 145 .It Pa /boot/kernel/bridge.ko
 146 .Nm
 147 loadable module.
 148 .El
 149 .Sh EXAMPLES
 150 A simple
 151 .Nm
 152 configuration with three interfaces in the same
 153 cluster can be set as follows.
 154 No cluster-ID is specified here, which
 155 will cause the interfaces to appear as part of cluster #1.
 156 .Pp
 157 .Dl "sysctl net.link.ether.bridge.config=dc0,dc1,fxp1"
 158 .Pp
 159 If you do not know what actual interfaces will be present on
 160 your system, you can just put all existing interfaces in the
 161 configuration, as follows:
 162 .Pp
 163 .Dl sysctl net.link.ether.bridge.config="`ifconfig -l`"
 164 .Pp
 165 This will result in a space-separated list of interfaces.
 166 Out of the list, only Ethernet and VLAN interfaces will be
 167 used for bridging, whereas for others the kernel will produce
 168 a warning message.
 169 .Pp
 170 More complex configurations can be used to create multiple
 171 clusters, e.g.\&
 172 .Pp
 173 .Dl "sysctl net.link.ether.bridge.config=dc0:3,dc1:3,fxp0:4,fxp1:4"
 174 .Pp
 175 will create two completely independent clusters.
 176 .Pp
 177 Finally, interesting configurations involve VLANs and parent interfaces.
 178 As an example, the following configuration will use interface
 179 .Li dc0
 180 as a
 181 .Dq trunk
 182 interface, and pass packets
 183 for 802.1q VLANs 10 and 20 to physical interfaces
 184 .Li dc1
 185 and
 186 .Li dc2 ,
 187 respectively:
 188 .Bd -literal -offset indent
 189 sysctl net.link.ether.bridge.config=vlan0:34,dc1:34,vlan1:56,dc2:56
 190 ifconfig vlan0 vlan 10 vlandev dc0
 191 ifconfig vlan1 vlan 20 vlandev dc0
 192 .Ed
 193 .Pp
 194 Note how there is no relation between the 802.1q VLAN identifiers
 195 (10 and 20) and the cluster-ID's (34 and 56) used in
 196 the
 197 .Va bridge.config
 198 variable.
 199 .Pp
 200 Note also that the trunk interface
 201 does not even appear in the
 202 .Va bridge.config ,
 203 as VLAN tag insertion/removal
 204 is performed by the
 205 .Xr vlan 4
 206 devices.
 207 When using VLAN devices, care must be taken by not creating loops
 208 between these devices and their parent interfaces.
 209 .Sh SEE ALSO
 210 .Xr ip 4 ,
 211 .Xr ng_bridge 4 ,
 212 .Xr vlan 4 ,
 213 .Xr ipf 8 ,
 214 .Xr ipfw 8 ,
 215 .Xr sysctl 8
 216 .Sh HISTORY
 217 Bridging was introduced in
 218 .Fx 2.2.8
 219 by
 220 .An Luigi Rizzo Aq luigi@iet.unipi.it .
 221 .Sh BUGS
 222 Care must be taken not to construct loops in the
 223 .Nm
 224 topology.
 225 The kernel supports only a primitive form of loop detection, by disabling
 226 some interfaces when a loop is detected.
 227 No support for a daemon running the
 228 spanning tree algorithm is currently provided.
 229 .Pp
 230 With bridging active, interfaces are in promiscuous mode,
 231 thus causing some load on the system to receive and filter
 232 out undesired traffic.
 233 .Pp
 234 When passing bridged packets to
 235 .Xr ipfw 8 ,
 236 remember that only IP packets are passed to the firewall, while
 237 other packets are silently accepted.
 238 Also remember that bridged packets are accepted after the
 239 first pass through the firewall irrespective of the setting
 240 of the sysctl variable
 241 .Va net.inet.ip.fw.one_pass ,
 242 and that some
 243 .Xr ipfw 8
 244 actions such as
 245 .Cm divert
 246 do not apply to bridged packets.
 247 It might be useful to have a rule of the form
 248 .Pp
 249 .Dl "skipto 20000 ip from any to any bridged"
 250 .Pp
 251 near the beginning of your ruleset to implement specific rulesets
 252 for bridged packets.