From: Michael Tremer <michael.tremer@ipfire.org>
Date: Thu, 7 Jun 2012 21:41:22 +0000 (+0000)
Subject: doc: Add man page for the bridge hook.
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=de12581066be29fbd614a964e217ffc551b9345a;p=people%2Fstevee%2Fnetwork.git

doc: Add man page for the bridge hook.
---

diff --git a/hooks/zones/bridge b/hooks/zones/bridge
index eae6ece1..3db92aa8 100755
--- a/hooks/zones/bridge
+++ b/hooks/zones/bridge
@@ -21,6 +21,8 @@
 
 . /usr/lib/network/header-zone
 
+HOOK_MANPAGE="network-zone-bridge"
+
 HOOK_SETTINGS="HOOK STP STP_FORWARD_DELAY STP_HELLO STP_MAXAGE STP_MODE"
 HOOK_SETTINGS="${HOOK_SETTINGS} STP_PRIORITY MAC MTU"
 
diff --git a/man/Makefile b/man/Makefile
index 285f9a36..eadee58d 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -29,7 +29,8 @@ MANPAGES8   = \
 	network.8 \
 	network-config.8 \
 	network-device.8 \
-	network-zone.8
+	network-zone.8 \
+	network-zone-bridge.8
 
 .PHONY: all
 all: $(MANPAGES)
diff --git a/man/network-zone-bridge.8.in b/man/network-zone-bridge.8.in
new file mode 100644
index 00000000..06b4532f
--- /dev/null
+++ b/man/network-zone-bridge.8.in
@@ -0,0 +1,88 @@
+.TH network-zone-bridge 8 "8 Jun 2012" "@VERSION@" "network man page"
+
+.SH NAME
+network-zone-bridge \- Network Configuration Control Program
+
+.SH SYNOPSIS
+\fBnetwork [OPTIONS] zone create <zone> bridge ...\fR
+.P
+All options may be edited on zones which have already been set up with the \fBbridge\fR hook:
+.P
+\fBnetwork [OPTIONS] zone <zone> edit ...\fR
+
+.SH DESCRIPTION
+The bridge hook creates an ethernet bridge which acts as an unmanaged network
+switch. It contains one or multiple phyisical network interfaces or virtual
+devices which will be connected to each other.
+.PP
+The bridge hook is the prefered hook for local area network zones which are
+connected to an ethernet network.
+
+.SH OPTIONS
+The \fBbridge\fR hook offers various configuration options:
+
+\fB--stp\fR = [\fBon\fR|off]
+.RS 4
+This option enables or disable the use of the \fBSpanning Tree Protocol\fR (STP).
+This protocol is used to avoid loops in networks by dynamically disabling packet
+forwarding on links.
+.PP
+It is highly recommended to leave this option enabled when you add more than
+one device to the zone. Read below how the behaviour of STP can be changed.
+.RE
+.PP
+
+\fB--mtu\fR = 1500
+.RS 4
+Sets the default MTU of the bridge. All ports in the bridge must support this
+MTU.
+.RE
+.PP
+
+\fB--mac\fR = ...
+.RS 4
+By this option, you may define the MAC address of the bridge. If this option
+is missing, a random MAC address will be generated.
+.RE
+.PP
+
+Spanning Tree Protocol configuration options:
+
+\fB--stp-mode\fR = [\fBrstp\fR|stp]
+.RS 4
+When STP is enabled, this option will set the operational mode which can either be:
+.PP
+* \fBSpanning Tree Protocol IEEE 802.1W\fR (stp) was introduced in 1998 by Radia
+Perlman.
+.P
+* \fBRapid Spanning Tree Protocol IEEE 802.1D\fR (rstp) which has much faster convergence
+times and was introduced in 2004. This is the default option.
+.RE
+.PP
+
+\fB--stp-forward-delay\fR = 0
+.RS 4
+This sets the default time the interfaces are hold off after they have been added
+to a bridge. The default value is 0.
+.RE
+.PP
+
+\fB--stp-hello\fR = 2
+.RS 4
+This option defines how often a hello message should be sent. The value is given in seconds
+and the default is 2.
+.RE
+.PP
+
+\fB--stp-priority\fR = 512
+.RS 4
+The STP priority sets the ranking of this network device within the network. The bridge
+with the best rank (0 is best) will become the root bridge.
+.RE
+.PP
+
+.SH SEE ALSO
+network(8)
+
+.SH AUTHOR
+Michael Tremer (michael.tremer@ipfire.org)