Hosting ZNetLab, and running real IOS on it

1What each half actually needs

2What Hostinger can and cannot run

3The layout that does work

Put everything on one VPS. nginx serves the static site at / and hands the WebSocket upgrade and /api/* to the Node process on 127.0.0.1:8080. The site and the lab server are then the same origin, which makes the default in the sign-in box correct instead of wrong, and there is no CORS, no mixed content and no second certificate.

4Build the server, step by step

# DNS
labs.yourdomain.com.   A   203.0.113.45

ssh root@203.0.113.45

apt-get update && apt-get install -y git nginx
git clone <your znetlab repo> /opt/znetlab-src
cd /opt/znetlab-src/znetlab/server

./deploy.sh

mkdir -p /var/www/znetlab
cp -r /opt/znetlab-src/znetlab/* /var/www/znetlab/
# the site is the HTML/JS/CSS; server/ and tools/ do not need to be public,
# but leaving them there is harmless — nothing serves them as code.

nano /etc/systemd/system/znetlab.service

# on the ExecStart line, add:
  --host 127.0.0.1 \
  --lab-url wss://labs.yourdomain.com

systemctl daemon-reload && systemctl restart znetlab

--lab-url-free       wss://free-labs.yourdomain.com
--lab-url-pro        wss://labs.yourdomain.com
--lab-url-enterprise wss://labs.yourdomain.com

# /etc/nginx/sites-available/znetlab
server {
  listen 80;
  server_name labs.yourdomain.com;
  root /var/www/znetlab;
  index index.html;

  # The API and the image upload.
  location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Images are large. 8192 MB is the server's own default cap.
    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_read_timeout  3600s;
    proxy_send_timeout  3600s;
  }

  # The WebSocket connects to the ROOT path, so this location has to serve
  # both the home page and the upgrade. Told apart by the Upgrade header.
  location / {
    if ($http_upgrade = "websocket") {
      proxy_pass http://127.0.0.1:8080;
    }
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host       $host;
    # Consoles sit idle while somebody reads. There is no application-level
    # keepalive, so a short read timeout silently kills live sessions.
    proxy_read_timeout 86400s;

    try_files $uri $uri/ /index.html;
  }
}

ln -s /etc/nginx/sites-available/znetlab /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# TLS, free, and it edits the config for you
apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d labs.yourdomain.com

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

# NOT open: 8080 (nginx reaches it on localhost)
# NOT open: 23000-23999, the raw telnet consoles

5The KVM question on a VPS

A Hostinger VPS is itself a virtual machine. Whether it can run another virtual machine inside itself — nested virtualisation — decides how fast QEMU images boot.

# on the VPS, after deploy.sh
ls -l /dev/kvm
egrep -c '(vmx|svm)' /proc/cpuinfo

6Prove it before you trust it

# the kernel
/opt/znetlab-src/znetlab/server/verify.sh

# the running server, driven over its own socket
node /opt/znetlab-src/znetlab/server/verify-lab.js ws://127.0.0.1:8080 admin <password>

# from your laptop — through nginx and TLS this time
curl https://labs.yourdomain.com/api/info

Then the human check, which takes a minute and needs no image at all: open the site, sign in, drop two Virtual PCs and a LAN Switch on the canvas, cable them, press Start lab, and ping across. If that works, the datapath works.

1Four ways in, one destination

Everything ends up in the same folder, and ZNetLab takes it from there. There is no path to type and no form to fill in.

# the drop folder, printed by deploy.sh when it finishes
/opt/znetlab/images/incoming/

2What happens to the file

The importer watches that folder. Nothing is typed; every step below is automatic.

# one file, start to finish
incoming/chr-7.15.3.img.zip
  → quiet for 2.5s
  → first bytes say PK, not QFI     the extension was a lie; it is a zip
  → unpacked, chr-7.15.3.img falls out
  → matched mikrotik 7.15.3
  → qemu-img convert -O qcow2
  → library/mikrotik-7.15.3/virtioa.qcow2
  → on the shelf, draggable

3Naming — the only thing it asks of you

Get the name right and there is nothing else to configure. Get it wrong and ZNetLab does not guess: the file is set aside and said so.

Dynamips — classic IOS

c7200-adventerprisek9-mz.152-4.S6.image
c3725-adventerprisek9-mz.124-15.T14.image
# Cisco's own filename. Leave it exactly as it came.

IOL / IOU — L2 and L3 images

i86bi-linux-l2-adventerprisek9-15.2d.bin
i86bi-linux-l3-adventerprisek9-15.4.1T.bin
# The build date is part of the name, not an extension.

library/iourc          <- covers everything below it
library/iol-15.2d/
  ├── i86bi-linux-l2-adventerprisek9-15.2d.bin
  └── iourc          <- or per image, keyed to the host

The licence file itself

Cisco IOL/IOU images (i86bi…, x86_64…). Nothing else needs one. A plain-text file called iourc — a few hundred bytes, no extension. ZNetLab saves it under that name whatever your copy is called.

Three ways in, and no shell needed for any of them: Images → IOL/IOU licence paste the licence as text; the same box takes the file if you have it; or drop the iourc into incoming/ and it is filed as library/iourc. Whichever you use, the file is read before it is kept — the wrong file is refused there and then, with the format, instead of becoming a node that exits at boot with an empty console.

# the format
[license]
<hostname> = <16 hex digits>;

# for example, on a server whose hostname is znetlab-lab
[license]
znetlab-lab = a1b2c3d4e5f60718;

• The first line is the section header, literally [license].
• Then one line per host: the hostname of this lab server, a space, an = sign, the 16-hex-digit key, and a semicolon.
• The hostname is the one the licence was issued for. It need not be this server: IOL exits immediately if the licence names a different host, so ZNetLab starts the image under the hostname the licence names (this needs unshare/util-linux).
• Never edit the hostname line to match your server. The key is derived from the hostname, so an edited file carries the wrong key and IOL refuses it. Install the licence exactly as it was issued.
• More than one host may be listed; extra lines and blank lines are harmless.
• ZNetLab ships no licences, and one may only be used where your agreement with Cisco permits it.

QEMU — disk images

# the DIRECTORY carries the identity; the disk keeps its own name
library/vios-15.6.2T/virtioa.qcow2
library/csr1000vng-17.03.04a/virtioa.qcow2
library/asav-9.16/virtioa.qcow2

4When it will not recognise a file

images/unidentified/     <- it went here, and the Images tab says so

Rename it the way the tables above show and drop it in again. ZNetLab refuses to guess on purpose: a guessed platform becomes a device that fails to boot twenty minutes later, in front of somebody who has already built a topology around it.

5Check it landed

Open Images. An installed image shows its platform, which engine will run it, and whether it is on the shelf. Or from the shell:

ls -R /opt/znetlab/images/library/
ls    /opt/znetlab/images/unidentified/
journalctl -u znetlab -f          # the importer narrates every step

6Test the server with images that need no licence

Before you put anything licensed on a new box, prove it with something free. All of these are legitimately downloadable and between them cover BGP, OSPF, IS-IS, MPLS L3VPN, VXLAN with EVPN, IPsec, multicast and QoS:

FRRouting · VyOS · MikroTik CHR · Cumulus VX · Arista vEOS · Open vSwitch · pfSense CE · OPNsense · FortiGate VM · Alpine · Ubuntu Server · Ostinato

7Keep the library off the system disk

Attach a second volume and mount it at the image directory before you fill it. Images outlive servers: when you rebuild the VPS, you want to reattach a disk rather than re-download 40 GB.

mkfs.ext4 /dev/sdb
mkdir -p /opt/znetlab/images
mount /dev/sdb /opt/znetlab/images
echo '/dev/sdb /opt/znetlab/images ext4 defaults 0 2' >> /etc/fstab

# and back up the OTHER directory — the one that cannot be re-downloaded
tar czf znetlab-state.tgz /var/lib/znetlab   # accounts, saved labs, billing, tickets

1The order, and why it is that order

Doing these in any other sequence produces a lab that looks right and does not forward, which is the worst failure a teaching tool can have.

2Step 4, in detail — the wiring

# one link becomes one bridge
ip link add br-l1 type bridge
ip link set  br-l1 up

# one interface becomes one tap, in that bridge, BEFORE the emulator opens it
ip tuntap add dev n1i0 mode tap
ip link set n1i0 master br-l1
ip link set n1i0 up

The tap name is <nodeId>i<interface index>. That is the name handed to the emulator on its command line, which is how a drawn cable becomes a real one.

3Step 6 — what each engine is actually given

Dynamips — classic IOS on an emulated CPU

dynamips -P 7200 -r 256 -C 128 --idle-pc 0x60c08728 \
         <slot cards> -s 0:0:tap:n1i0 -s 1:0:tap:n1i1 \
         /opt/znetlab/images/library/c7200-…-mz.152-4.S6.image

-P chassis, -r RAM, -C NVRAM, and one -s slot:port:tap:<tap> per interface. The idle-PC value is what stops a 7200 burning a whole core doing nothing.

IOL — IOS as an ordinary Linux process

# the image IS the binary; there is no emulator in front of it
./i86bi-linux-l2-adventerprisek9-15.2d.bin  3  -e 2 -s 0 -n 128
# argv[1] is the instance id, and it must match what NETMAP says
# cwd is the shared lab directory; IOURC points at the staged licence

-e is ethernet slots — four interfaces per slot — -s serial slots, -n NVRAM in KB.

QEMU — full disk images

qemu-system-x86_64 -enable-kvm -cpu host \
  -m 4096 -smp 2 \
  -drive file=…/csr1000vng-17.03/virtioa.qcow2,if=virtio,format=qcow2 \
  -nographic -serial mon:stdio \
  -device virtio-net-pci,netdev=n0,mac=52:54:00:… \
  -netdev tap,id=n0,ifname=n1i0,script=no,downscript=no

• -enable-kvm -cpu host appear only if /dev/kvm exists. Without it the same command runs under software emulation.
• The disk format is read from the file, not assumed.
• The NIC model and the bus come from the platform — a CSR wants virtio, an ASAv does not.
• The MAC is derived from the device name, so it is stable across restarts.

The three built-ins — no process at all

# a Virtual PC is a network namespace with a real TCP/IP stack
ip netns add pc1
ip link add pc1-eth0 type veth peer name br-l1-p0
ip link set pc1-eth0 netns pc1

# a LAN Switch is the bridge itself — real MAC learning, real flooding
# a NAT Cloud is a bridge plus iptables masquerade onto the uplink

4The console

Every node gets a TCP port from 23000. The browser console and an external telnet client attach to the same session — what you type in either is seen in both, which is genuinely useful when two people are looking at one problem.

*** ZNetLab console: R1 ***
R1> enable
R1# show ip interface brief

For Dynamips and QEMU the process's own stdout is the console. For a Virtual PC there is no pty, so ZNetLab does the line editing itself.

5What "starting" and "running" actually mean

The states that are reported honestly: stopped when the process exits — with its exit code — and error when it could not be run at all, with the reason on the device rather than buried in a log.

6When a device will not start

Generated by tools/hosting-pdf.js. Ports, timings, ceilings, platform counts and command lines are read from assets/plans.js, assets/platforms.js, server/server.js and server/importer.js rather than transcribed, so this document goes stale only when the product does. ZNetLab ships no vendor software: every image referred to here is one you supply and are licensed to run.