Router

router is the SCION router. Due to the encapsulation of SCION packets, this can use ordinary UDP sockets for network communication and so can run on almost any host system without requiring any special privileges.

Command Line Reference

Synopsis

router [--config <config.toml> | help | version]

Options

--config <config.toml>

Specifes the configuration file and starts the router.

help, -h, --help [subcommand]

Display help text for subcommand.

version

Display version information.

sample [file]

Display sample files.

config

Display a configuration file sample.

completion [shell]

Generate the autocompletion script for router for the specified shell.

Run router help completion for a list of the available shells.

Run router help completion [shell] for usage information on the autocomplete script for a particular shell.

Environment Variables

SCION_TESTING_DRKEY_EPOCH_DURATION

For testing only. This option relates features.experimental_scmp_authentication.

Override the global duration for Dynamically Recreatable Key (DRKey) Infrastructure epochs.

Also applies to the control service.

Type:

duration

Default:

24h

SCION_TESTING_ACCEPTANCE_WINDOW

For testing only. This option relates features.experimental_scmp_authentication.

Defines the length of the window around the current time for which SCMP authentication timestamps are accepted. See SPAO specification.

Type:

duration

Default:

5m

GOMAXPROCS

Specified by the GO runtime. The Go runtime starts a number kernel threads such that the number of non-sleeping threads never exceeds GOMAXPROCS. By default GOMAXPROCS is equal to the number of cores in the host. That value can be changed via the GOMAXPROCS environment variable (or programatically by the application code). See the go runtime documentation for more information. One reason to change this is running multiple routers on the same host. In such a case, it is best to split the available cores among the routers, lest Go’s default assumptions causes them to compete for cores and incurr futile context switching. This precaution is especially useful in performance testing situations.

Type:

unsigned integer

Default:

all cores

Configuration

The router is configured by two main files. First, the .toml configures common features like logging and metrics and specifies the configuration directory from which all other configuration files are read. The second one is topology.json, which contains all the AS information that the router uses to forward packets.

Router Configuration

In addition to the common .toml configuration options, the router considers the following options.

general

general.id = <string> (Required)

Identifier for this router.

This is used to identify which parts of the topology.json file refer to self. Thus, id must match a key in the topology.json files’ border_routers section.

general.config_dir = <string> (Required)

Path to a directory for loading AS topology.json and keys.

If this is a relative path, it is interpreted as relative to the current working directory of the program (i.e. not relative to the location of this .toml configuration file).

features

Features is a container for generic, boolean feature flags (usually for experimental or transitional features).

features.experimental_scmp_authentication = <bool> (Default: false)

Enable the DRKey-based authentication of SCMPs in the router, which is experimental and currently incomplete.

When enabled, the router inserts the SCION Packet Authenticator Option for SCMP messages. For now, the MAC is computed based on a dummy key, and consequently is not practically useful.

router

router.receive_buffer_size = <int> (Default: 0)

The receive buffer size in bytes. 0 means use system default.

router.send_buffer_size = <int> (Default: 0)

The send buffer size in bytes. 0 means use system default.

router.num_processors = <int> (Default: GOMAXPROCS)

Number of goroutines started for SCION packets processing.

These goroutines make the routing decision for the SCION packets by inspecting, validating and updating the path information in the packet header. Packets are processed asynchronously from the corresponding read/write operations on the individual interface sockets.

Goroutines are the Go programming language’s light-weight user-space concurrency primitives. Go’s runtime schedules goroutines on top of a smaller number of kernel threads. The default is to use as many packet processors as there are kernel threads started by Go, letting other goroutines displace them sporadically. Whether more or fewer processors are preferable is to be determined experimentaly.

The number of kernel threads that go creates depends on the number of usable cores, which is controlled by the environment variable GOMAXPROCS. See GOMAXPROCS.

router.num_slow_processors = <int> (Default: 1)

Number of goroutines started for the slow-path processing which includes all SCMP traffic and traceroutes. A minimum of 1 slow-path processor is required.

router.batch_size = <int> (Default: 256)

The batch size used by the receiver and forwarder to read or write from / to the network socket.

bfd

disable = <bool> (Default: false)

Set whether the BFD feature is disabled by default.

This setting applies to BFD sessions to all neighboring routers, including sibling routers (other routers in the same AS).

Can be overridden for specific inter-AS BFD sessions with bfd.disable.

detect_mult = <uint8>, default 3

Set the BFD detection time multiplier.

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

Can be overridden for specific inter-AS BFD sessions with bfd.detect_mult.

desired_min_tx_interval = <duration>, default 200ms

Defines the frequency at which this router should send BFD control messages. 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).

Can be overridden for specific inter-AS BFD sessions with bfd.desired_min_tx_interval.

required_min_rx_interval = <duration>, default 200ms

Defines an upper bound for the frequency at which this router wants to receive BFD control messages. 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)

Can be overridden for specific inter-AS BFD sessions with bfd.required_min_rx_interval.

topology.json

The router reads the border_routers section of the topology.json file.

It uses the entry referring to its own general.id to determine the intra-AS links that this router instance is responsible for. The other router entries (“sibling routers”) define which router is responsible for which interface. This mapping is consulted during packet forwarding to determine the sibling router to which a packet transitting the AS needs to forwarded to.

Additionally, the router considers the control_service and discovery_service entries. These entries define the underlay addresses that the router uses to resolves anycast or multicast service addresses.

Keys

The router loads the forwarding secret keys master0.key/master1.key from <config_dir>/keys.

The key files contain a base64-encoded high-entropy random string. The keys should be exactly 16 bytes long (corresponding to a base64 encoding of 24 bytes with two trailing pad bytes ==). These keys must be identical to the corresponding keys used by the control service.

Note

The router and Control Service currently use these keys as input for PBKDF2 to generate the actual forwarding key. Consequently, keys of any size can currently be used. This may be changed to only accept high-entropy 16 byte keys directly in the future.

Port table

Description	Transport	Port(s)	Application protocol
Underlay data-plane	UDP	30042-30051	none
Monitoring	TCP	30442	HTTP/2

Metrics

Metrics can expose any combination of the following set of labels:

• interface: The SCION Interface ID of the interface (e.g., 4, internal).

• neighbor_isd_as: The ISD-AS of the neighboring router from which this packet was received. This label is set to the local ISD-AS for internal interfaces.

• isd_as: The local ISD-AS to which this interface belongs (note that in a multi-ISD environment a router can belong to multiple ISD-ASes, but an interface can only belong to one).

• sibling: A human-readable description of the sibling router (e.g. br1-ff_00_5-2).

Interface state

Name: router_interface_up

Type: Gauge

Description: 1 if the router in the remote AS is reachable, 0 otherwise.

Labels: interface, isd_as and neighbor_isd_as.

Connectivity to sibling router instances

Name: router_sibling_reachable

Type: Gauge

Description: 1 if a sibling router instance within the local AS is reachable.

Labels: sibling and isd_as.

Input/output bytes total

Name: router_input_bytes_total, router_output_bytes_total

Type: Counter

Description: Total number of bytes received/sent by the router. This only includes data-plane bytes. Bytes received/sent by the Dispatcher on the local system (if any) are not counted in this number. The underlay header bytes are not included in this number.

Labels: interface, isd_as and neighbor_isd_as.

Input/output packets total

Name: router_input_pkts_total, router_output_pkts_total

Type: Counter

Description: Total number of packets received/sent by the router. This only includes data-plane packets. Packets received/sent by the Dispatcher on the local system (if any) are not counted in this number.

Labels: interface, isd_as and neighbor_isd_as.

Dropped packets total

Name: router_dropped_pkts_total

Type: Counter

Description: Total number of packets dropped by the router. This metric reports the number of packets that were dropped because of errors.

Labels: interface, isd_as and neighbor_isd_as.

BFD state changes (inter-AS)

Name: router_bfd_state_changes_total

Type: Counter

Description: Total number of BFD state changes in a BFD session with a router in a different AS.

Labels: interface, isd_as and neighbor_isd_as.

BFD state changes (intra-AS)

Name: router_bfd_sibling_state_changes_total

Type: Counter

Description: Total number of BFD state changes in a BFD session with a router in the local AS.

Labels: interface, isd_as and neighbor_isd_as.

BFD packets sent/received (inter-AS)

Name: router_bfd_sent_packets_total, router_bfd_received_packets_total

Type: Counter

Description: Number of BFD packets sent to, respectively received from, the router in a different AS.

Labels: interface, isd_as and neighbor_isd_as.

BFD packets sent/received (intra-AS)

Name: router_bfd_sent_sibling_packets_total, router_bfd_received_sibling_packets_total

Type: Counter

Description: Number of BFD packets sent to, respectively received from, the router in the local AS.

Labels: sibling and isd_as.

Service instance count

Name: router_service_instance_count

Type: Gauge

Description: Number of service instances known by the data plane. The router monitors the reachability of control and discovery service instances. Instances are dynamically added and removed from the data plane based on their reachability. Packets with an svc address as destination are sent to any instance known by the data plane.

Labels: service and isd_as.

Service instance changes total

Name: router_service_instance_changes_total

Type: Counter

Description: Number of total service instance changes. Both addition and removal of a service instance is accumulated.

Labels: service and isd_as.

HTTP API

The HTTP API is exposed by the router application. The IP address and port of the HTTP API is taken from the metrics.prometheus configuration setting.

The HTTP API does not support user authentication or HTTPS. Applications will want to firewall this port or bind to a loopback address.

The router currently only supports the common HTTP API.