diff --git a/content/config/setup_endhost.md b/content/advanced/setup_endhost.md similarity index 61% rename from content/config/setup_endhost.md rename to content/advanced/setup_endhost.md index 9811fce6..76c9635c 100644 --- a/content/config/setup_endhost.md +++ b/content/advanced/setup_endhost.md @@ -1,11 +1,15 @@ -# Set up an end host +# Configuring SCION end host + +!!! Note + You should go through this tutorial if you want to install SCION end host but do not want to run other SCION AS services on that machine. + Before proceeding you should already have SCION AS services available in your network, otherwise end host will not run properly. ## Introduction In this tutorial we will cover the steps necessary to configure a SCION end host in a SCIONLab AS. -An SCION _end host_ is a simply a computer running SCION applications in a SCION AS, i.e. it is not a router and does not run any infrastructure services for the AS. -An end host will communicate with the Path- and Certificate-service of the AS to get paths and certificate information. For communication to hosts in different ASes, traffic will be sent to the SCION border routers of the AS. +A SCION end host is a machine running SCION applications in a SCION AS, i.e. it is not a router and does not run any infrastructure services for the AS. +An end host will communicate with the path and certificate servers of the AS to get paths and certificate information. For communication to hosts in different ASes, traffic will be sent to the SCION border routers of the AS. The end host knows the addresses for these services from a configuration file (`topology.json`). The software stack for a SCION end host application consists of the `dispatcher`, responsible for managing sockets and encapsulating/decapsulating SCION packets for IP/UDP overlay, @@ -16,13 +20,12 @@ Compared to the perhaps more familiar software stack for IP, we can see some rou - `dispatcher`: corresponds to the kernels `socket` API - `sciond`: similar to a local caching DNS resolver daemon (like e.g. dnsmasq, unbound), except it's for paths and certificates, not for names - ## 1. Install SCION on end host The software stack for a SCION end host consists of the `dispatcher` and the `sciond`, contained in the `scion-dispatcher` and `scion-daemon` packages. Just install an end host application that you're planning to run. -On Ubuntu/Debian, run the following snippet to add the package repository: +On Debian-based OS run the following snippet to add the package repository: ```shell 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 @@ -30,8 +33,7 @@ sudo apt-get update ``` and then install the packages using: ``` -sudo apt-get install scionlab scion-apps-* # Just get everything OR -sudo apt-get install scion-apps-bwtester # get individual application(s), with only minimal dependencies +sudo apt-get install scion-daemon scion-dispatcher ``` Of course you can also use the other [available installation options](../install/index.md). @@ -46,35 +48,42 @@ To run an end host on a different host, the services need to bind on an IP that On the host running the AS services, locate the `topology.json` files in `/etc/scion/gen/`. In this configuration file, we change the occurrences of IP `127.0.0.1` to the hosts IP. + ``` -NODE_IP=#..host IP..# sed -i "s/127\.0\.0\.1/$NODE_IP/" /etc/scion/gen/ISD*/AS*/*/topology.json +export NODE_IP=example +sed -i "s/127\.0\.0\.1/$NODE_IP/" /etc/scion/gen/ISD*/AS*/*/topology.json ``` !!! Note - Only `PathServer`, `CertificateServer` and the `InternalAddrs` of `BorderRouter` _need_ to be accessible for the end host. + Only `PathServer`, `CertificateServer` and the `InternalAddrs` of `BorderRouter` need to be accessible for the end host. This command also changes the address for the `BeaconServer` and the `CtrlAddr` of the `BorderRouter` as a bonus, for the sake of simplicity. -Restart your AS services by running `sudo systemctl restart scionlab.target`. +Restart your AS services by running + +``` +sudo systemctl restart scion-daemon.service scion-dispatcher.service +``` ## 3. Extract and adapt end host configuration To create the configuration for the end host, we copy the configuration (modified in the previous step) from the node's `/etc/scion/gen` directory: we'll need the `dispatcher/` and the `ISD*/AS*/end host` directory. -The following snippet describes one way to achieve this: +The following snippet removes configuration of the SCION services from directory, keeping only the required part ```shell cp /etc/scion/gen /tmp/ -rm -r /tmp/gen/ISD*/AS*/{br,bs,ps,cs}*/ # strip config for AS services +rm -r /tmp/gen/ISD*/AS*/{br,bs,ps,cs}*/ ``` -Then we need to fix another configuration file: -the localhost addresses in `/etc/scion/gen/ISD*/AS*/end host/sd.toml` must be changed to to the end host's IP address. +The Configuration of the `scion-daemon` also needs to be changed in order to use the IP address of the end host + ``` -ENDHOST_IP=#..host IP..# sed -i "s/127\.0\.0\.1/$ENDHOST_IP/" /etc/scion/gen/ISD*/AS*/end host/sd.toml +export ENDHOST_IP=example +sed -i "s/127\.0\.0\.1/$ENDHOST_IP/" /tmp/gen/ISD*/AS*/endhost/sd.toml ``` -Now copy `/tmp/gen` to the end host (e.g. using `scp`) and install it in the `/etc/scion/` directory. +At this moment `/tmp/gen` contains a full configuration needed for the SCION end host. You can use e.g. `scp` to install it in the `/etc/scion/` directory on the target machine. ## 4. Start SCION on end host @@ -83,8 +92,8 @@ Finally we can start the `scion-dispatcher` and `scion-daemon` services: ```shell # replace XX and YYYY with your ISD/AS number e.g. scion-daemon@17-ffaa_1_15b.service -systemctl enable scion-daemon@XX-ffaa_1_YYYY.service -systemctl start scionlab.target +systemctl enable --now scion-dispatcher.service +systemctl enable --now scion-daemon@XX-ffaa_1_YYYY.service ``` -Test that your connection is working, e.g. by using [`scmp echo`](../config/check.md#ping) and start using the applications as described in the Applications-section. +Test that your connection is working, e.g. by using `scmp echo` (as described in [checking AS configuration](../config/check.md#ping)) and start using the applications. diff --git a/content/apps/bwtester.md b/content/apps/bwtester.md index 19071dc7..f2f80f52 100644 --- a/content/apps/bwtester.md +++ b/content/apps/bwtester.md @@ -14,22 +14,14 @@ See [Installation](../install/pkg.md#applications) for details. Sample servers are installed at the following locations: -* `17-ffaa:0:1102,[192.33.93.177]:30100` * `17-ffaa:1:13,[192.168.1.79]:30100` * `17-ffaa:1:f,[10.0.2.15]:30100` * `19-ffaa:1:22,[141.44.25.146]:30100` -And at the attachment points: - -* `17-ffaa:0:1107,[10.0.8.1]:30100` -* `18-ffaa:0:1202,[10.0.8.1]:30100` -* `19-ffaa:0:1303,[10.0.8.1]:30100` -* `20-ffaa:0:1404,[10.0.8.1]:30100` - You can test the application as follows: ``` -scion-bwtestclient -c 17-ffaa:1:89,[127.0.0.1]:0 -s 17-ffaa:0:1102,[192.33.93.177]:30100 +scion-bwtestclient -c 17-ffaa:1:89,[127.0.0.1]:0 -s 17-ffaa:1:13,[192.168.1.79]:30100 ``` Here, `-s` specifies the bandwidth server whereas `-c` specifies your machine. @@ -51,7 +43,7 @@ SCION host to the `/etc/hosts` file. Below you can see an example: The application supports specification of the test duration (up to 10 seconds), the packet size to be used (at least 4 bytes), the total number of packets that will be sent, and the target bandwidth. For instance, `5,100,10,1600bps` specifies that 10 packets of size 100 bytes will be sent over 5 seconds, resulting in a bandwidth of 1600bps. The question mark `?` character can be used as wildcard for any of these parameters. Its value is then computed according to the other parameters. The parameters for the test in the client-to-server direction are specified with `-cs`, and the server-to-client direction with `-sc`. So for instance to send 1 Mbps for 10 seconds from the client to the server, and 10 Mbps from the server to the client, you can use this command: ``` -scion-bwtestclient -s 17-ffaa:0:1102,[192.33.93.177]:30100 -cs 10,1000,1250,1Mbps -sc 10,1000,12500,10Mbps +scion-bwtestclient -s 17-ffaa:1:13,[192.168.1.79]:30100 -cs 10,1000,1250,1Mbps -sc 10,1000,12500,10Mbps ``` For more information run the application without arguments to print its usage. diff --git a/content/apps/rains.md b/content/apps/rains.md index aadae789..131d3f21 100644 --- a/content/apps/rains.md +++ b/content/apps/rains.md @@ -1,7 +1,8 @@ # RAINS, Another Internet Naming Service -!!! TODO - Update & check +!!! Warning + + This page has not been updated after the latest changes to SCIONLab and is out of date. RAINS is an alternate protocol for Internet name resolution, designed as a replacement of the Domain Name System (DNS) and is used in SCIONLab. diff --git a/content/apps/remote_sig.md b/content/apps/remote_sig.md index ed213cee..2fcfa54f 100644 --- a/content/apps/remote_sig.md +++ b/content/apps/remote_sig.md @@ -1,7 +1,8 @@ # SCION IP Gateway (SIG) -!!! TODO - Update & check +!!! Warning + + This page has not been updated after the latest changes to SCIONLab and is out of date. The [SCION IP Gateway `SIG`](https://github.com/netsec-ethz/netsec-scion/tree/scionlab/go/sig) enables legacy IP applications to communicate over SCION. This tutorial describes how to set up two SIGs locally to test the SIG can enable any IP application to communicate over SCION. diff --git a/content/as_visualization/webapp.md b/content/as_visualization/webapp.md index f02ed400..a1ee0cb9 100644 --- a/content/as_visualization/webapp.md +++ b/content/as_visualization/webapp.md @@ -49,7 +49,7 @@ scion-webapp \ Several menu options are available at the top of each `webapp` page, which are outlined below. Each of the features below use your SCIONLab IA the the source address. ### Health -The Health tab is the landing page for `webapp` that will automatically test your SCIONLab configuration for configuration and communication health. Additional help is available in our [troubleshooting guide](../tips/troubleshooting.md), if needed. +The Health tab is the landing page for `webapp` that will automatically test your SCIONLab configuration for configuration and communication health. Additional help is available in our [troubleshooting guide](../faq/introduction.md), if needed. ![SCIONLab download page](../images/scion_healthcheck.png) diff --git a/content/config/check.md b/content/config/check.md index 7fcce39c..f9a28505 100644 --- a/content/config/check.md +++ b/content/config/check.md @@ -1,11 +1,9 @@ -# Check AS Configuration +# Checking AS configuration ## Introduction -After having [configured your AS on the SCIONLab website](../config/create_as.md), [installed SCION](../install/index.md) and, depending on the chosen installation type, installed the configuration on your host you should now have a running SCIONLab AS. - -Follow the steps below to check that it is working as expected. +After [configuring your AS on the SCIONLab website](../config/create_as.md) and [installing SCION](../install/index.md) you should now have a running SCIONLab AS. Follow the steps below to check that it is working as expected. ## Running Webapp @@ -17,9 +15,9 @@ This browser-based tool serves as a dashboard to your SCIONLab VM and includes v ## Terminal based For the following steps, log into the machine hosting the SCION services (with `vagrant ssh` if it is a virtual machine). -If any of the checks fail, head over to the [Troubleshooting Guide](../tips/troubleshooting.md) +If any of the checks fail, head over to the [Troubleshooting Guide](../faq/introduction.md) -#### Check VPN tunnel +### Check VPN tunnel This only applies if you've configured your as to use an OpenVPN connection to the Attachment Point. @@ -60,23 +58,22 @@ In this entry, the `PublicOverlay` address should correspond to the local addres Finally, check that you can ping the address listed in `RemoteOverlay`. -#### Check SCION service status +### Check SCION service status sudo systemctl list-dependencies scionlab.target -This should show all entries as green. If there are any failed services in this list, start [troubleshooting](../tips/troubleshooting.md#) +This should show all entries as green. If there are any failed services in this list, start [troubleshooting](../faq/troubleshooting.md) !!! Note - - Ignore duplicate entries, this is a known issue in some systemd versions. + Duplicated entries are bug in systemd which is fixed in Ubuntu 18.04. When using older platform, you can simply ignore them. If you're running a build from sources, you will need to use the developer scripts instead of `systemctl`. Run `scion.sh status` or `supervisor/supervisor.sh status`. -#### Inspect log files +### Inspect log files Log files for the SCION services are located in `/var/log/scion`. @@ -91,15 +88,15 @@ Inspect the beacon server's log file using e.g. `less -f /var/log/scion/bs*.log` Check that you find entries `Registered beacons ...`. -#### Ping +### Ping Ping somebody! Run `scmp echo` to send an "SCMP echo request"; this is just like the `ping` command for IP. The syntax is: - scmp echo -local [my scion address] -remote [someone else's scion address] + scmp echo -local [source SCION address] -remote [destination SCION address] -where a SCION address has the form `ISD-AS,[IP]`. For example, to ping any host in the attachment point AS in Korea from my SCIONLab AS, I would run: +where a SCION address has the form `ISD-AS,[IP]`. An example of pinging a host in the attachment point AS in Korea would look as follows: $ scmp echo -local 17-ffaa:1:15b,[127.0.0.1] -remote 20-ffaa:0:1404,[0.0.0.0] Using path: @@ -119,5 +116,4 @@ where a SCION address has the form `ISD-AS,[IP]`. For example, to ping any host If you're running the application on a local topology, make sure to specify the correct socket using the `-sciond` flag, e.g. by adding `-sciond /run/shm/sciond/sd1-ff00_0_110.sock`. -Passing this test is a condition sufficient to say that your AS works as expected. -If it fails, please refer to [the troubleshooting section](../tips/troubleshooting.md). +Passing this test is a condition sufficient to say that your AS works as expected. If it fails, please refer to [the troubleshooting section](../faq/troubleshooting.md). diff --git a/content/config/create_as.md b/content/config/create_as.md index 8d25f652..9c3c8538 100644 --- a/content/config/create_as.md +++ b/content/config/create_as.md @@ -1,4 +1,4 @@ -# Configure your SCIONLab AS +# Creating SCIONLab AS ## SCIONLab Portal Overview diff --git a/content/faq/join_infrastructure.md b/content/faq/join_infrastructure.md new file mode 100644 index 00000000..28622a00 --- /dev/null +++ b/content/faq/join_infrastructure.md @@ -0,0 +1,49 @@ +# Joining the SCIONLab infrastructure + +If you are part of an organization and/or you are committed to do research with SCION, and using user ASes is not enough for your plans, then you could join SCIONLab with a dedicated host. We have compiled a short guide to document the requirements. +You can join the SCIONLab network as an infrastructure AS with one or more machines, or you can start as small as dedicating only a simple commodity PC. + +!!! Danger "Attention needed" + + This page is supposed to give you a general overview over joining as a part of the infrastructure. In any case, if you are interested in joining, please [contact us directly](../index.md#contact). + +## Procedure + +- [Get in contact with us](../index.md#contact) telling you want to join the infrastructure. +- Once the node(s) are ready on your side, create a `scionlab` user with full `sudo` rights and access for the SCIONLab team. +- The SCIONLab admins will perform measurements to find the most appropriate neighbors to your AS. We will notify you of the result. +- Once the neighboring ASes have been decided, the administrators will install SCION services and configure monitoring for the node(s). +- Your AS is now connected to the infrastructure of SCIONLab and hosts within your network now have direct access to SCIONLab. + +Once the node(s) are part of the SCIONLab infrastructure, their configuration will be centrally managed via Ansible in order to keep the whole infrastructure in the best shape. You will not be required to take any action as long as the machine remains accessible for us. + +## Requirements + +There are a few requirements for you or your organization to join SCIONLab as an infrastructure node: + +- Infrastructure ASes and nodes are required to be active 24 hours a day, 7 days a week. The SCIONLab administrators can typically handle all SCION related problems, but sometimes they will contact you if they cannot perform certain tasks. An example would be to change a drive if it failed, etc. +- The machine should have a minimum of 4 CPUs, 8 GB of RAM and 40 GB of disk space. In most of the cases a VM can suffice. +- OS for the SCION infrastructure node must be Ubuntu 18.04. +- The border router node(s) must have a public static IP. Any other SCION services can run with private static IP. +- Firewall has to be configured according to the connectivity matrix below. + +### Connectivity requirements + +| Protocol | Port | Source | Comment | +| :------------- | :----------: | :-----------: | -----------: | +| UDP | 50000--50010 | 0.0.0.0/0 | SCION inter-AS connectivity | +| UDP | 30000 - 35000 | machines in the same SCION AS | SCION intra-AS connectivity | +| TCP | 22 | 82.130.64.0/18
129.132.0.0/16
195.176.96.0/19
192.33.87.0/24
192.33.88.0/23
192.33.91.0/24
192.33.92.0/24
192.33.93.0/24
192.33.94.0/23
192.33.96.0/21
192.33.104.0/22
192.33.108.0/23
192.33.110.0/24 | Administrative SSH access for configuration management | + +!!! note + Inter-AS connectivity is required only with the neighbouring ASes. In order to allow dynamic topology adjustments we recommend firewall opening for 0.0.0.0/0. In most cases, after determining the best neighbours for your AS, we can provide a narrowed-down list of networks. + +!!! note + As an alternative we can also operate connections over a tunnel, e.g. OpenVPN or Wireguard. However please note this will be done only in a special scenarios, e.g. installing a node in a country with strict network policy regarding connectivity abroad. In that case UDP connectivity can be stricter, but inbound SSH connectivity from networks listed above must work. + +### Recommendations + +The following are not requirements, but recommendations: + +- The border router should be near (latency-wise) the IP border of your AS or organization. +- Co-locating the nodes in your datacenter is usually a good idea as it reduces network latency. diff --git a/content/tips/troubleshooting.md b/content/faq/troubleshooting.md similarity index 84% rename from content/tips/troubleshooting.md rename to content/faq/troubleshooting.md index c20e2180..5e66df68 100644 --- a/content/tips/troubleshooting.md +++ b/content/faq/troubleshooting.md @@ -1,9 +1,4 @@ -# FAQ and Troubleshooting - - -This section answers some frequently asked questions and assists with troubleshooting for SCIONLab ASes. - - +# Troubleshooting ## Virtual Machine The following relate to [running a Vagrant Virtual Machine](../install/vm.md). @@ -49,9 +44,6 @@ If you've lost track of which VMs are running or lost your `Vagrantfile`s, you c $ VBoxManage controlvm "SCIONLabVM-ffaa:1:15b" poweroff $ VBoxManage list vms - - - ## VPN The following relate to AS [configured to use VPN](../config/create_as.md#configure-a-scionlab-as). @@ -88,7 +80,7 @@ The following are common issues or troubleshooting strategies for a SCION AS. Typically, this indicates a configuration error. -If you've configured to use VPN, check the [Border Router fails to start][#border-router-fails-to-start] entry in the VPN section. +If you've configured to use VPN, check the "Border Router fails to start" entry in the VPN section above. Inspect the logs of the failed services to find details. In case of multiple failures, fixing issues in the following order usually works best: @@ -104,17 +96,14 @@ In case of multiple failures, fixing issues in the following order usually works #### Not receiving beacons -You're beacon server log `/var/logs/scion/bs*.log` does not contain (recent) entries referring to `Registered beacons`. +Log of the beacon server (`/var/logs/scion/bs*.log`) does not contain recent entries referring to `Registered beacons`. -First thing to try, is to turn it off and on again: +As at the time of writing there are certain failure modes of the border routers that are hard to diagnose and are fixed with a simple restart, first thing to try is to turn it off and on again: ``` sudo systemctl restart scionlab.target ``` -This may seem silly but there are (at the time of writing) certain failure modes of the border routers that are hard to diagnose and are fixed with a simple restart. - - ## Getting help If your stuck, don't hesitate to [get in contact](../index.md#contact) diff --git a/content/index.md b/content/index.md index 896c73af..d14a397e 100644 --- a/content/index.md +++ b/content/index.md @@ -84,6 +84,7 @@ In order to simplify the management of ASes and lower the entry-barrier for part ## Contact -* For questions on running your SCIONLab AS and general discussion about SCION-related topics, visit our [SCION community mailing list](https://lists.inf.ethz.ch/mailman/listinfo/scion) -* For bug reports, please post them on the [scionlab GitHub site](https://github.com/netsec-ethz/scionlab) -* For suggestion on these pages, please post them on the [scion-tutorials GitHub site](https://github.com/netsec-ethz/scion-tutorials) +* For questions on running your SCIONLab AS and discussion about SCION-related topics, visit our [SCION community mailing list](https://lists.inf.ethz.ch/mailman/listinfo/scion) +* For suggestions or bugs on these pages, please post them on the [tutorial GitHub repo](https://github.com/netsec-ethz/scion-tutorials) +* For bug reports when running SCION, please post them on the [SCIONLab GitHub repo](https://github.com/netsec-ethz/scionlab) +* SCIONLab NOC is available via email diff --git a/content/install/android.md b/content/install/android.md index 1a778283..f1adcb63 100644 --- a/content/install/android.md +++ b/content/install/android.md @@ -1,15 +1,15 @@ -# Install on Android +# Building from sources (Android) -!!! Warning +!!! Danger "Attention needed" - This page has not been updated after the latest changes to SCIONLab and is out of date. + This page is supposed to be rewritten. Procedures described here are highly outdated and are not guaranteed to work. ## Introduction It is possible to run SCION on an Android device. The easiest way is to install [SCION as an Android app](#scion-app). The other alternative is to [manually install SCION on your Android device](#manual-setup). Both variants are based on [Termux](https://github.com/termux/termux-app), which emulates a Terminal environment with the Linux base system that Android is based upon. -This tutorial is primarily targeted at running a SCION endhost on Android. While it is also possible to run an entire SCION AS, this currently doesn't run stable within Termux, as it requires Apache Zookeeper, which frequently crashes the Termux environment as described [here](#endhost-configuration-vs-full-as). +This tutorial is primarily targeted at running a SCION end host on Android. While it is also possible to run an entire SCION AS, this currently doesn't run stable within Termux, as it requires Apache Zookeeper, which frequently crashes the Termux environment as described [here](#endhost-configuration-vs-full-as). ## Prerequisites @@ -41,7 +41,7 @@ That’s it! The process takes a while but is fully automatic. At the end, a dia That means of course, that the ‘gen’ folder needs to be readily available on the internal memory. Download it directly or push it onto the device with ADB. !!! warning - SCION for Android currently only supports a SCION endhost configuration, as described [in this tutorial](../config/setup_endhost.md) + SCION for Android currently only supports a SCION end host configuration, as described [in this tutorial](../advanced/setup_endhost.md) !!! warning SCIOND config in the ‘gen’ folder needs a little adjustment on Android, as described [here](#changes-to-gen-folder) @@ -222,7 +222,7 @@ cd $SC/env/go After finishing the installation of SCION, there are different ways of running different topologies. The following tutorials will cover this in further detail: 1. [Running a local network topology](../general_scion_configuration/local_top.md) – Generate a sample topology and run SCION locally -1. [Connecting to SCIONLab as an endhost](../config/setup_endhost.md) – Connect to the already running SCION topology as a mobile endhost through an existing SCION setup. +1. [Connecting to SCIONLab as an endhost](../advanced/setup_endhost.md) – Connect to the already running SCION topology as a mobile end host through an existing SCION setup. #### Changes to gen folder @@ -233,7 +233,7 @@ Note that in `gen/ISDx/AS10xx/supervisord.conf` the path of the SCION Deamon soc Unfortunately, OpenVPN is not currently supported from within the Termux environment. Alternatively, the [Open VPN app](https://play.google.com/store/apps/details?id=net.openvpn.openvpn) can be installed to connect to SCIONLab via VPN. The `client.conf` file that is provided by the [SCIONLab coordinator](https://www.scionlab.org/) needs to be renamed to `client.ovpn` before it can be imported into the app. Additionally, the line `route 10.0.8.0/24` needs to be added to the file. -#### Endhost configuration vs. full AS +#### End host configuration vs. full AS It is possible to run the full SCION on Android, it is, however, currently not recommended. The full SCION requires a Zookeeper instance which itself is a Java program. While it is possible to install a Java Virtual Machine in Termux, the actual Termux packages have been disabled or removed due to instabilities with high CPU usage. diff --git a/content/install/index.md b/content/install/index.md index cab14e06..b855cecd 100644 --- a/content/install/index.md +++ b/content/install/index.md @@ -1,25 +1,17 @@ -# Pick an Option +# Available options -SCIONLab supports three main options to run the SCION services that make up a SCION AS: +SCIONLab supports three main options to run the SCION services that make up a SCION AS -1. [Run a Virtual Machine](../install/vm.md) +1. [Run a virtual machine](../install/vm.md) - This is the simplest option to get started and is supported on all platforms that can run Vagrant and VirtualBox. + The simplest option to get started and is supported on all platforms that can run Vagrant and VirtualBox. Inside the Ubuntu VM, the SCION installation uses packages (the same as described in the next step). - Inside the Ubuntu VM, the SCION installation uses packages, identical to the setup described in [Install with a Package Manager](../install/pkg.md). +2. [Install with a package manager](../install/pkg.md) - The (perhaps obvious) downsides of running in a VM is the implied performance and memory overhead. + Applicable to any Debian-based systems for the most common CPU platforms. Painless installation procedure and no performance overhead from running a VM. -2. [Install with a Package Manager](../install/pkg.md) +3. [Build from sources](../install/src.md) - This is applicable to any recent Ubuntu (or other Debian-based) systems for - the most common CPU platforms. - - Painless installation procedure and no performance overhead from running a VM. + Use this option if you want to make modifications to the SCION services. Requires following lengthy instructions and installing various development dependencies. -3. [Build from Sources](../install/src.md) - - This requires following lengthy instructions and installing various development dependencies. - Use this option if you want to make modifications to the SCION services. - -Additionally, you can [install SCION on Android](../install/android.md)! +Additionally, you can [build and run SCION on Android](../install/android.md). diff --git a/content/install/pkg.md b/content/install/pkg.md index f8dc2232..7a38855e 100644 --- a/content/install/pkg.md +++ b/content/install/pkg.md @@ -1,4 +1,4 @@ -# Install with a Package Manager +# Installing packages ## SCION Services Prebuilt SCION packages are available for Ubuntu (or other Debian based systems) for x86, x86-64, arm32 and arm64 platforms. @@ -17,7 +17,6 @@ This will install all the SCION services (which come as individual packages), install the SCION configuration generated by the SCIONLab coordination website. - ## Configuration After [creating or modifying your AS](../config/create_as.md) in the SCIONLab coordination website, you can deploy the generated configuration to your machine. @@ -86,7 +85,7 @@ If using VPN, ensure that the OpenVPN-client is up **before** starting the SCION ```shell sudo systemctl start openvpn@client ``` -Check that the expected `tun0` tunnel-interface is created before continuing. Please refer to corresponding [troubleshooting](../tips/troubleshooting.md#vpn) page. +Check that the expected `tun0` tunnel-interface is created before continuing. Please refer to corresponding [troubleshooting](../faq/introduction.md#vpn) page. [//]: # (TODO This may become obsolete if openvpn@client is included as a dependency for the BRs.) diff --git a/content/install/src.md b/content/install/src.md index 81560ec0..024eb8b1 100644 --- a/content/install/src.md +++ b/content/install/src.md @@ -1,4 +1,5 @@ -# Build from Sources +# Building from sources (Linux) + If you're planning to make modifications to SCION implementation, you can build SCION from sources and run your SCIONLab AS with your own version of SCION. For developer's convenience, SCIONLab supports generating configurations that are compatible with the scripts and machinery intended to run SCION in a development environment. @@ -10,7 +11,7 @@ Please follow the instructions in the [GitHub README](https://github.com/netsec- !!! Note SCIONLab runs a version of SCION built from the branch `scionlab` in netsec-ethz/netsec-scion. - This branch (intenionally) lags behind the scionproto/scion master. As there are still (rarely) breaking changes in the SCION protocol, running `master` may or may not be compatible with `scionlab`. + This branch (intentionally) lags behind the scionproto/scion master. As there are still (rarely) breaking changes in the SCION protocol, running `master` may or may not be compatible with `scionlab`. !!! Tip diff --git a/content/install/vm.md b/content/install/vm.md index 32ae70c7..6fd09a1a 100644 --- a/content/install/vm.md +++ b/content/install/vm.md @@ -1,11 +1,10 @@ -# Run a VM +# Running inside a VM ## Install Vagrant and Virtualbox -If you choose to run a SCIONLab virtual machine, you'll only need to install -[Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/). -These are available for most platforms, including Linux, Windows and macOS. +If you choose to run a SCIONLab virtual machine, you need to install [Vagrant](https://www.vagrantup.com/) and +[VirtualBox](https://www.virtualbox.org/). These are available for most platforms, including Linux, Windows and macOS. -On recent Ubuntu or Debian systems, it may be enough to run +On recent Debian-based systems you can install both using the following command ```shell sudo apt-get install vagrant virtualbox @@ -16,25 +15,22 @@ For other platforms, please consult the official installation instructions: - [Install Vagrant](https://www.vagrantup.com/docs/installation/) - [Install VirtualBox](https://www.virtualbox.org/wiki/Downloads) - ## Using Vagrant to run the VM After [creating your AS](../config/create_as.md) in the SCIONLab coordination -website, you will be able to download a tarfile that includes a `Vagrantfile` -which includes all that is needed to build your SCIONLab VM. +website, you will be able to download a tarfile with `Vagrantfile` allowing you to easily build your SCIONLab VM. + +!!! note + All the commands below need to be executed from the directory containing the Vagrantfile. -Navigate your shell to the directory containing the Vagrantfile. -Note that all vagrant commands always need to be run in this directory! To start your VM, run ```shell vagrant up ``` -When running your VM for the first time, this will download the Ubuntu base box -and then install all the SCION packages and their dependencies. - -This will already start the services for your SCIONLab AS. +When running your VM for the first time, base Ubuntu OS will be installed together with SCIONLab packages and their +dependencies. After the installation SCIONLab services should be already up and running. Once the `vagrant up` command returns the prompt, you can connect to your VM to start exploring: @@ -48,24 +44,20 @@ will appear in the `/vagrant/` directory. This is a convenient way to share files between your host machine and your VM, and allows to move data both ways. -To shutdown the VM, run - -```shell -vagrant halt -``` - -To start it back up, just type `vagrant up` again. Finally, if you want to wipe -your VM, e.g. to start fresh, run `vagrant destroy`. +!!! note + You can use following Vagrant commands to perform various operations with your VM + + * `vagrant halt` - stops the VM + * `vagrant destroy` - restores VM to its initial state -More information for `vagrant` commands can be found at: - + More information about `vagrant` commands can be found at ## Configuration As indicated above, the initial version of the configuration will automatically be provisioned. To update the configuration in an existing VM, the workflow is the same as when running -an [installation from packages](../install/pkg.md#configure); connect to your running VM +an [installation from packages](../install/pkg.md) -- connect to your running VM (`vagrant ssh`) and execute ```shell @@ -77,8 +69,8 @@ sudo scionlab-config The SCION services are automatically started when the VM boots up. -To interact with the SCION services, you can use the same tools as when running an [installation from packages](../install/pkg.md#running-scion); -connect to your running VM (`vagrant ssh`) and use the `systemd` commands to start/stop the services +To interact with the SCION services, you can use the same tools as when running an [installation from packages](../install/pkg.md#running-scion) -- +connect to your running VM (`vagrant ssh`) and use systemd to start and stop the services ``` sudo systemctl start scionlab.target # Start all SCION services sudo systemctl list-dependencies scionlab.target # Check the status diff --git a/content/join_infrastructure.md b/content/join_infrastructure.md deleted file mode 100644 index af0ee72d..00000000 --- a/content/join_infrastructure.md +++ /dev/null @@ -1,42 +0,0 @@ -# Join the SCIONLab Infrastructure - -If you are part of an organization and/or you are committed to do research with SCION, and using user ASes is not enough for your plans, then you could join SCIONLab with a dedicated host. We have compiled a short guide to document the requirements. -You can join the SCIONLab network as an infrastructure AS with one or more machines, or you can start as small as dedicating only a simple commodity PC. - - -## Procedure - -- Get in contact with us. Send us an email to telling us you want to join the infrastructure. -- Once the node(s) are ready, create a user with the name `scionlab` and permission to run `sudo`. Grant the SCIONLab admins `ssh` access to the machine via a key for that `scionlab` user. -- The SCIONLab admins will perform some measurements to find the appropriate neighbors to your AS. We will notify you of the result. -- Once the neighboring ASes have been decided, the administrators will install the necessary services of SCION and monitoring. This is typically done by us using `Ansible`. We deploy the configuration of the node(s) in the AS at the same time. -- Your AS is now connected to the infrastructure of SCIONLab and hosts within your network now have direct access to SCIONLab. - - -## Requirements - -There are a few requirements for you or your organization to join SCIONLab as an infrastructure node: - -- Infrastructure ASes and nodes are required to be active 24 hours a day, 7 days a week. The SCIONLab administrators can typically handle all SCION related problems, but sometimes they will contact you if they cannot perform certain tasks. An example would be to change a drive if it failed, etc. -- The machine should have a minimum of 4 GB of RAM. A VM can suffice, given sufficient resources. -- Currently the SCION code works with Ubuntu 16.04. -- The border router node(s) must have a public static IP. -- The following ports need to be accessible: - - For each configured SCION inter-domain connection one UDP port for SCION inter-domain traffic, preferrably in the 50000~50010 range.
- Preferrably, these ports should be open for any source IP, as this simplifies changing the SCIONLab topology. However, we can provide the specific allowed source IP for each port if necessary.
- As the SCION border routers send a continuous trickle of keep-alive messages, it may be enough if a firewall allows return traffic to the same port. - - SSH access for management of the node by the SCIONLab-team:
- TCP 22: source 192.33.96.0/20, 192.33.88.0/21, 192.33.87.0/24, 54.176.0.0/12 - - As an alternative, we can also operate the connections over a tunnel, e.g. OpenVPN, Wireguard or SSH tunnels. - -### Recommendations - -The following are not requirements, but recommendations: - -- The border router should be near (latency wise) the IP border of your AS or organization. -- Co-locating the node or nodes in your datacenter is usually a good idea in terms of network latency. -- To join the SCION network, we have a specific hardware recommendation: [HP Proliant DL20 gen9](https://www.hpe.com/us/en/product-catalog/servers/proliant-servers/pip.specifications.hpe-proliant-dl20-gen9-server.1008556817.html). -We further customize the machine with additional 8G ECC Ram and SSD, but a regular HDD also works. -- Instead of a blade type server machine, a regular PC with a similar spec works as well. - diff --git a/content/tips/wireshark.md b/content/tools/wireshark.md similarity index 100% rename from content/tips/wireshark.md rename to content/tools/wireshark.md diff --git a/docs/config/setup_endhost/index.html b/docs/advanced/setup_endhost/index.html similarity index 79% rename from docs/config/setup_endhost/index.html rename to docs/advanced/setup_endhost/index.html index 1492ee4b..72a8ce1d 100644 --- a/docs/config/setup_endhost/index.html +++ b/docs/advanced/setup_endhost/index.html @@ -38,7 +38,7 @@ - Set up an end host - SCION Tutorials + Configuring SCION end host - SCION Tutorials @@ -73,7 +73,7 @@ - + Skip to content @@ -99,7 +99,7 @@ SCION Tutorials - Set up an end host + Configuring SCION end host @@ -201,8 +201,8 @@
  • - - Pick an Option + + Available options
    • @@ -213,8 +213,8 @@
  • - - Run a VM + + Running inside a VM
    • @@ -225,8 +225,8 @@
  • - - Install with a Package Manager + + Installing packages
    • @@ -237,8 +237,8 @@
  • - - Build from Sources + + Building from sources (Linux)
    • @@ -249,8 +249,8 @@
  • - - Install on Android + + Building from sources (Android)
    • @@ -264,12 +264,10 @@ - - -
  • +
  • - +
  • - - Configure your SCIONLab AS + + Creating SCIONLab AS
    • @@ -299,12 +297,38 @@
  • - - Check AS Configuration + + Checking AS configuration
    • + + + + + + + + + + + + +
  • + + + + +