[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.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index a0c3995..02324b9 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 c859782..4c4b04b 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 @@
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 @@
@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 @@
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 @@
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 @@
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 @@
@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 @@
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 @@
@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 @@
@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 @@
@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 @@
@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 @@
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 2cb2a63..435834b 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 @@
* 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 @@
@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 @@
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 @@
@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 @@
@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,25 +244,17 @@
@comment node-name, next, previous, up
@section How to get Quagga
-Quagga is still beta software and there is no officially released
-version.
-
-Zebra's official web page is located at:
-
-@uref{http://www.gnu.org/software/zebra/zebra.html}.
-
-The original Zebra 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:
+The official Quagga web-site is located at:
@uref{http://www.quagga.net/}
-for further information, as well as links to additional zebra resources.
+and contains further information, as well as links to additional
+resources.
+
+@uref{http://www.quagga.net/,Quagga} is a fork of GNU Zebra, whose
+web-site is located at:
+
+@uref{http://www.zebra.org/}.
@node Mailing List
@comment node-name, next, previous, up
diff --git a/doc/quagga.texi b/doc/quagga.texi
index 6e7ac1c..ff8002c 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 @@
* Packet Binary Dump Format::
* Command Index::
* VTY Key Index::
+* Index::
@end menu
@contents
@@ -132,4 +131,8 @@
@printindex ky
+@node Index
+@unnumbered Index
+
+@printindex cp
@bye
diff --git a/doc/routeserver.texi b/doc/routeserver.texi
index afbbd8f..f4a4546 100644
--- a/doc/routeserver.texi
+++ b/doc/routeserver.texi
@@ -261,6 +261,7 @@
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'
!