Minor bugfixes and changes (#122)

* Closes: #120
* Closes: #119
* Closes: #118
* Closes: #116
* Closes: #114
* Closes: #115
* Closes: #117
* Partially-implements: #111

content/config/setup_endhost.md → 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,22 +20,20 @@ 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
 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.

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.
 

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.
 

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.
 

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)
 

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).

content/config/create_as.md

@@ -1,4 +1,4 @@
-# Configure your SCIONLab AS
+# Creating SCIONLab AS
 
 ## SCIONLab Portal Overview
 

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<br> 129.132.0.0/16<br> 195.176.96.0/19<br> 192.33.87.0/24<br> 192.33.88.0/23<br> 192.33.91.0/24<br> 192.33.92.0/24<br> 192.33.93.0/24<br> 192.33.94.0/23<br> 192.33.96.0/21<br> 192.33.104.0/22<br> 192.33.108.0/23<br> 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.

content/tips/troubleshooting.md → 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)