Date: Thu, 25 Jun 2009 17:24:36 +0000 (UTC) From: Andrew Thompson <thompsa@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r194980 - head/share/man/man4 Message-ID: <200906251724.n5PHOa2Q058415@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: thompsa Date: Thu Jun 25 17:24:36 2009 New Revision: 194980 URL: http://svn.freebsd.org/changeset/base/194980 Log: Rename man4/if_bridge.4 to man4/bridge.4 in order to be consistent with other peueso interfaces. The .Nm name hasnt been changed and all xrefs are still valid. Added: head/share/man/man4/bridge.4 - copied unchanged from r194929, head/share/man/man4/if_bridge.4 Deleted: head/share/man/man4/if_bridge.4 Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Thu Jun 25 17:21:12 2009 (r194979) +++ head/share/man/man4/Makefile Thu Jun 25 17:24:36 2009 (r194980) @@ -53,6 +53,7 @@ MAN= aac.4 \ bktr.4 \ blackhole.4 \ bpf.4 \ + bridge.4 \ bt.4 \ bwi.4 \ cardbus.4 \ @@ -130,7 +131,6 @@ MAN= aac.4 \ ida.4 \ idt.4 \ ieee80211.4 \ - if_bridge.4 \ ifmib.4 \ igb.4 \ igmp.4 \ @@ -474,6 +474,7 @@ MLINKS+=bce.4 if_bce.4 MLINKS+=bfe.4 if_bfe.4 MLINKS+=bge.4 if_bge.4 MLINKS+=bktr.4 brooktree.4 +MLINKS+=bridge.4 if_bridge.4 MLINKS+=bwi.4 if_bwi.4 MLINKS+=cas.4 if_cas.4 MLINKS+=crypto.4 cryptodev.4 @@ -506,7 +507,6 @@ MLINKS+=hatm.4 if_hatm.4 MLINKS+=hme.4 if_hme.4 MLINKS+=${_hptrr.4} ${_rr232x.4} MLINKS+=idt.4 if_idt.4 -MLINKS+=if_bridge.4 bridge.4 MLINKS+=igb.4 if_igb.4 MLINKS+=ip.4 rawip.4 MLINKS+=ipfirewall.4 ipaccounting.4 \ Copied: head/share/man/man4/bridge.4 (from r194929, head/share/man/man4/if_bridge.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/bridge.4 Thu Jun 25 17:24:36 2009 (r194980, copy of r194929, head/share/man/man4/if_bridge.4) @@ -0,0 +1,449 @@ +.\" $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. +.\" +.\" $FreeBSD$ +.\" +.Dd June 8, 2009 +.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 +The +.Nm +interface randomly chooses a link (MAC) address in the range reserved for +locally administered addresses when it is created. +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 the 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 non-zero value, newly created bridge will inherit MAC address +from its first member instead of choosing random link-level address. +This will provide more predictable bridge MAC 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 . +Now 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, and traffic isolation. +.Pp +A bridge works like a hub, 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 +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 are required to have exactly the same value. +.Pp +The TXCSUM capability is disabled for any interface added to the bridge, and it +is restored when the interface is removed again. +.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. +.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 enabling the +.Va net.link.bridge.log_stp +variable using +.Xr sysctl 8 . +.Pp +.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 behaviour can be controlled using +.Xr sysctl 8 : +.Bl -tag -width ".Va net.link.bridge.pfil_onlyip" +.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 currenly 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: it can be changed 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 +Then if the MAC address +.Nm nn:nn:nn:nn:nn:nn +is equal to the +.Nm xx:xx:xx:xx:xx:xx +then the filter will see the packet on the 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 the +.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 we taken just as the example of such situation. +So if one wants the 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 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 +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 +.Pp +Note that +.Fx +6.1, 6.2, 6.3, 7.0, 7.1, and 7.2 have a bug in the EtherIP protocol. +For more details and workaround, see +.Xr gif 4 manual page. +.Sh SEE ALSO +.Xr gif 4 , +.Xr ipf 4 , +.Xr ipfw 4 , +.Xr pf 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 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 thorpej@wasabisystems.com . +.Pp +Rapid Spanning Tree Protocol (RSTP) support was added by +.An Andrew Thompson +.Aq thompsa@FreeBSD.org . +.Sh BUGS +The +.Nm +driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) +network devices, with exactly the same interface MTU size as the bridge device.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200906251724.n5PHOa2Q058415>