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