[doc] minor tweaks, refine ospf redist,passive-inter, and abr-type help

2006-07-27 Paul Jakma <paul.jakma@sun.com>

	* quagga.texi: Remove unused index definitions
	  Add an Index node - for the concept index.
	* routeserver.texi: Set exampleindex to 0, so the example configs
	  with long IPv6 addresses stand better chance of fitting.
	* overview.texi: 'Supported RFC' -> 'Supported RFCs'
	  Remove paragraph indentation - texinfo does that.
	  Revise the supported OS list slightly.
	  Remove the IPv6 stack list, seems very dated and irrelevant.
	  Revise the 'How to get Quagga' section.
	* ospfd.texi: minor tweaks: add some anchors, fix some minor
	  format issues.
	  Revise the help for 'abr-type'.
	  Note that text authentication is unwise, recc'd MD5.
	  Add some extra text for redistribute and passive-interface,
	  about how latter can substitute for redist connected.

5 files changed, 96 insertions, 61 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a0c39953..02324b99 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,21 @@
+2006-07-27 Paul Jakma <paul.jakma@sun.com>
+
+	* quagga.texi: Remove unused index definitions
+	  Add an Index node - for the concept index.
+	* routeserver.texi: Set exampleindex to 0, so the example configs
+	  with long IPv6 addresses stand better chance of fitting.
+	* overview.texi: 'Supported RFC' -> 'Supported RFCs'
+	  Remove paragraph indentation - texinfo does that.
+	  Revise the supported OS list slightly.
+	  Remove the IPv6 stack list, seems very dated and irrelevant.
+	  Revise the 'How to get Quagga' section.
+	* ospfd.texi: minor tweaks: add some anchors, fix some minor
+	  format issues.
+	  Revise the help for 'abr-type'.
+	  Note that text authentication is unwise, recc'd MD5.
+	  Add some extra text for redistribute and passive-interface,
+	  about how latter can substitute for redist connected.
+
 2006-07-27 Andrew J. Schorr <ajschorr@alumni.princeton.edu>
 
 	* vtysh.1: Document new options -d and -E, and note that now multiple
diff --git a/doc/ospfd.texi b/doc/ospfd.texi
index c859782e..4c4b04b9 100644
--- a/doc/ospfd.texi
+++ b/doc/ospfd.texi
@@ -1,15 +1,17 @@
+@cindex OSPFv2
 @node OSPFv2
 @chapter OSPFv2
 
 @acronym{OSPF,Open Shortest Path First} version 2 is a routing protocol
 which is described in @cite{RFC2328, OSPF Version 2}.  OSPF is an
-@acronym{IGP,Interior Gateway Protocol}@..  Compared with @acronym{RIP},
+@acronym{IGP,Interior Gateway Protocol}.  Compared with @acronym{RIP},
 @acronym{OSPF} can provide scalable network support and faster
 convergence times.  OSPF is widely used in large networks such as
 @acronym{ISP,Internet Service Provider} backbone and enterprise
 networks.
 
 @menu
+
 * Configuring ospfd::           
 * OSPF router::                 
 * OSPF area::                   
@@ -46,6 +48,7 @@ support multiple OSPF processes.  So you can not specify an OSPF process
 number.
 @end deffn
 
+@anchor{ospf router-id}
 @deffn {OSPF Command} {ospf router-id @var{a.b.c.d}} {}
 @deffnx {OSPF Command} {no ospf router-id} {}
 This sets the router-ID of the OSPF process. The router-ID may be an IP
@@ -58,7 +61,24 @@ configured with the same router-ID! If one is not specified then
 
 @deffn {OSPF Command} {ospf abr-type @var{type}} {}
 @deffnx {OSPF Command} {no ospf abr-type @var{type}} {}
-@var{type} can be cisco|ibm|shortcut|standard.
+@var{type} can be cisco|ibm|shortcut|standard. The "Cisco" and "IBM" types
+are equivalent.
+
+The OSPF standard for ABR behaviour does not allow an ABR to consider
+routes through non-backbone areas when its links to the backbone are
+down, even when there are other ABRs in attached non-backbone areas
+which still can reach the backbone - this restriction exists primarily
+to ensure routing-loops are avoided.
+
+With the "Cisco" or "IBM" ABR type, the default in this release of
+Quagga, this restriction is lifted, allowing an ABR to consider
+summaries learnt from other ABRs through non-backbone areas, and hence
+route via non-backbone areas as a last resort when, and only when,
+backbone links are down.
+
+Note that areas with fully-adjacent virtual-links are considered to be
+"transit capable" and can always be used to route backbone traffic, and
+hence are unaffected by this setting (@pxref{OSPF virtual-link}).
 
 More information regarding the behaviour controlled by this command can
 be found in @cite{RFC 3509, Alternative Implementations of OSPF Area
@@ -72,15 +92,11 @@ external destinations. If this requirement is not met, all traffic
 destined for the areas not connected to such an ABR or out of the
 OSPF domain, is dropped.  This document describes alternative ABR
 behaviors implemented in Cisco and IBM routers."
-
-The default ABR type is 'Cisco', allowing an ABR to consider summaries
-from non-backbone areas if, and only if, it has lost its link(s) to the
-backbone area.
 @end deffn
 
 @deffn {OSPF Command} {ospf rfc1583compatibility} {}
 @deffnx {OSPF Command} {no ospf rfc1583compatibility} {}
-This @cite{RFC2328}, the sucessor to @cite{RFC1583}, suggests according
+@cite{RFC2328}, the sucessor to @cite{RFC1583}, suggests according
 to section G.2 (changes) in section 16.4 a change to the path
 preference algorithm that prevents possible routing loops that were
 possible in the old version of OSPFv2. More specifically it demands
@@ -97,17 +113,18 @@ detail argument, all changes in adjacency status are shown.  Without detail,
 only changes to full or regressions are shown.
 @end deffn
 
-@deffn {OSPF Command} {passive interface @var{interface}} {}
-@deffnx {OSPF Command} {no passive interface @var{interface}} {}
+@anchor{OSPF passive-interface}
+@deffn {OSPF Command} {passive-interface @var{interface}} {}
+@deffnx {OSPF Command} {no passive-interface @var{interface}} {}
 
 Do not speak OSPF interface on the given interface, but do advertise
 the interface as a stub link in the router-@acronym{LSA,Link State
 Advertisement} for this router. This allows one to advertise addresses
 on such connected interfaces without having to originate
 AS-External/Type-5 LSAs (which have global flooding scope) - as would
-occur if connected addresses were redistributed into OSPF,
-@xref{Redistribute routes to OSPF}.
-
+occur if connected addresses were redistributed into OSPF
+(@pxref{Redistribute routes to OSPF})@. This is the only way to advertise
+non-OSPF links into stub areas.
 @end deffn
 
 @deffn {OSPF Command} {timers throttle spf @var{delay} @var{initial-holdtime} @var{max-holdtime}} {}
@@ -272,6 +289,7 @@ network-LSA) from range 10.0.0.0/8.
 This command makes sense in ABR only.
 @end deffn
 
+@anchor{OSPF virtual-link} 
 @deffn {OSPF Command} {area @var{a.b.c.d} virtual-link @var{a.b.c.d}} {}
 @deffnx {OSPF Command} {area <0-4294967295> virtual-link @var{a.b.c.d}} {}
 @deffnx {OSPF Command} {no area @var{a.b.c.d} virtual-link @var{a.b.c.d}} {}
@@ -282,7 +300,7 @@ This command makes sense in ABR only.
 @deffnx {OSPF Command} {area <0-4294967295> shortcut} {}
 @deffnx {OSPF Command} {no area @var{a.b.c.d} shortcut} {}
 @deffnx {OSPF Command} {no area <0-4294967295> shortcut} {}
-Configure th area as Shortcut capable. See @cite{RFC3509}. This requires
+Configure the area as Shortcut capable. See @cite{RFC3509}. This requires
 that the 'abr-type' be set to 'shortcut'.
 @end deffn
 
@@ -295,7 +313,7 @@ originates routes external to OSPF and hence an area where all external
 routes are via the ABR(s). Hence, ABRs for such an area do not need
 to pass AS-External LSAs (type-5s) or ASBR-Summary LSAs (type-4) into the
 area. They need only pass Network-Summary (type-3) LSAs into such an area,
-just a default summary.
+along with a default-route summary.
 @end deffn
 
 @deffn {OSPF Command} {area @var{a.b.c.d} stub no-summary} {}
@@ -380,8 +398,12 @@ area.
 @deffnx {Interface Command} {no ip ospf authentication-key} {}
 Set OSPF authentication key to a simple password.  After setting @var{AUTH_KEY},
 all OSPF packets are authenticated. @var{AUTH_KEY} has length up to 8 chars.
+
+Simple text password authentication is insecure and deprecated in favour of
+MD5 HMAC authentication (@pxref{OSPF MD5 HMAC authentication}).
 @end deffn
 
+@anchor{OSPF MD5 HMAC authentication}
 @deffn {Interface Command} {ip ospf message-digest-key KEYID md5 KEY} {}
 @deffnx {Interface Command} {no ip ospf message-digest-key} {}
 Set OSPF authentication key to a cryptographic password.  The cryptographic
@@ -446,10 +468,10 @@ Set explicitly network type for specifed interface.
 
 @deffn {Interface Command} {ip ospf priority <0-255>} {}
 @deffnx {Interface Command} {no ip ospf priority} {}
-Set RouterPriority integer value.  Setting higher value, router will be more
-eligible to become Designated Router.  Setting the value to 0, router is no
-longer eligible to Designated Router.
-The default value is 1.
+Set RouterPriority integer value.  The router with the highest priority
+will be more eligible to become Designated Router.  Setting the value
+to 0, makes the router ineligible to become Designated Router. The
+default value is 1.
 @end deffn
 
 @deffn {Interface Command} {ip ospf retransmit-interval <1-65535>} {}
@@ -469,6 +491,7 @@ The default value is 1 seconds.
 @node Redistribute routes to OSPF
 @section Redistribute routes to OSPF
 
+@anchor{OSPF redistribute}
 @deffn {OSPF Command} {redistribute (kernel|connected|static|rip|bgp)} {}
 @deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) @var{route-map}} {}
 @deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2)} {}
@@ -478,9 +501,18 @@ The default value is 1 seconds.
 @deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214>} {}
 @deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214> route-map @var{word}} {}
 @deffnx {OSPF Command} {no redistribute (kernel|connected|static|rip|bgp)} {}
-Redistribute routes of the specified protocol or kind into OSPF, with the
-metric type and metric set if specified, filtering the routes using the given
-route-map if specified.
+Redistribute routes of the specified protocol or kind into OSPF, with
+the metric type and metric set if specified, filtering the routes using
+the given route-map if specified. Redistributed routes may also be
+filtered with distribute-lists, see @ref{ospf distribute-list}.
+
+Redistributed routes are distributed as into OSPF as Type-5 External
+LSAs into links to areas that accept external routes, Type-7 External LSAs
+for NSSA areas and are not redistributed at all into Stub areas, where
+external routes are not permitted.
+
+Note that for connected routes, one may instead use
+@dfn{passive-interface}, see @ref{OSPF passive-interface}.
 @end deffn
 
 @deffn {OSPF Command} {default-information originate} {}
@@ -498,8 +530,11 @@ type. If the 'always' keyword is given then the default is always
 advertised, even when there is no default present in the routing table.
 @end deffn
 
+@anchor{ospf distribute-list}
 @deffn {OSPF Command} {distribute-list NAME out (kernel|connected|static|rip|ospf} {}
 @deffnx {OSPF Command} {no distribute-list NAME out (kernel|connected|static|rip|ospf} {}
+Apply the access-list filter, NAME, to redistributed routes of the given type
+before allowing the routes to redistributed into OSPF (@pxref{OSPF redistribute}).
 @end deffn
 
 @deffn {OSPF Command} {default-metric <0-16777214>} {}
diff --git a/doc/overview.texi b/doc/overview.texi
index 2cb2a630..435834b7 100644
--- a/doc/overview.texi
+++ b/doc/overview.texi
@@ -5,7 +5,7 @@
   @uref{http://www.quagga.net,,Quagga} is a routing software package that
 provides TCP/IP based routing services with routing protocols support such
 as RIPv1, RIPv2, RIPng, OSPFv2, OSPFv3, BGP-4, and BGP-4+ (@pxref{Supported
-RFC}). Quagga also supports special BGP Route Reflector and Route Server
+RFCs}). Quagga also supports special BGP Route Reflector and Route Server
 behavior.  In addition to traditional IPv4 routing protocols, Quagga also
 supports IPv6 routing protocols.  With SNMP daemon which supports SMUX
 protocol, Quagga provides routing protocol MIBs (@pxref{SNMP Support}).
@@ -22,7 +22,7 @@ can use Quagga library as your program's client user interface.
 * About Quagga::                Basic information about Quagga
 * System Architecture::         The Quagga system architecture
 * Supported Platforms::         Supported platforms and future plans
-* Supported RFC::               Supported RFCs
+* Supported RFCs::               Supported RFCs
 * How to get Quagga::            
 * Mailing List::                Mailing list information
 * Bug Reports::                 Mail address for bug data
@@ -113,7 +113,7 @@ architecture creates new possibilities for the routing system.
 @end group
 @end example
 
-  Multi-process architecture brings extensibility, modularity and
+Multi-process architecture brings extensibility, modularity and
 maintainability.  At the same time it also brings many configuration files
 and terminal interfaces.  Each daemon has it's own configuration file and
 terminal interface.  When you configure a static route, it must be done in
@@ -123,7 +123,7 @@ thing.  To resolve the problem, Quagga provides integrated user interface
 shell called @command{vtysh}.  @command{vtysh} connects to each daemon with
 UNIX domain socket and then works as a proxy for user input.
 
-  Quagga was planned to use multi-threaded mechanism when it runs with a
+Quagga was planned to use multi-threaded mechanism when it runs with a
 kernel that supports multi-threads.  But at the moment, the thread library
 which comes with @sc{gnu}/Linux or FreeBSD has some problems with running
 reliable services such as routing software, so we don't use threads at all. 
@@ -139,20 +139,20 @@ events.
 @cindex Compatibility with other systems
 @cindex Operating systems that support Quagga
 
-  Currently Quagga supports @sc{gnu}/Linux, BSD and Solaris. Porting Quagga
+Currently Quagga supports @sc{gnu}/Linux, BSD and Solaris. Porting Quagga
 to other platforms is not too difficult as platform dependent code should
 most be limited to the @command{zebra} daemon.  Protocol daemons are mostly
 platform independent. Please let us know when you find out Quagga runs on a
 platform which is not listed below.
 
-  The list of officially supported platforms are listed below. Note that
+The list of officially supported platforms are listed below. Note that
 Quagga may run correctly on other platforms, and may run with partial
 functionality on further platforms.
 
 @sp 1
 @itemize @bullet
 @item
-@sc{gnu}/Linux 2.2.x and higher
+@sc{gnu}/Linux 2.4.x and higher
 @item
 FreeBSD 4.x and higher
 @item
@@ -160,26 +160,12 @@ NetBSD 1.6 and higher
 @item
 OpenBSD 2.5 and higher
 @item
-Solaris 2.6 and higher (IPv6 support requires a patch at moment)
+Solaris 8 and higher
 @end itemize
 
-@sp 1
-  Some IPv6 stacks are in development.  Quagga supports following IPv6
-stacks.  For BSD, we recommend KAME IPv6 stack.  Solaris IPv6 stack is
-not yet supported.
-@sp 1
-@itemize @bullet
-@item
-Linux IPv6 stack for GNU/Linux 2.2.x and higher.
-@item
-KAME IPv6 stack for BSD.
-@item
-INRIA IPv6 stack for BSD.
-@end itemize
-
-@node Supported RFC
+@node Supported RFCs
 @comment  node-name,  next,  previous,  up
-@section Supported RFC
+@section Supported RFCs
 
   Below is the list of currently supported RFC's.
 
@@ -258,26 +244,18 @@ November 1995.}
 @comment  node-name,  next,  previous,  up
 @section How to get Quagga
 
-Quagga is still beta software and there is no officially released
-version.
+The official Quagga web-site is located at:
 
-Zebra's official web page is located at:
+@uref{http://www.quagga.net/}
 
-@uref{http://www.gnu.org/software/zebra/zebra.html}.
+and contains further information, as well as links to additional
+resources. 
 
-The original Zebra web site is located at: 
+@uref{http://www.quagga.net/,Quagga} is a fork of GNU Zebra, whose
+web-site is located at:
 
 @uref{http://www.zebra.org/}.
 
-As of this writing, development by zebra.org on Zebra has slowed down. Some
-work is being done by third-parties to try maintain bug-fixes and
-enhancements to the current Zebra code-base, which has resulted in a fork of
-Zebra called Quagga, see:
-
-@uref{http://www.quagga.net/}
-
-for further information, as well as links to additional zebra resources.
-
 @node Mailing List
 @comment  node-name,  next,  previous,  up
 @section Mailing List
diff --git a/doc/quagga.texi b/doc/quagga.texi
index 6e7ac1c7..ff8002c8 100644
--- a/doc/quagga.texi
+++ b/doc/quagga.texi
@@ -3,8 +3,6 @@
 @setchapternewpage odd
 @settitle @uref{http://www.quagga.net,,@value{PACKAGE_NAME}}
 @setfilename quagga.info
-@defcodeindex op
-@synindex pg cp
 @c %**end of header
 
 @c Set variables - sourced from defines.texi
@@ -100,6 +98,7 @@ for @value{PACKAGE_STRING}. @uref{http://www.quagga.net,,Quagga} is a fork of
 * Packet Binary Dump Format::
 * Command Index::
 * VTY Key Index::
+* Index::
 @end menu
 @contents
 
@@ -132,4 +131,8 @@ for @value{PACKAGE_STRING}. @uref{http://www.quagga.net,,Quagga} is a fork of
 
 @printindex ky
 
+@node Index
+@unnumbered Index
+
+@printindex cp
 @bye
diff --git a/doc/routeserver.texi b/doc/routeserver.texi
index afbbd8f0..f4a45462 100644
--- a/doc/routeserver.texi
+++ b/doc/routeserver.texi
@@ -261,6 +261,7 @@ against the other two routers. These peerings have In and Out route-maps
 configured, named like ``PEER-X-IN'' or ``PEER-X-OUT''. For example the
 configuration file for router RA could be the following:
 
+@exampleindent 0
 @example
 #Configuration for router 'RA'
 !