path: root/sbin/brconfig/brconfig.8

.\"	$OpenBSD: brconfig.8,v 1.6 2000/02/11 04:22:27 jason Exp $
.\"
.\" Copyright (c) 1999, 2000 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 blocknonip interface-name
.Op Ar -blocknonip interface-name
.Op Ar discover interface-name
.Op Ar -discover interface-name
.Op Ar learn interface-name
.Op Ar -learn interface-name
.Op Ar rulefile file-name
.Op Ar flushrule interface-name
.Op Ar link0
.Op Ar link1
.Op Ar -link0
.Op Ar -link1
.Op Ar ...
.Nm brconfig
.Ar bridge-name rule {block|pass} {in|out|in/out} on
.Ar interface-name
.Op Ar src address
.Op Ar dst address
.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.
With the third synopsis, rules for filtering Ethernet MAC addresses can
be added to a 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 blocknonip interface
Mark an interface so that no packets that are not IPv4, IPv6, ARP, or Reverse
ARP are accepted from it or are forwarded to it from other bridge member
interfaces.
.It Ar -blocknonip interface
Allow non-IPv4, IPv6, ARP, or Reverse ARP packets through the
.Cm interface .
.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 flushrule interface
Remove all Ethernet MAC filtering rules from
.Cm interface
.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.
.It Ar rule [rulespec]
Add a filtering rule to an interface.
Rules have a similiar syntax to
.Xr ipf 4 .
Rules can be used to selectively block or pass frames based on Ethernet
MAC address.  Rules are processed in the order in which they were added
to the interface, and the first rule matched takes the action (block or pass)
of the rule.  If no source or destination address is specified, the
rule will match all frames (good for creating a catchall policy).
.It Ar rulefile filename
Load a set of rules from the file
.Cm filename .
.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 propagated 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.
.It Cm "brconfig bridge0 rule pass in on fxp0 8:0:1:2:3:4:5 dst 5:4:3:2:1:0"
.It Cm "brconfig bridge0 rule pass out on fxp0 src 5:4:3:2:1:0 dst 0:1:2:3:4:5"
.It Cm brconfig bridge0 rule block in on fxp0
.It Cm brconfig bridge0 rule block out on fxp0
The above commands will set up a filter so that 0:1:2:3:4:5 can send frames
through fxp0 only to 5:4:3:2:1, and 5:4:3:2:1:0 can return frames through
fxp0 to 0:1:2:3:4:5.  All other traffic trying to go into and be sent from
fxp0 will be blocked.
.El
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr bridgename.if 5 ,
.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
.An Jason L. Wright Aq 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 chipsets have serious flaws when running in promiscuous mode, like the
TI ThunderLAN (see
.Xr tl 4 ),
which receives its own transmissions (this renders the address learning
cache useless).  Most other chipsets work fine though.