doc: ospfd / ospf6d: document RFC 9129 ietf-ospf config-write scope

lamestllama · lamestllama · commit 777454fb833b · 2026-05-26T09:45:46.000+09:30
Replace the older "operational data only" sections in doc/user/ospfd.rst
and doc/user/ospf6d.rst with a YANG / NETCONF Support entry that lists
every config-write leaf the ietf-ospf series now supports plus the
deliberate scope gaps:

  * redistribute and default-information-originate remain legacy-CLI
    only (RFC 9129 / RFC 8349 leave them to a separate import / export
    mechanism).
  * Per-address overrides (e.g. `ip ospf cost N A.B.C.D`) have no RFC
    9129 counterpart; YANG is strictly per-interface.
  * FRR-specific NSSA augments (translator-role, suppress-fa,
    default-information-originate) are not in the RFC 9129 area
    grouping; they remain legacy-CLI-only.
  * `router ospf [vrf NAME]` instance creation is still CLI-only;
    YANG operations that target a non-existent instance are rejected
    at VALIDATE with a clear error pointing at `router ospf`.
  * ospf6d has no per-area stub default-cost knob; the leaf is not
    implemented (mgmtd reports "no backend handles this path"). This
    matches the existing v3 CLI surface, not a regression introduced
    by this conversion.
  * ospf6 interface-type rejects non-broadcast and hybrid at VALIDATE
    (ospf6d only accepts broadcast, point-to-point and
    point-to-multipoint).

Adds a worked example showing mgmt set-config / commit apply for the
explicit-router-id leaf so operators see the end-to-end mgmtd path.
Documents the frr-deviations-ietf-routing-ospf interface-name leafref
relaxation and the restoration of referential checks inside the
per-interface callbacks.

Signed-off-by: lamestllama &lt;eric@eparsonage.com&gt;
diff --git a/doc/developer/ospf-yang-northbound-notes.rst b/doc/developer/ospf-yang-northbound-notes.rst
@@ -45,45 +45,64 @@ Earlier OSPF northbound work is useful context for future development:
   * Most callbacks are TODO/no-op stubs, so it should not be transplanted
     wholesale.
 
-Implementation Plan
--------------------
-
-1. Do not register inert FRR-native OSPF modules. ``yang/frr-ospfd.yang``
-   remains on disk for future work, but ``ospfd`` no longer links its generated
-   schema into the daemon binary or advertises it with no callbacks behind it.
-   Add ``frr-ospfd`` or future ``frr-ospf6d`` module registrations only when
-   there is a concrete FRR-specific augment or callback to expose.
-
-2. Keep ``ietf-ospf`` loaded for both daemons and map FRR behavior toward the
-   RFC 9129
-   ``/ietf-routing:routing/control-plane-protocols/control-plane-protocol/ietf-ospf:ospf``
-   tree. The first OSPFv2 and OSPFv3 operational callbacks now expose the RFC
-   ``control-plane-protocol`` list, router-id, instance LSA counters, area
-   SPF/ABR/ASBR/LSA counters, interface list, and neighbor list with neighbor
-   address and state. The default instance name is ``default`` for both daemons.
-   The OSPFv2 interface list currently exposes the first ``ospf_interface`` per
-   interface key because RFC 9129 keys the list by interface name while FRR can
-   hold multiple OSPFv2 interface objects for different addresses on the same
-   interface.
-
-3. Add mgmtd backend registration after there is at least a narrow set of real
-   callbacks or an explicitly operational-only xpath set. ``ospfd`` and
-   ``ospf6d`` register as mgmtd backend clients for
-   ``/ietf-routing:routing/control-plane-protocols/control-plane-protocol``.
-   ``mgmtd`` also loads the RFC OSPF modules so it can parse OSPF backend
-   replies in the merged operational datastore.
-
-4. Port operational callbacks from PR #18401 into the current model, beginning
-   with OSPF instance and area statistics.
-
-5. Convert configuration in narrow CLI-equivalent slices. For each leaf or list,
-   move existing CLI behavior into a northbound callback and make the CLI set
-   the YANG node. ``ietf-ospf`` should be the canonical configuration tree for
-   everything RFC 9129 models; ``frr-ospfd`` and future ``frr-ospf6d`` should
-   augment only FRR-specific behavior that the RFC model does not cover.
-
-6. Add FRR-native OSPFv3 YANG only when a concrete FRR-specific augment is
-   needed.
+Current Implementation
+----------------------
+
+This branch implements the RFC 9129 ``ietf-ospf`` tree directly for OSPFv2 and
+OSPFv3 rather than adding an FRR-native OSPF model with parallel semantics.
+``yang/frr-ospfd.yang`` remains on disk for future FRR-specific OSPFv2 work,
+but ``ospfd`` does not link its generated schema into the daemon binary or
+advertise it with no callbacks behind it.
+
+Both daemons load ``ietf-ospf`` and map FRR behavior toward the RFC 9129
+``/ietf-routing:routing/control-plane-protocols/control-plane-protocol/ietf-ospf:ospf``
+tree. OSPFv2 and OSPFv3 operational callbacks expose the RFC
+``control-plane-protocol`` list, router-id, instance LSA counters, area
+SPF/ABR/ASBR/LSA counters, interface list, and neighbor list with neighbor
+address and state. The default instance name is ``default`` for both daemons.
+The OSPFv2 interface list exposes one entry per interface key because RFC 9129
+keys the list by interface name while FRR can hold multiple OSPFv2 interface
+objects for different addresses on the same interface.
+
+``ospfd`` and ``ospf6d`` register as mgmtd backend clients for typed
+``control-plane-protocol`` entries so OSPFv2 and OSPFv3 can share the standard
+``ietf-routing`` list without one daemon claiming the other daemon's instance.
+``mgmtd`` also loads the RFC OSPF modules so it can parse OSPF backend replies
+in the merged operational datastore.
+
+The mgmtd backend matcher treats predicates in backend registrations as
+ownership constraints, not as a reason to hide unfiltered list data. A query
+with ``type='ietf-ospf:ospfv2'`` must dispatch only to ``ospfd`` and a query
+with ``type='ietf-ospf:ospfv3'`` must dispatch only to ``ospf6d``. A query that
+omits the ``type`` predicate, such as a request for the whole
+``control-plane-protocol`` list or one of its unkeyed descendants, still
+dispatches to both daemons so mgmtd can merge the OSPFv2 and OSPFv3 entries.
+This keeps shared IETF lists usable for current OSPF and future protocol
+families without special-casing OSPF in mgmtd.
+
+Configuration write support is intentionally limited to CLI-equivalent RFC 9129
+leaves. The converted leaves are router-id, preference, area lifecycle,
+area-type, area summary, OSPFv2 default-cost, area ranges, per-interface area
+attachment, interface cost, hello-interval, dead-interval, retransmit-interval,
+priority, mtu-ignore, interface-type, and passive. Existing CLI commands for
+those leaves set the same YANG nodes as mgmtd writes.
+
+Direct daemon config-file loads in ``ospfd`` and ``ospf6d`` opt in to batching
+so cross-leaf validation can evaluate a whole startup file in one northbound
+transaction. Other daemons keep the legacy per-line config-file behavior.
+
+Remaining Scope
+---------------
+
+``ietf-ospf`` remains the canonical configuration tree for everything RFC 9129
+models. ``frr-ospfd`` and future ``frr-ospf6d`` should augment only
+FRR-specific behavior that the RFC model does not cover.
+
+The current config-write scope deliberately does not include redistribution,
+default-information-originate, virtual links, per-address OSPFv2 interface
+overrides, OSPFv2 NSSA translator/suppress-fa knobs, or other FRR-specific
+extensions outside RFC 9129. A native OSPFv3 module should be added only when
+there is concrete FRR-specific state or configuration to expose.
 
 Test Coverage
 -------------
@@ -94,6 +113,25 @@ neighbor state. It also checks that ``ospfd`` and ``ospf6d`` register with mgmtd
 and that mgmtd's operational xpath registry includes the RFC 9129 control-plane
 protocol subtree.
 
+The operational tests also include a targeted mgmtd dispatch check. Predicate
+queries for ``ietf-ospf:ospfv2`` and ``ietf-ospf:ospfv3`` must return exactly
+one protocol entry from the correct backend, and the backend subscription check
+must show that the other OSPF daemon was not selected. Unfiltered parent/list
+queries must still select both OSPF daemons. A predicate query against
+``ietf-interfaces`` verifies that untyped backend registrations still match.
+
+The same test file includes config-write checks for the supported OSPFv2 and
+OSPFv3 leaves. The tests exercise mgmtd writes, legacy CLI writes routed through
+YANG, negative validation paths, and cleanup after deleting and recreating an
+area.
+
+``tests/topotests/ospf_yang_startup_config/test_ospf_yang_startup_config.py``
+checks startup config-file batching in an isolated one-router topology. Its
+``r1/ospfd.conf`` places an OSPFv2 ``default-cost`` line before the stub-area
+line that makes it valid; startup succeeds only when the whole daemon config
+file is committed as one northbound transaction. ``r1/ospf6d.conf`` keeps a
+matching OSPFv3 stub area in the startup path.
+
 The test queries the merged mgmtd operational datastore rather than daemon-local
 ``show yang operational-data`` output. Zebra supplies the narrow
 ``/ietf-interfaces:interfaces/interface`` operational state needed to satisfy RFC
diff --git a/doc/user/ospf6d.rst b/doc/user/ospf6d.rst
@@ -933,21 +933,46 @@ Showing OSPF6 information
    This command shows the graceful-restart helper details including helper
    configuration parameters.
 
-YANG Operational Data
----------------------
-
-OSPFv3 operational state is available through the standard :rfc:`9129`
-``ietf-ospf`` YANG model. The current support is operational data only; OSPFv3
-configuration is still managed through the existing FRR CLI.
+YANG / NETCONF Support
+----------------------
 
-The following example retrieves the OSPFv3 instance from the mgmtd operational
-datastore:
+OSPFv3 operational state and a subset of OSPFv3 configuration are exposed
+through the standard :rfc:`9129` ``ietf-ospf`` YANG model. The OSPFv3
+instance itself remains owned by the legacy ``router ospf6`` CLI, but
+per-area, per-interface and per-instance configuration leaves are routed
+through the mgmtd northbound and can be read, set, and committed through
+NETCONF / RESTCONF / ``vtysh``'s ``mgmt`` subcommands as well as the legacy
+CLI.
+
+The supported set mirrors the OSPFv2 side documented in :ref:`ospfv2`, with
+two v3-specific gaps:
+
+* ``areas/area/default-cost``: ospf6d has no per-area stub default-cost
+  knob, so this leaf is not implemented. Setting it via YANG is rejected
+  by mgmtd as ``no backend handles this path``. This matches FRR's existing
+  v3 CLI surface (which has no ``area X default-cost`` equivalent) and is a
+  pre-existing v2/v3 feature gap, not introduced by this conversion.
+* ``interface-type``: RFC 9129 declares ``broadcast``, ``non-broadcast``,
+  ``point-to-multipoint``, ``point-to-point`` and ``hybrid``. ospf6d only
+  accepts ``broadcast``, ``point-to-point`` and ``point-to-multipoint``;
+  the NB callback rejects ``non-broadcast`` and ``hybrid`` at VALIDATE
+  with a clear error.
+
+Otherwise the set of supported leaves (router-id, area lifecycle,
+area-type, area summary, ranges, per-interface attachment, cost,
+hello-interval, dead-interval, retransmit-interval, priority, mtu-ignore,
+passive, preference) is identical to OSPFv2.
+
+Examples
+^^^^^^^^
+
+Retrieve the OSPFv3 instance from the operational datastore:
 
 .. code-block:: shell
 
    vtysh -c 'show mgmt get-data /ietf-routing:routing/control-plane-protocols/control-plane-protocol[type="ietf-ospf:ospfv3"][name="default"] datastore operational'
 
-To retrieve the merged operational datastore, including the OSPFv3 protocol
+Retrieve the merged operational datastore, including the OSPFv3 protocol
 entry and the ``ietf-interfaces`` data used by OSPF interface leafrefs:
 
 .. code-block:: shell
diff --git a/doc/user/ospfd.rst b/doc/user/ospfd.rst
@@ -1083,27 +1083,91 @@ Showing Information
    Displays the Graceful Restart Helper details including helper
    config changes.
 
-YANG Operational Data
----------------------
-
-OSPF operational state is available through the standard :rfc:`9129`
-``ietf-ospf`` YANG model. The current support is operational data only; OSPF
-configuration is still managed through the existing FRR CLI.
+YANG / NETCONF Support
+----------------------
 
-The following example retrieves the OSPFv2 instance from the mgmtd operational
-datastore:
+OSPF operational state and a subset of OSPF configuration are exposed through
+the standard :rfc:`9129` ``ietf-ospf`` YANG model.  The OSPF instance itself
+remains owned by the legacy ``router ospf`` CLI, but per-area, per-interface
+and per-instance configuration leaves are routed through the mgmtd northbound
+so they can be read, set and committed via NETCONF / RESTCONF / ``vtysh``'s
+``mgmt`` subcommands as well as the legacy CLI.
+
+Supported configuration leaves
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Under ``/ietf-routing:routing/control-plane-protocols/control-plane-protocol[type='ietf-ospf:ospfv2']/ietf-ospf:ospf``:
+
+* ``explicit-router-id``
+* ``preference/{all,intra-area,inter-area,internal,external}`` (admin distance)
+* ``areas/area`` (list create / destroy keyed by ``area-id``)
+* ``areas/area/area-type`` (``normal-area``, ``stub-area``, ``nssa-area``)
+* ``areas/area/summary`` (totally-stubby toggle; RFC 9129 inverts FRR's
+  ``no-summary`` sense)
+* ``areas/area/default-cost`` (stub / NSSA only)
+* ``areas/area/ranges/range`` (list create / destroy), with ``advertise``
+  and ``cost`` leaves
+* ``areas/area/interfaces/interface`` (list create / destroy: assigns an
+  interface to the area), plus the per-interface leaves
+  ``cost``, ``hello-interval``, ``dead-interval``, ``retransmit-interval``,
+  ``priority``, ``mtu-ignore``, ``interface-type``, ``passive``
+
+Out of scope for this slice
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``redistribute`` and ``default-information-originate`` are FRR-specific
+  concepts that RFC 9129 / :rfc:`8349` leave to a separate import / export
+  mechanism. They stay reachable through the legacy CLI on the
+  direct-mutation path.
+* Per-address overrides (e.g. ``ip ospf cost N A.B.C.D``) have no RFC 9129
+  counterpart; the YANG model is strictly per-interface. The legacy CLI
+  with an explicit address argument continues to use direct mutation.
+* FRR-specific area NSSA augments (translator-role,
+  default-information-originate, suppress-fa) are not in the RFC 9129 area
+  grouping; they remain legacy-CLI-only.
+* The ``router ospf [vrf NAME]`` instance creation step is still
+  CLI-only; YANG operations that target a non-existent instance are
+  rejected at VALIDATE with a clear error pointing at ``router ospf``.
+
+Examples
+^^^^^^^^
+
+Retrieve the OSPFv2 instance from the operational datastore:
 
 .. code-block:: shell
 
    vtysh -c 'show mgmt get-data /ietf-routing:routing/control-plane-protocols/control-plane-protocol[type="ietf-ospf:ospfv2"][name="default"] datastore operational'
 
-To retrieve the merged operational datastore, including the OSPF protocol
+Retrieve the merged operational datastore, including the OSPF protocol
 entry and the ``ietf-interfaces`` data used by OSPF interface leafrefs:
 
 .. code-block:: shell
 
    vtysh -c 'show mgmt get-data /* datastore operational'
 
+Set the router-id through mgmtd, then commit:
+
+.. code-block:: shell
+
+   vtysh -c 'configure terminal file-lock'                 \
+         -c 'mgmt set-config /ietf-routing:routing/control-plane-protocols/control-plane-protocol[type="ietf-ospf:ospfv2"][name="default"]/ietf-ospf:ospf/explicit-router-id "10.0.0.1"' \
+         -c 'mgmt commit apply'
+
+The corresponding ``ospf router-id 10.0.0.1`` legacy CLI command takes the
+same path through the northbound; both surfaces converge on the same
+committed running configuration.
+
+Interface leafref relaxation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+RFC 9129's per-interface entry keys on a leafref into
+``/ietf-interfaces:interfaces/interface/name``. The
+``frr-deviations-ietf-routing-ospf`` deviation relaxes this so OSPF config
+can be staged ahead of interface plumbing (useful when emitting config from
+an external orchestrator). The relaxation removes libyang's referential
+check; the NB callbacks restore it themselves, rejecting unknown interface
+names at VALIDATE with a clear error.
+
 .. _opaque-lsa:
 
 Opaque LSA
