SCION

The Configuration reference section provides the full configuration reference and in the following sections you will find a description of most relevant SCION configuration sections with more elaborated examples.

Configuration reference

Select API Version:

v0.40v0.39v0.38next

Anapaya appliance configuration (scion only)

scion object

The SCION section contains the configuration of the SCION protocol and AS. It consists of a list of SCION AS configurations. An Anapaya appliance can have configurations for multiple SCION ASes, however, in most cases there will only be a single SCION AS configured. Additionally, the path and beacon synchronization between multiple appliances can be configured in this section.

ases object[]

List of SCION ASes that this device is part of identified by their ISD-AS identifier.

Array [

ca_service object

SCION CPPKI (Control Plane Public Key Infrastructure) CA service configuration data. This section defines how the anapaya-scion interacts with the SCION CPPKI CA service backend. It is only required for SCION ASes that act as a CA in their respective ISD.

anapaya_vault object

The configuration data of the Anapaya SCION CPPKI CA service. This section must be provided when the CA service type is ANAPAYA_VAULT.

addressesstring[]

The list of addresses where the Anapaya Vault backend can be reached. This list must be non-empty.

credentials object

The necessary credentials to be logged into the Anapaya Vault backend.

role_idstring

The role ID used to authenticate with the Vault backend via the AppRole Authentication Method. See https://www.vaultproject.io/docs/auth/approle for more details.

secret_id_refstring<secret-ref>

Reference to the secret ID used to authenticate with the Vault backend via the AppRole Authentication Method. See https://www.vaultproject.io/docs/auth/approle for more details.

validation object

The validation option configures how the Anapaya Vault backend validate CSRs.

subjectstring

The subject option configures how the Anapaya Vault backend validates the subject of the CSRs.

Possible values: [MATCHING_ISD_AS, EXACT_MATCH]

external object

The configuration data for the External SCION CPPKI CA service. This section must be provided when the CA service is of type EXTERNAL.

addressstring

The address where the external SCION CPPKI CA service can be reached.

Example: 192.0.2.3:5000

client_idstring

The client ID that is used to authenticate with the CA service. The client ID is set in the 'sub' and 'iss' claim of the generated JWT. If unset, a generic client ID based on the ISD-AS is used.

shared_secret_refstring<secret-ref>

Reference to the shared secret used between the appliance and the CA service (used to generate JWTs for authentication).

service_typestring

The type of CA service that is used by the appliance.

EXTERNAL is a generic CA backend not implemented by Anapaya. Note that the external CA backend must implement the SCION CA API to be compatible with the Anapaya appliance. If this service type is used, the external section must be configured.

ANAPAYA_VAULT is the SCION CA backend provided by Anapaya. It is based on Hashicorp Vault with a suitable frontend. If this service type is used, the anapaya_vault section must be configured.

IN_PROCESS is a CA service that is implemented in the Anapaya appliance. It should only be used for testing purposes and is not suitable for productive use. If this service type is used, no other section needs to be configured.

Possible values: [EXTERNAL, ANAPAYA_VAULT, IN_PROCESS]

control object

The configuration for the SCION control service.

addressstring

The address of the control service. Clients connect to this address to request control plane data, e.g., SCION path segments. The address needs to be specified as a string in the format :. If the port is set to 0 it will be automatically assigned.

Example: 192.168.1.1:30100

enabledbooleanrequired

Whether the service is enabled.

coreboolean

Indicate whether the AS is core in its ISD. The core flag must only be set if the AS is a core AS in its ISD (as indicated in the TRC of the ISD). A core AS provides connectivity to other SCION ISDs and operates the main path directories within its ISD. It also regularly initiates path construction beacons that create path segments to other SCION ASes in the same ISD or to other core ASes in different ISDs. For most of the ASes this is not the case and the flag must be set to false or not specified (defaults to false)

Default value: false

cppki object

SCION CPPKI configuration for the SCION AS.

disable_auto_renewalboolean

Whether automatic renewal of AS certificates should be disabled. Usually, this value should not be set. By disabling certificate renewal, the appliance is set into a manual mode where new AS certificates must be provisioned manually and periodically.

disable_issuer_fallbackboolean

Whether fallback to the certificate authorities listed in the latest TRC should be disabled. By disabling this feature, the appliance will only use the issuers explicitly set in the configuration. If not disabled, the certificate authorities in the latest TRC are tried in the order that their certificate appears in the TRC.

issuers object[]

The SCION CPPKI Issuers that issue certificates for the local SCION AS. The list of issuers is tried in order of their priority. If no issuers are set explicitly, the renewal process will use the issuer of the newest existing SCION CPPKI AS Certificate.

Array [

isd_asstring<isd-as>required

The ISD-AS identifier of the issuing AS.

Example: 1-ff00:0:120

priorityinteger<int32>required

The priority of the issuing AS. The appliance attempts to get certificates issued from the AS with the highest priority. The value 0 indicates the highest priority, higher numbers are lower priority.

]

defaultboolean

Default indicates whether the respective SCION AS should be used by default as the source AS by SCION applications, e.g., scion ping or scion showpaths. The configurations with more than one default ASes will be rejected because there can only be one default AS. If there is only a single AS configured, it will be the default. Therefore, this setting is only necessary if multiple ASes are configured on the appliance.

Default value: false

details object

User-defined details about the SCION AS for informational purpose.

descriptionstring

User-defined description, or comment, that describes this SCION AS.

namestring

SCION AS name for informational purpose.

forwarding_key_refstring<secret-ref>

Reference to the forwarding key of this AS. The forwarding key secret is used to authenticate the hop field of the SCION path which corresponds to this AS. It is a local secret that only needs to be known to the AS. The forwarding key MUST be identical across all appliances in an AS. The referenced secret must be a base64-encoded string.

isd_asstring<isd-as>required

The ISD-AS identifier is the tuple that uniquely identifies the AS within a SCION isolation domain (ISD). This number is usually assigned by a numbering authority.

Example: 1-ff00:0:110

neighbors object[]

List of neighbor SCION ASes that this device is connected to via one or multiple SCION interfaces. Each entry is identified by the remote ISD-AS.

Array [

descriptionstring

Description, or comment, for the neighbor AS.

interfaces object[]

The local SCION interfaces in the current AS that link to the neighbor AS. The local end of the link is an external SCION interface.

Array [

addressstring

UDP/IP underlay endpoint of the SCION Interface. The data plane traffic is received on this address. The address must be specified as host:port. Both host and port must be specified.

Example: 169.254.0.1:30100

administrative_statestring

The administrative state of the interface with one of the following values:

• UP The interface is up and ready to send/receive SCION packets as well as being advertised during beaconing.
• DATAPLANE_ONLY The interface is up and ready to send/receive SCION packets, but is not advertised during beaconing.
• ADMIN_DOWN The interface is down and neither sends/receives SCION packets nor is it advertised during beaconing.

Experimental: Currently only UP is supported.

Possible values: [UP, ADMIN_DOWN, DATAPLANE_ONLY]

bfd object

Bidrirectional Forwarding Detection (BFD) configuration for the SCION interface. BFD is used to track the healthiness of a SCION link.

desired_minimum_tx_intervalinteger<uint32>

The minimum interval between transmission of BFD control packets that the operator desires. This value is advertised to the peer, however the actual interval used is specified by taking the maximum of desired-minimum-tx-interval and the value of the remote required-minimum-receive interval value. This value is specified as an integer number of microseconds.

Default value: 200000

detection_multiplierinteger<uint8>

The number of packets that must be missed to declare this session as down. The detection interval for the BFD session is calculated by multiplying the value of the negotiated transmission interval by this value.

Possible values: >= 1 and <= 255

Default value: 3

enabledboolean

If set to true, then the BFD session is enabled on the SCION interface - if it is set to false, BFD is disabled on that SCION interface. When disabled, the health of the interface is not tracked and it is assumed to be healthy. Note that the remote side of this SCION interface should have the same setting for enabled.

Default value: true

required_minimum_receiveinteger<uint32>

The minimum interval between received BFD control packets that this system should support. This value is advertised to the remote peer to indicate the maximum frequency (i.e., minimum inter-packet interval) between BFD control packets that is acceptable to the local system.

Default value: 200000

descriptionstring

Description, or comment, for the SCION interface.

enable_scion_rssboolean

Flag to activate SCION RSS for this link. If activated, the router utilizes UDP source port entropy on the underlay such that the remote router can leverage RSS for SCION traffic. This can greatly improve throughput performance. For low throughput SCION links (up to 1 Gbps), enabling SCION RSS is not necessary. Before enabling this feature, please ensure that the remote router supports SCION RSS.

Default value: false

interface_idinteger<uint16>required

SCION interface identifier. It must be unique in the SCION AS.

Possible values: >= 1 and <= 65535

remote object

Remote SCION interface endpoint of the link.

addressstring

UDP/IP underlay endpoint of the remote SCION Interface. The address must be specified as host:port. This information is provided by the neighbor AS.

Example: 169.254.0.2:30200

interface_idinteger<uint16>required

The SCION interface identifier of the remote end of the link. This information is provided by the neighbor AS.

Possible values: >= 1 and <= 65535

scion_mtuinteger<uint16>

The maximum transmission unit in bytes for SCION packets on the external interface. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header. Note that the SCION MTU can differ between the various links and also from SCION MTU supported in the internal network of the local AS.

Default value: 1472

Example: 1472

]

neighbor_isd_asstring<isd-as>required

ISD-AS number of the neighbor AS.

Example: 2-ff00:0:210

relationshipstringrequired

The relationship to the neighbor AS. If the local AS is core, this value must either be CORE or CHILD. If the local AS is non-core, this value must either be PARENT, CHILD or PEER.

Possible values: [CORE, CHILD, PARENT, PEER]

]

router object

The configuration for the SCION router service. The address configures where the router is exposed. AS internal hosts send SCION data plane traffic to this address for forwarding over the local SCION interfaces.

enabledbooleanrequired

Whether the service is enabled.

internal_interfacestring

The internal SCION interface is where the appliance receives SCION packets from AS internal hosts/applications for forwarding. It is defined as a UDP/IP network endpoint on which the SCION packets are received from the internal network. The endpoint must be specified as a string in the format :. If the port is set to 0 it will be automatically assigned.

Example: 192.168.1.1:30100

scion_mtuinteger<uint16>

The maximum transmission unit in bytes for SCION packets. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header. If the Ethernet MTU is 1500, the SCION MTU is 1472 for an IPv4 underlay network and 1452 for an IPv6 underlay network.

Default value: 1472

Example: 1472

shard_idinteger<uint32>

The control and the data plane of a SCION AS is split into multiple shards. Each shard is responsible for processing and disseminating path information only for a subset of links. Shards are units that operate and fail independently from other shards. Usually, each appliance operates as a separate shard to increase the resiliency of the network. This field is the ID of the shard to which the control service and the router on this appliance belong.

]

synchronization object

The synchronization configuration contains the configuration for SCION path and beacon synchronization.

beacon_synchronization_intervalstring<duration-string>

The interval between two consecutive beacon synchronizations attempts to the cluster peers. It requires a unit suffix out of ['d', 'h', 'm', 's']. The encoding consists of a decimal number concatenated with a suffix; for example, '5s', '10m', '12h', and '1d'.

Default value: 4s

path_segment_synchronization_intervalstring<duration-string>

The interval between two consecutive path segment synchronizations attempts to cluster peers. It requires a unit suffix out of ['d', 'h', 'm', 's']. The encoding consists of a decimal number concatenated with a suffix; for example, '5s', '10m', '12h', and '1d'.

Default value: 4s

General AS configuration

Each SCION AS has several general AS configuration options, such as the ISD-AS identifier, the AS forwarding key reference, or a human-readable description of the AS.

Example

{
  "scion": {
    "ases": [
      {
        "isd_as": "1-ff00:1:1",
        "forwarding_key_ref": "forwarding-key_1-ff00:1:1@1",
        "core": true,
        "shard_id": 1,
        "scion_mtu": 1472,
        "default": true,
        "details": {
          "description": "This is a test AS in ISD 1",
          "name": "Test AS 1",
        }
      }
    ]
  }
}

forwarding key

Create a new forwarding key with the following command:

appliance-cli crypto forwarding-key

Data plane configuration

Even though SCION is a layer 3 network protocol, SCION packets are encapsulated in UDP/IP packets between individual SCION routers and SCION endhosts (generally referred to as SCION nodes). In other terms, SCION is using a UDP/IP underlay to transport SCION packets between SCION nodes. These UDP/IP packets are only valid between two SCION nodes and change after every SCION hop.

The SCION data plane configuration consists of the router and the neighbors sections. The router section contains the configuration of the internal SCION interface internal_interface, while the neighbors section defines all the SCION links to other SCION ASes, i.e., the external SCION interfaces.

Internal interface configuration

The internal SCION interface is where the appliance receives SCION packets from AS internal hosts for forwarding. It is defined as a UDP/IP network endpoint on which the SCION packets are received from the internal network. The endpoint needs to be specified as a string in the format <ip>:<port>. If the port is set to 0 it will be automatically assigned.

Example

{
  "scion": {
    "ases": [
      {
        "router": {
          "enabled": true,
          "internal_interface": "192.168.1.1:31000"
        }
      }
    ]
  }
}

External interface configuration

The external SCION interfaces are configured using the neighbors section. Each neighbor is another SCION AS identified by its ISD-AS identifier. There can be multiple SCION links configured towards the same neighbor AS. Each link is defined by a local and remote SCION interface ID and a local and remote UDP/IP endpoint. Note that the local SCION interface ID MUST be unique within the AS. The remote SCION interface ID and the UDP/IP endpoint is given by the remote operator.

An important aspect is the relationship with the neighbor AS. This can either be CORE, CHILD, PARENT, or PEER and defines the relationship of the AS to the neighbor AS. CORE relationships are used for core ASes, CHILD/PARENT encode upstream/downstream relationships, and PEER denotes a peer relationship. Note that the CORE relationship is only valid for core ASes, i.e., CORE property must be set to true in the general AS configuration.

note

The PEER relationship is currently not supported by the appliance.

Example: Single parent link to an upstream AS

{
  "scion": {
    "ases": [
      {
        "neighbors": [
          {
            "neighbor_isd_as": "1-ff00:1:1",
            "relationship": "PARENT",
            "interfaces": [
              {
                "interface_id": 1,
                "address": "[fd02:e8a2:c9e2:03e6::2]:30100",
                "administrative_state": "UP",
                "scion_mtu": 1452,
                "remote": {
                  "address": "[fd02:e8a2:c9e2:03e6::1]:30100",
                  "interface_id": 201
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Two CORE links between two SCION Core ASes

{
  "scion": {
    "ases": [
      {
        "neighbors": [
          {
            "neighbor_isd_as": "1-ff00:1:1",
            "relationship": "CORE",
            "interfaces": [
              {
                "interface_id": 1,
                "address": "169.254.1.1:30100",
                "administrative_state": "UP",
                "scion_mtu": 1472,
                "remote": {
                  "address": "169.254.1.2:30101",
                  "interface_id": 3
                }
              },
              {
                "interface_id": 200,
                "address": "169.254.100.1:30100",
                "administrative_state": "ADMIN_DOWN",
                "scion_mtu": 1472,
                "remote": {
                  "address": "169.254.100.2:30101",
                  "interface_id": 1
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Bidirectional Forwarding Detection (BFD)

Bidirectional Forwarding Detection (BFD) is used to track the health of a SCION link and can be configured for each SCION link.

note

In most cases, the default values work well and the BFD configuration does not need to be explicitly set.

The following example shows how to configure BFD for an external interface that runs over an unreliable network. To account for that, the detection multiplier is increased to 10 and timers decreased to 50ms (50000us), i.e., BFD packets are sent more frequently and more missing packets are tolerated before declaring the link as down.

Example: Custom BFD configuration for an unreliable underlay

{
  "bfd": {
    "enabled": true,
    "desired_minimum_tx_interval": 50000,
    "detection_multiplier": 10,
    "required_minimum_receive": 50000
  }
}

Control plane configuration

The SCION control plane configuration consists of the control service and the control plane PKI (CP-PKI). The control service participates in the SCION path discovery and path management (beaconing and registration) and is responsible that the appliance can fetch and register SCION paths. The control plane PKI is used to sign and verify SCION control plane objects, such as beacons or path segments. Each appliance has its own SCION AS certificate and needs to frequently renew it.

Example with two issuing CAs

{
  "scion": {
    "ases": [
      {
        "control": {
          "enabled": true,
          "address": "192.168.1.1:40100"
        },
        "cppki": {
          "issuers": [
            {
              "isd_as": "1-ff00:1:100",
              "priority": 0,
            },
            {
              "isd_as": "1-ff00:1:200",
              "priority": 1,
            }
          ]
        }
      }
    ]
  }
}

Certificate authority configuration

For ASes that act as a certificate authority (CA) in one or multiple SCION ISDs, the CA configuration section contains the necessary parameters to interface with SCION CA backend.

note

The CA configuration is only needed for SCION ASes that act as a certificate authority in one or multiple SCION ISDs. For all other ASes this section must not be configured. If you are not sure whether you have to configure the CA section, chances are that you do not have to.

There are three possible backends that can be configured: ANAPAYA_VAULT, EXTERNAL, or IN_PROCESS:

• ANAPAYA_VAULT is the SCION CA backend provided by Anapaya. It is based on Hashicorp Vault with a suitable frontend. If this service type is used, the anapaya_vault section must be configured.
• EXTERNAL is a generic CA backend not implemented by Anapaya. Note that the external CA backend must implement the SCION CA API to be compatible with the Anapaya appliance. If this service type is used, the external section must be configured.
• IN_PROCESS is a CA service that is implemented in the Anapaya appliance. It should only be used for testing purposes and is not suitable for productive use. If this service type is used, no other section needs to be configured.

Example: Anapaya Vault CA configuration

{
  "ca_service": {
    "service_type": "ANAPAYA_VAULT",
    "anapaya_vault": {
      "addresses": [
        "https://vault.example.com:8200"
      ],
      "credentials": {
        "role_id": "role-id",
        "secret_id_ref": "ca-secret-id_<isd-as>@1"
      },
    }
  }
}

Example: External CA configuration

{
  "ca_service": {
    "service_type": "EXTERNAL",
    "external": {
      "address": "https://ca.example.com:5000",
      "client_id": "client-id",
      "shared_secret_ref": "ca-shared-secret_<isd-as>@1"
    }
  }
}

Path and beacon synchronization

Each appliance automatically synchronizes SCION paths and beacons with other appliances in the same SCION AS. This ensures that all appliances in the same SCION AS eventually have the same path and beacon information. Synchronization happens at regular intervals - every 4s by default. This interval can be configured in the synchronization section, e.g., to 30s as shown in the example below.

Example: Synchronization configuration

{
  "scion": {
    "synchronization": {
      "beacon_synchronization_interval": "30s",
      "path_segment_synchronization_interval": "30s"
    }
  }
}