Page MenuHomeFreeBSD
Files F144492526

D51185.id158068.diff
No OneTemporary
Actions

D51185.id158068.diff
View Options

diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4
--- a/share/man/man4/bridge.4
+++ b/share/man/man4/bridge.4
@@ -36,7 +36,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd July 5, 2025
+.Dd July 6, 2025
.Dt IF_BRIDGE 4
.Os
.Sh NAME
@@ -275,50 +275,309 @@
The
.Nm
driver has full support for virtual LANs (VLANs).
-The bridge implements independent VLAN learning, i.e. MAC addresses are
-learned on a per-VLAN basis, and the same MAC address may be learned on
-multiple interfaces on different VLANs.
-Incoming frames with an 802.1Q tag will be assigned to the appropriate
-VLAN.
+VLAN support comes in two flavours: the
+.Dq legacy
+flavour is the VLAN behavior supported by previous
+.Fx
+releases, while the
+.Dq filtering
+flavour is the modern VLAN behavior supported by
+.Fx 15.0
+and later.
+For compatibility with previous releases, a newly-created bridge uses
+the
+.Dq legacy
+flavour by default, but the
+.Dq filtering
+flavour is recommended for new configurations.
+.Ss Legacy VLAN support
+Legacy VLAN bridges accept both tagged and untagged frames on every
+member interface, learn Ethernet addresses for each VLAN (sometimes
+called IVL (Independent VLAN Learning)), and forward frames unchanged
+based on the destination Ethernet address.
+Frames will never have VLAN tags added or removed when forwarding,
+and all member interfaces may send and receive frames for any VLAN.
+.Pp
+Untagged frames are considered to be in
+.Dq VLAN 0 ,
+which is a pseudo-VLAN distinct from any VLAN ID used on the wire.
+IP addresses configured on the bridge itself communicate in this
+pseudo-VLAN.
+.Pp
+Because legacy bridges lack VLAN access control and support for
+(de)tagging of frames, it is recommended (but not required) that
+one instance of
+.Nm
+be configured for each VLAN and the
+.Xr vlan 4
+interface used to handle frame tagging.
+For example, to configure a bridge for VLAN 100 where
+.Dq ix0
+is a tagged port, and
+.Dq em0
+and
+.Dq em1
+are untagged ports:
+.Bd -literal -offset indent
+ifconfig ix0.100 create
+ifconfig bridge100 create \e
+ addm ix0.100 \e
+ addm em0 \e
+ addm em1
+.Ed
.Pp
-Traffic sent to or from the host is not assigned to a VLAN by default.
-To allow the host to communicate on a VLAN, configure a
+Because the
.Xr vlan 4
-interface on the bridge and (if necessary) assign IP addresses there.
+interface handles tagging, the trunk port is restricted to communicating
+in VLAN 100, and it may communicate with the untagged bridge ports since
+the VLAN tags are removed before the frames are passed to
+.Nm .
.Pp
-By default no access control is enabled, so any interface may
-participate in any VLAN.
+Any IP addresses configured on
+.Dq bridge100
+will also function as if they were in VLAN 100.
+.Pp
+When configured this way, the bridge runs a separate STP instances for
+every VLAN, sometimes called
+.Dq PVST
+(Per-VLAN Spanning Tree), meaning STP frames are sent with 802.1Q VLAN
+tags attached.
+This is a non-standard mode of operation and may not be compatible
+with other bridges that expect standards-based RSTP.
+.Ss Interaction between Xr bridge 4 and Xr vlan 4
+When using both
+.Nm
+and
+.Xr vlan 4
+on the same interface, a conflict arises because both drivers wish to
+handle VLAN-tagged frames received on the interface.
+This conflict is resolved as follows:
.Pp
-VLAN filtering may be enabled on an interface using the
-.Xr ifconfig 8
+When a tagged frame is initially received, it is passed to
+.Nm
+for handling.
+The bridge will examine the frame's destination Ethernet address.
+If the destination address is the address of the local system (i.e.,
+the address of the bridge itself or of the member interface the frame
+was received on), then the packet will be passed to
+.Xr vlan 4
+for handling; otherwise, the frame will be handled by the bridge.
+.Pp
+This affects configuration similar to the following:
+.Bd -literal -offset indent
+ifconfig ix0.100 create
+ifconfig bridge0 create addm ix0
+.Ed
+.Pp
+The practical consequence is that the
+.Dq ix0.100
+interface will only see frames addressed to its own MAC address.
+This implies that tools such as
+.Xr tcpdump 1
+will not show the expected traffic even if the interface is placed in
+promiscuous mode, and adding the
+.Xr vlan 4
+interface to another bridge will not work correctly.
+.Pp
+To avoid this conflict, do not configure a
+.Xr vlan 4
+interface on an interface which is also a member of an
+.Nm
+interface.
+In most cases, a
+.Dq filtering
+bridge configuration can be used instead.
+.Ss VLAN filtering configuration
+VLAN filtering is an alternative to the legacy bridge VLAN support
+described above.
+A bridge configured to use VLAN filtering provides several advantages
+over the legacy configuration:
+.Bl -bullet
+.It
+A single
+.Nm
+instance can support any number of VLANs, while still allowing
+interfaces to be restricted to specific VLANs.
+.It
+Configuration is greatly simplified, especially for complex network
+topologies.
+.It
+The bridge's behaviour aligns more closely with the behaviour
+described by IEEE 802.1Q and expected by network administrators.
+.It
+The conflict between
+.Nm
+and
+.Xr vlan 4
+is avoided, since
+.Xr vlan 4
+interfaces are not used for trunk members.
+.El
+.Pp
+VLAN filtering is enabled by setting the
.Cm vlanfilter
-option.
-When VLAN filtering is enabled, an interface may only send and receive
-frames based on its configured VLAN access list.
+flag on member interfaces:
+.Bd -literal -offset indent
+ifconfig bridge0 addm ix0
+ifconfig bridge0 vlanfilter ix0
+.Ed
+.Pp
+While both legacy and VLAN filtering interfaces can co-exist in the
+same bridge, this is not recommended.
+Instead, VLAN filtering should be enabled using the
+.Cm defvlanfilter
+flag when the bridge is created, which causes all interfaces added to
+the bridge to have VLAN filtering enabled by default:
+.Bd -literal -offset indent
+ifconfig bridge0 create defvlanfilter
+ifconfig bridge0 addm ix0
+.Ed
+.Pp
+VLAN filtering bridge members can be identified by the presence of the
+.Dq VLANFILTER
+flag in the output of
+.Xr ifconfig 8 .
.Pp
-The interface's untagged VLAN ID may be configured using the
+By default, a VLAN filtering interface is not permitted to pass any
+traffic on the bridge.
+To allow untagged frames on an interface, the interface's Port VLAN ID
+(PVID) can be configured using the
.Xr ifconfig 8
.Cm untagged
-option.
-If an untagged VLAN ID is configured, incoming frames will be assigned
-to that VLAN, and the interface may receive outgoing untagged frames
-in that VLAN.
+command:
+.Bd -literal -offset indent
+ifconfig bridge0 untagged ix0 100
+.Ed
+.Pp
+This will cause incoming frames on the
+.Dq ix0
+interface to be assigned to VLAN 100.
+If many member interfaces share the same PVID, the default PVID can be
+configured using the
+.Xr ifconfig 8
+.Cm defuntagged
+command when the bridge is created:
+.Bd -literal -offset indent
+ifconfig bridge0 create defvlanfilter defuntagged 100
+.Ed
.Pp
-The tagged VLAN access list may be configured using the
+This will cause all newly-added bridge members to be configured with
+PVID 100.
+.Pp
+To allow tagged frames on an interface, the interface's VLAN access list
+can be configured using the
+.Xr ifconfig 8
.Cm tagged ,
.Cm +tagged
and
.Cm -tagged
-options to
-.Xr ifconfig 8 .
-An interface may send and receive tagged frames for any VLAN in its
-access list.
+commands.
+For example, to allow
+.Dq ix0
+to communicate on VLANs 1 and 2, and any VLAN from 100 to 199
+(inclusive):
+.Bd -literal -offset indent
+ifconfig bridge0 tagged ix0 1,2,100-199
+.Ed
.Pp
-The bridge will automatically insert or remove 802.1q tags as needed,
-based on the interface configuration, when forwarding frames between
-interfaces.
-This tag processing is only done for interfaces with VLAN filtering
-enabled.
+Note that if an untagged VLAN ID is configured on an interface, that
+VLAN ID must still be listed in the interface's VLAN access list to
+pass tagged packets for that VLAN.
+.Pp
+The bridge will automatically add and remove 802.1Q VLAN tags as
+required to allow member interfaces to communicate.
+For example, if a tagged frame for VLAN 100 is received on
+.Dq ix0 ,
+and the destination interface
+.Dq ix1
+has VLAN 100 configured as its untagged VLAN, then the 802.1Q tag will
+be stripped before the frame is transmitted on
+.Dq ix1 .
+.Pp
+To allow the host to communicate with a VLAN, a
+.Xr vlan 4
+interface may be configured on the bridge for each VLAN.
+For example, to create a host interface in VLAN 100:
+.Bd -literal -offset indent
+ifconfig bridge0.100 create
+.Ed
+.Pp
+This interface may be configured with
+.Xr inet 4
+and
+.Xr inet6 4
+addresses as normal.
+.Ss Migrating from legacy to VLAN filtering bridge configuration
+For most configuration, migrating an existing legacy configuration to
+a VLAN filtering configuration is straightforward.
+Some common examples will be demonstrated.
+.Bl -ohang
+.It Sy A single bridge
+.Pp
+A legacy bridge configuration for a typical
+.Xr jail 8
+or
+.Xr bhyve 8
+host may look similar to this:
+.Bd -literal -offset indent
+ifconfig bridge0 create
+ifconfig bridge0 addm ix0 # Internet interface
+ifconfig bridge0 addm tap0 # A bhyve virtual machine
+ifconfig bridge0 addm epair0a # A jail interface
+.Ed
+.Pp
+This configuration will allow all interfaces, including the virtual
+machine and jail interfaces, to communicate on any VLAN.
+In most cases this is not desirable, so converting this configuration
+to a VLAN filtering bridge can be done by setting the
+.Cm defvlanfilter
+and
+.Cm defuntagged
+options on the bridge:
+.Bd -literal -offset indent
+ifconfig bridge0 create defvlanfilter defuntagged 1
+ifconfig bridge0 addm ix0
+ifconfig bridge0 addm tap0
+ifconfig bridge0 addm epair0a
+.Ed
+.Pp
+VLAN ID 1 is chosen arbitrarily here, since all interfaces are untagged.
+The bridge VLAN ID could be configured to match the VLAN ID used by the
+switch that ix0 is connected to, but since the ID will never be sent on
+the wire, this is not required.
+.Pp
+.It Sy Two bridges for internal and DMZ VLANs
+.Pp
+For this example, we will assume VLAN 100 is an
+.Dq internal
+VLAN, while VLAN 200 is a
+.Dq DMZ
+VLAN.
+A legacy bridge configuration supporting both VLANs on a trunk port,
+with some members in each VLAN, might look similar to this:
+.Bd -literal -offset indent
+ifconfig ix0.100 create
+ifconfig bridge100 create
+ifconfig bridge100 addm ix0.100
+ifconfig bridge100 addm em0
+ifconfig bridge100 addm em1
+ifconfig ix0.200 create
+ifconfig bridge200 create
+ifconfig bridge200 addm ix0.200
+ifconfig bridge200 addm em2
+ifconfig bridge200 addm em3
+.Ed
+.Pp
+This configuration can be replaced with a single VLAN filtering bridge
+as follows:
+.Bd -literal -offset indent
+ifconfig bridge0 create defvlanfilter
+ifconfig bridge0 addm ix0 tagged ix0 100,200
+ifconfig bridge0 addm em0 untagged em0 100
+ifconfig bridge0 addm em1 untagged em1 100
+ifconfig bridge0 addm em2 untagged em2 200
+ifconfig bridge0 addm em3 untagged em3 200
+.Ed
.Sh PACKET FILTERING
Packet filtering can be used with any firewall package that hooks in via the
.Xr pfil 9
@@ -513,7 +772,7 @@
.Sh EXAMPLES
The following when placed in the file
.Pa /etc/rc.conf
-will cause a bridge called
+will cause a legacy bridge called
.Dq Li bridge0
to be created, and will add the interfaces
.Dq Li wlan0
@@ -538,10 +797,11 @@
.Ed
.Pp
Consider a system with two 4-port Ethernet boards.
-The following will cause a bridge consisting of all 8 ports with
-Rapid Spanning Tree enabled to be created:
+The following will cause a VLAN filtering bridge to be created
+consisting of all 8 ports on a single VLAN and with Rapid Spanning Tree
+enabled:
.Bd -literal -offset indent
-ifconfig bridge0 create
+ifconfig bridge0 create defvlanfilter defuntagged 1
ifconfig bridge0 \e
addm fxp0 stp fxp0 \e
addm fxp1 stp fxp1 \e
@@ -554,10 +814,10 @@
up
.Ed
.Pp
-The bridge can be used as a regular host interface at the same time as bridging
-between its member ports.
-In this example, the bridge connects em0 and em1, and will receive its IP
-address through DHCP:
+The bridge can be used as a regular host interface at the same time as
+bridging between its member ports.
+In this example, the legacy bridge connects em0 and em1, and will
+receive its IP address through DHCP:
.Bd -literal -offset indent
cloned_interfaces="bridge0"
ifconfig_bridge0="addm em0 addm em1 DHCP"
@@ -565,6 +825,17 @@
ifconfig_em1="up"
.Ed
.Pp
+To achieve the same configuration with a VLAN filtering bridge, DHCP
+can be run on the bridge VLAN interface:
+.Bd -literal -offset indent
+cloned_interfaces="bridge0"
+ifconfig_bridge0="defvlanfilter defuntagged 1 addm em0 addm em1"
+ifconfig_em0="up"
+ifconfig_em1="up"
+vlans_bridge0="100"
+ifconfig_bridge0_100="DHCP"
+.Ed
+.Pp
The bridge can tunnel Ethernet across an IP internet using the EtherIP
protocol.
This can be combined with

File Metadata

Mime Type
text/plain
Expires
Mon, Feb 9, 7:59 PM (9 h, 58 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28601257
Default Alt Text
D51185.id158068.diff (12 KB)

Event Timeline