Move information describing the bridge and brconfig behaviour into

the relevant manual pages.  Functionality is described in the (4)
pages, controlling the functionality in ifconfig(8), and the hostname.if
gains the old bridgename.if(5) functionality.
ok claudio jmc

2 files changed, 179 insertions, 13 deletions

diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4
index 8aef2d206d3..43ba0555ba3 100644
--- a/share/man/man4/bridge.4
+++ b/share/man/man4/bridge.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: bridge.4,v 1.67 2009/11/09 03:16:07 deraadt Exp $
+.\"	$OpenBSD: bridge.4,v 1.68 2009/11/22 22:01:55 deraadt Exp $
 .\"
 .\" Copyright (c) 1999-2001 Jason L. Wright (jason@thought.net)
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 9 2009 $
+.Dd $Mdocdate: November 22 2009 $
 .Dt BRIDGE 4
 .Os
 .Sh NAME
@@ -58,7 +58,7 @@ A
 interface can be created at runtime using the
 .Ic ifconfig bridge Ns Ar N Ic create
 command or by setting up a
-.Xr bridgename.if 5
+.Xr hostname.if 5
 configuration file for
 .Xr netstart 8 .
 .Pp
@@ -79,7 +79,7 @@ an IP firewall without changing the topology of the network.
 The algorithm works as follows by default, but can be modified via
 .Xr ioctl 2
 or the utility
-.Xr brconfig 8 .
+.Xr ifconfig 8 .
 When a frame comes in, the origin segment and the source address are
 recorded.
 If the bridge has no knowledge about where the destination is to be found,
@@ -99,6 +99,41 @@ pf interface so that it can be filtered.
 See the
 .Sx NOTES
 section for details.
+.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 IOCTLS
 A
 .Nm
@@ -623,24 +658,36 @@ and certificates, to impersonate the protected host(s)).
 .Xr netintro 4 ,
 .Xr pf 4 ,
 .Xr vether 4 ,
-.Xr bridgename.if 5 ,
-.Xr brconfig 8 ,
+.Xr hostname.if 5 ,
+.Xr ifconfig 8 ,
 .Xr ipsecctl 8 ,
 .Xr isakmpd 8 ,
 .Xr netstart 8
 .Sh HISTORY
 The
-.Xr brconfig 8
-command and the
 .Nm
 kernel interface first appeared in
 .Ox 2.5 .
 .Sh AUTHORS
 The
-.Xr brconfig 8
-command and the
 .Nm
-kernel interface were written by
+kernel interface was 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.
diff --git a/share/man/man4/gif.4 b/share/man/man4/gif.4
index 3c974ebbeda..caeca90af83 100644
--- a/share/man/man4/gif.4
+++ b/share/man/man4/gif.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: gif.4,v 1.18 2007/05/31 19:19:50 jmc Exp $
+.\"	$OpenBSD: gif.4,v 1.19 2009/11/22 22:01:55 deraadt Exp $
 .\"	$KAME: gif.4,v 1.15 2000/04/19 09:39:42 itojun Exp $
 .\"
 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: November 22 2009 $
 .Dt GIF 4
 .Os
 .Sh NAME
@@ -104,6 +104,125 @@ interface whose "physical" addresses match the source/destination
 addresses of the packet (the source address of the packet must match
 the destination "physical" address, and vice versa).
 .\"
+.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
+First create the bridge interface,
+then add the encapsulation interface and internal Ethernet interface
+to the bridge interface:
+.Bd -literal -offset indent
+# ifconfig bridge0 add gif0 add fxp1
+.Ed
+.Pp
+Create and configure the gif0 interface:
+.Bd -literal -offset indent
+(on bridge 1) # ifconfig gif0 tunnel 1.2.3.4 4.3.2.1
+(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 # ifconfig bridge0 up link2
+.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 SEE ALSO
 .Xr sysctl 3 ,
 .Xr bridge 4 ,