2005-10-29 Paul Jakma <paul@dishone.st>
* ospfd.texi: Document the new spf and max-metric commands, and
the additional form of dead-interval. Add documentation for
various other commands. Cleanup misc stuff, citations, etc.
Add some example configurations.
* overview.texi: RFC3137 support added.
* Makefile.am: Make quagga.pdf depend on the _TEXINFOS
variable, this still doesn't fix the dependency though,
sadly.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 263a2d7..dd8b7ef 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,14 @@
+2005-10-29 Paul Jakma <paul@dishone.st>
+
+ * ospfd.texi: Document the new spf and max-metric commands, and
+ the additional form of dead-interval. Add documentation for
+ various other commands. Cleanup misc stuff, citations, etc.
+ Add some example configurations.
+ * overview.texi: RFC3137 support added.
+ * Makefile.am: Make quagga.pdf depend on the _TEXINFOS
+ variable, this still doesn't fix the dependency though,
+ sadly.
+
2005-10-11 Paul Jakma <paul@dishone.st>
* quagga.texi: Rejiggle the copyright sections a bit, seems to
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0c1960b..22dec5a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -40,7 +40,7 @@
# us to have a generic automatic .pdf rule to build the figure sources
# because it cant just work from the png's directly it seems - contrary
# to the documentation...
-quagga.pdf: $(srcdir)/quagga.texi $(figures_pdf)
+quagga.pdf: $(info_TEXINFOS) $(figures_pdf)
$(TEXI2PDF) -o "$@" $<
quagga_TEXINFOS = appendix.texi basic.texi bgpd.texi filter.texi install.texi \
diff --git a/doc/ospfd.texi b/doc/ospfd.texi
index 789e9bf..65d4e84 100644
--- a/doc/ospfd.texi
+++ b/doc/ospfd.texi
@@ -1,11 +1,13 @@
@node OSPFv2
@chapter OSPFv2
- OSPF version 2 is a routing protocol which described in
-@asis{RFC2328} - @cite{OSPF Version 2}. OSPF is IGP (Interior Gateway
-Protocols). Compared with RIP, OSPF can provide scalable network
-support and faster convergence time. OSPF is widely used in large
-networks such as ISP backbone and enterprise networks.
+@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{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::
@@ -15,18 +17,20 @@
* Redistribute routes to OSPF::
* Showing OSPF information::
* Debugging OSPF::
+* OSPF Configuration Examples::
@end menu
@node Configuring ospfd
@section Configuring ospfd
-There is no @command{ospfd} specific options. Common options can be
+There are no @command{ospfd} specific options. Common options can be
specified (@pxref{Common Invocation Options}) to @command{ospfd}.
-@command{ospfd} needs interface information from @command{zebra}. So
-please make it sure @command{zebra} is running before invoking
-@command{ospfd}.
+@command{ospfd} needs to acquire interface information from
+@command{zebra} in order to function. Therefore @command{zebra} must be
+running before invoking @command{ospfd}. Also, if @command{zebra} is
+restarted then @command{ospfd} must be too.
-Like other daemons, @command{ospfd} configuration is done in OSPF
+Like other daemons, @command{ospfd} configuration is done in @acronym{OSPF}
specific configuration file @file{ospfd.conf}.
@node OSPF router
@@ -44,15 +48,23 @@
@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
+address of the router, but need not be - it can be any arbitrary 32bit
+number. However it MUST be unique within the entire OSPF domain to the
+OSPF speaker - bad things will happen if multiple OSPF speakers are
+configured with the same router-ID! If one is not specified then
+@command{ospfd} will obtain a router-ID automatically from @command{zebra}.
@end deffn
@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.
+
More information regarding the behaviour controlled by this command can
-be found in draft-ietf-ospf-abr-alt-05.txt and
-draft-ietf-ospf-shortcut-abr-02.txt
-Quote: "Though the definition of the Area Border Router (ABR)
+be found in @cite{RFC 3509, Alternative Implementations of OSPF Area
+Border Routers}, and @cite{draft-ietf-ospf-shortcut-abr-02.txt}.
+
+Quote: "Though the definition of the @acronym{ABR,Area Border Router}
in the OSPF specification does not require a router with multiple
attached areas to have a backbone connection, it is actually
necessary to provide successful routing to the inter-area and
@@ -60,33 +72,122 @@
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 rfc2328, the sucessor to 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 that inter-area
-paths and intra-area path are now of equal preference but still both
-preferred to external paths.
+This @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
+that inter-area paths and intra-area path are now of equal preference
+but still both preferred to external paths.
+
+This command should NOT be set normally.
@end deffn
@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}.
+
@end deffn
-@deffn {OSPF Command} {timers spf <0-4294967295> <0-4294967295>} {}
-@deffnx {OSPF Command} {no timers spf} {}
+@deffn {OSPF Command} {timers throttle spf @var{delay} @var{initial-holdtime} @var{max-holdtime}} {}
+@deffnx {OSPF Command} {no timers throttle spf} {}
+This command sets the initial @var{delay}, the @var{initial-holdtime}
+and the @var{maximum-holdtime} between when SPF is calculated and the
+event which triggered the calculation. The times are specified in
+milliseconds and must be in the range of 0 to 600000 milliseconds.
+
+The @var{delay} specifies the minimum amount of time to delay SPF
+calculation (hence it affects how long SPF calculation is delayed after
+an event which occurs outside of the holdtime of any previous SPF
+calculation, and also serves as a minimum holdtime).
+
+Consecutive SPF calculations will always be seperated by at least
+'hold-time' milliseconds. The hold-time is adaptive and initially is
+set to the @var{initial-holdtime} configured with the above command.
+Events which occur within the holdtime of the previous SPF calculation
+will cause the holdtime to be increased by @var{initial-holdtime}, bounded
+by the @var{maximum-holdtime} configured with this command. If the adaptive
+hold-time elapses without any SPF-triggering event occuring then
+the current holdtime is reset to the @var{initial-holdtime}. The current
+holdtime can be viewed with @ref{show ip ospf}, where it is expressed as
+a multiplier of the @var{initial-holdtime}.
+
+@example
+@group
+router ospf
+ timers throttle spf 200 400 10000
+@end group
+@end example
+
+In this example, the @var{delay} is set to 200ms, the @var{initial
+holdtime} is set to 400ms and the @var{maximum holdtime} to 10s. Hence
+there will always be at least 200ms between an event which requires SPF
+calculation and the actual SPF calculation. Further consecutive SPF
+calculations will always be seperated by between 400ms to 10s, the
+hold-time increasing by 400ms each time an SPF-triggering event occurs
+within the hold-time of the previous SPF calculation.
+
+This command supercedes the @command{timers spf} command in previous Quagga
+releases.
@end deffn
-@deffn {OSPF Command} {refresh group-limit <0-10000>} {}
-@deffnx {OSPF Command} {refresh per-slice <0-10000>} {}
-@deffnx {OSPF Command} {refresh age-diff <0-10000>} {}
+@deffn {OSPF Command} {max-metric router-lsa [on-startup|on-shutdown] <5-86400>} {}
+@deffnx {OSPF Command} {max-metric router-lsa administrative} {}
+@deffnx {OSPF Command} {no max-metric router-lsa [on-startup|on-shutdown|administrative]} {}
+This enables @cite{RFC3137, OSPF Stub Router Advertisement} support,
+where the OSPF process describes its transit links in its router-LSA as
+having infinite distance so that other routers will avoid calculating
+transit paths through the router while still being able to reach
+networks through the router.
+
+This support may be enabled administratively (and indefinitely) or
+conditionally. Conditional enabling of max-metric router-lsas can be
+for a period of seconds after startup and/or for a period of seconds
+prior to shutdown.
+
+Enabling this for a period after startup allows OSPF to converge fully
+first without affecting any existing routes used by other routers,
+while still allowing any connected stub links and/or redistributed
+routes to be reachable. Enabling this for a period of time in advance
+of shutdown allows the router to gracefully excuse itself from the OSPF
+domain.
+
+Enabling this feature administratively allows for administrative
+intervention for whatever reason, for an indefinite period of time.
+Note that if the configuration is written to file, this administrative
+form of the stub-router command will also be written to file. If
+@command{ospfd} is restarted later, the command will then take effect
+until manually deconfigured.
+
+Configured state of this feature as well as current status, such as the
+number of second remaining till on-startup or on-shutdown ends, can be
+viewed with the @ref{show ip ospf} command.
@end deffn
-@deffn {OSPF Command} {auto-cost refrence-bandwidth <1-4294967>} {}
-@deffnx {OSPF Command} {no auto-cost refrence-bandwidth} {}
+@deffn {OSPF Command} {auto-cost reference-bandwidth <1-4294967>} {}
+@deffnx {OSPF Command} {no auto-cost reference-bandwidth} {}
+This sets the reference bandwidth for cost calculations, where this
+bandwidth is considered equivalent to an OSPF cost of 1, specified in
+Mbits/s. The default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s
+or higher will have a cost of 1. Cost of lower bandwidth links will be
+scaled with reference to this cost).
+
+This configuration setting MUST be consistent across all routers within the
+OSPF domain.
@end deffn
@deffn {OSPF Command} {network @var{a.b.c.d/m} area @var{a.b.c.d}} {}
@@ -97,12 +198,14 @@
an address from range 192.168.1.0/24 then the command below enables ospf
on this interface so router can provide network information to the other
ospf routers via this interface.
+
@example
@group
router ospf
network 192.168.1.0/24 area 0.0.0.0
@end group
@end example
+
Prefix length in interface must be equal or bigger (ie. smaller network) than
prefix length in network statement. For example statement above doesn't enable
ospf on interface with address 192.168.1.1/23, but it does on interface with
@@ -121,6 +224,7 @@
router-LSAs (Type-1) and network-LSAs (Type-2) (ie. LSAs with scope area) can
be summarized. Type-5 AS-external-LSAs can't be summarized - their scope is AS.
Summarizing Type-7 AS-external-LSAs isn't supported yet by Quagga.
+
@example
@group
router ospf
@@ -129,6 +233,7 @@
area 0.0.0.10 range 10.0.0.0/8
@end group
@end example
+
With configuration above one Type-3 Summary-LSA with routing info 10.0.0.0/8 is
announced into backbone area if area 0.0.0.10 contains at least one intra-area
network (ie. described with router or network LSA) from this range.
@@ -144,6 +249,7 @@
@deffn {OSPF Command} {area @var{a.b.c.d} range IPV4_PREFIX substitute IPV4_PREFIX} {}
@deffnx {OSPF Command} {no area @var{a.b.c.d} range IPV4_PREFIX substitute IPV4_PREFIX} {}
Substitute summarized prefix with another prefix.
+
@example
@group
router ospf
@@ -152,6 +258,7 @@
area 0.0.0.10 range 10.0.0.0/8 substitute 11.0.0.0/8
@end group
@end example
+
One Type-3 summary-LSA with routing info 11.0.0.0/8 is announced into backbone area if
area 0.0.0.10 contains at least one intra-area network (ie. described with router-LSA or
network-LSA) from range 10.0.0.0/8.
@@ -168,22 +275,33 @@
@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
+that the 'abr-type' be set to 'shortcut'.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} stub} {}
@deffnx {OSPF Command} {area <0-4294967295> stub} {}
@deffnx {OSPF Command} {no area @var{a.b.c.d} stub} {}
@deffnx {OSPF Command} {no area <0-4294967295> stub} {}
+Configure the area to be a stub area. That is, an area where no router
+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.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} stub no-summary} {}
@deffnx {OSPF Command} {area <0-4294967295> stub no-summary} {}
@deffnx {OSPF Command} {no area @var{a.b.c.d} stub no-summary} {}
@deffnx {OSPF Command} {no area <0-4294967295> stub no-summary} {}
+Prevents an @command{ospfd} ABR from injecting inter-area
+summaries into the specified stub area.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} default-cost <0-16777215>} {}
@deffnx {OSPF Command} {no area @var{a.b.c.d} default-cost <0-16777215>} {}
+Set the cost of default-summary LSAs announced to stubby areas.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} export-list NAME} {}
@@ -192,6 +310,7 @@
@deffnx {OSPF Command} {no area <0-4294967295> export-list NAME} {}
Filter Type-3 summary-LSAs announced to other areas originated from intra-
area paths from specified area.
+
@example
@group
router ospf
@@ -203,11 +322,14 @@
access-list foo deny any
@end group
@end example
+
With example above any intra-area paths from area 0.0.0.10 and from range
10.10.0.0/16 (for example 10.10.1.0/24 and 10.10.2.128/30) are announced into
other areas as Type-3 summary-LSA's, but any others (for example 10.11.0.0/16
or 10.128.30.16/30) aren't.
-This command makes sense in ABR only.
+
+This command is only relevant if the router is an ABR for the specified
+area.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} import-list NAME} {}
@@ -234,16 +356,20 @@
@deffnx {OSPF Command} {area <0-4294967295> authentication} {}
@deffnx {OSPF Command} {no area @var{a.b.c.d} authentication} {}
@deffnx {OSPF Command} {no area <0-4294967295> authentication} {}
+Specify that simple password authentication should be used for the given
+area.
@end deffn
@deffn {OSPF Command} {area @var{a.b.c.d} authentication message-digest} {}
@deffnx {OSPF Command} {area <0-4294967295> authentication message-digest} {}
+Specify that OSPF packets should be authenticated with MD5 HMACs for the given
+area.
@end deffn
@node OSPF interface
@section OSPF interface
-@deffn {Interface Command} {ip ospf authentication-key AUTH_KEY} {}
+@deffn {Interface Command} {ip ospf authentication-key @var{AUTH_KEY}} {}
@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.
@@ -256,7 +382,7 @@
digest. KEY is the actual message digest key up to 16 chars.
Note that OSPF MD5 authentication requires that time never go backwards
-(correct time is not important, only that it never goes backwards), even
+(correct time is NOT important, only that it never goes backwards), even
across resets, if ospfd is to be able to promptly reestabish adjacencies
with its neighbours after restarts/reboots. The host should have system
time be set at boot from an external source (eg battery backed clock, NTP,
@@ -271,11 +397,22 @@
metric field and used for SPF calculation.
@end deffn
+@anchor{ip ospf dead-interval minimal}
@deffn {Interface Command} {ip ospf dead-interval <1-65535>} {}
+@deffnx {Interface Command} {ip ospf dead-interval minimal hello-multiplier <2-20>} {}
@deffnx {Interface Command} {no ip ospf dead-interval} {}
Set number of seconds for RouterDeadInterval timer value used for Wait Timer
and Inactivity Timer. This value must be the same for all routers attached
to a common network. The default value is 40 seconds.
+
+If 'minimal' is specified instead, then the dead-interval is set to 1
+second and one must specify a hello-multiplier. The hello-multiplier
+specifies how many Hellos to send per second, from 2 (every 500ms) to
+20 (every 50ms). Thus one can have 1s convergence time for OSPF. If this form
+is specified, then the hello-interval advertised in Hello packets is set to
+0 and the hello-interval on received Hello packets is not checked, thus
+the hello-multiplier need NOT be the same across multiple routers on a common
+link.
@end deffn
@deffn {Interface Command} {ip ospf hello-interval <1-65535>} {}
@@ -284,6 +421,9 @@
Hello packet will be sent every timer value seconds on the specified interface.
This value must be the same for all routers attached to a common network.
The default value is 10 seconds.
+
+This command has no effect if @ref{ip ospf dead-interval minimal} is also
+specified for the interface.
@end deffn
@deffn {Interface Command} {ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point)} {}
@@ -325,6 +465,9 @@
@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.
@end deffn
@deffn {OSPF Command} {default-information originate} {}
@@ -336,6 +479,10 @@
@deffnx {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2)} {}
@deffnx {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2) route-map @var{word}} {}
@deffnx {OSPF Command} {no default-information originate} {}
+Originate an AS-External (type-5) LSA describing a default route into
+all external-routing capable areas, of the specified metric and metric
+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
@deffn {OSPF Command} {distribute-list NAME out (kernel|connected|static|rip|ospf} {}
@@ -361,10 +508,15 @@
@node Showing OSPF information
@section Showing OSPF information
+@anchor{show ip ospf}
@deffn {Command} {show ip ospf} {}
+Show information on a variety of general OSPF and area state and configuration
+information.
@end deffn
@deffn {Command} {show ip ospf interface [INTERFACE]} {}
+Show state and configuration of OSPF the specified interface, or all
+interfaces if no interface is given.
@end deffn
@deffn {Command} {show ip ospf neighbor} {}
@@ -390,10 +542,8 @@
@deffn {Command} {show ip ospf database self-originate} {}
@end deffn
-@deffn {Command} {show ip ospf refresher} {}
-@end deffn
-
@deffn {Command} {show ip ospf route} {}
+Show the OSPF routing table, as determined by the most recent SPF calculation.
@end deffn
@node Debugging OSPF
@@ -430,3 +580,55 @@
@deffn {Command} {show debugging ospf} {}
@end deffn
+@node OSPF Configuration Examples
+@section OSPF Configuration Examples
+A simple example, with MD5 authentication enabled:
+
+@example
+@group
+!
+interface bge0
+ ip ospf authentication message-digest
+ ip ospf message-digest-key 1 md5 ABCDEFGHIJK
+!
+router ospf
+ network 192.168.0.0/16 area 0.0.0.1
+ area 0.0.0.1 authentication message-digest
+@end group
+@end example
+
+An @acronym{ABR} router, with MD5 authentication and performing summarisation
+of networks between the areas:
+
+@example
+@group
+!
+password ABCDEF
+log file /var/log/quagga/ospfd.log
+service advanced-vty
+!
+interface eth0
+ ip ospf authentication message-digest
+ ip ospf message-digest-key 1 md5 ABCDEFGHIJK
+!
+interface ppp0
+!
+interface br0
+ ip ospf authentication message-digest
+ ip ospf message-digest-key 2 md5 XYZ12345
+!
+router ospf
+ ospf router-id 192.168.0.1
+ redistribute connected
+ passive interface ppp0
+ network 192.168.0.0/24 area 0.0.0.0
+ network 10.0.0.0/16 area 0.0.0.0
+ network 192.168.1.0/24 area 0.0.0.1
+ area 0.0.0.0 authentication message-digest
+ area 0.0.0.0 range 10.0.0.0/16
+ area 0.0.0.0 range 192.168.0.0/24
+ area 0.0.0.1 authentication message-digest
+ area 0.0.0.1 range 10.2.0.0/16
+!
+@end group
+@end example
diff --git a/doc/overview.texi b/doc/overview.texi
index 911553f..2cb2a63 100644
--- a/doc/overview.texi
+++ b/doc/overview.texi
@@ -229,6 +229,8 @@
@item @asis{RFC2842}
@cite{Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.}
+@item @asis{RFC3137}
+@cite{OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin, D. McPherson. June 2001}
@end table
When SNMP support is enabled, below RFC is also supported.