doc: touch up manuals, enable fail-on-warning for docs (scionproto#4416)

- add missing documentation for `remote_interface_id` in `topology.json`
  for peering links (fix-up for scionproto#4390)
- fix duplicate envvar documentation in router.rst and control.rst
  (envvars can only have one definition in rst), and expand the
  description (fix-up for scionproto#4300). Consistent  formatting for envvar
  documentation.
- move the description of the duration string format to the common
  section, as it's referenced by multiple components (currently control
  service and router).
- fix references in SPAO doc
- enable fail-on-warning for read-the-docs builds: this makes PR fail
  the the read-the-docs check if there are build warnings. Also enable
  the same build flags in the Makefile for local documentation builds.

.readthedocs.yaml

@@ -11,6 +11,7 @@ build:
 
 sphinx:
    configuration: doc/conf.py
+   fail_on_warning: true
 
 python:
    install:

doc/Makefile

@@ -1,5 +1,5 @@
 # These variables can be overridden from the command line from the environment.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W --keep-going # treat warnings as errors, but process all files when an error occurs
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -16,9 +16,10 @@ html latex latexpdf linkcheck help:
 	sphinx-build -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 # Autobuild; automatically build HTML on source changes and serve on localhost
+# Note: most options are forwarded as-is to sphinx, but --keep-going is not understood and we explicitly drop it.
 .PHONY: autobuild
 autobuild:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(filter-out --keep-going,$(SPHINXOPTS))
 
 # Generate commandline docs by building the tools and running their `gendocus` subcommand
 .PHONY: command-gendocs

doc/control-plane.rst

@@ -266,6 +266,8 @@ path-lookup on behalf of applications. This SCION daemon also caches path-segmen
    Down-segment Control service of core ASes in destination ISD (either the local ISD or a remote ISD)
    ============ ===========================
 
+.. _control-plane-segment-combination:
+
 Path-Segment Combination
 ========================
 

doc/manuals/common.rst

@@ -202,6 +202,8 @@ of the individual fields below.
 
          In this ``topology.json`` file, the ID is contained in a string.
 
+      .. _topology-json-interface-isd_as:
+
       .. option:: isd_as = <isd-as>, required
 
          The ISD-AS of the neighboring AS.
@@ -211,16 +213,34 @@ of the individual fields below.
          Type of the link relation to the neighbor AS.
          See :ref:`overview-link-types`.
 
-         .. warning::
+      .. option:: remote_interface_id = <int>
+
+         The :term:`interface ID <Interface ID>` for the corresponding interface in the
+         neighboring AS.
+
+         This is required if, and only if, :option:`link_to <topology-json link_to>` is ``peer``.
+
+         This ``remote_interface_id`` is used when announcing peering links as part of AS Entries in
+         PCBs (see :ref:`control-plane-beaconing`).
+         During :ref:`path-segment combination <control-plane-segment-combination>`, this interface
+         ID, will then be used together with the ISD-AS to match up the peering entries from
+         AS entries in different path segments.
 
-            Link type ``peer`` is not fully implemented yet. See :issue:`4093`.
+         If ``remote_interface_id`` is set incorrectly, the peering entries cannot be matched up
+         correctly, resulting in missing or broken end-to-end paths:
+
+         - If the ``remote_interface_id`` does not match `any` interface ID used for peering links
+           in the neighboring AS, the segment combination will not find paths making use of this
+           interface.
+         - If two ASes are connected by multiple peering links and ``remote_interface_id`` matches the
+           `wrong` interface ID, an incorrect path may be constructed which will be rejected in the
+           data plane (i.e. the routers will drop all packets).
 
       .. option:: mtu = <int>, required
 
          Maximum Transmission Unit in bytes for SCION packets (SCION headers and payload) on this
          link.
 
-
       .. object:: underlay, required for "self"
 
          Underlay specifies the local addresses used for the underlay IP/UDP connection to the
@@ -325,6 +345,28 @@ of the individual fields below.
    .. option:: addr = <ip:port>, required
 
       See ``control_service.addr``, above.
+
+.. _common-conf-duration:
+
+Duration Format
+===============
+
+Where duration values are loaded from configuration options, the following format is expected:
+
+.. code-block::
+
+   [\-0-9]+(y|w|d|h|m|s|ms|us|µs|ns)
+
+The unit suffixes have their usual meaning of ``y`` year, ``w`` week, ``d`` day, ``h`` hour,
+``m`` minute, ``s`` second, ``ms`` millisecond, ``us`` or ``µs`` microsecond, and ``ns`` nanosecond.
+
+Mixed unit durations are not supported (e.g. ``1h10m10s`` is not supported).
+The long duration units are simple factors, not calendar offsets:
+
+- ``d`` is always 24 hours
+- ``w`` is always 7 days
+- ``y`` is always 365 days
+
 .. _common-http-api:
 
 HTTP API

doc/manuals/control.rst

@@ -64,6 +64,7 @@ Options
    Run :option:`control help completion [shell] <control help>` for usage information on the
    autocomplete script for a particular shell.
 
+.. _control-envvars:
 
 Environment variables
 ---------------------
@@ -76,7 +77,10 @@ Environment variables
    This can only work correctly if the same value is set for all connected control services in the
    test network.
 
-   The format is a :ref:`duration <control-conf-duration>` with unit suffix (e.g. ``10s``).
+   Also applies to the :ref:`router <router-envvars>`.
+
+   :Type: :ref:`duration <common-conf-duration>`
+   :Default: ``24h``
 
 Configuration
 =============
@@ -264,7 +268,7 @@ considers the following options.
 
       .. option:: ca.service.lifetime = <duration> (Default: "10m")
 
-         Validity period (a :ref:`duration <control-conf-duration>`) of JWT authorization tokens
+         Validity period (a :ref:`duration <common-conf-duration>`) of JWT authorization tokens
          for the CA service.
 
       .. option:: ca.service.client_id = <string> (Default: general.id)
@@ -315,7 +319,7 @@ considers the following options.
 
       Expiration of cached entries in nanoseconds.
 
-      **TODO:** this should be changed to accept values in :ref:`duration format <control-conf-duration>`.
+      **TODO:** this should be changed to accept values in :ref:`duration format <common-conf-duration>`.
 
 .. object:: drkey
 
@@ -775,29 +779,6 @@ There is one top-level entry for each type of metadata, all of which are optiona
 
    A free form string to communicate interesting/important information to other network operators.
 
-
-.. _control-conf-duration:
-
-Duration Format
----------------
-
-Where duration values are loaded from configuration options, the following format is expected:
-
-.. code-block::
-
-   [\-0-9]+(y|w|d|h|m|s|ms|us|µs|ns)
-
-The unit suffixes have their usual meaning of ``y`` year, ``w`` week, ``d`` day, ``h`` hour,
-``m`` minute, ``s`` second, ``ms`` millisecond, ``us`` or ``µs`` microsecond, and ``ns`` nanosecond.
-
-Mixed unit durations are not supported (e.g. ``1h10m10s`` is not supported).
-The long duration units are simple factors, not calendar offsets:
-
-- ``d`` is always 24 hours
-- ``w`` is always 7 days
-- ``y`` is always 365 days
-
-
 Port table
 ==========
 

doc/manuals/router.rst

@@ -51,6 +51,8 @@ Options
    Run :option:`router help completion [shell] <router help>` for usage information on the
    autocomplete script for a particular shell.
 
+.. _router-envvars:
+
 Environment Variables
 ---------------------
 
@@ -62,40 +64,63 @@ Environment Variables
    Can be overridden for specific inter-AS BFD sessions with :option:`bfd.disable <topology-json disable>`
    in an interface entry in the ``topology.json`` configuration.
 
+   :Type: bool (``0``/``f``/``F``/``FALSE``/``false``/``False``,  ``1``/``t``/``T``/``TRUE``/``true``/``True``)
+   :Default: ``false``
+
 .. envvar:: SCION_EXPERIMENTAL_BFD_DETECT_MULT
 
    Set the :term:`BFD` detection time multiplier.
 
-   Default 3
-
    Same applicability as above; can be overridden for specific inter-AS BFD sessions with
    :option:`bfd.detect_mult <topology-json detect_mult>`.
 
+   :Type: unsigned integer
+   :Default: ``3``
+
 .. envvar:: SCION_EXPERIMENTAL_BFD_DESIRED_MIN_TX
 
    Defines the frequence at which this router should send :term:`BFD` control messages.
 
-   Default 200ms
-
    Same applicability as above; can be overridden for specific inter-AS BFD sessions with
    :option:`bfd.desired_min_tx_interval <topology-json desired_min_tx_interval>`.
 
+   :Type: :ref:`duration <common-conf-duration>`
+   :Default: ``200ms``
+
 .. envvar:: SCION_EXPERIMENTAL_BFD_REQUIRED_MIN_RX
 
    Defines an frequence at which this router should send :term:`BFD` control messages.
 
-   Default 200ms
-
    Same applicability as above; can be overridden for specific inter-AS BFD sessions with
    :option:`bfd.required_min_rx_interval <topology-json required_min_rx_interval>`.
-.. envvar:: SCION_TESTING_DRKEY_EPOCH_DURATION
 
-   Defines the global DRKey :ref:`Epoch<drkey-epoch>` duration that the border router
-   assumes.
+   :Type: :ref:`duration <common-conf-duration>`
+   :Default: ``200ms``
+
+.. object:: SCION_TESTING_DRKEY_EPOCH_DURATION
+
+   For **testing only**.
+   This option relates to :ref:`DRKey-based authentication of SCMPs <scmp-authentication>` in the
+   router, which is **experimental** and currently **incomplete**.
+
+   Override the global duration for :doc:`/cryptography/drkey` epochs.
+
+   Also applies to the :ref:`control service <control-envvars>`.
+
+   :Type: :ref:`duration <common-conf-duration>`
+   :Default: ``24h``
 
 .. envvar:: SCION_TESTING_ACCEPTANCE_WINDOW
 
-   Defines the acceptance window following the :ref:`SPAO specification<spao-absTime>`.
+   For **testing only**.
+   This option relates to :ref:`DRKey-based authentication of SCMPs <scmp-authentication>` in the
+   router, which is **experimental** and currently **incomplete**.
+
+   Defines the length of the window around the current time for which SCMP authentication timestamps
+   are accepted. See :ref:`SPAO specification <spao-absTime>`.
+
+   :Type: :ref:`duration <common-conf-duration>`
+   :Default: ``5m``
 
 Configuration
 =============

doc/protocols/authenticator-option.rst

@@ -60,7 +60,7 @@ Timestamp / Sequence Number:
   (See :ref:`Appendix<spao-appendix>` for a more detailed explanation about the field interpretation).
   The timestamp MAY be used to compute the absolute time (*AbsTime*) value,
   which corresponds to the time when the packet was sent.
-  The section :ref:`Absolute time derivation<spao-timestamp>` describes the derivation of *AbsTime* and
+  The section :ref:`Absolute time derivation<spao-absTime>` describes the derivation of *AbsTime* and
   the associated DRKey.
 
   The receiver SHOULD drop packets with *AbsTime* outside of a locally chosen