> 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/getting-started/install-the-ova.md).

# Install the OVA

![Install OVA path (diagram)](https://1807546539-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhgHCHWL3861o2DBW53aA%2Fuploads%2F8YZ6vrcdHrApLVTaO7Bv%2Fve20261112v5-diagram-install-ova.png?alt=media)

## Goal

Import `vex-nx-<version>.ova` into **VMware Workstation** or **ESXi / vSphere**, complete first boot, and reach the web login.

The OVA install is **automatic**. You do not manually create Hard Disk 2. After a correct import, Disk 1 + Disk 2 + the cidata CD are already part of the VM. The short checklist below only confirms ESXi (or Workstation) imported everything before the first power-on.

## What you need

| Item        | Detail                                                                                                            |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| File        | `vex-nx-<version>.ova` only (example: `vex-nx-2.0.0.ova`). Prefer the **single `.ova`**, not a partial OVF folder |
| Workstation | VMware Workstation **14+**                                                                                        |
| ESXi        | ESXi / vSphere **6.5+** (7/8 supported). **ESXi 6.0 is not supported**                                            |
| Nested virt | Required later for QEMU labs - see System requirements                                                            |
| Browser     | Current Chrome, Edge, or Firefox                                                                                  |

Day-1 credentials (forced password change):

| Access | User  | Password |
| ------ | ----- | -------- |
| Web UI | admin | vexnx    |
| SSH    | vexnx | vexnx    |

***

## Path A - VMware Workstation (step by step)

### A1. Prepare the Windows host

1. Confirm Workstation 14+ is installed.
2. For QEMU labs inside the appliance, turn **Hyper-V / hypervisorlaunchtype Off** on the Windows host and reboot (see System requirements).
3. Place the `.ova` on local disk with enough free space (OVA is tens of GB).

### A2. Import the OVA

1. Open **VMware Workstation**.
2. **File -> Open** (or **File -> Import**).
3. Select `vex-nx-<version>.ova`.
4. Accept the import wizard. Raise RAM/CPU now if you already know you need larger labs (defaults are the absolute minimum).

### A3. Confirm networks (do not reorder NICs)

Keep adapter order **1 / 2 / 3**:

| Adapter | Role                  | Typical VMnet    |
| ------- | --------------------- | ---------------- |
| 1       | Management (UI / LAN) | VMnet0 Bridged   |
| 2       | Internet (lab egress) | VMnet8 NAT       |
| 3       | Lab (isolated L2)     | VMnet1 Host-only |

If all three land on Bridged after import, open **VM Settings -> Network Adapter** and remap them to the VMnets above. Do not rename OVF networks in a way that breaks auto-map.

### A4. Before first power-on (required)

1. Power off if the wizard left the VM on.
2. **VM -> Settings -> Processors**:
   * Enable **Virtualize Intel VT-x/EPT or AMD-V/RVI**
   * Enable **Virtualize CPU performance counters**
3. Confirm hardware after a stock import:
   * **Hard Disk 1** \~**40 GB** (OS). Expanding Disk 1 after import for lab images (for example to 200-250 GB) is fine and expected for heavier labs.
   * **Hard Disk 2** \~**53 GB** (install payload, `LABEL=pram-payload`) - do not remove
   * **CD/DVD** cidata from this OVA, **Connected = ON** (Workstation may rename the ISO to the VM name)
   * **Three** network adapters (Management / Internet / Lab)
4. Optional but recommended for teaching labs: raise to **8+ vCPU** and **16+ GB RAM**, and grow Hard Disk 1 for images (see sizing table below).

### A5. First power-on

1. Power on the VM (**fresh import only** - do not reuse a disk from a previous failed first boot; delete the old VM and import again).
2. Open the **VGA console immediately**.
3. Within about **two minutes** you must see the **management network** menu on tty1 (before `VEX-NX login:`):
   * **1** = DHCP (default if you press nothing)
   * **2** = Static IP (no timeout while you type IP / mask / gateway / DNS)
4. After the menu, a branded splash may show install progress. Wait until the login prompt or MOTD shows an IP.
5. Console login remains **vexnx** / **vexnx** after the menu. Do **not** power off during first-boot install.

### A6. Open the UI

1. On your PC browser: `http://<management-ip>/` (prefer http; avoid `172.17.0.1` which is docker0).
2. Login **admin** / **vexnx** and set a new password when prompted.
3. Optional SSH: `ssh vexnx@<management-ip>` with password **vexnx**, then change when forced.
4. In the UI, open **Infrastructure** and confirm host pulse / KVM when you plan QEMU labs (`ls -l /dev/kvm` inside the guest).

***

## Path B - ESXi / vSphere (step by step)

### B1. Prepare the host

1. ESXi / vSphere **6.5+** with a local SSD/NVMe datastore preferred.
2. Create or choose **three port groups** (or reuse existing):
   * Management / VM Network (UI access)
   * Uplink / internet (lab NAT egress)
   * Isolated lab (Bridge cloud / L2)
3. Copy the **single** `vex-nx-<version>.ova` to a place the Host Client or vSphere Client can upload from.

### B2. Deploy from the OVA (correct procedure)

1. In **ESXi Host Client** or **vSphere Client**: **Create / Register VM** -> **Deploy a virtual machine from an OVF or OVA file**.
2. Select the **`.ova`** file (one file).\
   **Do not** deploy a half-copied OVF folder that is missing `*-disk2.vmdk` or `*-cidata.iso`.
3. Large OVA tip: browser upload of a \~50 GB file often fails with **"A required disk image was missing"**. Prefer:
   * Copy the `.ova` to a datastore with SCP/WinSCP, **or**
   * Deploy with **ovftool** from an admin workstation: `ovftool --acceptAllEulas --datastore=datastore1 --network=VLAN93 path\to\vex-nx-2.0.0.ova vi://user@esxi-host/`
4. Name the VM and pick the datastore.
5. Map networks during deploy (keep order):

| OVF / role | Guest NIC (typical) | Map to                  |
| ---------- | ------------------- | ----------------------- |
| Management | ens160              | Management / VM Network |
| Internet   | ens161              | Port group with uplink  |
| Lab        | ens192              | Isolated lab port group |

6. Finish the deploy wizard. **Do not power on yet.**

### B3. Mandatory check before first power-on

Open **Edit settings** and confirm all of the following:

| Item             | Required                                                          |
| ---------------- | ----------------------------------------------------------------- |
| Hard Disk 1      | Present (OS, \~40 GB capacity default; expanding for labs is OK)  |
| Hard Disk 2      | Present (install payload \~53 GB, `LABEL=pram-payload`)           |
| CD/DVD           | Present, **Connected = ON**, cidata ISO from this OVA             |
| Network adapters | Three, in Management / Internet / Lab order                       |
| Nested virt      | **Expose hardware assisted virtualization to the guest** = **ON** |

If you see only **one** hard disk, the import is incomplete. Delete that VM and redeploy from the full `.ova` (do not try to "build" Disk 2 by hand unless support walks you through it).

### B4. Size (optional before first labs)

OVA default is absolute minimum (**4 vCPU / 8 GB**). Raise before heavy QEMU / vJunos:

| Tier             | vCPU   | RAM        | Hard Disk 1 |
| ---------------- | ------ | ---------- | ----------- |
| Absolute minimum | 4      | 8 GB       | 40+ GB      |
| Recommended      | 8-16   | 16-32 GB   | 200-250 GB  |
| Advanced         | 16-32+ | 64-128+ GB | 500 GB-1 TB |

Hard Disk 1 grows for images and overlays. Hard Disk 2 is install payload only.

### B5. First power-on

1. Power on.
2. Open the **console immediately** (do not wait minutes).
3. Within about two minutes you should see the DHCP / Static management menu on tty1 **before** `VEX-NX login:`, then install progress, then hostname **VEX-NX**.
4. Note the management IP from the console MOTD (Management NIC, typically ens160).

### B6. Open the UI

Same as Workstation: `http://<management-ip>/` with **admin** / **vexnx**, SSH **vexnx** / **vexnx**.

***

## Sizing cheat sheet (both hypervisors)

See also System requirements and Sizing and upgrades.

***

## Expected result

* Console hostname **VEX-NX** (not `vex-nx-bake`)
* Browser reaches `http://<management-ip>/`
* First login forces a password change
* Offline Docker seeds for FRR / Alpine load in the background on current media
* For QEMU labs: `/dev/kvm` exists when nested virt is enabled

***

## If it fails

| Symptom                                                      | What it usually means                                            | What to do                                                                                                                                                                                       |
| ------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **"A required disk image was missing"** (ESXi deploy wizard) | Incomplete Host Client upload / truncated OVA                    | Cancel; redeploy the full single `.ova` via ovftool or datastore copy - do not use a partial OVF folder                                                                                          |
| Console `vex-nx-bake login:`                                 | cidata CD did not apply                                          | Power off; set CD/DVD to the OVA cidata ISO, **Connected = ON**; confirm Hard Disk 2; power on. If still stuck: with CD connected, `sudo cloud-init clean --logs` and reboot once                |
| `VEX-NX login:` but **no** DHCP/Static menu                  | cidata CD not connected, or first-boot net unit did not own tty1 | Power off; confirm **two** hard disks + cidata **Connected = ON**; power on and watch console from the first seconds. Prefer redeploy from the republished `.ova` if media predates the tty1 fix |
| Console shows **Hard Disk 2 missing** banner                 | Payload not found after SCSI wait                                | Attach Disk 2 / redeploy full `.ova`                                                                                                                                                             |
| `payload disk not found` / `payload missing`                 | Same as above - Disk 2                                           | Attach Disk 2 from this OVA version, or redeploy                                                                                                                                                 |
| Only one hard disk in Edit settings                          | Incomplete import                                                | Redeploy from the single `.ova`                                                                                                                                                                  |
| Console `Login incorrect` for `vexnx`                        | Wrong password, or password already changed / expired            | Prefer browser **admin** / **vexnx**; console first login is `vexnx` / `vexnx` then forced change                                                                                                |
| No UI IP                                                     | Wrong Management port group / no DHCP / wrong NIC                | Check Management mapping; on console `ip a` on ens160                                                                                                                                            |
| No `/dev/kvm` / QEMU Start fails                             | Nested virt off                                                  | Enable expose VT-x; power cycle VM; on Windows host ensure Hyper-V is off for Workstation                                                                                                        |
| Cannot reach web                                             | Firewall / wrong IP / using docker0                              | Use management IP; allow browser; avoid `172.17.0.1`                                                                                                                                             |
| FRR Start needs pull                                         | Seed still loading or DNS                                        | Wait; or `sudo vexnx-seed-docker`; fix DNS under Infrastructure -> Management network                                                                                                            |

### Field recovery (ESXi) - short form

1. Power off.
2. Edit settings: **Disk1 + Disk2 + cidata Connected**.
3. Nested virt ON.
4. Power on and watch the console from the first seconds.
5. If hardware was wrong, prefer **redeploy** over hand-editing disks.

***

## What users do *not* need to do (normal path)

* Manually create Hard Disk 2
* Manually invent a cidata ISO
* Use a partial OVF folder when the `.ova` is available

Those steps appear only when **import already failed**.

***

## Next

* [First login](/getting-started/first-login.md)
* [Management network](/getting-started/management-network.md)
* [Networks and clouds](/getting-started/networks-and-clouds.md)
* [First lab walkthrough](/labs/first-lab-walkthrough.md)
* Troubleshooting


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.vex-nx.com/getting-started/install-the-ova.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.