diff options
Diffstat (limited to 'static/freebsd/man4/bridge.4')
| -rw-r--r-- | static/freebsd/man4/bridge.4 | 743 |
1 files changed, 743 insertions, 0 deletions
diff --git a/static/freebsd/man4/bridge.4 b/static/freebsd/man4/bridge.4 new file mode 100644 index 00000000..3af95225 --- /dev/null +++ b/static/freebsd/man4/bridge.4 @@ -0,0 +1,743 @@ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $ +.\" +.\" Copyright 2001 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 13, 2025 +.Dt IF_BRIDGE 4 +.Os +.Sh NAME +.Nm if_bridge +.Nd network bridge device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device if_bridge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bridge_load="YES" +bridgestp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver creates a logical link between two or more IEEE 802 networks +that use the same (or +.Dq "similar enough" ) +framing format. +For example, it is possible to bridge Ethernet and 802.11 networks together, +but it is not possible to bridge Ethernet and Token Ring together. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Pp +When it is created, the +.Nm +interface gets assigned a link (MAC) address in the range of universally +administered addresses reserved for the FreeBSD Foundation by hashing +the host UUID, jail name, and the interface name. +If this fails, a random, locally administered address is generated instead. +This address is guaranteed to be unique +.Em only +across all +.Nm +interfaces on the local machine. +Thus you can theoretically have two bridges on different machines with +the same link addresses. +The address can be changed by assigning the desired link address using +.Xr ifconfig 8 . +.Pp +If +.Xr sysctl 8 +node +.Va net.link.bridge.inherit_mac +has a non-zero value, the newly created bridge will inherit the MAC +address from its first member instead of choosing a random link-level +address. +This will provide more predictable bridge MAC addresses without any +additional configuration, but currently this feature is known to break +some L2 protocols, for example PPPoE that is provided by +.Xr ng_pppoe 4 +and +.Xr ppp 8 . +Currently this feature is considered as experimental and is turned off +by default. +.Pp +A bridge can be used to provide several services, such as a simple +802.11-to-Ethernet bridge for wireless hosts, or traffic isolation. +.Pp +A bridge works like a switch, forwarding traffic from one interface +to another. +Multicast and broadcast packets are always forwarded to all +interfaces that are part of the bridge. +For unicast traffic, the bridge learns which MAC addresses are associated +with which interfaces and will forward the traffic selectively. +.Pp +By default the bridge logs MAC address port flapping to +.Xr syslog 3 . +This behavior can be disabled by setting the +.Xr sysctl 8 +variable +.Va net.link.bridge.log_mac_flap +to +.Li 0 . +.Pp +All the bridged member interfaces need to be up +in order to pass network traffic. +These can be enabled using +.Xr ifconfig 8 +or +.Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up" +in +.Xr rc.conf 5 . +.Pp +The MTU of the first member interface to be added is used as the bridge MTU. +All additional members will have their MTU changed to match. +If the MTU of a bridge is changed after its creation, the MTU of all member +interfaces is also changed to match. +.Pp +The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the +bridge are disabled if any of the interfaces do not support/enable them. +The LRO capability is always disabled. +All the capabilities are restored when the interface is removed from the bridge. +Changing capabilities at run-time may cause NIC reinit and a link flap. +.Pp +The bridge supports +.Dq monitor mode , +where the packets are discarded after +.Xr bpf 4 +processing, and are not processed or forwarded further. +This can be used to multiplex the input of two or more interfaces into a single +.Xr bpf 4 +stream. +This is useful for reconstructing the traffic for network taps +that transmit the RX/TX signals out through two separate interfaces. +.Pp +To allow the host to communicate with bridge members, IP addresses +should be assigned to the +.Nm +interface itself, not to the bridge's member interfaces. +Attempting to assign an IP address to a bridge member interface, or add +a member interface with an assigned IP address to a bridge, will return +an +.Dv EINVAL +.Dq ( "Invalid argument" ) +error. +For compatibility with older releases where this was permitted, setting +the +.Xr sysctl 8 +variable +.Va net.link.bridge.member_ifaddrs +to 1 will permit this configuration. +This sysctl variable will be removed in +.Fx 16.0. +.Sh IPV6 SUPPORT +.Nm +supports the +.Li AF_INET6 +address family on bridge interfaces. +The following +.Xr rc.conf 5 +variable configures an IPv6 link-local address on +.Li bridge0 +interface: +.Bd -literal -offset indent +ifconfig_bridge0_ipv6="inet6 auto_linklocal" +.Ed +.Pp +However, the +.Li AF_INET6 +address family has a concept of scope zone. +Bridging multiple interfaces changes the zone configuration because +multiple links are merged to each other and form a new single link +while the member interfaces still work individually. +This means each member interface still has a separate link-local scope +zone and the +.Nm +interface has another single, +aggregated link-local scope zone at the same time. +This situation is clearly against the description +.Qq zones of the same scope cannot overlap +in Section 5, +RFC 4007. +Although it works in most cases, +it can cause some counterintuitive or undesirable behavior in some +edge cases when both, the +.Nm +interface and one of the member interfaces, have an IPv6 address +and applications use both of them. +.Pp +To prevent this situation, +.Nm +checks whether a link-local scoped IPv6 address is configured on +a member interface to be added and the +.Nm +interface. +When the +.Nm +interface has IPv6 addresses, +IPv6 addresses on the member interface will be automatically removed +before the interface is added. +.Pp +This behavior can be disabled by setting +.Xr sysctl 8 +variable +.Va net.link.bridge.allow_llz_overlap +to +.Li 1 . +.Pp +Note that +.Li ACCEPT_RTADV +and +.Li AUTO_LINKLOCAL +interface flags are not enabled by default on +.Nm +interfaces even when +.Va net.inet6.ip6.accept_rtadv +and/or +.Va net.inet6.ip6.auto_linklocal +is set to +.Li 1 . +.Sh SPANNING TREE +The +.Nm +driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with +backwards compatibility with the legacy Spanning Tree Protocol (STP). +Spanning Tree is used to detect and remove loops in a network topology. +.Pp +RSTP provides faster spanning tree convergence than legacy STP, the protocol +will exchange information with neighbouring switches to quickly transition to +forwarding without creating loops. +.Pp +The code will default to RSTP mode but will downgrade any port connected to a +legacy STP network so is fully backward compatible. +A bridge can be forced to operate in STP mode without rapid state transitions +via the +.Va proto +command in +.Xr ifconfig 8 . +.Pp +The bridge can log STP port changes to +.Xr syslog 3 +by setting the +.Va net.link.bridge.log_stp +node using +.Xr sysctl 8 . +.Sh VLAN SUPPORT +Virtual LANs (VLANs), defined in the IEEE 802.1Q standard, allow traffic +on a bridge to be segregated into separate logical networks which cannot +communicate with each other. +For example, two interfaces in VLAN 10 would be able to communicate +with each other, but not with another interface in VLAN 20. +.Pp +Each VLAN is identified by a number between 1 and 4094 inclusive. +By default, all traffic on the bridge is assigned to "VLAN 0", +a pseudo-VLAN used for historical compatibility. +When VLANs are in use on a bridge, it is recommended to explicitly +assign all traffic to a VLAN rather than using VLAN 0. +.Pp +The bridge implements Independent VLAN Learning (IVL), meaning that +host addresses are learned separately for each VLAN, and the same host +address may exist on several different ports in different VLANs. +.Pp +If a +.Xr vlan 4 +interface is configured on an interface which is also an +.Nm +member interface, all tagged frames will be processed by the +.Xr vlan 4 +interface and will not be visible to the bridge. +This configuration is not recommended and may be unsupported in a +future release. +.Ss Tagged and untagged traffic +Incoming frames on a member interface may be either tagged or untagged. +Tagged frames contain an 802.1Q header indicating which VLAN the +frame belongs to, while untagged frames do not. +When a tagged frame is received, the frame is automatically assigned to +the VLAN in the tag (subject to any configured VLAN access list), +while untagged frames are assigned to the interface's configured +Port VLAN ID (PVID), or to VLAN 0 if no PVID is configured. +.Ss Assigning interfaces to VLANs +An interface's PVID may be configured using the +.Xr ifconfig 8 +.Cm ifuntagged +command: +.Bd -literal -offset indent +ifconfig bridge0 ifuntagged ix0 10 +.Ed +.Pp +Or by using the +.Cm untagged +option to +.Cm addm : +.Bd -literal -offset indent +ifconfig bridge0 addm ix0 untagged 10 +.Ed +.Pp +This will assign all untagged traffic received on the interface to the +specified VLAN, and any traffic transmitted on the interface in this +VLAN will have its VLAN tag (if present) removed. +Conversely, any traffic transmitted on the interface in a different +VLAN will have a tag added, to allow the remote system to assign the +traffic to the appropriate VLAN. +.Ss Host communication in a VLAN +Sometimes it is useful to allow the host itself to communicate in a VLAN, +for example to provide routing to other hosts in the VLAN. +To do this, create a +.Xr vlan 4 +interface on top of the +.Nm +interface with the appropriate VLAN tag. +For example, to allow the host to communicate in VLAN 10: +.Bd -literal -offset indent +ifconfig bridge0.10 create inet6 2001:db8::1/64 +.Ed +.Ss Configuring the VLAN access list (VLAN filtering) +For historical reasons, the default +.Nm +configuration allows all interfaces to send tagged traffic for any VLAN, +meaning that VLANs do not provide security separation. +To restrict which interfaces may communicate in which VLANs, +enable VLAN filtering on the bridge: +.Bd -literal -offset indent +ifconfig bridge0 vlanfilter +.Ed +.Pp +This has the following effects on bridge members: +.Bl -bullet -offset indent +.It +No untagged frames will be accepted from a member interface unless +the interface has a PVID configured. +.It +No tagged frames will be accepted from a member interface unless +the VLAN identifier is present in the interface's VLAN access list. +.It +Frames with stacked tags (Q-in-Q) will not be accepted from a +member interface unless the +.Cm qinq +option (see below) has been configured for that member. +.El +.Pp +To configure the VLAN access list, use the +.Xr ifconfig 8 +.Cm iftagged , +.Cm +iftagged +or +.Cm -iftagged +commands. +For example, to allow an interface to communicate in VLANs 10, 20, +and any VLAN from 100 to 199: +.Bd -literal -offset indent +ifconfig bridge0 iftagged ix0 10,20,100-199 +.Ed +.Ss IEEE 802.1ad (Q-in-Q) configuration +IEEE 802.1ad, also called Q-in-Q or +.Dq tag stacking , +allows a single Ethernet frame to contain multiple tags. +This allows one Ethernet network to transport traffic between endpoints +using its own VLAN tags without interfering with any pre-existing tags, +and is often used in service provider networks to provide +.Dq virtual wire +Ethernet services. +.Pp +When VLAN filtering is enabled, +.Nm +does not permit member interfaces to send Q-in-Q frames, because in +certain configuration this allows +.Dq VLAN-hopping +attacks on the bridge. +For example, consider a bridge with port ix0 configured as a tagged +port in VLAN 10, and port ix1 configured as untagged in VLAN 10 and +tagged in VLAN 20. +If ix0 is allowed to send Q-in-Q frames, then it can send a frame with +two tags: one for VLAN 10, followed by one for VLAN 20. +When the bridge forwards the frame to ix1, it will strip the VLAN tag +for VLAN 10, then forward the frame to ix1 with the tag for VLAN 20 +intact, effectively allowing ix1 to send traffic on VLAN 20 even +though the bridge configuration should not permit that. +.Pp +To permit an interface to send Q-in-Q frames, set the +.Xr ifconfig 8 +.Cm qinq +flag on the interface. +This is only required on the interface which will send Q-in-Q frames, +not the interface receiving the frames. +.Pp +Alternatively, set the +.Cm defqinq +flag on the bridge itself to enable Q-in-Q for all newly-added +interfaces by default. +.Sh PACKET FILTERING +Packet filtering can be used with any firewall package that hooks in via the +.Xr pfil 9 +framework. +When filtering is enabled, bridged packets will pass through the filter +inbound on the originating interface, on the bridge interface and outbound on +the appropriate interfaces. +Either stage can be disabled. +The filtering behavior can be controlled using +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va net.link.bridge.pfil_onlyip +Controls the handling of non-IP packets which are not passed to +.Xr pfil 9 . +Set to +.Li 1 +to only allow IP packets to pass (subject to firewall rules), set to +.Li 0 +to unconditionally pass all non-IP Ethernet frames. +.It Va net.link.bridge.pfil_member +Set to +.Li 1 +to enable filtering on the incoming and outgoing member interfaces, set +to +.Li 0 +to disable it. +.It Va net.link.bridge.pfil_bridge +Set to +.Li 1 +to enable filtering on the bridge interface, set +to +.Li 0 +to disable it. +.It Va net.link.bridge.pfil_local_phys +Set to +.Li 1 +to additionally filter on the physical interface for locally destined packets. +Set to +.Li 0 +to disable this feature. +.It Va net.link.bridge.ipfw +Set to +.Li 1 +to enable layer2 filtering with +.Xr ipfirewall 4 , +set to +.Li 0 +to disable it. +This needs to be enabled for +.Xr dummynet 4 +support. +When +.Va ipfw +is enabled, +.Va pfil_bridge +and +.Va pfil_member +will be disabled so that IPFW +is not run twice; these can be re-enabled if desired. +.It Va net.link.bridge.ipfw_arp +Set to +.Li 1 +to enable layer2 ARP filtering with +.Xr ipfirewall 4 , +set to +.Li 0 +to disable it. +Requires +.Va ipfw +to be enabled. +.El +.Pp +ARP and REVARP packets are forwarded without being filtered and others +that are not IP nor IPv6 packets are not forwarded when +.Va pfil_onlyip +is enabled. +IPFW can filter Ethernet types using +.Cm mac-type +so all packets are passed to +the filter for processing. +.Pp +The packets originating from the bridging host will be seen by +the filter on the interface that is looked up in the routing +table. +.Pp +The packets destined to the bridging host will be seen by the filter +on the interface with the MAC address equal to the packet's destination +MAC. +There are situations when some of the bridge members are sharing +the same MAC address (for example the +.Xr vlan 4 +interfaces: they are currently sharing the +MAC address of the parent physical interface). +It is not possible to distinguish between these interfaces using +their MAC address, excluding the case when the packet's destination +MAC address is equal to the MAC address of the interface on which +the packet was entered to the system. +In this case the filter will see the incoming packet on this +interface. +In all other cases the interface seen by the packet filter is chosen +from the list of bridge members with the same MAC address and the +result strongly depends on the member addition sequence and the +actual implementation of +.Nm . +It is not recommended to rely on the order chosen by the current +.Nm +implementation since it may change in the future. +.Pp +The previous paragraph is best illustrated with the following +pictures. +Let +.Bl -bullet +.It +the MAC address of the incoming packet's destination is +.Nm nn:nn:nn:nn:nn:nn , +.It +the interface on which packet entered the system is +.Nm ifX , +.It +.Nm ifX +MAC address is +.Nm xx:xx:xx:xx:xx:xx , +.It +there are possibly other bridge members with the same MAC address +.Nm xx:xx:xx:xx:xx:xx , +.It +the bridge has more than one interface that are sharing the +same MAC address +.Nm yy:yy:yy:yy:yy:yy ; +we will call them +.Nm vlanY1 , +.Nm vlanY2 , +etc. +.El +.Pp +If the MAC address +.Nm nn:nn:nn:nn:nn:nn +is equal to +.Nm xx:xx:xx:xx:xx:xx +the filter will see the packet on interface +.Nm ifX +no matter if there are any other bridge members carrying the same +MAC address. +But if the MAC address +.Nm nn:nn:nn:nn:nn:nn +is equal to +.Nm yy:yy:yy:yy:yy:yy +then the interface that will be seen by the filter is one of the +.Nm vlanYn . +It is not possible to predict the name of the actual interface +without the knowledge of the system state and the +.Nm +implementation details. +.Pp +This problem arises for any bridge members that are sharing the same +MAC address, not only to the +.Xr vlan 4 +ones: they were taken just as an example of such a situation. +So if one wants to filter the locally destined packets based on +their interface name, one should be aware of this implication. +The described situation will appear at least on the filtering bridges +that are doing IP-forwarding; in some of such cases it is better +to assign the IP address only to the +.Nm +interface and not to the bridge members. +Enabling +.Va net.link.bridge.pfil_local_phys +will let you do the additional filtering on the physical interface. +.Sh NETMAP +.Xr netmap 4 +applications may open a bridge interface in emulated mode. +The netmap application will receive all packets which arrive from member +interfaces. +In particular, packets which would otherwise be forwarded to another +member interface will be received by the netmap application. +.Pp +When the +.Xr netmap 4 +application transmits a packet to the host stack via the bridge interface, +.Nm +receive it and attempts to determine its +.Ql source +interface by looking up the source MAC address in the interface's learning +tables. +Packets for which no matching source interface is found are dropped and the +input error counter is incremented. +If a matching source interface is found, +.Nm +treats the packet as though it was received from the corresponding interface +and handles it normally without passing the packet back to +.Xr netmap 4 . +.Sh EXAMPLES +The following when placed in the file +.Pa /etc/rc.conf +will cause a bridge called +.Dq Li bridge0 +to be created, and will add the interfaces +.Dq Li wlan0 +and +.Dq Li fxp0 +to the bridge, and then enable packet forwarding. +Such a configuration could be used to implement a simple +802.11-to-Ethernet bridge (assuming the 802.11 interface is +in ad-hoc mode). +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="addm wlan0 addm fxp0 up" +.Ed +.Pp +For the bridge to forward packets, +all member interfaces and the bridge need to be up. +The above example would also require: +.Bd -literal -offset indent +create_args_wlan0="wlanmode hostap" +ifconfig_wlan0="up ssid my_ap mode 11g" +ifconfig_fxp0="up" +.Ed +.Pp +The following will cause a bridge to be created with two VLANs, +10 and 20, where the +.Dq Li em +interfaces can only communicate in their assigned VLANs, +while +.Dq Li ix0 +is a trunk port which can communicate in either VLAN: +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="vlanfilter \e + addm em0 untagged 10 \e + addm em1 untagged 10 \e + addm em2 untagged 20 \e + addm em3 untagged 20 \e + addm ix0 tagged 10,20" +ifconfig_em0="up" +ifconfig_em1="up" +ifconfig_em2="up" +ifconfig_em3="up" +ifconfig_ix0="up" +.Ed +.Pp +The previous example could be extended to allow the host to +communicate in VLANs 10 and 20: +.Bd -literal -offset indent +vlans_bridge0="10 20" +ifconfig_bridge0_10_ipv6="inet6 2001:db8:0:10::1/64" +ifconfig_bridge0_20_ipv6="inet6 2001:db8:0:20::1/64" +.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: +.Bd -literal -offset indent +ifconfig bridge0 create +ifconfig bridge0 \e + addm fxp0 stp fxp0 \e + addm fxp1 stp fxp1 \e + addm fxp2 stp fxp2 \e + addm fxp3 stp fxp3 \e + addm fxp4 stp fxp4 \e + addm fxp5 stp fxp5 \e + addm fxp6 stp fxp6 \e + addm fxp7 stp fxp7 \e + 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: +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="addm em0 addm em1 DHCP" +ifconfig_em0="up" +ifconfig_em1="up" +.Ed +.Pp +The bridge can tunnel Ethernet across an IP internet using the EtherIP +protocol. +This can be combined with +.Xr ipsec 4 +to provide an encrypted connection. +Create a +.Xr gif 4 +interface and set the local and remote IP addresses for the +tunnel, these are reversed on the remote bridge. +.Bd -literal -offset indent +ifconfig gif0 create +ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up +ifconfig bridge0 create +ifconfig bridge0 addm fxp0 addm gif0 up +.Ed +.Sh SEE ALSO +.Xr gif 4 , +.Xr ipf 4 , +.Xr ipfw 4 , +.Xr netmap 4 , +.Xr pf 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm bridge +driver was originally written by +.An Jason L. Wright Aq Mt jason@thought.net +as part of an undergraduate independent study at the University of +North Carolina at Greensboro. +.Pp +This version of the +.Nm +driver has been heavily modified from the original version by +.An Jason R. Thorpe Aq Mt thorpej@wasabisystems.com . +.Pp +Rapid Spanning Tree Protocol (RSTP) support was added by +.An Andrew Thompson Aq Mt thompsa@FreeBSD.org . +.Sh BUGS +The +.Nm +driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) +network devices, which can be configured with the same MTU size as the bridge +device. |