Configuration

The general pattern for the long-running SCION services (Router, Control Service, Gateway, Daemon), is to load a .toml configuration file which is specified with a --config option when starting the service. This configuration file specifies all options for running the service, in particular the configuration directory from which all other configuration files are read.

The set of required configuration files differs between the applications. The configuration files are organized specifically to allow sharing the configuration directory between different services.

Configuration .toml

This configuration is a TOML-file.

The following options are implemented by all applications.

log

log.console.level = "debug"|"info"|"error" (Default: "info")

Log level at startup.

The log level can be changed at runtime via the HTTP API.

log.console.format = "human"|"json" (Default: "human"): Encode the log either in a human oriented form or json.

log.console.disable_caller = <boolean>: If true, disable annotating logs with the calling function’s file name and line number. By default, all logs are annotated.

metrics

metrics.prometheus = <string>

Address on which to export the common HTTP API, in the form host:port, ip:port or :port. The eponymous prometheus metrics can be found under /metrics, but other endpoints are always exposed as well.

If not set, the HTTP API is not enabled.

Database Connections

The services use different SQLite database files, with paths and advanced connection options configured individually. The pattern is:

some_db

some_db.connection = <string>: File path or SQLite URI for SQLite database.

some_db.max_open_conns = <int> (Default: 1)

Sets sets the maximum number of open connections to the database.

This should be left at 1 for SQLite databases.

some_db.max_idle_conns = <int> (Default: 2)

Sets the maximum number of connections in the idle connection pool. If this value is higher than max_open_conns, then the effective value is the same as max_open_conns.

This should be left > 0 for SQLite databases, in particular if an in-memory database is used.

topology.json

The topology.json file of an AS specifies all the inter-AS connections to neighboring ASes, and defines the underlay IP/UDP addresses of services and routers running in this AS. The topology information is needed by Router and Control Service instances, and also by end-host applications (including the Gateway) which usually obtain it indirectly from the Daemon running on the same host.

Note

The topology.json configuration file contains information that is not relevant for all consumers of the file.

For the sake of simplicity, you can use the same topology.json file on all SCION components within the SCION AS. In more advanced configurations, an extract of the topology.json file can be presented to each specific component.

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

Pseudo-JSON description of the structure of the topology.json configuration file.

{
   "isd_as": <isd-as>,
   "attributes" = [<"core">?]
   "mtu": <int>,
   "border_routers": {
      <router-id>: {
         "internal_addr": <ip:port>,
         "interfaces": {
            # ... interfaces definitions ... (see below)
         }
      }
      # ...
   },
   "control_service": {
      <cs-id>: {
         "addr": <ip:port>
      }
      # ...
   },
   "discovery_service": {
      <ds-id>: {
         "addr": <ip:port>
      }
      # ...
   },
}

Each interfaces entry defines one inter-domain link to a neighboring AS.

<interface-id>: {
   "isd_as": <neighbor-isd-as>,
   "link_to": <"parent"|"child"|"peer"|"core">,
   "mtu": <int>,
   "underlay": {
      "public": <ip:port>,
      "bind": <ip>,
      "remote": <ip:port>,
   },
   "bfd": {              # optional
      "disable": <bool>,
      "detect_mult": <uint8>,
      "desired_min_tx_interval": <duration>,
      "required_min_rx_interval": <duration>
   }
}

isd_as = <isd-as>, required: The ISD-AS of this AS.

attributes = [<"core">?], default []: Role of this AS. ["core"] for core ASes, [] for non-core ASes.

Note

Historical relict; there used to be multiple different attributes (“core”, “issuing”, “authoritative”, “voting”) which could apply a more fine granular role configuration. This functionality has moved into different places, only “core” remains.

mtu = <int>, required: Common Maximum Transmission Unit in bytes for SCION packets (SCION headers and payload) for intra-AS connections. This is the minimum MTU between any two internally connected border router interfaces.

border_routers

<router-id>: Identifier for a border router instance. Matches the general.id of a router instance.

internal_addr = <ip:port>, required: UDP address on which the router receives SCION packets from sibling routers and end hosts in this AS.

interfaces

<interface-id>

The interface ID for an inter-domain link.

In this topology.json file, the ID is contained in a string.

isd_as = <isd-as>, required: The ISD-AS of the neighboring AS.

link_to = "parent"|"child"|"peer"|"core", required: Type of the link relation to the neighbor AS. See Link Types.

Warning

Link type peer is not fully implemented yet. See #4093.

mtu = <int>, required: Maximum Transmission Unit in bytes for SCION packets (SCION headers and payload) on this link.

underlay, required for "self"

Underlay specifies the local addresses used for the underlay IP/UDP connection to the neighbor router. These addresses are only relevant to the router that operates this link, i.e. the router instance with general.id matching <router-id>.

The underlay.public is the address of this side of the link, while underlay.remote is the address of the remote side of the link.

In the configuration for the corresponding interface in the neighbor AS, these addresses are exactly swapped.

public = <ip:port>, required: The IP/UDP address of this router interface.

bind = <ip>, optional

IP address to which the router should bind(2).

This can optionally override the the IP in public, for the case that router instance is running in a container, a VM, or generally any kind of NAT. If NAT occurs, public is the address of the interface as seen by the neighbor router, while bind is the local address.

remote = <ip:port>, required: The IP/UDP address of the corresponding router interface in the neighbor AS.

bfd, optional

Bidirectional Forwarding Detection (BFD) is used to determine the liveness of the link by sending BFD control messages at regular intervals.

These settings are only relevant to the router that operates this link, i.e. the router instance with general.id matching <router-id>.

disable = <bool>, default false

Disable BFD, unconditionally consider the connection alive.

Takes precedence over SCION_EXPERIMENTAL_BFD_DISABLE.

detect_mult = <uint8>, default 3

After detect_mult consecutively missing control packets, the BFD session is considered “down” and is reset.

Takes precedence over SCION_EXPERIMENTAL_BFD_DETECT_MULT.

desired_min_tx_interval = <duration>, default 200ms

Defines the frequency at which this router should send BFD control messages for this inter-domain link. The effective interval is the result of negotiating with the remote router during session establishment; the value will be max(desired_min_tx_interval, remote.required_min_rx_interval).

Takes precedence over SCION_EXPERIMENTAL_BFD_DESIRED_MIN_TX.

required_min_rx_interval = <duration>, default 200ms

Defines an upper bound for the frequency at which this router wants to receive BFD control messages for this inter-domain link. The effective interval at which the remote router will send control messages is the result of negotiating with the remote router during session establishment; the value will be max(remote.desired_min_tx_interval, required_min_rx_interval).

Takes precedence over SCION_EXPERIMENTAL_BFD_REQUIRED_MIN_RX.

control_service

<cs-id>: Identifier for a control service instance. Matches the general.id of a control service instance.

addr = <ip:port>, required

The address of the control service. This is both a UDP and TCP address;

The UDP address is the underlay address for the control service’s anycast address. This is used when communicating with control services in other SCION ASes, using SCION.
The TCP address is used to serve the grpc API to end hosts in the local AS.

discovery_service

<ds-id>: Identifier for a discovery service instance.

Hint

The implementation of the discovery service is part of the control service. This usually points to a control service instance.

addr = <ip:port>, required: See control_service.addr, above.

HTTP API

Known issue. If an unknown route is accessed (e.g., /this-does-not-exist), the HTTP reply will respond as if the / route were used and print an HTML page with links to all exposed APIs. This response will have a 200 (OK) HTTP Status Code.

The following APIs are exposed by most applications:

/: (EXPERIMENTAL) - Method GET. Returns an HTML page containing links to exposed APIs.
/config: (EXPERIMENTAL)
- Method GET. Prints the TOML representation of the config the application is currently using.
/info: (EXPERIMENTAL)
- Method GET. Prints a plaintext representation of general information about the application. Amongst others, the information includes version, process ID, and user/group IDs.
/log/level: (EXPERIMENTAL)
- Method GET: Returns the current logging level, in JSON.
- Method PUT: Sets the current logging level. Either JSON or URL encoded request body is supported.For example, to set the logging level to debug run:
```
curl -X PUT "http://172.20.1.3:30442/log/level" -d level=debug
curl -X PUT "http://172.20.1.3:30442/log/level" -H "Content-Type: application/json" -d '{"level":"debug"}'
```
  If the content type is set to application/x-www-form-urlencoded (curl default), the endpoint expects a URL encoded request body. In all other cases, a JSON encoded request body is expected.
/metrics:
- Method GET: Returns the Prometheus metrics exposed by the application.
/debug/pprof:
- Serves runtime profiling data in the format expected by the pprof visualization tool. See net/http/pprof for details on usage.