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_EXPERIMENTAL_BFD_DISABLE

Disable BFD, unconditionally consider the connection alive.

Applies to BFD sessions to all sibling routers (other routers in the same AS). Can be overridden for specific inter-AS BFD sessions with bfd.disable in an interface entry in the topology.json configuration.

SCION_EXPERIMENTAL_BFD_DETECT_MULT

Set the BFD detection time multiplier.

Default 3

Same applicability as above; can be overridden for specific inter-AS BFD sessions with bfd.detect_mult.

SCION_EXPERIMENTAL_BFD_DESIRED_MIN_TX

Defines the frequence at which this router should send BFD control messages.

Default 200ms

Same applicability as above; can be overridden for specific inter-AS BFD sessions with bfd.desired_min_tx_interval.

SCION_EXPERIMENTAL_BFD_REQUIRED_MIN_RX

Defines an frequence at which this router should send BFD control messages.

Default 200ms

Same applicability as above; can be overridden for specific inter-AS BFD sessions with bfd.required_min_rx_interval.

SCION_TESTING_DRKEY_EPOCH_DURATION

Defines the global DRKey Epoch duration that the border router assumes.

SCION_TESTING_ACCEPTANCE_WINDOW

Defines the acceptance window following the SPAO specification.

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).

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 pramming language’s light-weight user-space concurrency primitives. Go’s runtime schedules goroutines on top of a fixed number of kernel threads. The number of kernel threads is controlled by the GOMAXPROCS environment variable. See also the go runtime documentation.

By default, the router uses GOMAXPROCS packet processor goroutines, i.e. exactly one goroutine for each kernel thread created by the runtime.

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.

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.