OML User Guide #

OML (Open Multi-vendor Lab) is a self-hosted network emulation platform that runs real Cisco IOS, ASA, Juniper, Arista, Palo Alto, Linux, and Windows VMs — entirely from your browser. No physical hardware, no simulator shortcuts.

This guide walks you from a fresh OML install all the way through building multi-vendor labs, capturing packets, and using the built-in AI assistant.

What OML can do #

System Requirements #

OML is installed on a Linux host (bare-metal or VM). Students access it via browser — no client software needed.

OML ships as an OVA — a pre-built virtual machine you import into VMware or Proxmox. The host running the hypervisor must meet these specs.

Hypervisor host #

OML VM resource allocation #

The OML VM itself is lightweight. The resources you assign to it become the pool available for running network nodes:

Client browser #

Any modern browser works. Chrome/Chromium 110+ and Firefox 115+ are tested. Safari works for console but may lag on VNC.

Installation #

OML is distributed as a pre-built OVA (Open Virtual Appliance). Everything — Ubuntu OS, backend API, QEMU, PostgreSQL, Redis, and the web frontend — is already installed and configured inside the image. You just import it into your hypervisor and boot.

Import on VMware (ESXi / Workstation / Fusion) #

• 1
  Download the OVA

  Log in to your OML account at license.omllabs.com and download OML-latest.ova from the Downloads section.
• 2
  Import the OVA

  ESXi / vSphere: Actions → Deploy OVF Template → browse to the OVA file → follow the wizard. Accept default storage and networking.
  
  VMware Workstation: File → Open → select the OVA file → click Import.
  
  VMware Fusion: File → Import → select the OVA file.
• 3
  Enable hardware virtualization on the VM

  Before powering on: VM Settings → Processors → check "Virtualize Intel VT-x/EPT or AMD-V/RVI". Without this, QEMU inside OML cannot use KVM and nodes will be extremely slow.
• 4
  Set RAM and vCPU

  Allocate at least 8 GB RAM and 4 vCPUs to the OML VM. More is better — each network node you run inside OML consumes RAM from this pool.
• 5
  Power on and note the IP address

  OML boots in ~60 seconds. The console screen displays the assigned IP address (DHCP by default). Open that IP in your browser to reach the OML web UI.

Import on Proxmox VE #

• 1
  Upload the OVA to Proxmox

  Copy the OVA to your Proxmox node via SCP, or upload via Datacenter → Storage → Upload. Proxmox stores it under ISO images.

  bash — proxmox node shell

  scp OML-latest.ova root@<proxmox-ip>:/var/lib/vz/template/iso/

• 2
  Import the OVA

  Proxmox doesn't have a native OVA wizard — extract it and import the disk. Run in the Proxmox shell:

  bash — proxmox node shell

  # Extract OVA (it's a tar archive)
  cd /var/lib/vz/template/iso/
  tar xf OML-latest.ova
  
  # Create a new VM (adjust VMID and storage name as needed)
  qm create 200 --name "OML" --memory 8192 --cores 4 --net0 virtio,bridge=vmbr0
  
  # Import the disk (replace 'local-lvm' with your storage)
  qm importdisk 200 OML-latest-disk001.vmdk local-lvm
  
  # Attach disk as primary boot disk
  qm set 200 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-200-disk-0
  qm set 200 --boot c --bootdisk scsi0

• 3
  Enable nested virtualisation

  In the VM Hardware tab → Processors → check Enable KVM and set CPU type to host. This passes through the real CPU flags so QEMU inside OML can use KVM acceleration.

  bash — alternative via CLI

  qm set 200 --cpu host
  # Verify KVM is enabled on the Proxmox host itself
  cat /sys/module/kvm_intel/parameters/nested  # should print Y or 1

• 4
  Start the VM

  Click Start in the Proxmox GUI or run qm start 200. Open the Console tab — OML boots and prints its IP address when ready.

After first boot #

Open http://<oml-vm-ip> in your browser. Default credentials are printed on the VM console screen. Proceed to First Login to change the password and configure the server.

First Login #

After installation, open http://<server-ip>. You'll land on the OML login page.

• 1
  Log in as admin

  Use the admin username and the password shown on the VM console screen after first boot. Change it immediately from Settings → Profile.
• 2
  Set server hostname & external IP

  Go to Admin → Server Settings. Set the External IP / Hostname to the address students will use. This controls where browser console connections are directed.
• 3
  Create student accounts

  Go to Admin → Users → New User. Assign a role: Student (lab access only) or Instructor (can see all labs, manage images).
• 4
  Upload your first QEMU image

  Go to Admin → Images → Upload. See Uploading an Image for naming conventions and RAM/CPU profiles.

License Activation #

OML runs in Free mode with up to 3 simultaneous nodes. Activate a paid license to unlock the full node limit and Pro/Enterprise features.

• 1
  Purchase a license

  Visit omllabs.com/#pricing, choose a plan, and complete checkout. An activation token (16-character code) is emailed to you within 60 seconds.
• 2
  Open License Settings

  In OML, navigate to Admin → Settings → License. You'll see the current tier and a token input field.
• 3
  Paste and activate

  Paste the token from your email and click Activate. OML contacts the license server, binds the license to this machine, and upgrades immediately — no restart needed.

Tier comparison #

Create Your First Lab #

A Lab in OML is a saved topology — nodes, links, and configurations. Labs are isolated per user; multiple labs can run concurrently on the same server.

• 1
  Click "New Lab" on the dashboard

  Give it a name (e.g. OSPF Practice) and an optional description. Click Create. You're taken to the canvas.
• 2
  Understand the canvas

  The topology canvas is where you drag, drop, and wire devices. The toolbar on the left holds node templates. The top bar has Start All / Stop All / Save buttons.
• 3
  Add nodes

  Drag a node type from the left panel onto the canvas, or right-click the canvas → Add Node. See Adding Nodes for image selection and RAM/CPU settings.
• 4
  Connect nodes

  Hover over a node until the port dots appear. Click a port and drag to another node's port to create a link. See Connecting Nodes.
• 5
  Start the lab

  Click Start All in the top bar. Nodes boot in parallel. Status indicators turn green when the OS is ready for console.
• 6
  Open a console

  Double-click any running node. The HTML5 console opens in a new tab — no SSH client required.

Adding Nodes #

Each node in OML is a QEMU VM backed by a disk image. When you add a node, OML creates a copy-on-write (COW) overlay so the base image is never modified.

Node settings #

Node templates #

Admins can create Node Templates under Admin → Node Templates. Templates pre-fill image, vCPU, RAM, and NIC count — students just drag the template icon and the node is pre-configured.

Connecting Nodes #

Links in OML are TAP-based virtual Ethernet pairs. Each link is full-duplex, and packet capture is available on every link.

Draw a link #

• 1
  Hover over the source node

  Small port circles appear at each interface position. The number corresponds to the interface order (e.g. GigabitEthernet0/0 → port 0).
• 2
  Click and drag to target

  Drag from the source port to any port on the target node. Release to create the link. OML creates a TAP pair and connects both ends immediately (even if the nodes are not yet started).
• 3
  Verify the link

  A line appears between the nodes. Hover over it to see port labels on both ends. Right-click → Capture to start a live pcap.

Delete a link #

Right-click the link → Delete. This removes the TAP pair; the interface on the VM side becomes unconnected (link-down) but is not removed. You can reconnect it later.

Network Types #

Beyond point-to-point links, OML supports Network Objects — virtual switches and bridge networks you can connect multiple nodes to.

Add a network object by right-clicking the canvas → Add Network. Then draw links from nodes to the network object icon just as you would between two nodes.

Start / Stop / Wipe #

Individual node #

Right-click any node on the canvas to see: Start, Stop, Wipe, Snapshot, Restore.

All nodes #

The top toolbar has Start All and Stop All. Start All boots every node in the lab in parallel. Stop All sends a graceful shutdown to all running nodes simultaneously.

Console Access #

OML provides an in-browser HTML5 terminal for every node. No SSH client, no Putty — just your browser.

Open the console #

• 1
  Double-click a running node

  If the node is stopped, a prompt asks if you want to start it. If it's starting, the console opens immediately but output appears once the OS boots.
• 2
  Console opens in a new tab

  The tab title shows the node name. Tabs stay open even if you navigate away from the lab canvas. Multiple console tabs can be open simultaneously.
• 3
  Send special keys

  Use the toolbar inside the console tab for Ctrl+C, Ctrl+Z, Ctrl+A, Break, and Escape. Some OS boot prompts (ROMMON, GRUB) need these.

Alternative: external Telnet client #

Every node exposes a raw Telnet port starting at 5000. The port for each node is shown in the node properties panel. Connect with:

telnet <oml-server-ip> 5001   # port shown in node properties

Keyboard shortcuts inside the console #

VNC & RDP #

GUI nodes (Windows, Ubuntu Desktop, Palo Alto) expose a VNC or RDP connection accessible from the browser.

VNC (Palo Alto, Linux GUI) #

Right-click the node → Open VNC. A noVNC window opens in-browser. The VNC WebSocket port starts at 6900. You can also connect with a native VNC client:

vncviewer <oml-server-ip>:<vnc-port>   # e.g. 192.168.1.79:5901

RDP (Windows) #

Right-click the node → Open RDP. An RDP connection proxied through the browser opens. The host-side RDP forward port starts at 13389. Connect with a native RDP client:

mstsc /v:<oml-server-ip>:<rdp-port>

Hotplug Interfaces #

OML supports hotplugging network interfaces on running nodes — you can add or remove links without stopping the VM.

To add a link to a running node: draw the link on the canvas as normal. OML automatically detects the node is running and injects the TAP without interrupting existing connections.

To remove a hotplugged link: right-click the link → Delete. The interface on the VM side goes link-down but is not removed from the OS interface list.

Supported Images #

OML runs any QEMU-compatible disk image. Below are commonly used images and their tested configurations.

Uploading an Image #

Images live in /opt/OML/qemu-images/. Organise them in subdirectories by vendor:

/opt/OML/qemu-images/
  cisco/
    c7200-adventerprisek9-mz.124-24.T5.bin
    csr1000v-universalk9.17.03.06.qcow2
  paloalto/
    PA-VM-KVM-10.1.0.qcow2
  ubuntu/
    ubuntu-22.04-server-cloudimg-amd64.img
  windows/
    win2022-base.qcow2

Via Admin UI #

• 1
  Go to Admin → Images → Upload

  Drag the image file onto the upload area or click to browse. Supported formats: qcow2, raw, vmdk (auto-converted), iso.
• 2
  Fill in the image metadata

  Set name, type (QEMU/IOL/Dynamips), default vCPU, default RAM, and interface count. These become the defaults when students drag this image onto the canvas.
• 3
  Click Save

  The image appears in the node panel immediately. No server restart needed.

Via SCP (large files) #

For images over a few GB, copy directly to the server and register via API:

# Copy image to server
scp csr1000v.qcow2 oml@<server-ip>:/opt/OML/qemu-images/cisco/

# Register via API (replace TOKEN with your admin token)
curl -X POST https://<server>/api/v1/images/register \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"CSR1000v","path":"cisco/csr1000v.qcow2","vcpus":2,"ram":4096,"nics":4}'

Palo Alto Bootstrap #

PAN-OS VMs require a bootstrap ISO to configure the management interface and initial credentials on first boot. OML can auto-generate and attach this ISO.

• 1
  Enable bootstrap in OML settings

  In /opt/OML/backend/.env (or Admin → Server Settings), set OML_PANOS_ATTACH_BOOTSTRAP=true. This is enabled by default.
• 2
  Add a Palo Alto node to your lab

  OML automatically generates a bootstrap ISO with: mgmt IP from the lab subnet, admin / OMLadmin1! as default credentials, panorama disabled.
• 3
  Start the node

  First boot takes 8–12 minutes. Watch VNC — the login prompt appears when PAN-OS is ready.
• 4
  Access the web UI

  PAN-OS web UI is on the management interface. Access it via the Management (OOB) network object or by connecting to the mgmt port from a Linux VM in the lab.

Packet Capture #

Every link in OML can be captured in real time. Captures are stored on the server and can be downloaded as .pcap files openable in Wireshark.

Start a capture #

• 1
  Right-click a link → Capture

  The link turns orange to indicate capture is active. A counter shows the packet count in real time.
• 2
  Generate traffic

  Generate traffic through the link (ping, routing updates, HTTP, etc.). All L2 frames are captured — no filter on the capture side.
• 3
  Stop and download

  Right-click the link → Stop Capture → Download .pcap. The file is named lab-name_nodeA_nodeB_timestamp.pcap.

Live streaming to Wireshark #

Stream directly into a running Wireshark on your laptop using the OML pcap API:

wireshark -k -i <(curl -s --no-buffer \
  -H "Authorization: Bearer TOKEN" \
  "https://<oml-ip>/api/v1/labs/<lab-id>/capture/<link-id>/stream")

Capture files are stored in /opt/OML/captures/ and are automatically pruned after 7 days.

AI Assistant #

OML includes a context-aware AI assistant that can help with config generation, protocol debugging, and topology design. It is aware of the current lab topology and can reference node names and link endpoints.

The assistant supports multiple backends — choose the one that fits your deployment.

Configure the AI backend #

Set one or more keys in /opt/OML/backend/.env (or Admin → Settings → AI):

# Cloud — fastest, best quality
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Local — air-gapped, no API cost
OLLAMA_BASE_URL=http://localhost:11434
# Optional: for Ollama Cloud instead of local
OLLAMA_API_KEY=

# LM Studio
LMSTUDIO_BASE_URL=http://localhost:1234/v1

Using the assistant #

• 1
  Open the assistant panel

  Click the AI button in the top-right of any lab view, or press ? while the canvas is focused.
• 2
  Ask a question

  The assistant has context about your lab topology. Examples:
  "Generate OSPF config for R1 and R2 connected on the R1-R2 link"
  "Why would BGP not come up between SW1 and FW1?"
  "Explain what this Wireshark output means"
• 3
  Paste config directly to console

  Click Copy on an AI-generated config block, switch to the console tab, and paste. The config is ready to run.

Export & Import Labs #

Labs can be exported as a JSON bundle and imported on any OML instance. Disk images are not bundled — the target OML must have the same images installed.

Export #

Open a lab → top-bar ⋮ menu → Export Lab. Downloads a .oml file containing: topology (nodes, links, positions), node metadata (names, vCPU, RAM, NIC count), and saved snapshots (optional, large).

Import #

Dashboard → Import Lab → drag the .oml file. OML validates that all required images exist. If an image is missing, it's highlighted in red — you must upload it before the lab can start.

Ansible export #

Generate an Ansible inventory + playbook skeleton from your topology. Enterprise

Top-bar ⋮ → Export as Ansible. Produces inventory.yml (all nodes with mgmt IPs) and a site.yml stub ready to run with ansible-playbook.

Troubleshooting #

Node stuck in "Starting" #

The most common cause is insufficient RAM or vCPU. Check server resources:

free -h && nproc
journalctl -u oml-backend -n 50 --no-pager

If the log shows qemu: cannot set up guest memory, reduce RAM on the node or stop other running nodes.

Console shows blank / no output #

Press Enter once — some images output nothing until you interact. If still blank after 30 seconds, check that the Telnet port is reachable from your browser:

telnet <oml-server-ip> <console-port>

"Failed to fetch" in browser #

Usually a CORS or DNS issue. Check that:

1. The OML backend is running: systemctl status oml-backend
2. The server URL resolves from the browser's DNS (not a private IP)
3. ALLOWED_ORIGINS in .env includes the frontend URL

Palo Alto stuck at boot #

PAN-OS boots slowly (8–12 min). If stuck past 15 min, check that OML_PANOS_ATTACH_BOOTSTRAP=true is set and the VM has at least 6144 MB RAM and 2 vCPUs.

Check backend logs #

# Live tail
journalctl -u oml-backend -f

# Last 100 lines
journalctl -u oml-backend -n 100 --no-pager

# QEMU process list
ps aux | grep qemu

FAQ #

Can OML run on a laptop? #

Yes, for small labs. Import the OVA into VMware Workstation (Windows/Linux) or VMware Fusion (Mac). A laptop with 16 GB RAM and 4+ cores can comfortably run 3–5 lightweight nodes (Cisco IOS, MikroTik). Assign at least 8 GB RAM and 4 vCPUs to the OML VM and enable CPU virtualization pass-through.

Does OML need internet access? #

No. After installation OML is fully air-gapped. The only optional internet calls are the AI assistant (if using a cloud backend like OpenAI/Anthropic) and license activation. Both can be disabled.

How many students can share one server? #

Depends on hardware. A typical 32-core / 128 GB server can support 20–30 students each running a 5-node lab simultaneously. Labs are isolated — students only see their own labs.

Can I share a lab with students? #

Instructors can clone a master lab to all students with one click: Lab menu → Clone to users. Each student gets their own isolated copy.

What happens when my license expires? #

OML drops back to Free tier (3 node limit). Existing labs are preserved and can still be opened — just limited. Renew from the same pricing page; the token email arrives in under a minute.

Is OML open source? #

The core network emulation engine is proprietary. The REST API is documented at /api/docs on your OML instance (Swagger UI).

How do I get support? #

Email hello@omllabs.com. Enterprise customers get priority response within 4 hours (business hours IST). Community support is also available via the forum link in the nav.