BRCONFIG(8)             OpenBSD System Manager's Manual            BRCONFIG(8)

NAME
     brconfig - manipulate bridge interfaces

SYNOPSIS
     brconfig [-Aa] [interface] [parameters]
     brconfig interface rule { block | pass } { in | out | in/out } on
              interface [src address] [dst address] [tag tagname]

DESCRIPTION
     The brconfig utility retrieves kernel state of bridge interfaces and al-
     lows user control of these bridges.  Bridge devices create a logical link
     between two or more Ethernet interfaces or encapsulation interfaces (see
     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 iso-
     late traffic between sets of machines on the same segment and to provide
     a transparent filter for ip(4) datagrams.

     The options are as follows:

     -A      The same as -a, but also lists additional status information.

     -a      Lists the status of all bridges in the system.  This is the de-
             fault if brconfig is invoked without arguments.

     The following parameters may be set with brconfig:

     add interface
             Add 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.

     addr    Display the addresses that have been learned by the bridge.

     addspan interface
             Add interface as a span port on the bridge.  See the SPAN PORTS
             section for more details.

     autoedge interface
             Automatically detect the spanning tree edge port status on
             interface.  This is the default for interfaces added to the
             bridge.

     -autoedge interface
             Disable automatic spanning tree edge port detection on interface.

     autoptp interface
             Automatically detect the point-to-point status on interface by
             checking the full duplex link status.  This is the default for
             interfaces added to the bridge.

     -autoptp interface
             Disable automatic point-to-point link detection on interface.

     blocknonip interface
             Mark 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.

     -blocknonip interface
             Allow non-IPv4, IPv6, ARP, or Reverse ARP packets through
             interface.

     del interface
             Alias for delete.

     deladdr address
             Delete address from the cache.

     delete interface
             Remove interface from the bridge.  Promiscuous mode is turned off
             for the interface when it is removed from the bridge.

     delspan interface
             Delete interface from the list of span ports of the bridge.

     discover interface
             Mark 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.

     -discover interface
             Mark 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 in-
             terface'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.

     down    Stop the bridge from forwarding packets.

     edge interface
             Set 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.

     -edge interface
             Disable edge port status on interface.

     flush   Remove all dynamically learned addresses from the cache.

     flushall
             Remove all addresses from the cache including static addresses.

     flushrule interface
             Remove all Ethernet MAC filtering rules from interface.

     fwddelay time
             Set the time (in seconds) before an interface begins forwarding
             packets.  Defaults to 15 seconds, minimum of 4, maximum of 30.

     hellotime time
             Set the time (in seconds) between broadcasting spanning tree pro-
             tocol 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 proto command for setting the
             protocol version.

     holdcnt 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.

     ifcost interface num
             Set the spanning tree path cost of interface to num.  Defaults to
             55, minimum of 1, maximum of 200000000 in RSTP mode, and maximum
             of 65535 in STP mode.

     -ifcost interface
             Automatically calculate the spanning tree priority of interface
             based on the current link speed, interface status, and spanning
             tree mode.  This is the default for interfaces added to the
             bridge.

     ifpriority interface num
             Set the spanning tree priority of interface to num.  Defaults to
             128, minimum of 0, maximum of 240.

     learn interface
             Mark 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.

     -learn interface
             Mark interface so that the source address of packets received
             from interface are not entered into the address cache.

     link0   Setting this flag stops all IP multicast packets from being for-
             warded by the bridge.

     -link0  Clear the link0 flag on the bridge interface.

     link1   Setting this flag stops all non-IP multicast packets from being
             forwarded by the bridge.

     -link1  Clear the link1 flag on the bridge interface.

     link2   Setting this flag causes all packets to be passed on to ipsec(4)
             for processing, based on the policies established by the adminis-
             trator using the ipsecctl(8) command and ipsec.conf(5).  If ap-
             propriate security associations (SAs) exist, they will be used to
             encrypt or decrypt the packets.  Otherwise, any key management
             daemons such as 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 authenti-
             cation and authorization material, such as keys and certificates,
             to impersonate the protected host(s)).

     -link2  Clear the link2 flag on the bridge interface.

     maxaddr size
             Set the address cache size to size.  The default is 100 entries.

     maxage time
             Set the time (in seconds) that a spanning tree protocol configu-
             ration is valid.  Defaults to 20 seconds, minimum of 6, maximum
             of 40.

     priority num
             Set the spanning priority of this bridge to num.  Defaults to
             32768, minimum of 0, maximum of 61440.

     proto value
             Force the spanning tree protocol version.  The available values
             are rstp to operate in the default Rapid Spanning Tree (RSTP)
             mode or stp to force operation in Spanning Tree (STP) mode with
             rapid transitions disabled.

     ptp interface
             Set 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 trunk(4) with at least two physical links
             to the same network segment.

     -ptp interface
             Disable point-to-point link status on 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.

     rule [rulespec]
             Add a filtering rule to an interface.  Rules have a similar syn-
             tax to those in pf.conf(5).  Rules can be used to selectively
             block or pass frames based on Ethernet MAC addresses.  They can
             also tag packets for 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 giv-
             en, 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).

     rulefile filename
             Load a set of rules from the file filename.

     rules interface
             Display the active filtering rules in use on interface.

     static interface address
             Add a static entry into the address cache pointing to interface.
             Static entries are never aged out of the cache or replaced, even
             if the address is seen on a different interface.

     stp interface
             Enable spanning tree protocol on interface.

     -stp interface
             Disable spanning tree protocol on interface.  This is the default
             for interfaces added to the bridge.

     timeout time
             Set the timeout, in seconds, for addresses in the cache to time.
             The default is 240 seconds.  If time is set to zero, then entries
             will not be expired.

     up      Start the bridge forwarding packets.

IPSEC BRIDGE
     The bridge can also be used to tunnel Ethernet frames over IPv4 or IPv6
     by using the gif(4) interface.  In addition to adding Ethernet inter-
     faces, one or more gif(4), interfaces are added as members of the bridge.
     Ethernet frames sent through the gif(4) interfaces are encapsulated in-
     side 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, possi-
     bly 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 ipsec.conf(5) or
     isakmpd(8).  Otherwise, the Ethernet frames will be sent in the clear be-
     tween the two bridges.

     For example, given two physically separate Ethernet networks, the bridge
     can be used as follows to make them appear as the same local area net-
     work.  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 net-
     work2, respectively), the following configuration can be used to bridge
     network1 and network2.

     First create the bridge interface, then add the encapsulation interface
     and internal Ethernet interface to the bridge interface:

           # ifconfig bridge0 create
           # brconfig bridge0 add gif0 add fxp1

     Create and configure the gif0 interface:

           (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

     Create Security Associations (SAs) between the external IP address of
     each bridge and matching ingress flows by using the following
     ipsec.conf(5) file on bridge1:

           esp from 1.2.3.4 to 4.3.2.1 spi 0x4242:0x4243 \
                   authkey file "auth1:auth2" enckey file "enc1:enc2"
           flow esp proto etherip from 1.2.3.4 to 4.3.2.1

     Now load these rules into the kernel by issuing the ipsecctl(8) command:

                   # ipsecctl -f ipsec.conf

     Appropriate ipsec.conf(5) for bridge2:

           esp from 4.3.2.1 to 1.2.3.4 spi 0x4243:0x4242 \
                   authkey file "auth2:auth1" enckey file "enc2:enc1"
           flow esp proto etherip from 4.3.2.1 to 1.2.3.4

     And load them:

                   # ipsecctl -f ipsec.conf

     To use isakmpd(8) use this ipsec.conf(5) on bridge1:

           ike esp proto etherip from 1.2.3.4 to 4.3.2.1

     And that one on bridge2:

           ike esp proto etherip from 4.3.2.1 to 1.2.3.4

     Bring up the internal interface (if not already up) and encapsulation in-
     terface:

           # ifconfig fxp1 up
           # ifconfig gif0 up

     Finally, bring the bridge interface up and allow it to start processing
     frames:

           # brconfig bridge0 up link2

     The internal interface on each bridge need not have an IP address: the
     bridge can function without it.

     Note:  It is possible to put the above commands in the hostname.if(5) and
     bridgename.if(5) files, using the `!' operator.

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.  Us-
     ing the stp or -stp commands to brconfig, STP can be enabled or disabled
     on each port.

     The bridge will use the Rapid Spanning Tree Protocol (RSTP) by default to
     allow rapid transitions to the forwarding state.  The proto command to
     brconfig can be used to force operation in the common Spanning Tree Pro-
     tocol without rapid state transitions.  Note that RSTP will be compatible
     with remote bridges running common STP.

     STP will not work on gif(4) members because they lack a hardware MAC ad-
     dress.

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 use-
     ful for snooping a bridged network passively on another host connected to
     one of the span ports of the bridge.  Span ports cannot be bridge mem-
     bers; instead, the addspan and delspan commands are used to add and
     delete span ports to and from a bridge.

EXAMPLES
     Create a bridge pseudo network device:

           # ifconfig bridge0 create

     Bring the Ethernet interfaces rl0 and xl0 up, add them to the bridge,
     bridge0, and have the bridge start forwarding packets:

           # ifconfig rl0 up
           # ifconfig xl0 up
           # brconfig bridge0 add rl0 add xl0 up

     Retrieve a list of interfaces that are members of bridge0, and the ad-
     dresses learned by the bridge:

           # brconfig bridge0

     Stop bridge0 from forwarding packets:

           # brconfig bridge0 down

     Remove the interface xl0 from the bridge bridge0:

           # brconfig bridge0 delete xl0

     Flush all dynamically learned addresses from the address cache:

           # brconfig bridge0 flush

     Remove all addresses, including static addresses, from the address cache:

           # brconfig bridge0 flushall

     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.

           # brconfig bridge0 -learn xl0 static xl0 8:0:20:1e:2f:2b
           # brconfig bridge0 -discover xl0

     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.

           # brconfig bridge0 rule pass in  on fxp0 \
                   src 0:1:2:3:4:5 dst 5:4:3:2:1:0
           # brconfig bridge0 rule pass out on fxp0 \
                   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

     The following commands will tag packets from and to 9:8:7:6:5:4 on fxp0
     so that pf(4) can refer to them using the tagged directive:

           # 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

     An example pf.conf(5) rule using this tag is:

           pass tagged boss queue q_med

SEE ALSO
     bridge(4), gif(4), ip(4), ipsec(4), pf(4), bridgename.if(5), pf.conf(5),
     ifconfig(8), ipsecctl(8), isakmpd(8)

HISTORY
     The brconfig command first appeared in OpenBSD 2.5.

AUTHORS
     The brconfig command and the bridge(4) kernel interface were written by
     Jason L. Wright <jason@thought.net> as part of an undergraduate indepen-
     dent study at the University of North Carolina at Greensboro.

     Support for rapid spanning tree reconfigurations (RSTP) was added by
     Andrew Thompson <thompsa@freebsd.org> and ported to OpenBSD by
     Reyk Floeter <reyk@openbsd.org>.

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 tl(4)), which
     receives its own transmissions (this renders the address learning cache
     useless).  Most other chipsets work fine though.

OpenBSD 4.6                       May 4, 2009                                7
