doc: control service manual #4361

matzf · 2023-07-07T08:40:55Z

Add a conceptual description of the control plane and a reference manual for the control service.

The control plane description is mostly based on the IETF SCION control plane specification draft.

The reference manual for the control service describes the many command line flags, environment variables, configuration files and APIs. This documentation highlights a variety of usability shortcomings, redundancies and inconsistencies that should be addressed eventually.

This change is

oncilla

Reviewed 15 of 15 files at r1, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on @matzf)

doc/glossary.rst line 33 at r1 (raw file):

   Certificate Authority

      An entity that signs and issues digital certificates , certifying the ownership of a public

Suggestion:

certificates,

doc/manuals/control.rst line 14 at r1 (raw file):

In core ASes, the :program:`control` service also acts as the certificate authority from which ASes
in the local ISD request renewed certificates (or as a proxy thereof).

This is not accurate. A CA is not required to run as part of a core AS.

Core and CA are two separate properties of an AS.

Code quote:

In core ASes, the :program:`control` service also acts as the certificate authority from which ASes
in the local ISD request renewed certificates (or as a proxy thereof).

doc/manuals/control.rst line 126 at r1 (raw file):

   transitional features).

   .. option:: features.appropriate_digest_algorithm = <bool> (Default: false)

Blast from the past. By now, I think we can drop this feature.

matzf

Reviewable status: all files reviewed, 2 unresolved discussions (waiting on @oncilla)

doc/glossary.rst line 33 at r1 (raw file):

   Certificate Authority

      An entity that signs and issues digital certificates , certifying the ownership of a public

Done.

doc/manuals/control.rst line 14 at r1 (raw file):

Previously, oncilla (Dominik Roos) wrote…

This is not accurate. A CA is not required to run as part of a core AS.

Core and CA are two separate properties of an AS.

Done. I've added a short introduction text about the different AS roles to the overview section.

nicorusti

Hi Matthias, thanks a lot, I added some minor suggestions in the sections that are derived from the IETF draft.

I only skimmed through the rest of the changes, as I'm not too familiar with the control service. It is really great that you documented it better. When I tried to use it some time ago I would have really needed something like this :)

Reviewed 6 of 15 files at r1, 1 of 3 files at r2, all commit messages.
Reviewable status: 13 of 15 files reviewed, 8 unresolved discussions (waiting on @matzf and @oncilla)

doc/control-plane.rst line 135 at r2 (raw file):

----------

Every AS adds a signed *AS entry* to the PCBs it originates, propagates or terminates.

Here I think you mention "terminating" a PCB, however the concept of terminating a PCB is not yet introduced. If you don't know about its special meaning, it sounds a bit confusing (it almost feels like the PCB could be discarded).

Suggestion:

 or terminates. "Termination" consists of the case where the given AS is the first or last AS in the path segment.

doc/control-plane.rst line 137 at r2 (raw file):

Every AS adds a signed *AS entry* to the PCBs it originates, propagates or terminates.

This AS entry includes the relevant network topology information for this AS-hop

In the IETF drafts, we added a lot more details about message formats (like section 2.2.1.3. for the AS entry). I'm not sure if this is too detailed for the documentation, but perhaps you could add a pointer to that section. However, the challenge today is that the text structure and section numbers in the IETF drafts might change quite a bit. Just something to keep in consideration ( either for now or for the future).

doc/control-plane.rst line 191 at r2 (raw file):

  core AS that originated the PCB.
  As a result, a core AS's path database contains all down-segments registered by the
  non-core ASes in its customer cone.

Perhaps downstream is more appropriate? This is because the child of a child of a core AS is not necessary a customer of the core AS directly. At least in the iETF draft, we try to use "downstream" more rather than "customer"

Suggestion:

downstream cone

doc/control-plane.rst line 240 at r2 (raw file):

All remote path-segment lookups by the control service are cached.

On SCION end-hosts, a :doc:`SCION daemon <manuals/daemon>` is usually employed to do the

In the IETF draft we try to use endpoint (which you also used here a few times). Here you use end-hosts. I think it would be good to make it uniform.

Suggestion:

endpoint

doc/control-plane.rst line 259 at r2 (raw file):

path segments to end-to-end forwarding paths.
This path-segment combination process is done by each endpoint separately.
Typically, end-hosts run the :doc:`SCION daemon <manuals/daemon>` which centralizes the

Suggestion:

endpoints

doc/glossary.rst line 63 at r2 (raw file):

      An interface ID is the AS-local identifier for an inter-domain link.

      The interface ID is an arbitrary number between 1 and 65535,

IN the draft I tried to include field length when possible. As you mention that the max value is 65535, I thought we might as well indicate the field length.

Suggestion:

 16 bit

matzf

Reviewable status: 13 of 15 files reviewed, 3 unresolved discussions (waiting on @nicorusti and @oncilla)

doc/control-plane.rst line 135 at r2 (raw file):

Previously, nicorusti (Nicola Rustignoli) wrote…

Here I think you mention "terminating" a PCB, however the concept of terminating a PCB is not yet introduced. If you don't know about its special meaning, it sounds a bit confusing (it almost feels like the PCB could be discarded).

True. I've changed it to "registers", the "termination" is a part of the registration.

doc/control-plane.rst line 137 at r2 (raw file):

Previously, nicorusti (Nicola Rustignoli) wrote…

In the IETF drafts, we added a lot more details about message formats (like section 2.2.1.3. for the AS entry). I'm not sure if this is too detailed for the documentation, but perhaps you could add a pointer to that section. However, the challenge today is that the text structure and section numbers in the IETF drafts might change quite a bit. Just something to keep in consideration ( either for now or for the future).

Done. I've added message definitions to illustrate the AS entry and hop field which seem to be the main elements and added a reference to the "spec" draft too. The link is to a specific version of the draft, so the link will remain valid, but may not point to the latest version of the draft.

doc/control-plane.rst line 191 at r2 (raw file):

Previously, nicorusti (Nicola Rustignoli) wrote…

Perhaps downstream is more appropriate? This is because the child of a child of a core AS is not necessary a customer of the core AS directly. At least in the iETF draft, we try to use "downstream" more rather than "customer"

Customer cone is an existing term: https://asrank.caida.org/about#customer-cone
I'll just leave it. If it's confusing, I'd rephrase to something like "the direct and indirect customer ASes".

doc/control-plane.rst line 240 at r2 (raw file):

Previously, nicorusti (Nicola Rustignoli) wrote…

In the IETF draft we try to use endpoint (which you also used here a few times). Here you use end-hosts. I think it would be good to make it uniform.

As discussed in the glossary, endpoint vs end host: "End host is preferred where the focus is (physical or virtual) machines and the software running on them, and endpoint is used otherwise."

Here "end host" seems fine (except for the unnecessary hyphen).

doc/control-plane.rst line 259 at r2 (raw file):

path segments to end-to-end forwarding paths.
This path-segment combination process is done by each endpoint separately.
Typically, end-hosts run the :doc:`SCION daemon <manuals/daemon>` which centralizes the

Ditto.

doc/glossary.rst line 63 at r2 (raw file):

Previously, nicorusti (Nicola Rustignoli) wrote…

IN the draft I tried to include field length when possible. As you mention that the max value is 65535, I thought we might as well indicate the field length.

Done.

matzf

Reviewable status: 10 of 15 files reviewed, 3 unresolved discussions (waiting on @nicorusti and @oncilla)

doc/control-plane.rst line 191 at r2 (raw file):

Previously, matzf (Matthias Frei) wrote…

Customer cone is an existing term: https://asrank.caida.org/about#customer-cone
I'll just leave it. If it's confusing, I'd rephrase to something like "the direct and indirect customer ASes".

Oops, I seem to have accidentally saved with the change to "direct or indirect customer ASes". This seems also ok, I'll leave that now.

oncilla

Reviewed 1 of 3 files at r2, 4 of 4 files at r3, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @matzf)

jiceatscion

Reviewable status: all files reviewed (commit messages unreviewed), 15 unresolved discussions (waiting on @matzf)

doc/manuals/control.rst line 86 at r4 (raw file):

The :program:`control` service is configured with multiple files:

- the :ref:`.toml <control-conf-toml>`,

"the .toml" -> "the .toml file"

doc/manuals/control.rst line 111 at r4 (raw file):

   .. option:: general.id = <string> (Required)

      Identifier for this control service.

An identifier

Code quote:

Identifier

doc/manuals/control.rst line 113 at r4 (raw file):

      Identifier for this control service.

      This is used to identify which parts of the :ref:`control-conf-topo` file refer to self.

are refering

Code quote:

refer

doc/manuals/control.rst line 129 at r4 (raw file):

      .. Warning::
         This should be set to ``true``, unless your service orchestration ensures that
         failures of the dispatcher trigger a restart of :program:`control` also.

also trigger a restart of :program:control

Code quote:

trigger a restart of :program:`control` also

doc/manuals/control.rst line 150 at r4 (raw file):

   .. option:: api.addr = <string> (Optional)

      Address on which to expose the :ref:`control-rest-api`,

at

Code quote:

on

doc/manuals/control.rst line 173 at r4 (raw file):

      Local SCION address for inter-AS communication by QUIC/gRPC.
      By default, the address specified for this control service in its ``control_service`` entry of
      the :ref:`control-conf-topo` is used.

By default, the address used is that specified for this control service in its control_service entry of
the :ref:control-conf-topo.

Code quote:

      By default, the address specified for this control service in its ``control_service`` entry of
      the :ref:`control-conf-topo` is used.

doc/manuals/control.rst line 221 at r4 (raw file):

.. object:: ca

   .. option:: ca.mode = "disabled"|"in-process"|"delegating" (Default: "disabled")

delegating or delegated ?

doc/manuals/control.rst line 227 at r4 (raw file):

      If set to ``in-process``, :program:`control` handles certificate issuance requests on its own.
      If set to ``delegated``, the certificate issuance is delegated to the service defined in

delegated or delegating ?

doc/manuals/control.rst line 251 at r4 (raw file):

           based on `smallstep's step-ca <https://github.com/smallstep/certificates>`_,
         - ask SCION vendors for proprietary CA implementations and offerings,
         - or plug in your own CA service implementing the :file-ref:`spec/ca.gen.yaml` API.

Code quote:

- or

doc/manuals/control.rst line 381 at r4 (raw file):

-------------

The :program:`control` reads the ``control_service`` section of the :ref:`topology.json <common-conf-topo>` file.

This renders as "The control"
Did you mean this to read as "The program 'control'" or as "The control service" or as "Control"?

doc/manuals/control.rst line 401 at r4 (raw file):

Propagation
   Propagation is the process of receiving a beacon from a neighbor AS, extending it
   with the own AS entry and forwarding it to downstream neighbor ASes.

the own -> "the local"? "one's own"?

doc/manuals/control.rst line 470 at r4 (raw file):

   .. warning::

      Keep this parameter reasonably low to avoid explosion of beacon numbers.

an explosion

Code quote:

explosion

doc/manuals/control.rst line 518 at r4 (raw file):

   Filters are applied when a beacon is received, resulting in a "usage" classification of the
   beacon that is stored in the local beacon database.
   When the policy is changed, it will thus only be effective for newly received beacons.

Therefore, when the policy is changed, it will

Code quote:

When the policy is changed, it will thus

doc/manuals/control.rst line 526 at r4 (raw file):

      There are plans to extend this functionality but so far there are no concrete proposals.
      If you're interested to work on this, get in contact in the :ref:`chat <slack>` or create a

in working

Code quote:

to work

doc/manuals/control.rst line 648 at r4 (raw file):

If the configuration file exists, it must be syntactically valid..

The structure of the configuration is presented as a pseudo-JSON with a more detailed explanation

pseudo-JSON

Code quote:

a pseudo-JSON

matzf

Reviewable status: all files reviewed (commit messages unreviewed), 15 unresolved discussions (waiting on @jiceatscion)

doc/manuals/control.rst line 86 at r4 (raw file):