Skip to content

Latest commit

 

History

History
206 lines (155 loc) · 7.95 KB

README.md

File metadata and controls

206 lines (155 loc) · 7.95 KB
Raw

Bootstrapper

This repository contains a bootstrapper for network configuration. It retrieves hints from available zero conf services to discover the IP address and port of the discovery server serving the actual configuration files over HTTP.

It uses the following hinting mechanisms:

  • DHCP option www-server and Vendor-Identifying Vendor Option [RFC2132],[RFC3925]
  • DHCPv6 Vendor-specific Information Option [RFC3315]
  • IPv6 NDP: DNS resolver and DNS Search List [RFC6106]
  • DNS-SRV: DNS service resource records [RFC2782]
  • DNS-NAPTR: Naming Authority Pointer DNS Resource Record [RFC2915]
  • DNS-SD: DNS service discovery [RFC6763]
  • mDNS: multicast DNS [RFC6762]

It integrates with SCION by using the same OpenAPI as the control service uses for exposing TRCs (serving as root certificate) and the topology file (describing the local SCION topology).

Installing

Install from the netsec package repository at https://packages.netsec.inf.ethz.ch/debian: sudo apt-get install scion-bootstrapper

Building

To build the bootstrapper executable, simply run make bootstrapper in the top level directory. In order to build the bootstrapper debian package, we use Bazel. The service files are in the ./res/packaging/debian/ directory. You can install Bazel by following the instructions at https://docs.bazel.build/versions/master/install-ubuntu.html You can then build the package by running bazel build //:scion-bootstrapper-deb. When contributing, please run make all in order to make sure that all targets build and to run the linter.

Experimental availability is also provided for macOS and Windows. Run make darwin or make windows to build a Mach-O or PE32+ binary respectively.

NOTE

On macOS, you might need to remove the IPv6 address(es) from your network interface if IPv6 connectivity is broken. You can do so with the following command: sudo networksetup -setv6off Ethernet (use the flag -setv6automatic to reenable).
On Windows, you might need to run the bootstrapper via the Command Prompt (cmd) instead of the PowerShell prompt. Symlinking the output directory on shares or as unprivileged user is also not supported. You can check your connection specific DNS suffix with ipconfig or in the advanced DNS settings of the adapter properties.

You might also need to explicitly allow the connections in your firewall, in particular for the broadcast based hinting mechanisms.

Running

The package starts the bootstrapper service at installation and adds a client hook to detect connectivity changes.
It can be manually restarted with sudo systemctl restart 'scion-bootstrapper@*.service'

Manual configuration

Generate a default configuration with ./scion-bootstrapper -help-config > ./bootstrapper.yml.
Run it with ./scion-bootstrapper -config bootstrapper.yml.

Client bootstrap service configuration

This file contains configuration options and provide some instructions to get started.

Discovery mechanisms

DHCP (dnsmasq)

For example, with dnsmasq, an option 72 "Default WWW server" can be done by adding the following line to /etc/dnsmasq.conf: dhcp-option=72,<webserverIP>. Note that dnsmasq does not support DHCP option 72 www-server by default, https://thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html, supported DHCP options are registered in dhcp-common.c. dhcpd supports the option by default, https://github.com/koenning/isc-dhcpd/blob/master/common/tables.c. Make sure to disable the options you don't need: By default dnsmasq is enabled to reply to DNS queries, but it also has an integrated DHCP server that can be enabled for only specific interfaces or all interfaces. Make sure to also check how dnsmasq interacts with the resolvconf package and your local network DHCP setup.

DHCPv6 (dnsmasq)

DHCPv6 Option 17, Vendor-specific Information Option, is supported for discovery in IPv6 networks. Note that the option code and length field width are different from DHCPv4.

IPv6 NDP (dnsmasq)

IPv6 Neighbor Discovery Protocol Router Advertisements can be used to advertise DNS resolvers and DNS Search Lists to be used in the DNS based discovery mechanisms. Can be used in combination with DHCPv6, SLAAC or static address configuration.

mDNS (avahi)

Put the following configuration to /etc/avahi/services/sciondiscovery.service:

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="no"></name>
  <service>
    <type>_sciondiscovery._tcp</type>
    <port>8041</port>
  </service>
</service-group>

Make sure to disable the features you don't need.

Systemd service units

Bootstrapper

A minimal example of the bootstrapper service units [email protected].

[Unit]
After=network-online.target
Before=scion-daemon@%i.service
Wants=network-online.target

[Service]
Type=oneshot
WorkingDirectory=/etc/scion/
ExecStartPre=/bin/mkdir -p /etc/scion/certs/
ExecStartPre=/bin/cp /etc/scion/boot.toml /etc/scion/boot-%i.toml
ExecStartPre=/bin/sed -i s#NIC#%i#g /etc/scion/boot-%i.toml
ExecStart=/opt/scion/bootstrapper -config boot-%i.toml
RemainAfterExit=True

# Raw network is needed for DHCP
AmbientCapabilities=CAP_NET_RAW

SCIOND

A minimal example of the sciond service units [email protected].

[Unit]
After=network-online.target scion-bootstrapper@%i.service scion-dispatcher.service
BindsTo=scion-bootstrapper@%i.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/etc/scion/
ExecStartPre=/bin/mkdir -p /etc/scion/gen-cache /var/cache/scion /run/shm/sciond
ExecStart=/opt/scion/sciond --config /etc/scion/sd.toml

Nginx web server

After having installed Nginx, the network admin can follow these steps to expose the endpoints needed by the bootstrapper:

  • copy the site configuration to /etc/nginx/sites-available and enable it by creating a link that points to /etc/nginx/sites-available/scion in /etc/nginx/sites-enabled,
  • create a link to the topology at /srv/http/scion/topology.json, and
  • create a link to the trc index containing the TRCs to serve at /srv/http/scion/trcs.json.
  • create a link to the trc metadata containing the description of a TRC at /srv/http/scion/trcs/isd{isd}-b{base}-s{serial}.json.
  • create a link to the trc blob containing the TRC file itself at /srv/http/scion/trcs/ISD{isd}-B{base}-S{serial}.trc.

Site configuration

A simple site example configuration to host the SCION configuration resources. Use a proper OpenAPI configuration and server setup for more complex setups (the scionproto repository contains a Bazel target to generate boilerplate for use with a chi-server) or proxy the requests to the SCION control service if the corresponding OpenAPI endpoint is publicly reachable.

server {
        listen 8041 default_server;
        listen [::]:8041 default_server;

        location / {
                root /srv/http/;
                autoindex off;
        }
        location /topology { alias /srv/http/topology.json; }
        location /trcs { alias /srv/http/trcs.json; }
        location /trcs/isd{isd}-b{base}-s{serial} { alias /srv/http/isd{isd}-b{base}-s{serial}.json; }
        location /trcs/isd{isd}-b{base}-s{serial}/blob { alias /srv/http/ISD{isd}-B{base}-S{serial}.trc; }
}

Make sure to replace {isd}, {base}, and {serial} with the values corresponding to your TRC(s).

Check the web server

You can test that the web server is working with:

  • curl http://${SERVER_IP}:8041/topology, and
  • curl http://${SERVER_IP}:8041/trcs/isd{isd}-b{base}-s{serial}/blob (make sure to replace {isd}, {base}, and {serial} with the correct values.)

The former should return the topology of the AS. The latter should return a file containing the requested TRC.

Contributing

When contributing, please run make all in order to make sure that all targets build and to run the linter. To generate the go_deps.bzl file from scratch, delete it and run make go_deps.bzl.