# Networking

## Overview

There are three areas of networking to understand with Instruqt:

1. [**Inbound traffic**](#inbound-traffic) from learners and external systems to the sandbox hosts.
2. [**Host to host communication**](#host-to-host-communication) between sandbox hosts.
3. [**Outbound traffic**](#outbound-traffic-from-sandbox-hosts) from sandbox hosts to the public internet.

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2FDymokchrWXWriF7qyIli%2FGroup%202%20(3).png?alt=media&#x26;token=07b0b9a8-27b7-472c-baba-0fcf5d6e8b50" alt=""><figcaption></figcaption></figure>

## Inbound traffic&#x20;

There are two ways to send traffic to sandbox hosts on the Instruqt platform:

* **Authenticated web traffic** from *learners* through the Instruqt web proxy (instruq&#x74;*<mark style="color:green;">**.com**</mark>*).
* **Unauthenticated TCP/UDP traffic** to sandbox **VMs**, only if explicitly enabled (instruq&#x74;*<mark style="color:red;">**.io**</mark>*).

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2FuyunFyOjJNCXizHdjzUC%2FGroup%202%20(7).png?alt=media&#x26;token=c4796d6f-b1a0-4c3b-8998-01d25e93308f" alt=""><figcaption></figcaption></figure>

### Authenticated learner traffic

If you apply a `service` tab in a track, Instruqt forwards requests from learners to the sandbox hosts through the Instruqt web proxy:

The features of the proxy include the following: &#x20;

* Allowing requests from logged-in learners only.
* Forwarding requests to both containers and VMs.
* Terminating the HTTPS connection on the proxy and forwarding plain HTTP (or HTTPS if the port contains `443`).

#### Web proxy subdomain

The web proxy uses a ***formatted subdomain*** to decide where to forward a request to:

`https://[HOSTNAME]-[PORT][PROTOCOL]-[PARTICIPANT_ID].env.play.instruqt.com`

There are three components in the subdomain:

<table><thead><tr><th width="253">Component</th><th>Notes</th></tr></thead><tbody><tr><td><code>HOSTNAME</code></td><td>The name assigned to the host (VM or container).</td></tr><tr><td><code>[PORT]</code></td><td>The port to forward traffic to.</td></tr><tr><td><code>[PROTOCOL]</code></td><td><p>An optional protocol override for the backend service:<br><code>u</code> for (unencrypted) <code>http</code>, <code>s</code> for <code>https</code>, leave empty for default, automatic selection.</p><p>(e.g. <code>80</code>, <code>8080u</code>, <code>443</code> or <code>444s</code>)</p></td></tr><tr><td><code>[PARTICIPANT_ID]</code></td><td> An identifier that uniquely identifies a sandbox environment.</td></tr></tbody></table>

{% hint style="info" %}
If you're forwarding traffic to a container, [make sure to expose the port in its configuration.](https://docs.instruqt.com/sandboxes/hosts/add-hosts#add-containers-to-sandboxes)
{% endhint %}

**HTTPS endpoints**\
If a port contains `443` ( ex: `443`, `8443`, and `4431`), the proxy expects an *HTTPS endpoint* on the sandbox hos&#x74;*.* The web proxy accepts any non-expired TLS certificate, including self-signed certificates.

{% hint style="info" %}
Use the protocol override option to force either `http` or `https` when the above automatic protocol selection picks the wrong protocol.
{% endhint %}

### Unauthenticated TCP/UDP traffic

By default, sandbox hosts are not exposed to the public internet. You can change that behavior.&#x20;

* **Sandbox VMs** have an external IP address. You can allow external ingress traffic to some ports or port ranges.
* **Sandbox containers** can never receive direct traffic from external sources.&#x20;

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2FzXaYkCmSmmrZJPQwTiLA%2FGroup%203%20(1).png?alt=media&#x26;token=d1bc93e1-55e0-494c-a841-4e5ae27756d8" alt=""><figcaption></figcaption></figure>

You can allow external ingress traffic to sandbox VMs using the attribute `allow_external_ingress` in `config.yml` (There is currently no way to set this property using the Web UI. [Install Instruqt CLI first](https://docs.instruqt.com/getting-started/set-up-instruqt#step-3-set-up-your-chosen-tool) and pull your track to edit `config.yml`)

{% code title="config.yml" %}

```yaml
version: "3"
virtualmachines:
- name: host01
  image: ubuntu-minimal-2004-lts
  shell: /bin/bash
  machine_type: n1-standard-1
  allow_external_ingress:
  - http
  - https
  - high-ports 
```

{% endcode %}

You can specify one or more ports or port ranges. There are three valid values:

* `http`: Port `80` (HTTP)
* `https`: Port `443` (HTTPS)
* `high-ports`: Port range 1024-65535, excluding 15770-15779, which are reserved for Instruqt use.

#### Resolving the external IP of a sandbox VM

To connect to a sandbox VM from an external system, you will need to know its external IP address. Instruqt adds two temporary DNS records for every sandbox VM with `allow_external_ingress` enabled:&#x20;

* `[HOSTNAME].[SANDBOX ID].instruqt.io`
* `*.[HOSTNAME].[SANDBOX ID].instruqt.io` (wildcard record)

Here are three examples of fully qualified hostnames that resolve to the same sandbox VM:&#x20;

* `host1.lbnlkljkcpfa.instruqt.io`
* `api.host1.lbnlkljkcpfa.instruqt.io` (due to the wildcard)
* `www.host1.lbnlkljkcpfa.instruqt.io` (due to the wildcard)

Run this snippet on the sandbox VM to print its fully qualified hostname:&#x20;

```bash
# Prints the hostname of the sandbox host 
echo $HOSTNAME.$_SANDBOX_ID.instruqt.io
```

The environment variable `_SANDBOX_ID` contains the sandbox identifier.  Sandboxes are created on-demand for every track play, and every sandbox has a unique identifier.&#x20;

If the attribute `allow_external_ingress` is empty, we do not add DNS records.&#x20;

{% hint style="info" %}
When using unauthenticated access, you can directly link to the VM using a [website tab](https://docs.instruqt.com/reference/platform/broken-reference). If you use `${_SANDBOX_ID}` in the URL, it will be replaced with the sandbox ID—for example, `api.host1.${_SANDBOX_ID}.instruqt.io`

HTTP URLs are also supported, but due to browser security restrictions, you must enable the \`new\_window\` (or "Open website in a new window") option. This is because Instruqt is served over HTTPS, and modern browsers block embedding HTTP content (mixed content) in an iframe within an HTTPS page.
{% endhint %}

## Host to host communication

All hosts in a sandbox can communicate with one another without any restrictions or blocked ports. This includes both containers and VMs.\
\
The Instruqt platform provides internal DNS for sandbox environments. If you add a host with the name `host01`, and another host with the name `host02`, they can reach one another using these short hostnames.

Container-to-container, VM-to-container, and container-to-VM communications all work using this method, so you won't need to keep track of IP addresses.

```
root@host01:~# ping host02 -c 1
PING host02.cn7p5alqphbi.svc.cluster.local (10.96.8.158) 56(84) bytes of data.
64 bytes from 10.96.8.158 (10.96.8.158): icmp_seq=1 ttl=63 time=1.34 ms
```

You may also use the internal private domain names for host-to-host communication. The `_SANDBOX_DNS` environment variable contains the full domain address and can be used in complementary to the hostname to construct the FQDN, as demonstrated below. This should only be necessary if your application requires a fully-qualified domain name (FQDN) for communication.

`host01.${_SANDBOX_DNS}`

## Outbound traffic from sandbox hosts

Sandbox hosts can connect to the public internet without limitations, as we do not block any outbound traffic from the sandbox.