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

NAME
     brconfig - manipulate bridge interfaces

SYNOPSIS
     brconfig -a
     brconfig bridge-name [parameters]
     brconfig bridge-name rule { block | pass } { in | out | in/out } on
              interface-name [src address] [dst address]

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.

     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 com-
     mands are executed in the order they were specified.  If no command is
     specified in the second synopsis, the brconfig will display status infor-
     mation about the bridge.  With the third synopsis, rules for filtering
     Ethernet MAC addresses can be added to a bridge.

     The following parameters may be set with brconfig:

     up      Start the bridge forwarding packets.

     down    Stop the bridge from forwarding packets.

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

     add interface-name
             Add the interface named by 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.

     delete interface-name
             Remove the interface named by interface-name from the bridge.
             Promiscuous mode is turned off for the interface when it is re-
             moved from the bridge.

     del     Alias for delete.

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

     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.

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

     deladdr address
             Delete an address from the cache.


     flush   Remove all dynamically learned addresses from the cache.

     flushall
             Remove all addresses from the cache including static addresses.

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

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

     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, mean-
             ing that there is no static entry and no dynamically learned en-
             try for the destination, the bridge will forward the packet to
             all member interfaces that have this flag set.  This is the de-
             fault for interfaces added to the bridge.

     -discover interface
             Mark an interface so that packets are not sent out of the inter-
             face 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.

     learn interface
             Mark an interface so that the source address of packets received
             from interface are entered into the address cache.  This is the
             default for interfaces added to the bridge.

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

     flushrule interface
             Remove all Ethernet MAC filtering rules from interface.

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

     -link0  Clear the link0 flag on the bridge interface.

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

     -link1  Clear the link1 flag on the bridge interface.

     rule [rulespec]
             Add a filtering rule to an interface.  Rules have a similiar syn-
             tax to 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).

     rulefile filename

             Load a set of rules from the file filename.

     stp interface
             Enable spanning tree protocol on interface.

     -stp interface
             Disable spanning tree protocol on interface.

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

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

     hellotime time
             Set the time (in seconds) between broadcasting spanning tree pro-
             tocol configuration packets.  Defaults to 2 seconds, minimum of
             1, maximum of 255.

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

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

EXAMPLES
     brconfig bridge0 add rl0 add xl0 up
               Add the Ethernet interfaces rl0 and xl0 to the bridge bridge0,
               and start the bridge forwarding packets.

     brconfig bridge0
               Retrieve a list of interfaces that are members of bridge0, and
               the addresses learned by the bridge.

     brconfig bridge0 down
               Stop bridge0 from forwarding packets.

     brconfig bridge0 delete xl0
               Remove the interface xl0 from the bridge bridge0.

     brconfig bridge0 flush
               Flush all dynamically learned addresses from the address cache.

     brconfig bridge0 flushall
               Remove all addresses, including static addresses, from the ad-
               dress cache.

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

     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.  Al-
               so, 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.

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

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 ipsecadm(8) or isakmpd(8).
     Otherwise, the ethernet frames will be sent in the clear between 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.

     Add the encapsulation interface and internal ethernet interface to bridge
     interface:

     # brconfig bridge0 add gif0 add fxp1

     Configure the gif0 interface:

     (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

     Create Security Associations (SAs) between the external IP address of
     each bridge:

     # ipsecadm new esp -spi 4242 -dst 4.3.2.1 -src 1.2.3.4 \
             -enc 3des -auth md5 -keyfile keyfile1 -authkeyfile authkeyfile1

     # ipsecadm new esp -spi 4243 -dst 1.2.3.4 -src 4.3.2.1 \
             -enc 3des -auth md5 -keyfile keyfile2 -authkeyfile authkeyfile2

     Setup ingress flows so that traffic is allowed between the two bridges
     for the above associations:

     (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

     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

     The internal interface, ie. fxp1, on each bridge need not have an IP ad-
     dress; the bridge can function without it.

     Note:  It is possible to put all the following commands in the host-
     name.if(5) and bridgename.if(5) files, using the ! operator.

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 stp
     or -stp commands to brconfig STP can be enabled or disabled on each port.
     STP will not work on gif(4) members because they lack a hardware MAC ad-
     dress.

SEE ALSO
     bridge(4), gif(4), ip(4), ipsec(4), bridgename.if(5), ifconfig(8),
     ipsecadm(8)

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

HISTORY
     The brconfig command first appeared in OpenBSD 2.5.

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.

     The packets generated by the gif(4) interfaces must not cause transmis-
     sion over one of the "real" ethernet member interfaces of the bridge, or
     else an infinite packet forwarding loop will occur.

OpenBSD 3.0                    February 26, 1999                             5
