From: Quentin Young Date: Fri, 2 Feb 2018 17:19:28 +0000 (-0500) Subject: doc: fixup more broken xrefs X-Git-Tag: frr-5.0-dev~165^2~47 X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=6ee602cd137b63c2a3913d76d79819c5da9f9ccb;p=mirror%2Ffrr.git doc: fixup more broken xrefs Signed-off-by: Quentin Young --- diff --git a/doc/user/appendix.rst b/doc/user/appendix.rst index 8f0343da58..6120c3b989 100644 --- a/doc/user/appendix.rst +++ b/doc/user/appendix.rst @@ -3,10 +3,7 @@ Packet Binary Dump Format ========================= -Packet Binary Dump Format -------------------------- - -FRR can dump routing protocol packet into file with a binary format. +FRR can dump routing protocol packets into a file with a binary format. It seems to be better that we share the MRT's header format for backward compatibility with MRT's dump logs. We should also define the @@ -211,12 +208,13 @@ The file specified in "File Name" contains all routing entries, which are in the format of ``subtype == BGP4MP_ENTRY``. :: + Constants: - /* type value */ + /\* type value \*/ #define MSG_PROTOCOL_BGP4MP 16 #define MSG_PROTOCOL_BGP4MP_ET 17 - /* subtype value */ + /\* subtype value \*/ #define BGP4MP_STATE_CHANGE 0 #define BGP4MP_MESSAGE 1 #define BGP4MP_ENTRY 2 diff --git a/doc/user/isisd.rst b/doc/user/isisd.rst index 23b1af57ab..139d024e4f 100644 --- a/doc/user/isisd.rst +++ b/doc/user/isisd.rst @@ -39,12 +39,10 @@ writing, *isisd* does not support multiple ISIS processes. .. index:: no router isis WORD .. clicmd:: no router isis WORD - .. _router-isis-word: - Enable or disable the ISIS process by specifying the ISIS domain with 'WORD'. *isisd* does not yet support multiple ISIS processes but you must specify the name of ISIS process. The ISIS process name 'WORD' is then used - for interface (see command :ref:`ip-router-isis-word`). + for interface (see command :clicmd:`ip router isis WORD`). .. index:: net XX.XXXX. ... .XXX.XX .. clicmd:: net XX.XXXX. ... .XXX.XX @@ -91,8 +89,6 @@ writing, *isisd* does not support multiple ISIS processes. .. index:: no metric-style .. clicmd:: no metric-style -.. _metric-style: - Set old-style (ISO 10589) or new-style packet formats: - narrow @@ -203,7 +199,7 @@ ISIS interface Activate ISIS adjacency on this interface. Note that the name of ISIS instance must be the same as the one used to configure the ISIS process - (see command :ref:`router-isis-word`). + (see command :clicmd:`router isis WORD`). .. index:: isis circuit-type [level-1 | level-1-2 | level-2] .. clicmd:: isis circuit-type [level-1 | level-1-2 | level-2] @@ -284,7 +280,7 @@ ISIS interface Set default metric value globally, for an area (level-1) or a domain (level-2). Max value depend if metric support narrow or wide value (see - command :ref:`metric-style`). + command :clicmd:`metric-style [narrow | transition | wide]`). .. index:: isis network point-to-point .. clicmd:: isis network point-to-point diff --git a/doc/user/ospf_fundamentals.rst b/doc/user/ospf_fundamentals.rst index b9c2139a20..479b53a73c 100644 --- a/doc/user/ospf_fundamentals.rst +++ b/doc/user/ospf_fundamentals.rst @@ -121,10 +121,8 @@ OSPF defines several related mechanisms, used to manage synchronisation of :abbr:`LSDB` s between neighbours as neighbours form adjacencies and the propogation, or :term:`flooding` of new or updated :abbr:`LSA` s. -:ref:`ospf-flooding`. - - .. index:: OSPF Areas overview + .. _ospf-areas: Areas @@ -174,7 +172,11 @@ All LSAs share a common header with the following information: - Advertising Router - The Router ID of the router originating the LSA, see :ref:`ospf-router-id`. + The Router ID of the router originating the LSA. + +.. seealso:: + + :clicmd:`ospf router-id A.B.C.D`. - LSA ID @@ -186,7 +188,7 @@ All LSAs share a common header with the following information: The combination of the Type, ID and Advertising Router ID must uniquely identify the :abbr:`LSA`. There can however be multiple instances of an LSA with the same Type, LSA ID and Advertising Router ID, see - :ref:`ospf-lsa-sequence-number,,lsa-sequence-number`. + :ref:`Sequence Number `. - Age @@ -206,7 +208,7 @@ All LSAs share a common header with the following information: a router has shutdown without flushing its LSA(s), e.g. where it has become disconnected from the network. Such LSAs do little harm. - .. _ospf-lsa-sequence-number: +.. _ospf-lsa-sequence-number: - Sequence Number @@ -232,7 +234,7 @@ called :term:`intra-area routes`. Cost The output cost of that interface, scaled inversely to some commonly known - reference value, :ref:`ospf-auto-cost-reference-bandwidth,,auto-cost-reference-bandwidth`. + reference value, :clicmd:`auto-cost reference-bandwidth (1-4294967`. Link Type Transit Network @@ -272,7 +274,7 @@ called :term:`intra-area routes`. Stub links may also be used as a way to describe links on which OSPF is *not* spoken, known as :term:`passive interfaces`, see - :ref:`ospf-passive-interface,,passive-interface`. + :clicmd:`passive-interface INTERFACE`. - Network LSA diff --git a/doc/user/ospfd.rst b/doc/user/ospfd.rst index 5b2b5abd48..430b32af1c 100644 --- a/doc/user/ospfd.rst +++ b/doc/user/ospfd.rst @@ -51,8 +51,6 @@ writing, *ospfd* does not support multiple OSPF processes. .. index:: no ospf router-id .. clicmd:: no ospf router-id -.. _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 @@ -67,36 +65,36 @@ writing, *ospfd* does not support multiple OSPF processes. .. index:: no ospf abr-type TYPE .. clicmd:: no ospf abr-type TYPE - `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 - FRR, 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 (:ref:`ospf-virtual-link`). - - More information regarding the behaviour controlled by this command can - be found in :rfc:`3509`, and :t:`draft-ietf-ospf-shortcut-abr-02.txt`. - - Quote: "Though the definition of the :abbr:`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 - 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." + `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 + FRR, 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 (:clicmd:`area A.B.C.D virtual-link A.B.C.D`). + + More information regarding the behaviour controlled by this command can + be found in :rfc:`3509`, and :t:`draft-ietf-ospf-shortcut-abr-02.txt`. + + Quote: "Though the definition of the :abbr:`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 + 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." .. index:: ospf rfc1583compatibility .. clicmd:: ospf rfc1583compatibility @@ -129,16 +127,14 @@ writing, *ospfd* does not support multiple OSPF processes. .. index:: no passive-interface INTERFACE .. clicmd:: no passive-interface INTERFACE -.. _ospf-passive-interface: - - Do not speak OSPF interface on the - given interface, but do advertise the interface as a stub link in the - router-:abbr:`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 (:ref:`redistribute-routes-to-ospf`). This is the only way to - advertise non-OSPF links into stub areas. + Do not speak OSPF interface on the + given interface, but do advertise the interface as a stub link in the + router-:abbr:`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 (:ref:`redistribute-routes-to-ospf`). This is the only way to + advertise non-OSPF links into stub areas. .. index:: timers throttle spf DELAY INITIAL-HOLDTIME MAX-HOLDTIME .. clicmd:: timers throttle spf DELAY INITIAL-HOLDTIME MAX-HOLDTIME @@ -164,7 +160,7 @@ writing, *ospfd* does not support multiple OSPF processes. by the `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 `initial-holdtime`. The current - holdtime can be viewed with :ref:`show-ip-ospf`, where it is expressed as + holdtime can be viewed with :clicmd:`show ip ospf`, where it is expressed as a multiplier of the `initial-holdtime`. :: @@ -218,7 +214,7 @@ writing, *ospfd* does not support multiple OSPF processes. 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. + viewed with the :clicmd:`show ip ospf` command. .. index:: auto-cost reference-bandwidth (1-4294967) .. clicmd:: auto-cost reference-bandwidth (1-4294967) @@ -226,8 +222,6 @@ writing, *ospfd* does not support multiple OSPF processes. .. index:: no auto-cost reference-bandwidth .. clicmd:: no auto-cost reference-bandwidth -.. _OSPF-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 @@ -250,8 +244,6 @@ writing, *ospfd* does not support multiple OSPF processes. .. index:: no network A.B.C.D/M area (0-4294967295) .. clicmd:: no network A.B.C.D/M area (0-4294967295) -.. _ospf-network-command: - This command specifies the OSPF enabled interface(s). If the interface has 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 @@ -276,7 +268,7 @@ writing, *ospfd* does not support multiple OSPF processes. contains the local address prefix of the interface. In some cases it may be more convenient to enable OSPF on a per - interface/subnet basis (:ref:`ospf-ip-ospf-area-command`). + interface/subnet basis (:clicmd:`ip ospf area AREA [ADDR]`). .. _ospf-area: @@ -357,8 +349,6 @@ OSPF area .. index:: no area (0-4294967295) virtual-link A.B.C.D .. clicmd:: no area (0-4294967295) virtual-link A.B.C.D -.. _OSPF-virtual-link: - .. index:: area A.B.C.D shortcut .. clicmd:: area A.B.C.D shortcut @@ -513,15 +503,13 @@ OSPF area .. index:: area (0-4294967295) authentication message-digest .. clicmd:: area (0-4294967295) authentication message-digest -.. _area-authentication-message-digest: - - Specify that OSPF packets - must be authenticated with MD5 HMACs within the given area. Keying - material must also be configured on a per-interface basis (:ref:`ip-ospf-message-digest-key`). + Specify that OSPF packets must be authenticated with MD5 HMACs within the + given area. Keying material must also be configured on a per-interface basis + (:clicmd:`ip ospf message-digest-key`). - MD5 authentication may also be configured on a per-interface basis - (:ref:`ip-ospf-authentication-message-digest`). Such per-interface - settings will override any per-area authentication setting. + MD5 authentication may also be configured on a per-interface basis + (:clicmd:`ip ospf authentication message-digest`). Such per-interface + settings will override any per-area authentication setting. .. _ospf-interface: @@ -534,11 +522,10 @@ OSPF interface .. index:: no ip ospf area [ADDR] .. clicmd:: no ip ospf area [ADDR] -.. _ospf-ip-ospf-area-command: - Enable OSPF on the interface, optionally restricted to just the IP address - given by `ADDR`, putting it in the `AREA` area. Per interface area - settings take precedence to network commands (:ref:`ospf-network-command`). + given by `ADDR`, putting it in the `AREA` area. Per interface area settings + take precedence to network commands + (:clicmd:`network A.B.C.D/M area A.B.C.D`). If you have a lot of interfaces, and/or a lot of subnets, then enabling OSPF via this command may result in a slight performance improvement. @@ -553,26 +540,24 @@ OSPF interface all OSPF packets are authenticated. `AUTH_KEY` has length up to 8 chars. Simple text password authentication is insecure and deprecated in favour of - MD5 HMAC authentication (:ref:`ip-ospf-authentication-message-digest`). + MD5 HMAC authentication. .. index:: ip ospf authentication message-digest .. clicmd:: ip ospf authentication message-digest -.. _ip-ospf-authentication-message-digest: - - Specify that MD5 HMAC - authentication must be used on this interface. MD5 keying material must - also be configured (:ref:`ip-ospf-message-digest-key`). Overrides any - authentication enabled on a per-area basis (:ref:`area-authentication-message-digest`). + Specify that MD5 HMAC authentication must be used on this interface. MD5 + keying material must also be configured. Overrides any authentication + enabled on a per-area basis + (:clicmd:`area A.B.C.D authentication message-digest`) Note that OSPF MD5 authentication requires that time never go backwards (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 or non-volatile source (eg battery backed clock, NTP, - etc.) or else the system clock should be periodically saved to non-volative - storage and restored at boot if MD5 authentication is to be expected to work - reliably. + with its neighbours after restarts/reboots. The host should have system time + be set at boot from an external or non-volatile source (eg battery backed + clock, NTP, etc.) or else the system clock should be periodically saved to + non-volative storage and restored at boot if MD5 authentication is to be + expected to work reliably. .. index:: ip ospf message-digest-key KEYID md5 KEY .. clicmd:: ip ospf message-digest-key KEYID md5 KEY @@ -580,17 +565,15 @@ OSPF interface .. index:: no ip ospf message-digest-key .. clicmd:: no ip ospf message-digest-key -.. _ip-ospf-message-digest-key: - - Set OSPF authentication key to a - cryptographic password. The cryptographic algorithm is MD5. + Set OSPF authentication key to a cryptographic password. The cryptographic + algorithm is MD5. - KEYID identifies secret key used to create the message digest. This ID - is part of the protocol and must be consistent across routers on a - link. + KEYID identifies secret key used to create the message digest. This ID + is part of the protocol and must be consistent across routers on a + link. - KEY is the actual message digest key, of up to 16 chars (larger strings - will be truncated), and is associated with the given KEYID. + KEY is the actual message digest key, of up to 16 chars (larger strings + will be truncated), and is associated with the given KEYID. .. index:: ip ospf cost (1-65535) .. clicmd:: ip ospf cost (1-65535) @@ -610,21 +593,18 @@ OSPF interface .. index:: no ip ospf dead-interval .. clicmd:: no ip ospf dead-interval -.. _ip-ospf-dead-interval-minimal: + 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. - 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. + 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. .. index:: ip ospf hello-interval (1-65535) .. clicmd:: ip ospf hello-interval (1-65535) @@ -637,7 +617,8 @@ OSPF 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 + This command has no effect if + :clicmd:`ip ospf dead-interval minimal hello-multiplier (2-20)` is also specified for the interface. .. index:: ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point) @@ -725,7 +706,7 @@ Redistribute routes to OSPF 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`. + :ref:`OSPF distribute-list configuration `. Redistributed routes are distributed as into OSPF as Type-5 External LSAs into links to areas that accept external routes, Type-7 External LSAs @@ -733,7 +714,11 @@ Redistribute routes to OSPF external routes are not permitted. Note that for connected routes, one may instead use - :term:`passive-interface`, see :ref:`ospf-passive-interface`. + :term:`passive-interface`; + +.. seealso:: + + clicmd:`passive-interface INTERFACE`. .. index:: default-information originate .. clicmd:: default-information originate @@ -777,7 +762,7 @@ Redistribute routes to OSPF Apply the access-list filter, NAME, to redistributed routes of the given type before allowing the routes to - redistributed into OSPF (:ref:`ospf-redistribute`). + redistributed into OSPF (:ref:`OSPF redistribution `). .. index:: default-metric (0-16777214) .. clicmd:: default-metric (0-16777214) diff --git a/doc/user/protocol.rst b/doc/user/protocol.rst index bdd9c6b180..d35177962c 100644 --- a/doc/user/protocol.rst +++ b/doc/user/protocol.rst @@ -1,4 +1,4 @@ -.. _Zebra-Protocol +.. _Zebra-Protocol: ************** Zebra Protocol diff --git a/doc/user/routeserver.rst b/doc/user/routeserver.rst index 86fab0249f..890897bb62 100644 --- a/doc/user/routeserver.rst +++ b/doc/user/routeserver.rst @@ -43,6 +43,7 @@ it consists of three steps: accepted by the `Out` filters of a peer are announced to that peer. .. _fig-normal-processing: + .. figure:: ../figures/fig-normal-processing.png :alt: Normal announcement processing :align: center @@ -50,6 +51,7 @@ it consists of three steps: Announcement processing inside a 'normal' BGP speaker .. _fig-topologies-full: + .. figure:: ../figures/fig_topologies_full.png :alt: Full Mesh BGP Topology :align: center @@ -57,6 +59,7 @@ it consists of three steps: Full Mesh .. _fig-topologies-rs: + .. figure:: ../figures/fig_topologies_rs.png :alt: Route Server BGP Topology :align: center @@ -69,6 +72,7 @@ having a single BGP peering (against the route server), the BGP speakers can no longer distinguish from/to which peer each announce comes/goes. .. _filter-delegation: + This means that the routers connected to the route server are not able to apply by themselves the same input/output filters as in the full mesh scenario, so they have to delegate those functions to the route server. diff --git a/doc/user/vnc.rst b/doc/user/vnc.rst index c7de34458d..e3bff68d8a 100644 --- a/doc/user/vnc.rst +++ b/doc/user/vnc.rst @@ -56,8 +56,8 @@ following areas: .. _general-vnc-configuration: -.. General VNC Configuration -.. ------------------------- +General VNC Configuration +------------------------- .. _rfp-related-configuration: @@ -246,7 +246,7 @@ Defaults section. - ``IPv4-address:two-byte-integer`` - ``four-byte-autonomous-system-number:two-byte-integer`` - ``two-byte-autonomous-system-number:four-byte-integer`` - - ``auto:vn:`two-byte-integer` + - ``auto:vn:two-byte-integer`` Routes originated by NVEs in the NVE group will use the group's specified `route-distinguisher` when they are advertised via BGP. If the `auto` form @@ -902,7 +902,7 @@ Mesh NVA Configuration This example includes three NVAs, nine NVEs, and two NVE groups. Note that while not shown, a single physical device may support multiple logical NVEs. -:ref:`fig-vnc-mesh` shows ``code NVA-1`` (192.168.1.100), ``NVA 2`` +:ref:`vnc-fig-vnc-mesh` shows ``code NVA-1`` (192.168.1.100), ``NVA 2`` (192.168.1.101), and ``NVA 3`` (192.168.1.102), which are connected in a full mesh. Each is a member of the autonomous system 64512. Each NVA provides VNC services to three NVE clients in the 172.16.0.0/16 virtual-network address @@ -918,6 +918,7 @@ Each NVA advertises NVE underlay-network IP addresses using the Tunnel Encapsulation Attribute. .. _vnc-fig-vnc-mesh: + .. figure:: ../figures/fig-vnc-mesh.png :align: center :alt: Three-way Mesh @@ -1229,7 +1230,7 @@ While not shown, an NVA can also be configured as a route reflector. VNC with Commercial Route Reflector Configuration ------------------------------------------------- -This example is identical to :ref:`vnc-with-frr-route-reflector-configuration` +This example is identical to :ref:`vnc-with-frr-route-reflector-config` with the exception that the route reflector is a commercial router. Only the VNC-relevant configuration is provided.