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