doc: explain remote_interface_id

matzf · Sep 29, 2023 · ac43775 · ac43775
1 parent 241d6be
commit ac43775
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 3 deletions.
diff --git 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
@@ -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``.
 
-            Link type ``peer`` is not fully implemented yet. See :issue:`4093`.
+         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.
+
+         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