1.\" $NetBSD: brconfig.8,v 1.22 2024/09/03 10:42:58 uwe Exp $ 2.\" 3.\" Copyright 2001 Wasabi Systems, Inc. 4.\" All rights reserved. 5.\" 6.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed for the NetBSD Project by 19.\" Wasabi Systems, Inc. 20.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse 21.\" or promote products derived from this software without specific prior 22.\" written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC 28.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.Dd August 29, 2024 37.Dt BRCONFIG 8 38.Os 39.Sh NAME 40.Nm brconfig 41.Nd configure network bridge parameters 42.Sh SYNOPSIS 43.Nm 44.Fl a 45.Nm 46.Ar bridge 47.Nm 48.Ar bridge 49.Ar command 50.Op Ar args ... 51.Sh DESCRIPTION 52The 53.Nm 54utility is used to configure network bridge parameters and retrieve 55network bridge parameters and status from the kernel. 56The bridging function is implemented by the 57.Xr bridge 4 58driver. 59.Pp 60A network bridge creates a logical link between two or more 61IEEE 802 networks that use the same (or 62.Dq similar enough ) 63framing format. 64For example, it is possible to bridge Ethernet 65and 802.11 networks together, but it is not possible to bridge 66Ethernet and Token Ring together. 67.Pp 68Bridge interfaces are created using the 69.Xr ifconfig 8 70command's 71.Cm create 72sub-command. 73All other bridge configuration is performed using 74.Nm . 75.Pp 76The options are as follows: 77.Bl -tag -width Fl 78.It Fl a 79Display the status of all bridge devices present on the system. 80This flag is mutually exclusive with all other sub-commands. 81.El 82.Pp 83All other operations require that a bridge be specified. 84If a bridge is specified with no sub-commands, 85the status of that bridge is displayed. 86The following sub-commands are available: 87.Bl -tag -width Cm 88.It Cm up 89Start forwarding packets on the bridge. 90.It Cm down 91Stop forwarding packets on the bridge. 92.It Cm add Ar interface 93Add the interface named by 94.Ar interface 95as a member of the bridge. 96The interface is put into promiscuous mode 97so that it can receive every packet sent on the network. 98.It Cm delete Ar interface 99Remove the interface named by 100.Ar interface 101from the bridge. 102Promiscuous mode is disabled on the interface when 103it is removed from the bridge. 104.It Cm addr 105Display the addresses that have been learned by the bridge. 106.It Cm maxaddr Ar size 107Set the size of the bridge address cache to 108.Ar size . 109The default is 100 entries. 110.It Cm timeout Ar seconds 111Set the timeout of address cache entries to 112.Ar seconds 113seconds. 114If 115.Ar seconds 116is zero, then address cache entries will not be expired. 117The default is 1200 seconds. 118.It Cm deladdr Ar address 119Delete 120.Ar address 121from the address cache. 122.It Cm flush 123Delete all dynamically-learned addresses from the address cache. 124.It Cm flushall 125Delete all addresses, including static addresses, from the address cache. 126.It Cm discover Ar interface 127Mark an interface as a 128.Dq discovering 129interface. 130When the bridge has no address cache entry 131(either dynamic or static) 132for the destination address of a packet, 133the bridge will forward the packet to all 134member interfaces marked as 135.Dq discovering . 136This is the default for all interfaces added to a bridge. 137.It Cm -discover Ar interface 138Clear the 139.Dq discovering 140attribute on a member interface. 141For packets without the 142.Dq discovering 143attribute, the only packets forwarded on the interface are broadcast 144or multicast packets and packets for which the destination address 145is known to be on the interface's segment. 146.It Cm ipf 147Enable packet filtering with 148.Xr pfil 9 149on the bridge. 150The current implementation passes 151all ARP and RARP packets through the bridge 152while filtering IP and IPv6 packets through the configured packet 153filter, such as 154.Xr npf 7 . 155Other packet types are blocked. 156.It Cm learn Ar interface 157Mark an interface as a 158.Dq learning 159interface. 160When a packet arrives on such an interface, the source 161address of the packet is entered into the address cache as being a 162destination address on the interface's segment. 163This is the default for all interfaces added to a bridge. 164.It Cm -learn Ar interface 165Clear the 166.Dq learning 167attribute on a member interface. 168.It Cm protect Ar interface 169Mark an interface as a 170.Dq protected 171interface. 172When a packet arrives on a 173.Dq protected 174interface and is being forwarded to another 175.Dq protected 176interface, the packet will be discarded. 177.It Cm -protect Ar interface 178Clear the 179.Dq protected 180attribute on a member interface. 181.It Cm static Ar interface address 182Add a static entry into the address cache pointing to 183.Ar interface . 184Static entries are never aged out of the cache or replaced, even if the address 185is seen on a different interface. 186.It Cm stp Ar interface 187Enable Spanning Tree protocol on 188.Ar interface . 189The 190.Xr bridge 4 191driver has support for the IEEE 802.1D Spanning Tree protocol (STP). 192Spanning Tree is used to detect and remove loops in a network topology. 193.It Cm -stp Ar interface 194Disable Spanning Tree protocol on 195.Ar interface . 196This is the default for all interfaces added to a bridge. 197.It Cm maxage Ar seconds 198Set the time that a Spanning Tree protocol configuration is valid. 199The default is 20 seconds. 200The minimum is 1 second and the maximum is 255 seconds. 201.It Cm fwddelay Ar seconds 202Set the time that must pass before an interface begins forwarding 203packets when Spanning Tree is enabled. 204The default is 15 seconds. 205The minimum is 1 second and the maximum is 255 seconds. 206.It Cm hellotime Ar seconds 207Set the time between broadcasting of Spanning Tree protocol 208configuration messages. 209The default is 2 seconds. 210The minimum is 1 second and the maximum is 255 seconds. 211.It Cm priority Ar value 212Set the bridge priority for Spanning Tree. 213The default is 32768. 214Allowed numerical values range from 0 (highest priority) to 65535 215(lowest priority). 216.It Cm ifpriority Ar interface Ar value 217Set the Spanning Tree priority of 218.Ar interface 219to 220.Ar value . 221The default is 128. 222The minimum is 0 and the maximum is 255. 223.It Cm ifpathcost Ar interface Ar value 224Set the Spanning Tree path cost of 225.Ar interface 226to 227.Ar value . 228The default is 55. 229The minimum is 0 and the maximum is 65535. 230.El 231.Sh EXAMPLES 232The following, when placed in the file 233.Pa /etc/ifconfig.bridge0 , 234will cause a bridge called 235.Ql bridge0 236to be created, add the interfaces 237.Ql ray0 238and 239.Ql fxp0 240to the bridge, and then enable packet forwarding. 241Such a configuration could be used to implement a simple 242802.11-to-Ethernet bridge (assuming the 802.11 interface is 243in ad-hoc mode). 244.Bd -literal -offset indent 245create 246!brconfig $int add ray0 add fxp0 up 247.Ed 248.Pp 249Consider a system with two 4-port Ethernet boards. 250The following placed in the file 251.Pa /etc/ifconfig.bridge0 252will cause a bridge consisting of all 8 ports with Spanning Tree 253enabled to be created: 254.Bd -literal -offset indent 255create 256!brconfig $int \e 257 add tlp0 stp tlp0 \e 258 add tlp1 stp tlp1 \e 259 add tlp2 stp tlp2 \e 260 add tlp3 stp tlp3 \e 261 add tlp4 stp tlp4 \e 262 add tlp5 stp tlp5 \e 263 add tlp6 stp tlp6 \e 264 add tlp7 stp tlp7 \e 265 up 266.Ed 267.Sh SEE ALSO 268.Xr bridge 4 , 269.Xr pf 4 , 270.Xr ifconfig.if 5 , 271.Xr npf 7 , 272.Xr ifconfig 8 , 273.Xr pfil 9 274.Sh HISTORY 275The 276.Nm 277utility first appeared in 278.Nx 1.6 . 279.Sh AUTHORS 280.An -nosplit 281The 282.Xr bridge 4 283driver and 284.Nm 285utility were originally written by 286.An Jason L. Wright 287.Aq jason@thought.net 288as part of an undergraduate independent study at the 289University of North Carolina at Greensboro. 290.Pp 291This version of the 292.Nm 293utility was written from scratch by 294.An Jason R. Thorpe 295.Aq thorpej@wasabisystems.com . 296