From 2ea2d8913ef2b85a23cbad42b14b74c2c698c1c6 Mon Sep 17 00:00:00 2001 From: Matthias Frei Date: Thu, 12 Oct 2023 13:40:46 +0200 Subject: [PATCH] doc: touch up manuals, enable fail-on-warning for docs (#4416) - add missing documentation for `remote_interface_id` in `topology.json` for peering links (fix-up for #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 #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 | 1 + doc/Makefile | 5 +-- doc/control-plane.rst | 2 ++ doc/manuals/common.rst | 48 ++++++++++++++++++++++++-- doc/manuals/control.rst | 33 ++++-------------- doc/manuals/router.rst | 45 ++++++++++++++++++------ doc/protocols/authenticator-option.rst | 2 +- 7 files changed, 94 insertions(+), 42 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 973c7d33bb..cfcdbd001f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,6 +11,7 @@ build: sphinx: configuration: doc/conf.py + fail_on_warning: true python: install: diff --git a/doc/Makefile b/doc/Makefile index fc16ae6248..7191385949 100644 --- a/doc/Makefile +++ b/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 diff --git a/doc/control-plane.rst b/doc/control-plane.rst index eca9ce0720..edca6c4fbb 100644 --- a/doc/control-plane.rst +++ b/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 ======================== diff --git a/doc/manuals/common.rst b/doc/manuals/common.rst index 6bc3e4b218..863c58b15b 100644 --- a/doc/manuals/common.rst +++ b/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 = , 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 = + + The :term:`interface ID ` for the corresponding interface in the + neighboring AS. + + This is required if, and only if, :option:`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 `, 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 = , 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 = , 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 diff --git a/doc/manuals/control.rst b/doc/manuals/control.rst index 0bcbe80173..310a3bdcc6 100644 --- a/doc/manuals/control.rst +++ b/doc/manuals/control.rst @@ -64,6 +64,7 @@ Options Run :option:`control help completion [shell] ` 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 ` with unit suffix (e.g. ``10s``). + Also applies to the :ref:`router `. + + :Type: :ref:`duration ` + :Default: ``24h`` Configuration ============= @@ -264,7 +268,7 @@ considers the following options. .. option:: ca.service.lifetime = (Default: "10m") - Validity period (a :ref:`duration `) of JWT authorization tokens + Validity period (a :ref:`duration `) of JWT authorization tokens for the CA service. .. option:: ca.service.client_id = (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 `. + **TODO:** this should be changed to accept values in :ref:`duration format `. .. 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 ========== diff --git a/doc/manuals/router.rst b/doc/manuals/router.rst index 6427ab6165..494012ec59 100644 --- a/doc/manuals/router.rst +++ b/doc/manuals/router.rst @@ -51,6 +51,8 @@ Options Run :option:`router help completion [shell] ` 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 ` 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 `. + :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 `. + :Type: :ref:`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 `. -.. envvar:: SCION_TESTING_DRKEY_EPOCH_DURATION - Defines the global DRKey :ref:`Epoch` duration that the border router - assumes. + :Type: :ref:`duration ` + :Default: ``200ms`` + +.. object:: SCION_TESTING_DRKEY_EPOCH_DURATION + + For **testing only**. + This option relates to :ref:`DRKey-based authentication of SCMPs ` 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 `. + + :Type: :ref:`duration ` + :Default: ``24h`` .. envvar:: SCION_TESTING_ACCEPTANCE_WINDOW - Defines the acceptance window following the :ref:`SPAO specification`. + For **testing only**. + This option relates to :ref:`DRKey-based authentication of SCMPs ` 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 `. + + :Type: :ref:`duration ` + :Default: ``5m`` Configuration ============= diff --git a/doc/protocols/authenticator-option.rst b/doc/protocols/authenticator-option.rst index 0770696036..a8ecca2efd 100644 --- a/doc/protocols/authenticator-option.rst +++ b/doc/protocols/authenticator-option.rst @@ -60,7 +60,7 @@ Timestamp / Sequence Number: (See :ref:`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` describes the derivation of *AbsTime* and + The section :ref:`Absolute time derivation` describes the derivation of *AbsTime* and the associated DRKey. The receiver SHOULD drop packets with *AbsTime* outside of a locally chosen