Troubleshooting

Troubleshooting

Help index · Project overview

Web page or startup problems

Check docker compose logs --tail=100 lab, using the same Compose overrides as installation. The default address is http://127.0.0.1:8080/ on the server. For remote use, use an SSH tunnel or explicitly bind a trusted LAN address. The individual device consoles are proxied through the same HTTP port.

A port-already-in-use error means another server owns the listener. A “server already manages this data directory” error means the data directory is locked by another manager. Choose a different port and data directory for a second workspace; do not delete a live server's lock file.

After source updates, Docker installations need a rebuild and recreation, not just a restart. Save configurations and stop the lab first, then refresh the browser. Native installations need a server restart for Python/Perl changes; plain JS/CSS changes need a browser refresh.

Missing images or wrong ports

Check the image directory mount and filename. Uploaded files appear after the upload finishes. Manually copied IOL .bin files need execute permission; QCOW2 files need read permission. EXOS and Arista use filename prefixes to select the right profile. Arista also needs the exact companion Aboot ISO.

See device profiles. Arbitrary QCOW2 operating systems are not supported. Stop the lab and remove incompatible cables before changing a node between image families with different interface names.

QEMU cannot start or boot takes a long time

Check /dev/kvm, virtualization support in the host, nested virtualization if applicable, and the KVM Compose override. Ensure enough RAM is available for all nodes. vEOS-lab defaults to 6144 MB per node. A Running badge means the process started; IOSv, EXOS and vEOS may still be booting for several minutes. Watch the console before diagnosing forwarding.

IOL exits during startup

Open the node's launcher logs. Unexpected console-process exits include the last 16 KiB of device output, which may reveal a license, image, dependency or NETMAP problem. Native Linux needs the 32-bit libraries listed in installation.

Provide any required license for the execution environment; Weblab does not generate one. The app preserves a node-specific iourc, otherwise links one from the image directory. Native launches can also use the IOURC environment variable. Do not post license contents in an issue.

NETMAP is generated by the manager. With host networking, the container hostname must resolve locally; the provided Compose file includes that mapping. A netio error: mkaddr: No route to host can indicate a hostname/NETMAP issue. Do not reuse application IDs already owned by another process or lab.

For an Abnormal ciscoversion string error, compare the host/container DNS and hosts-file configuration as well as the image version. Check for custom DNS/hosts overrides, including mappings of vendor domains to loopback. This message alone does not establish a licensing cause.

PCs cannot start or reach another node

Install the requested Alpine image in the host Docker daemon. Check Docker socket access, /dev/net/tun, NET_ADMIN and host networking. Rootless Docker and Docker Desktop are not supported by the supplied setup. Start the connected router/switch before a PC.

Check ip address and ip route in the PC, interface state in the peer, VLAN membership, trunks, routing and link-fault settings. ARP and spanning-tree convergence can delay initial replies. PCs are not automatically connected to the host management network or internet.

PC files and packages disappear on restart because the container is disposable. Keep its startup IPv4/gateway in the inspector; an empty address field is allowed.

Console is read-only, blank or covered by the keyboard

A padlock/eye indicator can mean another station holds the input lock. Use Take over and confirm, or have the owner unlock it. All stations share one CLI session, not independent logins. A disconnected console cannot send input; use Reconnect and check whether the device is still running.

Use toolbar Ctrl+C, Tab and arrows when a mobile keyboard lacks them. The Keys menu includes Cisco's Ctrl+Shift+6 interrupt. If the keyboard consumes most of the screen, hide side drawers, resize/maximize the console or arrange windows with the keyboard visible. Try a current browser with visual-viewport support. Report the browser version and screen orientation if overlap persists.

On plain LAN HTTP, automatic system clipboard access is normally unavailable. Select Workspace clipboard to copy selected text between Instructions and terminals in this page. Use the browser's normal Paste or keyboard shortcut for text copied in another application. See clipboard.

Missing configuration or VLANs after import

Save device configuration before stopping/exporting. Plain topology JSON does not contain disks or current VLAN databases. JSON + saved configs contains startup text only; use Saved lab ZIP for complete supported saved storage.

Check that the archive includes vlan.dat-<application-ID> for each IOL switch that uses it. An incomplete archive cannot restore those VLANs or names. Recover from an intact saved lab or recreate the VLANs, then export again.

Import validates images and archive checksums. On mismatch, install the matching base image/Aboot instead of changing the manifest to hide the error. Restore already replaces the full node-storage tree; do not purge all of lab-data. See backup compatibility.

Initial snippets did not apply

Snippets apply only to fresh Cisco storage. Existing IOL NVRAM or the current IOSv writable disk takes precedence, including after a ZIP restore. Reusing node IDs is not a factory reset. For a new exercise, use distinct IDs or a separate data directory. Do not delete another lab's saved state to force a snippet.

Configuration export fails

Saved extraction requires stopped Cisco devices and supported storage. IOSv extraction also needs temporary disk space and QEMU/mtools/gzip. Live extraction requires every Cisco console at an unlocked privileged EXEC prompt, without a password prompt or configuration mode. EXOS/Arista config-text extraction is not supported. Neither source silently falls back to another source.

If live export reports that console logging could not be restored, follow its manual recovery commands and verify the result before saving device state.

Reporting a bug

Include the revision (git rev-parse --short HEAD), host OS, Docker/Compose and browser versions, image family/version, reproduction steps and relevant logs. State whether the problem occurs after a fresh import, a restart or a layout change. Describe expected and actual results. Remove credentials, license text and private configuration before sharing. Never attach vendor images or full personal lab archives to a public issue.

Experimental WSL installations

A user has reported running IOL from the prebuilt image under Windows 10 WSL with local DNS and hostname adjustments. This is a limited field report, not validation of all device families, Alpine/macvlan networking or Docker Desktop. The supported installation target remains rootful Docker Engine on x86-64 Linux. QEMU devices require usable /dev/kvm inside the application container; check that directly rather than inferring support from the Windows version alone.

Check hostname resolution separately from external DNS. For a container named weblab, use --hostname weblab --add-host weblab:127.0.0.1, as in the plain Docker example. The Compose files already include this mapping. An external --dns override is specific to the local resolver/network and is not a general installation step. Do not copy another machine's resolver address, loopback route or WSL address. Keep any required image licensing appropriate to its execution environment.