PNETLab Setup

Get a working network lab running on your laptop — images and all.
Automated node-image downloads, IOL licensing, and verification for PNETLab.

PNETLab runs as a virtual machine. These scripts run against that VM: you create the VM once, then the provisioning script installs the images your labs need, generates the IOL licence, fixes permissions, and verifies everything works.

---

Two ways to use this

	basic	complete
Installs ishare2	yes	yes
Generates IOL licence	yes	yes
Fixes permissions	yes	yes
Reports which images your labs need	yes	yes
Downloads missing images	no — prints the commands instead	yes — automatic
Best for	learning what the setup actually does	getting running quickly

Start with basic. It is short, readable, and shows you exactly what is missing and how to fetch it. Move to complete when you want it done for you.

basic — tell me what my labs need

It then prints the exact ishare2 commands to fetch whatever is missing.

complete — and install it for me

---

Quick start

1. Create the PNETLab VM

Download the official OVA from pnetlab.com and import it into VMware Workstation/Player, VMware Fusion, or VirtualBox.

Nested virtualisation must be enabled or every QEMU-based node will be unusably slow. See docs/VM-SETUP.md for per-hypervisor settings and recommended resources.

Boot it and note the IP shown on the console. Default login: root / pnet.

2. Import your labs

Open http://<vm-ip>/ in a browser (default login admin / pnet) and import the .unl labs you want to run.

This matters: the scripts install exactly what your labs reference. With no labs present there is nothing to install, and the script will tell you so.

3. Run the setup

Windows (PowerShell):

cd windows
.\pnetlab-setup.ps1 -VmHost <vm-ip>                  # basic
.\pnetlab-setup.ps1 -VmHost <vm-ip> -Mode complete   # with image downloads

Linux / macOS:

cd linux
./pnetlab-setup.sh --host <vm-ip>                    # basic
./pnetlab-setup.sh --host <vm-ip> --mode complete    # with image downloads

Or straight on the VM, if you prefer not to use the launchers:

scp -r scripts root@<vm-ip>:/opt/pnetlab-setup
ssh root@<vm-ip>
chmod +x /opt/pnetlab-setup/*.sh
/opt/pnetlab-setup/provision-basic.sh

---

Repository layout

scripts/                     run INSIDE the PNETLab VM
  pnetlab-lib.sh             shared helpers (detection, verification, licence)
  provision-basic.sh         simple setup, no downloads
  provision-complete.sh      full setup with automatic image downloads
  image-map.conf.example     template for mapping renamed images
linux/pnetlab-setup.sh       run on a Linux/macOS host; drives the VM over SSH
windows/pnetlab-setup.ps1    run on a Windows host; drives the VM over SSH
docs/
  VM-SETUP.md                creating the VM, nested virtualisation, resources
  IMAGES.md                  how images work, ishare2 usage, substitution
  TROUBLESHOOTING.md         real errors and what they actually mean
  img/                       diagrams, and terminal captures from real runs

The terminal images above are real output from these scripts, rendered to SVG by docs/img/make-terminal-svg.py.

---

What complete does about missing images

Community labs frequently reference image folder names that do not exist on any public mirror, because the lab author renamed them locally. The script handles this explicitly rather than silently failing:

Use --dry-run first to see exactly what it would do, without changing anything:

# accept the closest match automatically
sudo ./provision-complete.sh --auto-substitute

# or decide the mapping yourself (takes priority)
echo 'name-the-lab-wants = name-on-the-mirror' >> image-map.conf
sudo ./provision-complete.sh --map image-map.conf

It then copies the disk into a folder named exactly what the lab expects, as virtioa.qcow2 — the filename PNETLab boots.

A substituted image is a different software version than the lab author used. It usually works, but version-sensitive labs can behave differently — e.g. RESTCONF requires IOS-XE 16.x or newer. Every substitution is printed clearly.

---

Verification

Both scripts finish with a status table for every image every lab references, and complete also prints a RAM budget per lab:

LAB                                    NODES    RAM_MB      %VM  VERDICT
some-large-lab                            17     20480    72.8%  ok
some-small-lab                             1      1024     3.6%  ok

A lab asking for more RAM than the VM has cannot run — it will fail or thrash. Either give the VM more RAM or lower the per-node RAM in the lab's node settings.

---

Legal note on images

This project downloads nothing by itself and ships no images. ishare2 is a third-party tool that fetches from public community mirrors. Router/switch images (Cisco IOL, vIOS, CSR1000v, etc.) are proprietary software — you are responsible for holding the appropriate licences or entitlements to use them. Use this for study and lab purposes in line with the vendors' terms.

---

Requirements

Host: an SSH client. Windows 10 1809+/11 include OpenSSH; if ssh is missing:

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

VM: PNETLab (Ubuntu-based), internet access, and enough RAM/disk for your labs. Image downloads are multi-gigabyte — budget 40 GB+ of disk.

---

Security

The default PNETLab credentials (root/pnet for SSH, admin/pnet for the web UI) are public knowledge. Change them, and do not expose the VM directly to the internet:

passwd            # on the VM

---

Licence

MIT for the scripts and documentation in this repository. It does not extend to any images you download, which remain under their vendors' terms.