share/man/man4/bridge.4

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