netsec-ethz / scion-apps

Public repository for SCION applications
Apache License 2.0
20 stars 43 forks source link

scion-apps

This repo contains demo applications using the SCION protocol.

The applications are written in Go, with some supporting code in Python. A SCION Internet connection (for instance via SCIONLab) is required to run these applications.

More information on SCION, and tutorials on how to set up SCION and SCIONLab.

Installation:

Download and install our Debian packages:

sudo apt-get install apt-transport-https
echo "deb [trusted=yes] https://packages.netsec.inf.ethz.ch/debian all main" | sudo tee /etc/apt/sources.list.d/scionlab.list
sudo apt-get update
sudo apt install scion-apps-*

Build:

  1. Install Go. We currently support Go versions 1.19 and 1.20.

    See e.g. https://github.com/golang/go/wiki/Ubuntu

  2. Install dependencies

    Building the SSH tool requires libpam0g-dev:

    sudo apt-get install -y libpam0g-dev
  3. Clone this repository

    git clone https://github.com/netsec-ethz/scion-apps.git

    Note: because this is using go modules, there is no need to put this under $GOPATH

  4. Install golangci-lint, which is used to run format checks and various linter steps

    make setup_lint
  5. Run make to build all projects (and run linters). Run make -j to use multiple jobs to build.

  6. Run make test to run the linters and unit tests.

  7. Run make install to build all projects and install into $GOPATH/bin.

Running:

All of these applications require a running SCION endhost stack, i.e. a running SCION dispatcher and SCION daemon. Please refer to the SCIONLab tutorials to get started.

Environment

The dispatcher and sciond sockets are assumed to be at default locations, but this can be overridden using environment variables:

    SCION_DISPATCHER_SOCKET: /run/shm/dispatcher/default.sock
    SCION_DAEMON_ADDRESS: 127.0.0.1:30255

This is convenient for the normal use case of running the endhost stack for a single SCION AS. When running multiple local ASes, e.g. during development, the address of the sciond corresponding to the desired AS needs to be specified in the SCION_DAEMON_ADDRESS environment variable. In this case, the different sciond addresses can be found in their corresponding sd.toml configuration files in the gen/ASx directory, or summarized in the file gen/sciond_addresses.json.

Hostnames

Hostnames are resolved by scanning /etc/hosts, /etc/scion/hosts and by a RAINS lookup.

Hosts can be added to /etc/hosts, or /etc/scion/hosts by adding lines like this:

# The following lines are SCION hosts
17-ffaa:1:10,[10.0.8.100] server1
18-ffaa:0:11,[10.0.8.120] server2

The RAINS resolver address can be configured in /etc/scion/rains.cfg. This configuration file needs to contain the SCION address of the RAINS resolver, in the form <ISD>-<AS>,[<IP>].

_examples

The directory _examples contains examples for the usage of the SCION libraries.

bat

bat is a cURL-like tool for testing, debugging, and generally interacting with HTTP servers over SCION/QUIC. Documentation of the code is available in the bat README.

Installation and usage information is available on the SCION Tutorials web page for bat.

bwtester

The bandwidth testing application bwtester enables a variety of bandwidth tests on the SCION network. Documentation of the code and protocol are described in the bwtester README.

Installation and usage information is available on the SCION Tutorials web page for bwtester.

netcat

netcat contains a SCION port of the netcat application. See the netcat README for more information.

pkg

Pkg contains underlaying library code for scion-apps.

sensorapp

Sensorapp contains fetcher and server applications for sensor readings, using the SCION network.

Installation and usage information is available on the SCION Tutorials web page for sensorapp.

skip

skip is a very simple local HTTP proxy server for very basic SCION browser support. See the skip README for more information.

ssh

Directory ssh contains a SSH client and server running over SCION network.

More documentation is available in the ssh README.

web-gateway

web-gateway is a SCION web server that proxies web content from the TCP/IP web to the SCION web.

webapp

Webapp is a Go application that will serve up a static web portal to make it easy to experiment with SCIONLab test apps on a virtual machine.

Installation and usage information is available on the SCION Tutorials web page for webapp and in the webapp README.