path: root/sbin/brconfig/brconfig.8

.\"	$OpenBSD: brconfig.8,v 1.1 1999/09/01 03:28:01 deraadt Exp $
.\"
.\" Copyright (c) 1999 Jason L. Wright (jason@thought.net)
.\" All rights reserved.
.\"
.\" 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 by Jason L. Wright
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 THE AUTHOR 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 February 26, 1999
.Dt BRCONFIG 8
.Os
.Sh NAME
.Nm brconfig
.Nd manipulate bridge interfaces
.Sh SYNOPSIS
.Nm brconfig
.Ar -a
.Nm brconfig
.Ar bridge-name
.Op Ar up
.Op Ar down
.Op Ar addr
.Op Ar add interface-name
.Op Ar delete interface-name
.Op Ar maxaddr size
.Op Ar timeout time
.Op Ar static interface-name address
.Op Ar deladdr address
.Op Ar flush
.Op Ar flushall
.Op Ar discover interface-name
.Op Ar -discover interface-name
.Op Ar learn interface-name
.Op Ar -learn interface-name
.Op Ar link0
.Op Ar link1
.Op Ar -link0
.Op Ar -link1
.Op Ar ...
.Sh DESCRIPTION
The
.Nm brconfig
utility retrieves kernel state of bridge interfaces and allows
user control of these bridges.  In the first synopsis, the command
will list the status of all bridges in the system.
In the second, its command line consists
of the name of a bridge and a set of operations to be
performed on that bridge.  The commands are executed in
the order they were specified.  If no command is specified in
the second synopsis, the
.Nm brconfig
will display status information about the bridge.
.Pp
The available commands are:
.Bl -tag -width Ds
.It Ar up
Start the bridge forwarding packets.
.It Ar down
Stop the bridge from forwarding packets.
.It Ar addr
Display the addresses that have been learned by the bridge.
.It Ar add interface-name
Add the interface named by
.Ar interface-name
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 Ar delete interface-name
Remove the interface named by
.Ar interface-name
from the bridge.
Promiscuous mode is turned off for the interface when it is
removed from the bridge.
.It Ar del
Alias for `delete'.
.It Ar maxaddr size
Set the address cache size to
.Cm size .
The default is 100 entries.
.It Ar timeout time
Set the timeout, in seconds, for addresses in the cache to
.Cm time .
The default is 240 seconds.
If
.Cm time
is set to zero, then entries will not be expired.
.It Ar static interface-name address
Add a static entry into the address cache pointing to
.Cm interface-name .
Static entries are never aged out of the cache or replaced if the address
is seen on a different interface.
.It Ar deladdr address
Delete an address from the cache.
.It Ar flush
Remove all dynamically learned addresses from the cache.
.It Ar flushall
Remove all addresses from the cache including static addresses.
.It Ar discover interface
Mark an interface so that packets are sent out of the interface
if the destination port of the packet is unknown.
If the bridge has no address cache entry for the destination of
a packet, meaning that there is no static entry and no dynamically learned
entry for the destination, the bridge will forward the packet to all member
interfaces that have this flag set.
This is the default for interfaces added to the bridge.
.It Ar -discover interface
Mark an interface so that packets are not sent out of the interface
if the destination port of the packet is unknown.  Turning this flag
off means that the bridge will not send packets out of this interface
unless the packet is a broadcast packet, multicast packet, or a
packet with a destination address found on the interface's segment.
This, in combination with static address cache entries,
prevents potentially sensitive packets from being sent on
segments that have no need to see the packet.
.It Ar learn interface
Mark an interface so that the source address of packets received from
.Cm interface
are entered into the address cache.
This is the default for interfaces added to the bridge.
.It Ar -learn interface
Mark an interface so that the source address of packets received from
.Cm interface
are not entered into the address cache.
.It Ar link0
Setting this flag stops all non-IP multicast packets from
being forwarded by the bridge.
.It Ar -link0
Clear the
.Ar link0
flag on the bridge interface.
.It Ar link1
Setting this flags stops all IP multicast packets from
being forwarded by the bridge.
.It Ar -link0
Clear the
.Ar link1
flag on the bridge interface.
.El
.Sh EXAMPLES
.Bl -tag -width brconfig
.It Cm brconfig bridge0 add rl0 add xl0 up
Add the Ethernet interfaces rl0 and xl0 to the bridge bridge0, and
start the bridge forwarding packets.
.It Cm brconfig bridge0
Retrieve a list of interfaces that are members of bridge0, and the addresses
learned by the bridge.
.It Cm brconfig bridge0 down
Stop bridge0 from forwarding packets.
.It Cm brconfig bridge0 delete xl0
Remove the interface xl0 from the bridge bridge0.
.It Cm brconfig bridge0 flush
Flush all dynamically learned addresses from the address cache.
.It Cm brconfig bridge0 flushall
Remove all addresses, including static addresses, from the address cache.
.It Cm brconfig bridge0 -learn xl0 static xl0 8:0:20:1e:2f:2b
.It Cm brconfig bridge0 -discover xl0
The examples above mark the xl0 interface so that it will not learn
addresses and adds a static entry for the host 8:0:20:1e:2f:2b on the xl0
segment.
Finally, xl0 is marked so that it will not receive packets with
destinations not found in the address cache of bridge0.
This setup is the most secure,
and means that bogus MAC addresses seen by the xl0 side of the bridge
will not be propogated to the rest of the network.
Also, no packets will be sent on xl0 segment by the bridge unless they are
broadcast packets or are for 8:0:20:1e:2f:2b.
.El
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr ifconfig 8
.Sh HISTORY
.Nm brconfig
first appeared in
.Ox 2.5 .
.Sh AUTHOR
The
.Xr brconfig 8
command and the
.Xr bridge 4
kernel interface were written by Jason L. Wright <jason@thought.net> as
part of an undergraduate independent study
at the University of North Carolina at Greensboro.
.Sh BUGS
There are some rather special network interface chipsets which will
not work in a bridge configuration.  Some, like the Lite-On PNIC (see
.Xr pn 4 ),
have serious flaws when running in promiscuous mode, and others, like the
TI ThunderLAN (see
.Xr tl 4 ),
receive their own transmissions, which makes the address learning code
ineffective.  Most other chipsets work fine though.