 @@ -1,282 +1,281 @@
-.\"	$NetBSD: brconfig.8,v 1.19 2020/07/19 14:39:42 maxv Exp $
+.\"	$NetBSD: brconfig.8,v 1.20 2020/07/19 14:43:35 wiz 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 July 19, 2020
 .Dt BRCONFIG 8
 .Os
 .Sh NAME
 .Nm brconfig
 .Nd configure network bridge parameters
 .Sh SYNOPSIS
 .Nm
 .Fl a
 .Nm
 .Ar bridge
 .Nm
 .Ar bridge
 .Ar command
 .Op Ar args ...
 .Sh DESCRIPTION
 The
 .Nm
 utility is used to configure network bridge parameters and retrieve
 network bridge parameters and status from the kernel.
 The bridging function is implemented by the
 .Xr bridge 4
 driver.
 .Pp
 A network bridge 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
 Bridge interfaces are created using the
 .Xr ifconfig 8
 command's
 .Dq create
 sub-command.
 All other bridge configuration is performed using
 .Nm .
 .Pp
 The options are as follows:
 .Bl -tag -width indent
 .It Fl a
 Display the status of all bridge devices present on the system.
 This flag is mutually exclusive with all other sub-commands.
 .El
 .Pp
 All other operations require that a bridge be specified.
 If a bridge is specified with no sub-commands,
 the status of that bridge is displayed.
 The following sub-commands are available:
 .Pp
 .Bl -tag -width indent
 .It Cm up
 Start forwarding packets on the bridge.
 .It Cm down
 Stop forwarding packets on the bridge.
 .It Cm add Ar interface
 Add the interface named by
 .Ar interface
 as a member of the bridge.
 The interface is put into promiscuous mode
 so that it can receive every packet sent on the network.
 .It Cm delete Ar interface
 Remove the interface named by
 .Ar interface
 from the bridge.
 Promiscuous mode is disabled on the interface when
 it is removed from the bridge.
 .It Cm addr
 Display the addresses that have been learned by the bridge.
 .It Cm maxaddr Ar size
 Set the size of the bridge address cache to
 .Ar size .
 The default is 100 entries.
 .It Cm timeout Ar seconds
 Set the timeout of address cache entries to
 .Ar seconds
 seconds.
 If
 .Ar seconds
 is zero, then address cache entries will not be expired.
 The default is 1200 seconds.
 .It Cm deladdr Ar address
 Delete
 .Ar address
 from the address cache.
 .It Cm flush
 Delete all dynamically-learned addresses from the address cache.
 .It Cm flushall
 Delete all addresses, including static addresses, from the address cache.
 .It Cm discover Ar interface
 Mark an interface as a
 .Dq discovering
 interface.
 When the bridge has no address cache entry
 (either dynamic or static)
 for the destination address of a packet,
 the bridge will forward the packet to all
 member interfaces marked as
 .Dq discovering .
 This is the default for all interfaces added to a bridge.
 .It Cm -discover Ar interface
 Clear the
 .Dq discovering
 attribute on a member interface.
 For packets without the
 .Dq discovering
 attribute, the only packets forwarded on the interface are broadcast
 or multicast packets and packets for which the destination address
 is known to be on the interface's segment.
 .It Cm ipf
 Enable packet filtering with
 .Xr pfil 9
 on the bridge.
 The current implementation passes
 all ARP and RARP packets through the bridge
 while filtering IP and IPv6 packets through the configured packet
 filter, such as
 .Xr npf 7 .
 Other packet types are blocked.
 .It Cm learn Ar interface
 Mark an interface as a
 .Dq learning
 interface.
 When a packet arrives on such an interface, the source
 address of the packet is entered into the address cache as being a
 destination address on the interface's segment.
 This is the default for all interfaces added to a bridge.
 .It Cm -learn Ar interface
 Clear the
 .Dq learning
 attribute on a member interface.
 .It Cm static Ar interface address
 Add a static entry into the address cache pointing to
 .Ar interface .
 Static entries are never aged out of the cache or replaced, even if the address
 is seen on a different interface.
 .It Cm stp Ar interface
 Enable Spanning Tree protocol on
 .Ar interface .
 The
 .Xr bridge 4
 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
 Spanning Tree is used to detect and remove loops in a network topology.
 .It Cm -stp Ar interface
 Disable Spanning Tree protocol on
 .Ar interface .
 This is the default for all interfaces added to a bridge.
 .It Cm maxage Ar seconds
 Set the time that a Spanning Tree protocol configuration is valid.
 The default is 20 seconds.
 The minimum is 1 second and the maximum is 255 seconds.
 .It Cm fwddelay Ar seconds
 Set the time that must pass before an interface begins forwarding
 packets when Spanning Tree is enabled.
 The default is 15 seconds.
 The minimum is 1 second and the maximum is 255 seconds.
 .It Cm hellotime Ar seconds
 Set the time between broadcasting of Spanning Tree protocol
 configuration messages.
 The default is 2 seconds.
 The minimum is 1 second and the maximum is 255 seconds.
 .It Cm priority Ar value
 Set the bridge priority for Spanning Tree.
 The default is 32768.
 Allowed numerical values range from 0 (highest priority) to 65535
 (lowest priority).
 .It Cm ifpriority Ar interface Ar value
 Set the Spanning Tree priority of
 .Ar interface
 to
 .Ar value .
 The default is 128.
 The minimum is 0 and the maximum is 255.
 .It Cm ifpathcost Ar interface Ar value
 Set the Spanning Tree path cost of
 .Ar interface
 to
 .Ar value .
 The default is 55.
 The minimum is 0 and the maximum is 65535.
 .El
 .Sh EXAMPLES
 The following, when placed in the file
 .Pa /etc/ifconfig.bridge0 ,
 will cause a bridge called
 .Sq bridge0
 to be created, add the interfaces
 .Sq ray0
 and
 .Sq fxp0
 to the bridge, and then enable packet forwarding.
 Such a configuration could be used to implement a simple
 .11-to-Ethernet bridge (assuming the 802.11 interface is
 in ad-hoc mode).
 .Bd -literal -offset indent
 create
 !brconfig $int add ray0 add fxp0 up
 .Ed
 .Pp
 Consider a system with two 4-port Ethernet boards.
 The following placed in the file
 .Pa /etc/ifconfig.bridge0
 will cause a bridge consisting of all 8 ports with Spanning Tree
 enabled to be created:
 .Bd -literal -offset indent
 create
 !brconfig $int \e
     add tlp0 stp tlp0 \e
     add tlp1 stp tlp1 \e
     add tlp2 stp tlp2 \e
     add tlp3 stp tlp3 \e
     add tlp4 stp tlp4 \e
     add tlp5 stp tlp5 \e
     add tlp6 stp tlp6 \e
     add tlp7 stp tlp7 \e
     up
 .Ed
 .Sh SEE ALSO
 .Xr bridge 4 ,
 .Xr pf 4 ,
 .Xr ifconfig.if 5 ,
 .Xr ifconfig 8 ,
 .Xr npf 7 ,
 .Xr ifconfig 8 ,
 .Xr pfil 9
 .Sh HISTORY
 The
 .Nm
 utility first appeared in
 .Nx 1.6 .
 .Sh AUTHORS
 The
 .Xr bridge 4
 driver and
 .Nm
 utility were 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
 utility was written from scratch by
 .An Jason R. Thorpe
 .Aq thorpej@wasabisystems.com .