WireGuard lab: build a VPN tunnel between two sites in your browser

This lab gives each student two small sites to join. Four machines are built inside the student’s one Ubuntu VM: a host and a gateway at each site, with the two gateways linked by a link that stands for the internet and knows nothing of either private network. The student builds a WireGuard tunnel between the gateways, until a host at one site can ping a host at the other.

Nothing is installed on the student’s computer and no VPN appliance is needed: every host and gateway is a network namespace, and the tunnel is the real WireGuard that Ubuntu’s kernel provides, with the real wg and wg-quick commands.

What students learn

How a VPN tunnel joins two private networks: making a key pair on each gateway with wg genkey and wg pubkey, and why a private key must be readable by nobody else; writing wg0.conf with an address for the tunnel, each gateway’s peer and the networks that may go to it; bringing the tunnel up and reading wg show for the handshake; and routing the two networks through it. They watch the internet link with tcpdump and see that what crosses it is encrypted UDP, and they make the tunnel come back from its saved files after a restart.

The topology

Site A is the host a1 on 10.1.0.0/24 behind the gateway gwA, and site B is the host b1 on 10.2.0.0/24 behind the gateway gwB. The gateways are linked by 203.0.113.0/24, the internet, which has no route to either private network and must never be given one. A ping from a1 to b1 fails until the tunnel is built. Each gateway’s WireGuard files live in its own /etc/wireguard, which on the VM is /etc/netns/gwA/wireguard and /etc/netns/gwB/wireguard. The addresses are in the README the lab leaves in the home folder, which says what to do and gives none of the answers.

Run it in your browser

VM labs are set as a lab task in a module, and the sample is on the lab’s page. The machine is small: one CPU, 1 GB of memory and 10 GB of disk.

  1. Add the lab. In a module you teach, add a task and choose the Ubuntu VM lab card. The page shows a short description of the machine instead of a compose file.
  2. Start from the sample. The page offers ready-made labs to start from. Choose WireGuard tunnel. Using a sample replaces the text, and Undo brings yours back.
  3. Publish and start your own copy. Publish, then Start. The lab’s own setup script installs wireguard-tools and tcpdump from Ubuntu’s archive, and writes the wglab command and the README, the first time the VM starts, in a few seconds.
  4. Open the terminal. Open its terminal and read README.md in the home folder: it says what to build and gives none of the answers.

A basic lesson on this lab

WireGuard Basics is a small lesson worked in this lab, which is an Ubuntu VM: each step is explained and has a Run button that types its command into the machine’s terminal and shows what it printed. A student meets the machines, pings the far host and is told Destination Net Unreachable, reads the gateway’s two routes to see why, and finds that wg show prints nothing because there is no tunnel yet.

The lesson looks around and leaves the lab’s own task, building the tunnel, to the student, so it hands out no answers. It is deliberately small: it shows a teacher what a lesson worked in a lab is, and the lab does the rest. Copy it into a module of your own to change it.

How it is marked

The lab has a check. It runs on a copy of the saved machine after a fresh start, so it sees only what the student saved in each gateway’s wg0.conf, and it passes only if the real state holds: the configurations are readable by their owner alone, each names the other gateway’s public key, both gateways have a recent handshake, a ping between the hosts moves bytes through the tunnel, and a capture on the internet link shows only UDP and no private address. A plain static route between the two networks does not pass, nor does a tunnel brought up by hand and never saved, and the first line of what the check printed says why.

  1. Hand it out. Assign the lab like any task, with a due date if you want one. Each student gets a VM of their own, kept between sessions.
  2. Run the check. On a student’s row in the class list, press Run the check. It starts a copy of their saved machine that is not saved back, runs the lab’s check script as root and shows whether it passed, what it printed and when. The student is not told the result.
  3. Mark it. Read the first line of what the check printed: it says what is not right, such as a key anybody can read or a ping that did not go through the tunnel. Send the work back with a reason if it needs more.

The definition on GitHub

The file is the whole lab definition, the same text the platform runs: size, setup script, topology tool, README and check. Copy it and change the addresses, or add a third site, to make a longer lab.

Questions people ask

Does the lab need a VPN appliance or a licence?
No. WireGuard is free software, and the tunnel is made by the module in Ubuntu’s own kernel with the wireguard-tools package, installed from Ubuntu’s archive when the student’s VM starts. Nothing of it is distributed by us.
Can a student reach the real internet from the lab?
No. The VM reaches Ubuntu’s archive, PyPI, npm and GitHub and nothing else, and the “internet” between the two sites is a virtual link inside the VM, so the tunnel is between two sites that are both in the same machine.
How is the WireGuard lab marked?
The check runs on a copy of the saved machine after a fresh start. Each wg0.conf must be readable by its owner alone and name the other gateway’s public key, both gateways must have a recent handshake, and a ping between the hosts must move bytes through the tunnel. A plain static route does not pass.