.\"	$OpenBSD: brconfig.8,v 1.69 2007/05/31 19:19:43 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.
.\"
.\" 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 $Mdocdate: May 31 2007 $
.Dt BRCONFIG 8
.Os
.Sh NAME
.Nm brconfig
.Nd manipulate bridge interfaces
.Sh SYNOPSIS
.Nm
.Op Fl Aa
.Op Ar interface
.Op Ar parameters
.Nm
.Ar interface Cm rule No {
.Cm block | pass No } {
.Cm in | out | in/out No } Cm on
.Ar interface
.Op Cm src Ar address
.Op Cm dst Ar address
.Op Cm tag Ar tagname
.Sh DESCRIPTION
The
.Nm
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
The options are as follows:
.Bl -tag -width Ds
.It Fl A
The same as
.Fl a ,
but also lists additional status information.
.It Fl a
Lists the status of all bridges in the system.
This is the default if
.Nm
is invoked without arguments.
.El
.Pp
The following
.Ar parameters
may be set with
.Nm :
.Bl -tag -width Ds
.It Cm add Ar interface
Add
.Ar interface
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 addr
Display the addresses that have been learned by the bridge.
.It Cm addspan Ar interface
Add
.Ar interface
as a span port on the bridge.
See the
.Sx SPAN PORTS
section for more details.
.It Cm autoedge Ar interface
Automatically detect the spanning tree edge port status on
.Ar interface .
This is the default for interfaces added to the bridge.
.It Cm -autoedge Ar interface
Disable automatic spanning tree edge port detection on
.Ar interface .
.It Cm autoptp Ar interface
Automatically detect the point to point status on
.Ar interface
by checking the full duplex link status.
This is the default for interfaces added to the bridge.
.It Cm -autoptp Ar interface
Disable automatic point to point link detection on
.Ar interface .
.It Cm blocknonip Ar interface
Mark
.Ar 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
.Ar interface .
.It Cm del Ar interface
Alias for
.Cm delete .
.It Cm deladdr Ar address
Delete
.Ar address
from the cache.
.It Cm delete Ar interface
Remove
.Ar interface
from the bridge.
Promiscuous mode is turned off for the interface when it is
removed from the bridge.
.It Cm delspan Ar interface
Delete
.Ar interface
from the list of span ports of the bridge.
.It Cm discover Ar interface
Mark
.Ar 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
.Ar 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 down
Stop the bridge from forwarding packets.
.It Cm edge Ar interface
Set
.Ar interface
as a spanning tree edge port.
An edge port is a single connection to the network and cannot create
bridge loops.
This allows a straight transition to forwarding.
.It Cm -edge Ar interface
Disable edge port status on
.Ar interface .
.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 flushrule Ar interface
Remove all Ethernet MAC filtering rules from
.Ar interface .
.It Cm fwddelay Ar time
Set the time (in seconds) before an interface begins forwarding packets.
Defaults to 15 seconds, minimum of 4, maximum of 30.
.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 2.
This option is only supported in STP mode with rapid transitions disabled;
see the
.Cm proto
command for setting the protocol version.
.It Cm holdcnt Ar time
Set the transmit hold count, which is the number of spanning tree protocol
packets transmitted before being rate limited.
Defaults to 6, minimum of 1, maximum of 10.
.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 200000000 in RSTP mode,
and maximum of 65535 in STP mode.
.It Cm -ifcost Ar interface
Automatically calculate the spanning tree priority of
.Ar interface
based on the current link speed, interface status, and spanning tree mode.
This is the default for interfaces added to the bridge.
.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 240.
.It Cm learn Ar interface
Mark
.Ar interface
so that the source address of packets received from
the interface
are entered into the address cache.
This is the default for interfaces added to the bridge.
.It Cm -learn Ar interface
Mark
.Ar interface
so that the source address of packets received from interface
are not entered into the address cache.
.It Cm link0
Setting this flag stops all 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 flag stops all non-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 ipsecctl 8
command and
.Xr ipsec.conf 5 .
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 maxaddr Ar size
Set the address cache size to
.Ar size .
The default is 100 entries.
.It Cm maxage Ar time
Set the time (in seconds) that a spanning tree protocol configuration is valid.
Defaults to 20 seconds, minimum of 6, maximum of 40.
.It Cm priority Ar num
Set the spanning priority of this bridge to
.Ar num .
Defaults to 32768, minimum of 0, maximum of 61440.
.It Cm proto Ar value
Force the spanning tree protocol version.
The available values are
.Ar rstp
to operate in the default Rapid Spanning Tree (RSTP) mode
or
.Ar stp
to force operation in Spanning Tree (STP) mode with rapid transitions disabled.
.It Cm ptp Ar interface
Set
.Ar interface
as a point to point link.
This is required for straight transitions to forwarding and
should be enabled for a full duplex link or a
.Xr trunk 4
with at least two physical links to the same network segment.
.It Cm -ptp Ar interface
Disable point to point link status on
.Ar interface .
This should be disabled for a half duplex link and for an interface
connected to a shared network segment,
like a hub or a wireless network.
.It Cm rule Op Ar rulespec
Add a filtering rule to an interface.
Rules have a similar syntax to those in
.Xr pf.conf 5 .
Rules can be used to selectively block or pass frames based on Ethernet
MAC addresses.
They can also tag packets for
.Xr pf 4
to filter on.
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)
and, if given, the tag 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 rules Ar interface
Display the active filtering rules in use on
.Ar interface .
.It Cm static Ar interface address
Add a static entry into the address cache pointing to
.Ar interface .
Static entries are never aged out of the cache or replaced, even if the address
is seen on a different interface.
.It Cm stp Ar interface
Enable spanning tree protocol on
.Ar interface .
.It Cm -stp Ar interface
Disable spanning tree protocol on
.Ar interface .
This is the default for interfaces added to the bridge.
.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 up
Start the bridge forwarding packets.
.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 ipsec.conf 5
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 the bridge
interface:
.Pp
.Dl # brconfig bridge0 add gif0 add fxp1
.Pp
Create and configure the gif0 interface:
.Bd -literal -offset indent
(on bridge 1) # ifconfig gif0 create
(on bridge 1) # ifconfig gif0 tunnel 1.2.3.4 4.3.2.1
(on bridge 2) # ifconfig gif0 create
(on bridge 2) # ifconfig gif0 tunnel 4.3.2.1 1.2.3.4
.Ed
.Pp
Create Security Associations (SAs) between the external IP address of each
bridge and matching ingress flows by using the following
.Xr ipsec.conf 5
file on bridge1:
.Bd -literal -offset indent
esp from 1.2.3.4 to 4.3.2.1 spi 0x4242:0x4243 \e
	authkey file "auth1:auth2" enckey file "enc1:enc2"
flow esp proto etherip from 1.2.3.4 to 4.3.2.1
.Ed
.Pp
Now load these rules into the kernel by issuing the
.Xr ipsecctl 8
command:
.Bd -literal -offset indent
	# ipsecctl -f ipsec.conf
.Ed
.Pp
Appropriate
.Xr ipsec.conf 5
for bridge2:
.Bd -literal -offset indent
esp from 4.3.2.1 to 1.2.3.4 spi 0x4243:0x4242 \e
	authkey file "auth2:auth1" enckey file "enc2:enc1"
flow esp proto etherip from 4.3.2.1 to 1.2.3.4
.Ed
.Pp
And load them:
.Bd -literal -offset indent
	# ipsecctl -f ipsec.conf
.Ed
.Pp
To use
.Xr isakmpd 8
use this
.Xr ipsec.conf 5
on bridge1:
.Bd -literal -offset indent
ike esp proto etherip from 1.2.3.4 to 4.3.2.1
.Ed
.Pp
And that one on bridge2:
.Bd -literal -offset indent
ike esp proto etherip from 4.3.2.1 to 1.2.3.4
.Ed
.Pp
Bring up the internal interface (if not already up) and encapsulation
interface:
.Bd -literal -offset indent
# ifconfig fxp1 up
# ifconfig gif0 up
.Ed
.Pp
Finally, bring the bridge interface up and allow it to start processing
frames:
.Pp
.Dl # brconfig bridge0 up
.Pp
The internal interface on each bridge need not have an IP
address: the bridge can function without it.
.Pp
Note:  It is possible to put the above commands in the
.Xr hostname.if 5
and
.Xr bridgename.if 5
files, using the
.Sq !\&
operator.
.Sh SPANNING TREE
The bridge has support for 802.1D-2004 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 ,
STP can be enabled or disabled on each port.
.Pp
The bridge will use the Rapid Spanning Tree Protocol (RSTP) by default
to allow rapid transitions to the forwarding state.
The
.Cm proto
command to
.Nm
can be used to force operation in the common Spanning Tree Protocol
without rapid state transitions.
Note that RSTP will be compatible with remote bridges running common STP.
.Pp
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 EXAMPLES
Create a bridge pseudo network device:
.Pp
.Dl # ifconfig bridge0 create
.Pp
Bring the Ethernet interfaces rl0 and xl0 up,
add them to the bridge, bridge0,
and have the bridge start forwarding packets:
.Bd -literal -offset indent
# ifconfig rl0 up
# ifconfig xl0 up
# brconfig bridge0 add rl0 add xl0 up
.Ed
.Pp
Retrieve a list of interfaces that are members of bridge0, and the addresses
learned by the bridge:
.Pp
.Dl # brconfig bridge0
.Pp
Stop bridge0 from forwarding packets:
.Pp
.Dl # brconfig bridge0 down
.Pp
Remove the interface xl0 from the bridge bridge0:
.Pp
.Dl # brconfig bridge0 delete xl0
.Pp
Flush all dynamically learned addresses from the address cache:
.Pp
.Dl # brconfig bridge0 flush
.Pp
Remove all addresses, including static addresses, from the address cache:
.Pp
.Dl # brconfig bridge0 flushall
.Pp
The following commands mark the xl0 interface so that it will not learn
addresses and add 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 onto the xl0 segment by the bridge unless they are
broadcast packets or are destined for 8:0:20:1e:2f:2b.
.Bd -literal -offset indent
# brconfig bridge0 -learn xl0 static xl0 8:0:20:1e:2f:2b
# brconfig bridge0 -discover xl0
.Ed
.Pp
The following 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:0, and 5:4:3:2:1:0 can return frames through
fxp0 only to 0:1:2:3:4:5.
All other traffic trying to go into or be sent from fxp0 will be blocked.
.Bd -literal -offset indent
# brconfig bridge0 rule pass in  on fxp0 \e
	src 0:1:2:3:4:5 dst 5:4:3:2:1:0
# brconfig bridge0 rule pass out on fxp0 \e
	src 5:4:3:2:1:0 dst 0:1:2:3:4:5
# brconfig bridge0 rule block in  on fxp0
# brconfig bridge0 rule block out on fxp0
.Ed
.Pp
The following commands will tag packets from and to 9:8:7:6:5:4 on fxp0 so that
.Xr pf 4
can refer to them using the
.Cm tagged
directive:
.Bd -literal -offset indent
# brconfig bridge0 rule pass in  on fxp0 src 9:8:7:6:5:4 tag boss
# brconfig bridge0 rule pass out on fxp0 dst 9:8:7:6:5:4 tag boss
.Ed
.Pp
An example
.Xr pf.conf 5
rule using this tag is:
.Pp
.Dl pass tagged boss queue q_med
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr gif 4 ,
.Xr ip 4 ,
.Xr ipsec 4 ,
.Xr pf 4 ,
.Xr bridgename.if 5 ,
.Xr pf.conf 5 ,
.Xr ifconfig 8 ,
.Xr ipsecctl 8 ,
.Xr isakmpd 8
.Sh HISTORY
The
.Nm
command first appeared in
.Ox 2.5 .
.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.
.Pp
Support for rapid spanning tree reconfigurations (RSTP) was added by
.An Andrew Thompson Aq thompsa@freebsd.org
and ported to
.Ox
by
.An Reyk Floeter Aq reyk@openbsd.org .
.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.