Fix xref order.
[dragonfly.git] / 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 .