> For the complete documentation index, see [llms.txt](https://docs.vex-nx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vex-nx.com/images/import-images.md).

# Import images

Open **Images -> Import**.

Import has three supported paths:

| Path                  | Best for                                                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Convert & add**     | Virtual appliance disks (OVA, VMDK, VHD/VHDX, RAW/IMG, qcow2), Dynamips/IOL binaries, guided Windows/Linux ISO |
| **Upload ready disk** | Already-qcow2 (+ optional ISO) with no conversion                                                              |
| **Bulk import**       | Many folders already on the appliance after SCP                                                                |

**Virtual appliance vs hardware firmware:** VEX-NX converts vendor **virtual appliance** images to qcow2. Physical hardware packages (`.pkg`, `.pie`, `.rpm`, firmware `.tar`, Catalyst/Nexus/MX hardware `.bin`) **cannot** become QEMU VMs - download the vendor's virtual appliance (OVA/VMDK/qcow2) instead. Cisco Dynamips/IOL `.bin`/`.image` are a special copy-register path (not qemu-img convert).

Hard Disk 1 must have free space for large uploads and converts.

***

## Convert & add (recommended)

Default path for vendor appliance disks. VEX-NX runs shared **format pipelines** mapped to Catalog templates (not a separate converter script per product).

### Steps

1. Open **Images -> Import**.
2. Under **Convert & add**, tick the **legal acknowledgement** (you own licences for these files).
3. Click **Continue**, then choose a **platform / recipe** (search or "Show all recipes"). Featured recipes appear first; every qemu / Dynamips / IOL Catalog template has a recipe.
4. Confirm **Platform / template**, then **Continue**.
5. Choose files:
   * QEMU recipes: OVA/ZIP, VMDK, VHD/VHDX, RAW/IMG/VDI, qcow2, optional ISO
   * Dynamips/IOL recipes: `.bin` / `.image` (+ optional licence)
6. Optional: display name, version; for guided ISO, blank disk size in GB.
7. Click **Upload, convert & add**.
8. Watch **upload %** and **convert %** (phase label and ETA on long jobs).
9. When finished, the image is in **Library**. Click **Convert another** to repeat.

### Pipelines (what conversion does)

| Pipeline          | Input                                  | What VEX-NX does                                            |
| ----------------- | -------------------------------------- | ----------------------------------------------------------- |
| QEMU disk convert | OVA / ZIP, VMDK, VHD/VHDX, IMG/RAW/VDI | Unpack if needed -> `qemu-img convert` -> qcow2 -> register |
| QEMU ready        | Already qcow2 (+ optional ISO)         | Register (roles such as system / cdrom)                     |
| Dynamips          | `.bin` / `.image`                      | Copy-register (no qemu-img)                                 |
| IOL               | IOL binary (+ optional licence)        | Copy-register                                               |
| Guided ISO        | Windows / Linux install ISO            | Create blank qcow2 + attach ISO                             |

**Not convertible:** bare OVF/MF alone (upload OVA or companion VMDK/ZIP), hardware `.pkg`/`.pie`/`.rpm`/firmware tarballs, and QEMU-path hardware `.bin` (use Dynamips/IOL recipe only when the image is a Dynamips/IOL binary).

### Guided ISO (Windows / Linux)

1. Pick **Windows (guided ISO install)** or **Linux (guided ISO install)**.
2. Upload the install `.iso`.
3. VEX-NX creates a blank disk and attaches the ISO.
4. Place a Windows/Linux node in a lab, assign the image, **Start**, and finish the OS install in the **lab console** (VNC/serial).

This is **not** an unattended silent OS install.

### Dynamips / IOL

Pick a Dynamips or IOL recipe and upload `.bin` / `.image` (plus optional `iourc` / `.lic`). Files are **copy-registered**; they are not turned into qcow2. VEX-NX never ships IOL binaries or licences. IOL still needs a valid licence to boot: upload `iourc` with the binary, or place a shared file at `/opt/vex-nx/staging/iol/iourc` (hostname key must match `hostname`; value must match this host's Cisco hostid).

### Multi-node appliances

Some products need more than one disk/node (for example Juniper vMX VCP+VFP, vQFX RE+PFE, Cisco SD-WAN set). Convert & add registers **one** Library image per upload. Register each companion disk separately.

For **vMX** and **vQFX**, use Templates -> **Add pair** on the lab canvas to place both halves and an internal link on iface 0 (images are matched by role / folder name when present). You can still add a single node with **One** if needed.

***

## Upload ready disk <a href="#upload-ready-disk" id="upload-ready-disk"></a>

Use when you already have **qcow2** and do not need conversion.

1. Under **Upload ready disk (no convert)**, choose the disk file.
2. For Arista vEOS, also choose **Aboot / CDROM ISO** (`cdrom.iso`).
3. Select **Platform / template** (required).
4. Optional version and display name.
5. Tick legal acknowledgement -> **Upload**.

The image appears in **Library**.

### `virtioa.qcow2` / bus-matched disk names

Renaming a ready qcow2 to `virtioa.qcow2` (or `hda.qcow2` for IDE) tells VEX-NX which **disk bus** to use. That is **not** format conversion and **does not** make Junos/vJunos boot faster.

**Convert & add** uses the Catalog template bus and writes the matching stem into the Library (for example `virtioa.qcow2` under a **`vexnx-...` appliance folder**). Canonical Library folder names keep the `vexnx-` prefix.

On VEX-NX:

* Prefer **Upload ready disk** or Bulk import when the file is already qcow2 (not Convert & add), unless you need OVA/VMDK convert.
* Naming the file `virtioa.qcow2` (or using a template with `bus: virtio`, such as `vjunos-switch`) selects virtio attachment via bus heuristics.
* For **vjunos-switch** / **vjunos-router** / **vjunos-evolved**, VEX-NX uses a dedicated KVM launch profile (Start fails without `/dev/kvm`). Assign **8 vCPU / 8 GB** on the node; spare CPUs go to the inner VCP. Prefer bare-metal VEX-NX. After first boot use **Stop/Start**, not Wipe. See boot performance notes.
* **juniper-jspace** lab sizing is **4 vCPU / 16 GB** with virtio disk and VNC console.

***

## Bulk import

For folders already on the appliance (SCP/SFTP into staging), see [**Bulk folder import**](/images/bulk-folder-import.md).

Summary:

1. Transfer folders into `/opt/vex-nx/staging/qemu` (or dynamips / iol / ...).
2. **Images -> Import -> Bulk import** -> **Scan all folders**.
3. **Import selected** for ready qcow2 folders.
4. **Convert selected** for **Needs prepare** (VMDK/OVA), after choosing a platform - same convert jobs as Convert & add.

One child folder is fine; Bulk is not only for large batches.

***

## After import

1. Open **Library**, confirm the new row.
2. Set **Platform / template** mapping if needed, then save.
3. In a lab **Design** mode, place a matching template node and assign this image before **Start**.

For the product matrix (Serial vs VNC, Verified vs Experimental), see [Supported images](/images/supported-images.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vex-nx.com/images/import-images.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.