sbin/brconfig/brconfig.8

   1 .\"     $NetBSD: brconfig.8,v 1.16 2007/01/07 08:53:04 isaki 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 January 7, 2007
  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
  52 The
  53 .Nm
  54 utility is used to configure network bridge parameters and retrieve
  55 network bridge parameters and status from the kernel.
  56 The bridging function is implemented by the
  57 .Xr bridge 4
  58 driver.
  59 .Pp
  60 A network bridge creates a logical link between two or more
  61 IEEE 802 networks that use the same (or
  62 .Dq similar enough )
  63 framing format.
  64 For example, it is possible to bridge Ethernet
  65 and 802.11 networks together, but it is not possible to bridge
  66 Ethernet and Token Ring together.
  67 .Pp
  68 Bridge interfaces are created using the
  69 .Xr ifconfig 8
  70 command's
  71 .Dq create
  72 sub-command.
  73 All other bridge configuration is performed using
  74 .Nm .
  75 .Pp
  76 The options are as follows:
  77 .Bl -tag -width indent
  78 .It Fl a
  79 Display the status of all bridge devices present on the system.
  80 This flag is mutually exclusive with all other sub-commands.
  81 .El
  82 .Pp
  83 All other operations require that a bridge be specified.
  84 If a bridge is specified with no sub-commands,
  85 the status of that bridge is displayed.
  86 The following sub-commands are available:
  87 .Pp
  88 .Bl -tag -width indent
  89 .It Cm up
  90 Start forwarding packets on the bridge.
  91 .It Cm down
  92 Stop forwarding packets on the bridge.
  93 .It Cm add Ar interface
  94 Add the interface named by
  95 .Ar interface
  96 as a member of the bridge.
  97 The interface is put into promiscuous mode
  98 so that it can receive every packet sent on the network.
  99 .It Cm delete Ar interface
 100 Remove the interface named by
 101 .Ar interface
 102 from the bridge.
 103 Promiscuous mode is disabled on the interface when
 104 it is removed from the bridge.
 105 .It Cm maxaddr Ar size
 106 Set the size of the bridge address cache to
 107 .Ar size .
 108 The default is 100 entries.
 109 .It Cm timeout Ar seconds
 110 Set the timeout of address cache entries to
 111 .Ar seconds
 112 seconds.
 113 If
 114 .Ar seconds
 115 is zero, then address cache entries will not be expired.
 116 The default is 1200 seconds.
 117 .It Cm deladdr Ar address
 118 Delete
 119 .Ar address
 120 from the address cache.
 121 .It Cm flush
 122 Delete all dynamically-learned addresses from the address cache.
 123 .It Cm flushall
 124 Delete all addresses, including static addresses, from the address cache.
 125 .It Cm discover Ar interface
 126 Mark an interface as a
 127 .Dq discovering
 128 interface.
 129 When the bridge has no address cache entry
 130 (either dynamic or static)
 131 for the destination address of a packet,
 132 the bridge will forward the packet to all
 133 member interfaces marked as
 134 .Dq discovering .
 135 This is the default for all interfaces added to a bridge.
 136 .It Cm -discover Ar interface
 137 Clear the
 138 .Dq discovering
 139 attribute on a member interface.
 140 For packets without the
 141 .Dq discovering
 142 attribute, the only packets forwarded on the interface are broadcast
 143 or multicast packets and packets for which the destination address
 144 is known to be on the interface's segment.
 145 .It Cm ipf
 146 Enable packet filtering with
 147 .Xr pfil 9
 148 on the bridge.
 149 The current implementation passes
 150 all ARP and RARP packets through the bridge
 151 while filtering IP and IPv6 packets through the configured packet
 152 filter, such as
 153 .Xr ipf 4
 154 or
 155 .Xr pf 4 .
 156 Other packet types are blocked.
 157 .It Cm learn Ar interface
 158 Mark an interface as a
 159 .Dq learning
 160 interface.
 161 When a packet arrives on such an interface, the source
 162 address of the packet is entered into the address cache as being a
 163 destination address on the interface's segment.
 164 This is the default for all interfaces added to a bridge.
 165 .It Cm -learn Ar interface
 166 Clear the
 167 .Dq learning
 168 attribute on a member interface.
 169 .It Cm stp Ar interface
 170 Enable Spanning Tree protocol on
 171 .Ar interface .
 172 The
 173 .Xr bridge 4
 174 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
 175 Spanning Tree is used to detect and remove loops in a network topology.
 176 .It Cm -stp Ar interface
 177 Disable Spanning Tree protocol on
 178 .Ar interface .
 179 This is the default for all interfaces added to a bridge.
 180 .It Cm maxage Ar seconds
 181 Set the time that a Spanning Tree protocol configuration is valid.
 182 The default is 20 seconds.
 183 The minimum is 1 second and the maximum is 255 seconds.
 184 .It Cm fwddelay Ar seconds
 185 Set the time that must pass before an interface begins forwarding
 186 packets when Spanning Tree is enabled.
 187 The default is 15 seconds.
 188 The minimum is 1 second and the maximum is 255 seconds.
 189 .It Cm hellotime Ar seconds
 190 Set the time between broadcasting of Spanning Tree protocol
 191 configuration messages.
 192 The default is 2 seconds.
 193 The minimum is 1 second and the maximum is 255 seconds.
 194 .It Cm priority Ar value
 195 Set the bridge priority for Spanning Tree.
 196 The default is 32768.
 197 Allowed numerical values range from 0 (highest priority) to 65535
 198 (lowest priority).
 199 .It Cm ifpriority Ar interface Ar value
 200 Set the Spanning Tree priority of
 201 .Ar interface
 202 to
 203 .Ar value .
 204 The default is 128.
 205 The minimum is 0 and the maximum is 255.
 206 .It Cm ifpathcost Ar interface Ar value
 207 Set the Spanning Tree path cost of
 208 .Ar interface
 209 to
 210 .Ar value .
 211 The default is 55.
 212 The minimum is 0 and the maximum is 65535.
 213 .El
 214 .Sh EXAMPLES
 215 The following, when placed in the file
 216 .Pa /etc/ifconfig.bridge0 ,
 217 will cause a bridge called
 218 .Sq bridge0
 219 to be created, add the interfaces
 220 .Sq ray0
 221 and
 222 .Sq fxp0
 223 to the bridge, and then enable packet forwarding.
 224 Such a configuration could be used to implement a simple
 225 802.11-to-Ethernet bridge (assuming the 802.11 interface is
 226 in ad-hoc mode).
 227 .Bd -literal -offset indent
 228 create
 229 !brconfig $int add ray0 add fxp0 up
 230 .Ed
 231 .Pp
 232 Consider a system with two 4-port Ethernet boards.
 233 The following placed in the file
 234 .Pa /etc/ifconfig.bridge0
 235 will cause a bridge consisting of all 8 ports with Spanning Tree
 236 enabled to be created:
 237 .Bd -literal -offset indent
 238 create
 239 !brconfig $int \e
 240     add tlp0 stp tlp0 \e
 241     add tlp1 stp tlp1 \e
 242     add tlp2 stp tlp2 \e
 243     add tlp3 stp tlp3 \e
 244     add tlp4 stp tlp4 \e
 245     add tlp5 stp tlp5 \e
 246     add tlp6 stp tlp6 \e
 247     add tlp7 stp tlp7 \e
 248     up
 249 .Ed
 250 .Sh SEE ALSO
 251 .Xr bridge 4 ,
 252 .Xr pf 4 ,
 253 .Xr ifconfig.if 5 ,
 254 .Xr ifconfig 8 ,
 255 .Xr ipf 8 ,
 256 .Xr pfil 9
 257 .Sh HISTORY
 258 The
 259 .Nm
 260 utility first appeared in
 261 .Nx 1.6 .
 262 .Sh AUTHORS
 263 The
 264 .Xr bridge 4
 265 driver and
 266 .Nm
 267 utility were originally written by
 268 .An Jason L. Wright
 269 .Aq jason@thought.net
 270 as part of an undergraduate independent study at the
 271 University of North Carolina at Greensboro.
 272 .Pp
 273 This version of the
 274 .Nm
 275 utility was written from scratch by
 276 .An Jason R. Thorpe
 277 .Aq thorpej@wasabisystems.com .