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
andVendor-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).
Install from the netsec package repository at https://packages.netsec.inf.ethz.ch/debian
:
sudo apt-get install scion-bootstrapper
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.
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'
Generate a default configuration with ./scion-bootstrapper -help-config > ./bootstrapper.yml
.
Run it with ./scion-bootstrapper -config bootstrapper.yml
.
This file contains configuration options and provide some instructions to get started.
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 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 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.
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.
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
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
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}.trc
. - create a link to the trc blob containing the TRC file itself at
/srv/http/scion/trcs/isd{isd}-b{base}-s{serial}/blob
.
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).
You can test that the web server is working with:
curl http://${SERVER_IP}:8041/topology
, andcurl 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.
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
.