Running SCION Locally

SCION is an Internet architecture and SCION networks are composed of many hosts running the SCION control-plane services, routers, and SCION-enabled applications. To simplify development, testing, and tinkering, we provide a tool that generates test topologies and runs an entire SCION “Internet” on a single machine. Packets are only sent between different processes on the same host, not over the network.

Running SCION in this developement setup, is also called running a local topology.

The scripts support two different process orchestrators as “backends”:

supervisor. This is the default and a bit more light-weight. Packets are sent over the loopback interface.
docker compose. Runs individual processes in separate containers connected with docker network bridges. Only this mode supports running a “SCION-IP gateway”.

Hint

Before attempting to use the docker compose mode, be sure to build the necessary docker images with make docker-images

Quickstart

Prerequisites

Setting up the Development Environment
Build, using make

Generate the control-plane PKI keys and certificates, configuration files, and process orchestrator (supervisor or docker compose) configuration.
```
./scion.sh topology -c topology/tiny.topo
```
Attention

The certificates created by this command expire after 3 days if the infrastructure is not running for automatic renewal.
To start the infrastructure we just generated, run:
```
./scion.sh run
```
To verify that your topology is running correctly, you can run an end to end reachability test using:
```
bin/end2end_integration
```
This local infrastructure runs multiple SCION daemons, one in each AS. We need to specify which instance is used when running applications that rely on the SCION daemon, e.g. to query paths.
```
# show paths from 1-ff00:0:112 to 1-ff00:0:110
bin/scion showpaths --sciond $(./scion.sh sciond-addr 112) 1-ff00:0:110
```
To stop the infrastructure, run:
```
./scion.sh stop
```

Local Topology Environment

The scion.sh topology command generates configuration in the gen/ directory in the repository.

There is a subdirectory for each AS (e.g. gen/ASff00_0_110 for AS ff00:0:110), containing the configuration for the services and routers of that AS. Specifically, these contain the .toml configuration files for the individual components and a shared topology.json configuration.

Various helper files are also generated for the benefit of scripts and tooling of the test infrastructure, for example, gen/sciond_addresses.json is a simple mapping from AS number to the address of the corresponding scion daemon instance.

If scion.sh topology -d command is used, configuration files are created to enable running the SCION services in docker containers (see docker). Otherwise, a configuration file is created to enable running the SCION services as plain processes (see supervisor)

supervisor

The gen/supervisord.conf configuration defines the programs that make up the local topology.

All the SCION traffic goes via the loopback interface, the separation of the internal networks of the simulated ASes is not enforced in any way.

There is a single Dispatcher instance, receiving and sending the SCION packets for the Control Service instances and SCION applications/tools in all simulated ASes.

There is one Daemon instance running for each simulated AS. Commands accessing the SCION network can be run directly from the host. The information about the local AS in which the command is running, is determined by the SCION daemon instance that the command connects to. For example:

# show paths from 1-ff00:0:112 to 1-ff00:0:110
bin/scion showpaths --sciond $(./scion.sh sciond-addr 112) 1-ff00:0:110

# reveal the full SCION address of a simulated host in in 1-ff00:0:111
bin/scion address --sciond $(./scion.sh sciond-addr 111)

# and now ping this host from inside AS 1-ff00:0:110, with interactive path prompt
bin/scion ping --sciond $(./scion.sh sciond-addr 110) 1-ff00:0:111,127.0.0.1 --interactive

docker

The main docker compose file is gen/scion-dc.yml.

Each SCION service or router runs in a separate container, and the network access of the individual containers is configured to mimick real-world connectivity.

There are “tester” containers configured in each AS to mimick end hosts in a SCION AS. These tester containers can be used to run commands accessing the SCION network. As a shorthand for the somewhat unwieldy docker compose invocation, the tools/dc script can be used. For example:

# show paths from 1-ff00:0:112 to 1-ff00:0:110
tools/dc exec_tester 1-ff00_0_112 bin/scion showpaths 1-ff00:0:110

# reveal the full SCION address of the tester container in 1-ff00:0:111
tools/dc exec_tester 1-ff00_0_111 bin/scion address

# and now ping this host from inside AS 1-ff00:0:110, with interactive path prompt
tools/dc exec_tester 1-ff00_0_110 bin/scion ping 1-ff00:0:111,172.20.0.29

Note that the --sciond flag does not need to be provided in this setup, as it’s preconfigured in the tester containers via the environment variable SCION_DAEMON.

scion.sh

scion.sh is the developer script to setup and run a local topology.

Note

The SCION tools and services need to be built before running these commands, using make or make docker-images (when using the docker compose configuration).

The basic usage is ./scion.sh <subcommand> <options>. The main subcommands are:

topology

Generate the control-plane PKI keys and certificates, configuration files, and process orchestrator (supervisor or docker compose) configuration for a given network topopology defined in a *.topo configuration file.

-c <FILE.topo>, --topo-config <FILE.topo>: Path to the *.topo configuration file.

-d, --docker: Create a docker compose configuration (instead of default supervisord).

--sig: Generate a Gateway for each AS. Only available with -d.

-h, --help: Display help text, list all options

run, start: Start the local SCION topology.

stop: Terminate this run of the local SCION topology.

start-monitoring: Start the monitoring services (jaeger and prometheus).

stop-monitoring: Stop the monitoring services.

sciond-addr <ISD-AS>: Return the address for the scion daemon for the matching ISD-AS by consulting gen/sciond_addresses.json. The ISD-AS parameter can be a substring of the full ISD-AS (e.g. last three digits), as long as there is a unique match.

help: Describe all available subcommands

end2end_integration

bin/end2end_integration is a basic functional test.

The basic usage is ./end2end_integration <options>.

-d: Assume the SCION services are dockerized. Must be consistent with the last invocation of scion.sh topology.