sbin/brconfig/brconfig.8

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