.\"	$OpenBSD: brconfig.8,v 1.42 2003/05/10 20:56:36 jmc Exp $
.\"
.\" Copyright (c) 1999-2001 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
.Fl a
.Nm brconfig
.Ar bridge-name
.Op Ar parameters
.Nm brconfig
.Ar bridge-name Cm rule No {
.Ar block | pass No } {
.Ar in | out | in/out No } 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.
Bridge devices create a logical link between two or more Ethernet interfaces
or encapsulation interfaces (see
.Xr gif 4 ) ,
which will selectively forward frames from each interface on the bridge
to every other interface on the bridge.
This can be used to isolate traffic between sets of machines on the same
segment and to provide a transparent filter for
.Xr ip 4
datagrams.
.Pp
In the first synopsis, the
.Fl a
flag will cause
.Nm
to 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 following parameters may be set with
.Nm brconfig :
.Bl -tag -width Ds
.It Cm up
Start the bridge forwarding packets.
.It Cm down
Stop the bridge from forwarding packets.
.It Cm addr
Display the addresses that have been learned by the bridge.
.It Cm add Ar 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.
An interface can be a member of at most one bridge.
.It Cm delete Ar 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 Cm del
Alias for
.Cm delete .
.It Cm addspan Ar interface-name
Add the interface named by
.Ar interface-name
as a span port on the bridge.
See the SPAN PORTS section for more details.
.It Cm delspan Ar interface-name
Delete the interface named by
.Ar interface-name
from the list of span ports of the bridge.
.It Cm maxaddr Ar size
Set the address cache size to
.Ar size .
The default is 100 entries.
.It Cm timeout Ar time
Set the timeout, in seconds, for addresses in the cache to
.Ar time .
The default is 240 seconds.
If
.Ar time
is set to zero, then entries will not be expired.
.It Cm static Ar interface-name address
Add a static entry into the address cache pointing to
.Ar interface-name .
Static entries are never aged out of the cache or replaced if the address
is seen on a different interface.
.It Cm deladdr Ar address
Delete an address from the cache.
.It Cm flush
Remove all dynamically learned addresses from the cache.
.It Cm flushall
Remove all addresses from the cache including static addresses.
.It Cm blocknonip Ar interface
Mark an interface so that no non-IPv4, IPv6, ARP, or Reverse
ARP packets are accepted from it or forwarded to it from other
bridge member interfaces.
.It Cm -blocknonip Ar interface
Allow non-IPv4, IPv6, ARP, or Reverse ARP packets through the
.Ar interface .
.It Cm discover Ar 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 Cm -discover Ar 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 Cm learn Ar interface
Mark an interface so that the source address of packets received from
.Ar interface
are entered into the address cache.
This is the default for interfaces added to the bridge.
.It Cm -learn Ar interface
Mark an interface so that the source address of packets received from
.Ar interface
are not entered into the address cache.
.It Cm flushrule Ar interface
Remove all Ethernet MAC filtering rules from
.Ar interface .
.It Cm link0
Setting this flag stops all non-IP multicast packets from
being forwarded by the bridge.
.It Cm -link0
Clear the
.Cm link0
flag on the bridge interface.
.It Cm link1
Setting this flags stops all IP multicast packets from
being forwarded by the bridge.
.It Cm -link1
Clear the
.Cm link1
flag on the bridge interface.
.It Cm link2
Setting this flag causes all packets to be passed on to
.Xr ipsec 4
for processing, based on the policies established by the administrator
using the
.Xr ipsecadm 8
command.
If appropriate security associations (SAs) exist, they will be used to
encrypt or decrypt the packets.
Otherwise, any key management daemons such as
.Xr isakmpd 8
that are running on the bridge will be invoked to establish the
necessary SAs.
These daemons have to be configured as if they were running on the
host whose traffic they are protecting (i.e., they need to have the
appropriate authentication and authorization material, such as keys
and certificates, to impersonate the protected host(s).
.It Cm -link2
Clear the
.Cm link2
flag on the bridge interface.
.It Cm rule Op Ar rulespec
Add a filtering rule to an interface.
Rules have a similar syntax to
.Xr pf 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 Cm rulefile Ar filename
Load a set of rules from the file
.Ar filename .
.It Cm stp Ar interface
Enable spanning tree protocol on
.Ar interface .
.It Cm -stp Ar interface
Disable spanning tree protocol on
.Ar interface .
.It Cm maxage Ar time
Set the time (in seconds) that a spanning tree protocol configuration is valid.
Defaults to 20 seconds, minimum of 1, maximum of 255.
.It Cm fwddelay Ar time
Set the time (in seconds) before an interface begins forwarding packets.
Defaults to 15 seconds, minimum of 1, maximum of 255.
.It Cm hellotime Ar time
Set the time (in seconds) between broadcasting spanning tree protocol
configuration packets.
Defaults to 2 seconds, minimum of 1, maximum of 255.
.It Cm priority Ar num
Set the spanning priority of this bridge to
.Ar num .
Defaults to 32768, minimum of 0, maximum of 65535.
.It Cm ifpriority Ar interface Ar num
Set the spanning tree priority of
.Ar interface
to
.Ar num .
Defaults to 128, minimum of 0, maximum of 255.
.It Cm ifcost Ar interface Ar num
Set the spanning tree path cost of
.Ar interface
to
.Ar num .
Defaults to 55, minimum of 1, maximum of 65535.
.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 src 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 "IPSEC BRIDGE"
The bridge can also be used to tunnel ethernet frames over IPv4 or
IPv6 by using the
.Xr gif 4
interface.
In addition to adding Ethernet interfaces,
one or more
.Xr gif 4 ,
interfaces are added as members of the bridge.
Ethernet frames sent
through the
.Xr gif 4
interfaces are encapsulated inside
.Xr ip 4
datagrams and sent across the network to another bridge, which
decapsulates the datagram and then processes the resulting Ethernet
frame as if it had originated on a normal Ethernet interface.
This effectively allows a layer-2 network to be extended from one point to
another, possibly through the Internet.
This mechanism may be used in
conjunction with IPsec, by specifying the appropriate IPsec flows
between the two bridges.
To only protect the bridge traffic between
the two bridges, the transport protocol 97 (etherip) selector may be
used in
.Xr ipsecadm 8
or
.Xr isakmpd 8 .
Otherwise, the ethernet frames will be sent in the clear between the
two bridges.
.Pp
For example, given two physically separate Ethernet networks, the bridge can
be used as follows to make them appear as the same local area network.
If bridge1 on network1 has the external IP address 1.2.3.4 on fxp0,
bridge2 on network2 has the external IP address 4.3.2.1 on fxp0, and
both bridges have fxp1 on their internal network (network1 and network2,
respectively), the following configuration can be used to bridge
network1 and network2.
.Pp
Add the encapsulation interface and internal ethernet interface to bridge
interface:
.Bd -literal
# brconfig bridge0 add gif0 add fxp1
.Ed
.Pp
Configure the gif0 interface:
.Bd -literal
(on bridge 1) # ifconfig gif0 giftunnel 1.2.3.4 4.3.2.1
(on bridge 2) # ifconfig gif0 giftunnel 4.3.2.1 1.2.3.4
.Ed
.Pp
Create Security Associations (SAs) between the external IP address of each
bridge:
.Bd -literal
# ipsecadm new esp -spi 4242 -dst 4.3.2.1 -src 1.2.3.4 \\
	-enc 3des -auth md5 -keyfile keyfile1 -authkeyfile authkeyfile1
.Ed
.Pp
.Bd -literal
# ipsecadm new esp -spi 4243 -dst 1.2.3.4 -src 4.3.2.1 \\
	-enc 3des -auth md5 -keyfile keyfile2 -authkeyfile authkeyfile2
.Ed
.Pp
Set up ingress flows so that traffic is allowed between the two bridges
for the above associations:
.Bd -literal
(on bridge1) # ipsecadm flow -dst 4.3.2.1 -out \\
	-transport etherip -require \\
	-addr 1.2.3.4 255.255.255.255 4.3.2.1 255.255.255.255
(on bridge2) # ipsecadm flow -dst 1.2.3.4 -out \\
	-transport etherip -require \\
	-addr 4.3.2.1 255.255.255.255 1.2.3.4 255.255.255.255
.Ed
.Pp
Bring up the internal interface (if not already up) and encapsulation
interface:
.Bd -literal
# ifconfig fxp1 up
# ifconfig gif0 up
.Ed
.Pp
Finally, bring the bridge interface up and allow it to start processing
frames:
.Bd -literal
# brconfig bridge0 up
.Ed
.Pp
The internal interface, ie. fxp1, on each bridge need not have an IP
address; the bridge can function without it.
.Pp
Note:  It is possible to put all the following commands in the
.Xr hostname.if 5
and
.Xr bridgename.if 5
files, using the ! operator.
.Sh SPANNING TREE
The bridge has support for 802.1D Spanning Tree Protocol (STP), which can
be used to detect and remove loops in a network topology.
Using the
.Cm stp
or
.Cm -stp
commands
to
.Nm brconfig
STP can be enabled or disabled on each port.
STP will not work on
.Xr gif 4
members because they lack a hardware MAC address.
.Sh SPAN PORTS
The bridge can have interfaces added to it as span ports.
Span ports transmit a copy of every frame received by the bridge.
This is most useful for snooping a bridged network passively on
another host connected to one of the span ports of the bridge.
Span ports cannot be bridge members, instead the
.Cm addspan
and
.Cm delspan
commands are used to add and delete span ports to and from a bridge.
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr gif 4 ,
.Xr ip 4 ,
.Xr ipsec 4 ,
.Xr bridgename.if 5 ,
.Xr ifconfig 8 ,
.Xr ipsecadm 8 ,
.Xr isakmpd 8
.Sh AUTHORS
The
.Nm
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 HISTORY
The
.Nm brconfig
command first appeared in
.Ox 2.5 .
.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.