Fix xref order.
[dragonfly.git] / sbin / brconfig / brconfig.8
CommitLineData
3f0e6cb5
SS
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 $
375d1659 35.\" $DragonFly: src/sbin/brconfig/Attic/brconfig.8,v 1.2 2006/03/21 04:24:28 swildner Exp $
3f0e6cb5
SS
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
53The
54.Nm
55utility is used to configure network bridge parameters and retrieve
56network bridge parameters and status from the kernel.
57The bridging function is implemented by the
58.Xr bridge 4
59driver.
60.Pp
61A network bridge creates a logical link between two or more
62IEEE 802 networks that use the same (or
63.Dq similar enough )
64framing format.
65For example, it is possible to bridge Ethernet
66and 802.11 networks together, but it is not possible to bridge
67Ethernet and Token Ring together.
68.Pp
69Bridge interfaces are created using the
70.Xr ifconfig 8
71command's
72.Dq create
73sub-command.
74All other bridge configuration is performed using
75.Nm .
76.Pp
77The options are as follows:
78.Bl -tag -width indent
79.It Fl a
80Display the status of all bridge devices present on the system.
81This flag is mutually exclusive with all other sub-commands.
82.El
83.Pp
84All other operations require that a bridge be specified.
85If a bridge is specified with no sub-commands,
86the status of that bridge is displayed.
87The following sub-commands are available:
88.Pp
89.Bl -tag -width indent
90.It Cm up
91Start forwarding packets on the bridge.
92.It Cm down
93Stop forwarding packets on the bridge.
94.It Cm add Ar interface
95Add the interface named by
96.Ar interface
97as a member of the bridge.
98The interface is put into promiscuous mode
99so that it can receive every packet sent on the network.
100.It Cm delete Ar interface
101Remove the interface named by
102.Ar interface
103from the bridge.
104Promiscuous mode is disabled on the interface when
105it is removed from 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 240 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 learn Ar interface
147Mark an interface as a
148.Dq learning
149interface.
150When a packet arrives on such an interface, the source
151address of the packet is entered into the address cache as being a
152destination address on the interface's segment.
153This is the default for all interfaces added to a bridge.
154.It Cm -learn Ar interface
155Clear the
156.Dq learning
157attribute on a member interface.
158.It Cm stp Ar interface
159Enable Spanning Tree protocol on
160.Ar interface .
161The
162.Xr bridge 4
163driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
164Spanning Tree is used to detect and remove loops in a network topology.
165.It Cm -stp Ar interface
166Disable Spanning Tree protocol on
167.Ar interface .
168This is the default for all interfaces added to a bridge.
169.It Cm maxage Ar seconds
170Set the time that a Spanning Tree protocol configuration is valid.
171The default is 20 seconds.
172The minimum is 1 second and the maximum is 255 seconds.
173.It Cm fwddelay Ar seconds
174Set the time that must pass before an interface begins forwarding
175packets when Spanning Tree is enabled.
176The default is 15 seconds.
177The minimum is 1 second and the maximum is 255 seconds.
178.It Cm hellotime Ar seconds
179Set the time between broadcasting of Spanning Tree protocol
180configuration messages.
181The default is 2 seconds.
182The minimum is 1 second and the maximum is 255 seconds.
183.It Cm priority Ar value
184Set the bridge priority for Spanning Tree.
185The default is 32768.
186The minimum is 0 and the maximum is 65536.
187.It Cm ifpriority Ar interface Ar value
188Set the Spanning Tree priority of
189.Ar interface
190to
191.Ar value .
192The default is 128.
193The minimum is 0 and the maximum is 255.
194.It Cm ifpathcost Ar interface Ar value
195Set the Spanning Tree path cost of
196.Ar interface
197to
198.Ar value .
199The default is 55.
200The minimum is 0 and the maximum is 65535.
201.El
202.Sh EXAMPLES
203The following then placed in the file
204.Pa /etc/ifconfig.bridge0
205will cause the a bridge called
206.Sq bridge0
207to be created, and will add the interfaces
208.Sq ray0
209and
210.Sq fxp0
211to the bridge, and then enable packet forwarding.
212Such a configuration could be used to implement a simple
213802.11-to-Ethernet bridge (assuming the 802.11 interface is
214in ad-hoc mode).
215.Bd -literal -offset indent
216create
217!brconfig $int add ray0 add fxp0 up
218.Ed
219.Pp
220Consider a system with two 4-port Ethernet boards.
221The following placed in the file
222.Pa /etc/ifconfig.bridge0
223will cause a bridge consisting of all 8 ports with Spanning Tree
224enabled to be created:
225.Bd -literal -offset indent
226create
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 ,
375d1659
SW
240.Xr pf 4 ,
241.Xr ifconfig 8
3f0e6cb5
SS
242.Sh HISTORY
243The
244.Nm
245utility first appeared in
246.Nx 1.6 .
247.Sh AUTHORS
248The
249.Xr bridge 4
250driver and
251.Nm
252utility were originally written by
253.An Jason L. Wright
254.Aq jason@thought.net
255as part of an undergraduate independent study at the
256University of North Carolina at Greensboro.
257.Pp
258This version of the
259.Nm
260utility was written from scratch by
261.An Jason R. Thorpe
262.Aq thorpej@wasabisystems.com .