Lab 05 — Tailscale Mesh

Duration: 60 minutes

This lab builds a two-node Tailscale network (tailnet) between your operator console and the GL.iNet Mango. Both nodes will appear in the tailnet by name, resolve each other via MagicDNS, and be governed by an ACL policy that separates operator-side nodes (tag:operator) from device-side nodes (tag:device). By the end of the lab, tailscale ping drop-<student> from the operator console returns real latency to the Mango in front of you.

From this point forward, every subsequent lab can reach the Mango over the tailnet rather than via local LAN only. The bench connection is still used for the initial enrollment in this lab; after that, SSH to the Mango can come from any operator console on the tailnet.

Where each step runs

Lab 05 is marked codespaces: "supported" because the Codespace runs the operator console, and the Mango is enrolled from the laptop over local LAN. After enrollment completes, the Codespace can reach the Mango by tailnet hostname for all subsequent steps.

Learning objectives

• Understand Tailscale ACL tags and why tag:operator and tag:device must be distinct: the operator console can reach drop devices, but drop devices cannot reach other students’ drop devices.
• Generate and use ephemeral auth keys with specific ACL tag scopes.
• Bring up Tailscale on two heterogeneous nodes (Debian operator console and MIPS router) using the same CLI pattern.
• Verify MagicDNS resolution and peer presence via tailscale status --json.
• Record the Tailscale version to labs/output/build-manifest.json so all students pin the same version.

Pre-state

Before starting this lab confirm all of the following.

# Lab 03 ExtRoot is working (/overlay is on USB)
ssh root@192.168.8.1 'df -h | grep overlay'
# Expected: /dev/sda1 is /overlay, several GB free

# Tailscale binary is present on the Mango (installed in Lab 03 on ExtRoot)
ssh root@192.168.8.1 'tailscale --version'
# Expected: a version line, e.g. 1.76.6

# Tailscale is present in the operator console
tailscale --version
# Expected: same or close version

# Lab 04 domain is verified; your CF account is active.
# (Lab 05 Tailscale config is independent of CF; they converge in Lab 06.)

# You have the instructor-issued auth keys: one tagged tag:operator (for the
# operator console) and one tagged tag:device (for the Mango).
echo "Have both auth keys in hand before proceeding."

Instructor preparation (complete before class):

1. Create the workshop tailnet (free Tailscale account suffices for a class).
2. Install the acl-policy.example.hujson from this lab directory as the tailnet ACL.
3. Issue one ephemeral auth key per student tagged tag:device (for the Mango).
4. Issue one ephemeral auth key per student tagged tag:operator (for the operator console).
5. Write both keys to each student’s assignment card.
6. Recommended key TTL: 12 hours (expires end of workshop day).

Walkthrough

tailscale --version

1.76.6
  tailscale commit: abc1234...
  go version: go1.22.x

ssh root@192.168.8.1 'tailscale --version'

# Source the env file if not already in your shell
source /etc/environment 2>/dev/null || true

OPERATOR_KEY="tskey-auth-XXXXXXXXXXXX"   # replace with your tag:operator key
STUDENT="yourname"                       # replace with your student slot (e.g. alpha)

tailscale up \
  --auth-key="${OPERATOR_KEY}" \
  --hostname="ep-${STUDENT}" \
  --accept-routes \
  --ssh \
  ${TS_EXTRA_ARGS:-}

OPERATOR_KEY="tskey-auth-XXXXXXXXXXXX"   # replace with your tag:operator key
STUDENT="yourname"                       # replace with your student slot (e.g. alpha)

tailscale up \
  --auth-key="${OPERATOR_KEY}" \
  --hostname="ep-${STUDENT}" \
  --accept-routes \
  --ssh

tailscale status

100.x.x.x   ep-yourname    yourname@  linux   -

tailscale status --json | grep -A2 '"Tags"'
# Expected:  "Tags": ["tag:operator"]

# From your laptop
ssh root@192.168.8.1

# On the Mango
DEVICE_KEY="tskey-auth-YYYYYYYYYYYY"   # replace with your tag:device key
STUDENT="yourname"                     # same slot as Step 3

# Enable and start the tailscale daemon if it is not already running
/etc/init.d/tailscale enable
/etc/init.d/tailscale start
sleep 5

tailscale up \
  --auth-key="${DEVICE_KEY}" \
  --hostname="drop-${STUDENT}" \
  --accept-routes \
  --ssh \
  --timeout=60s \
  ${TS_EXTRA_ARGS:-}

tailscale status

100.x.x.y   drop-yourname  yourname@  linux   -
100.x.x.x   ep-yourname    yourname@  linux   idle; offers exit node

# Ping the Mango by MagicDNS name
tailscale ping "drop-${STUDENT}"

pong from drop-yourname (100.x.x.y) via DERP(ord) in 15ms
pong from drop-yourname (100.x.x.y) via 192.168.8.1:41641 in 2ms

# MagicDNS resolves the short hostname to a tailnet IP
tailscale ip --4 "drop-${STUDENT}"
# Expected: 100.x.x.y  (a Tailscale CGNAT address)

# Ping by short name (MagicDNS must be enabled on the tailnet)
ping -c 3 "drop-${STUDENT}"

# This should succeed: operator can reach device
ssh "root@drop-${STUDENT}"
exit

# On the Mango
# This should fail: device cannot initiate to operator
tailscale ping "ep-${STUDENT}"
# Expected: no route to host, or timeout
# The ACL blocks device -> operator initiation.

MANIFEST="labs/output/build-manifest.json"
TS_VERSION=$(tailscale --version | head -1)

# If the manifest does not exist yet, create a minimal stub
if [ ! -f "$MANIFEST" ]; then
  mkdir -p labs/output
  printf '{"role":"engagement-platform","openwrt_version":"23.05.3","created_at":"%s"}\n' \
    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MANIFEST"
fi

# Merge tailscale_version into the manifest
UPDATED=$(jq --arg v "$TS_VERSION" '. + {tailscale_version: $v}' "$MANIFEST")
printf '%s\n' "$UPDATED" > "$MANIFEST"

echo "tailscale_version recorded: $TS_VERSION"
cat "$MANIFEST"

Post-state

When this lab is complete you should be able to answer yes to all of the following:

• tailscale status --json on the operator console shows ep-<student> with tag:operator and lists drop-<student> as a peer.
• tailscale status --json on the Mango shows drop-<student> with tag:device and lists ep-<student> as a peer.
• tailscale ping drop-<student> from the operator console returns pong with latency.
• ssh root@drop-<student> from the operator console succeeds over the tailnet.
• tailscale ping ep-<student> from the Mango fails or is refused (ACL blocks device-to-operator initiation).
• labs/output/build-manifest.json contains a tailscale_version field.

Validation

Three validation paths. All three call the same validate.sh; only the delivery channel differs.

Path 1: epl CLI (recommended from the operator console).

export STUDENT=yourname
epl validate lab05-tailscale-mesh

The validator SSHes to the Mango via the tailnet (using the drop-<student> hostname), so no bench connection is required after Step 4. Re-run as many times as you like; only the most recent result is recorded.

Path 2: direct script.

export STUDENT=yourname
bash courses/engagement-platform-labs/labs/lab05-tailscale-mesh/validate.sh

Or via the Makefile:

cd courses/engagement-platform-labs/labs
make validate-lab05-tailscale-mesh

Path 3: paste output into the widget.

Run validate.sh anywhere, copy the full output, and paste it into the widget below.

What the script checks:

1. tailscale status --json on the operator console shows ep-<student> in Self with tag:operator.
2. ep-<student> appears as a peer in the Mango’s status output (via SSH).
3. drop-<student> appears as a peer in the operator console’s status output.
4. tailscale status --json on the Mango shows drop-<student> in Self with tag:device.
5. tailscale ping drop-<student> from the operator console returns pong.
6. labs/output/build-manifest.json contains tailscale_version.

The script reads STUDENT from the environment. Export it before running:

export STUDENT=yourname

Primitives and drop-in substitutes

Tailscale is this lab’s specific mesh implementation. The primitive it delivers decomposes into four substitutable layers. WireGuard is the data plane and the de-facto standard across the mesh-VPN landscape. The control plane governs who belongs to the mesh and what each peer can reach. The relay plane provides a TCP-based fallback when direct UDP between peers fails. MagicDNS-style name resolution is the fourth, optional, layer that maps peer hostnames to tailnet addresses. If a client network blocks Tailscale specifically, the WireGuard data plane usually continues to work; what you swap is one of the upper layers.

                  ┌───────────────┐
   PEERS  ←────→  │  DATA PLANE   │  ← WireGuard (kernel module or userspace)
                  └───────────────┘
                         ↑
                         │ keys, peer list, ACL
                         ↓
                  ┌───────────────┐
                  │ CONTROL PLANE │  ← Tailscale coordinator | headscale | Innernet | NetBird
                  └───────────────┘
                         ↑
                         │ when direct UDP fails
                         ↓
                  ┌───────────────┐
                  │  RELAY PLANE  │  ← DERP (Tailscale) | self-hosted DERP | Nebula lighthouse
                  └───────────────┘
                         ↑
                         │ optional
                         ↓
                  ┌───────────────┐
                  │  NAME SERVICE │  ← MagicDNS | headscale DNS | split-DNS resolver
                  └───────────────┘

Substitutes

Take-home prompt

Stand up headscale on a VPS or a local systemd-nspawn container, reconfigure your operator console’s tailscaled to point at the headscale URL, and re-run the Lab 05 enrollment steps against your own coordinator. Compare the user model: Tailscale’s OAuth-backed admin console and ACL hujson versus headscale’s CLI-managed users and namespaces. For an alternative track, replace the data plane entirely: generate raw WireGuard keypairs with wg genkey / wg pubkey, write a minimal wg-quick config for each peer, bring up the interface with wg-quick up, and verify direct reachability without any coordinator.

Further reading

Tailscale upstream:

• Tailscale userspace networking. The mode the Codespace path uses. Explains when userspace is needed, the performance trade-off versus kernel TUN, and how to opt out on a machine where kernel TUN is available.
• ACL tags. The mechanism behind tag:operator and tag:device. Covers pre-approved tags, tag owners, and how to build multi-tier ACL policies for more complex engagement architectures.
• MagicDNS. How Tailscale’s internal DNS resolver works, how to enable it, and the split-DNS behavior that makes short hostnames (drop-yourname) resolve inside the tailnet without affecting external DNS.
• Auth keys. Ephemeral vs reusable keys, pre-approved tags, and recommended TTL for workshop environments.

Workshop-internal:

• Lab 03: Overlay Deployment. Tailscale was installed on the Mango ExtRoot in Lab 03. If the tailscale --version check in the pre-state above fails, verify that Lab 03 is complete and the USB overlay is mounted.
• Lab 06: Cloudflare Tunnel. Alternative reachability path: cloudflared creates an outbound-only HTTPS tunnel from the Mango to Cloudflare’s network without any firewall rule or port forward. Lab 05 (Tailscale) and Lab 06 (cloudflared) are complementary; neither replaces the other.

View this page’s source: labs/lab05-tailscale-mesh/README.mdx

Troubleshooting

# On the Mango
/etc/init.d/tailscale restart
sleep 10
tailscale status

logread | grep tailscale
# Look for OOM or missing module errors

cat /etc/resolv.conf
# Should show 100.100.100.100 as the first nameserver

tailscale up --accept-dns=true <other-flags>

DROP_IP=$(tailscale ip --4 "drop-${STUDENT}")
ping -c 3 "$DROP_IP"

echo "$TS_EXTRA_ARGS"
# Expected: --tun=userspace-networking

source /etc/environment
tailscale up --tun=userspace-networking <other-flags>