|
Field |
Details |
|
Product Version |
CommBox EdgeOS 8.1.x (latest from CommBox Edge Cloud Portal) |
|
Platform |
VMware ESXi 7.x / 8.x |
|
Document Date |
April 2026 |
Overview
This guide walks through installing the CommBox Edge VX virtual appliance on VMware ESXi using the OVA file downloaded from the CommBox Edge Cloud Portal portal. The OVA (Open Virtual Appliance) format bundles the VMDK disk image, OVF descriptor, and manifest into a single archive, which ESXi can deploy natively through its Deploy OVF Template wizard. The process involves seven main phases:
|
Phase |
Description |
|
Phase 1 |
Pre-configure Port Groups on ESXi (WAN, LAN, Management) |
|
Phase 2 |
Download the OVA file from the CommBox Edge Cloud Portal portal |
|
Phase 3 |
Deploy the OVA using ESXi Deploy OVF Template wizard |
|
Phase 4 |
Review and finalise VM hardware settings |
|
Phase 5 |
Power on the VM and open the console |
|
Phase 6 |
VM Console — Assign Network Interfaces |
|
Phase 7 |
VX System Registration |
Prerequisites
System Requirements
|
Requirement |
Details |
|
Hypervisor |
VMware ESXi 7.x or 8.x (with access to the ESXi web UI or vSphere Client) |
|
vCPUs |
4 cores minimum (as specified by KVH KB) |
|
RAM |
16 GB minimum (as specified by KVH KB) |
|
Disk |
120 GB — provided by the OVA image. Do not resize. |
|
Network |
3 port groups required: WAN, LAN, Management |
|
Internet |
Required through the WAN port group for VX registration |
Access Requirements
|
Requirement |
Details |
|
KVH Portal |
Valid login at http://cloud.kognitive.net with software download access |
|
ESXi Host |
Root or administrator access to the ESXi web UI |
|
CommBox Edge Cloud Portal |
Account registered with an available, unallocated VX Device ID (DID) |
|
⚠️ Important — Do Not Resize the OVA Disk The OVA contains a pre-configured disk image whose filesystem size is fixed. Do not attempt to resize or expand the disk image before or after deployment — this will corrupt the CommBox EdgeOS filesystem. |
Phase 1 — Pre-configure Port Groups on ESXi
Before deploying the OVA, the required virtual networks must exist on the ESXi host so they can be mapped during the OVF deployment wizard. Three port groups are needed: WAN, LAN, and Management. The LAN port group requires special security settings to allow VX LAN services to function correctly.
|
1 |
Log in to the ESXi Web UI Open a browser and navigate to https://<esxi-host-ip>. Log in with root or administrator credentials. In the left sidebar, navigate to Networking → Port Groups. |
|
2 |
Create the WAN Port Group Click Add port group. Configure as follows:
Click Add. |
|
3 |
Create the Management Port Group Click Add port group. Configure as follows:
Click Add. |
|
4 |
Create the LAN Port Group — with Promiscuous Mode and Forged Transmits Click Add port group. Configure as follows:
Click Add. Then click the Edit pencil icon on the VX-LAN port group. Under Security, set:
Click Save. |
|
⚠️ LAN Port Group — Security Settings Are Mandatory Promiscuous Mode and Forged Transmits must be set to Accept on the VX-LAN port group. This is explicitly required by the KVH KB for the LAN interface. Without these settings, downstream LAN clients will not receive DHCP or network services from the VX. |
Phase 2 — Download the OVA File
The OVA file is downloaded from the CommBox Edge Cloud Portal portal. For ESXi deployments, select the OVA format from the Virtual EOS section.
|
5 |
Log in to the CommBox Edge Cloud Portal Portal Open a browser and navigate to http://cloud.kognitive.net . Log in with your KVH account credentials. |
|
6 |
Navigate to Software Downloads In the left sidebar, click S/W Configuration. Click the Current EOS tab. |
|
7 |
Download the OVA File In the Virtual EOS section, locate the latest version and click the Download link in the OVA column. The file will be named in the format:
The download is a gzip-compressed OVA archive, approximately 4 GB. Save it to a local machine or a location accessible to the ESXi host. |
|
📋 Tip — OVA Format for ESXi The OVA format is a TAR archive containing the VMDK disk, OVF descriptor, and MF manifest. VMware ESXi natively supports OVA deployment via the Deploy OVF Template wizard, making it the simplest installation method — no manual disk conversion or import commands required. Three download formats are available: VMDK, QCOW2, and OVA. This guide uses the OVA format. |
Phase 3 — Deploy the OVA using ESXi Deploy OVF Template
The ESXi web UI includes a built-in Deploy OVF Template wizard that handles the OVA extraction, VM creation, disk attachment, and network mapping in a single workflow. This is the recommended approach for ESXi OVA deployments.
|
8 |
Decompress the OVA Archive Before uploading to ESXi, decompress the .gz file to get the .ova file. Run the following on your local machine:
This produces the .ova file, which is the file you will upload to ESXi in the next step. |
|
9 |
Launch the Deploy OVF Template Wizard In the ESXi web UI, click on your host in the left sidebar. Then click Actions → Deploy OVF Template. The deployment wizard opens. |
|
10 |
Select the OVA File On the Select an OVF template screen, choose Local file. Click Choose Files and select the decompressed .ova file from your local machine. Click Next. |
|
11 |
Set VM Name and Folder Enter a name for the virtual machine (e.g., Edge-VX). Select the folder or host location. Click Next. |
|
12 |
Select the Datastore Choose the datastore where the VM disk will be stored. Ensure the datastore has at least 120 GB of free space. Click Next. |
|
13 |
Select Deployment Options On the Deployment options screen, configure:
Click Next. |
|
14 |
Map OVA Networks to ESXi Port Groups This is the critical step. The OVA defines networks internally (e.g., Network 1, Network 2, Network 3). Map each one to the correct ESXi port group you created in Phase 1:
Important: Set all network adapters to VX-WAN at this stage. This ensures the VM can reach the internet for registration. You will reassign adapters to their correct port groups (MGMT, LAN) after registration is complete. Click Next. |
|
15 |
Review and Finish Deployment Review the configuration summary on the final screen. Verify:
Click Finish. ESXi will upload and extract the OVA, create the VM, and import the disk. This may take several minutes depending on file size and network speed. |
|
✅ Checkpoint — OVA Deployed Successfully Once finished, the VM (e.g., Edge-VX) will appear in the ESXi inventory with the disk already attached and configured. The "Recent Tasks" pane will show "Deploy OVF Template: OK". Do not start the VM yet — complete Phase 4 first to verify hardware settings. |
Phase 4 — Review and Finalise VM Hardware Settings
After OVA deployment, verify that the VM hardware settings match the requirements specified in the KVH KB before powering on.
|
16 |
Open the VM Hardware Settings Click on the newly created VM in the ESXi inventory. Click Edit settings (or Actions → Edit Settings). Verify and adjust the following:
If CPU or Memory was not set correctly by the OVA defaults, adjust them now. Click Save. |
|
📋 Note — Network Adapters After Registration All four adapters are set to VX-WAN now to allow internet access for registration. After Phase 7 registration is complete, you must update the adapter assignments to match the interface roles assigned in Phase 6:
|
Phase 5 — Power On the VM and Open the Console
|
17 |
Power On the Virtual Machine Select the Edge-VX VM in the inventory. Click Power On. The VM status changes to Running. |
|
18 |
Open the Console Click Console in the VM toolbar, then select Open browser console (or Launch Remote Console if using vSphere client). The KVH CommBox EdgeOS terminal UI will appear after approximately 30–60 seconds of boot time. You will briefly see: System not ready, please wait before the CommBox EdgeOS dashboard appears. |
|
✅ VM Running — CommBox EdgeOS Console Ready At this point the VX VM is running with CommBox EdgeOS loaded. The console shows the CommBox EdgeOS version, system status, management URL, and the main terminal menu options. Phases 6 and 7 are performed entirely within the VM console. |
Phase 6 — VM Console: Assign Network Interfaces
After the VM boots, the initial personalization must be done from the VM console. This assigns each virtual network adapter to its role: Management, WAN, or LAN. These roles cannot be changed after provisioning without a full network reset.
|
19 |
Log in to the VM Console When the CommBox EdgeOS terminal UI appears, log in with the default VX credentials:
|
|
20 |
Launch the Setup Wizard From the terminal menu, select Setup Wizard (recommended) or Assign Network Interfaces (manual). Both paths lead to the same interface assignment screens. |
|
21 |
Assign the Management Interface The console lists the available virtual NICs (e.g., eth0, eth1, eth2, eth3). Select exactly one as the Management Interface. This provides out-of-band access to the CommBox EdgeOS web portal. The management IP defaults to DHCP; static IP can be configured optionally. |
|
22 |
Assign WAN Interface(s) Select one or more interfaces as WAN. At minimum, one WAN interface must have active internet connectivity for registration to succeed. Multiple WAN interfaces may be selected for SD-WAN bonding. |
|
23 |
Assign LAN Interface(s) and Edit Labels Select the remaining interface(s) as LAN. After all roles are assigned, the console presents the Edit Interface Labels screen. Labels must use alphanumeric characters only, with no spaces and no duplicates (e.g., WAN1, LAN1, MGMT). Update if needed and select OK. The system will reboot automatically to apply the interface configuration. |
|
⚠️ Interface Assignment is Permanent Interface roles (Management / WAN / LAN) cannot be changed once the VM is provisioned. Any role change requires a full reset of the network configuration and a repeat of this personalization process. After Phase 7 registration is complete, remember to update the ESXi VM network adapter assignments to match the roles assigned here: Management adapter → VX-MGMT, LAN adapter(s) → VX-LAN. Never clone a provisioned VX VM. Cloning a provisioned instance disables both the original and the clone. |
Phase 7 — VX System Registration
Registration binds this specific VM instance to a Device ID (DID) in the CommBox Edge Cloud Portal, bringing the VX fully online. The VM must have active internet access through its WAN interface before proceeding.
|
24 |
Verify Internet Connectivity — Ping Test After the reboot following interface assignment, log in again (configure/configure) and select Ping Host from the menu. Enter 8.8.8.8 as the target. Confirm ping replies are received before proceeding. If the ping fails, check that the WAN adapter is connected to the VX-WAN port group and the uplink has internet access. |
|
25 |
Register — Method A: SPORT Login (Recommended) Select Register System using SPORT Login from the console menu. Enter your CommBox Edge Cloud Portal credentials (email and password). The console retrieves all sites and Device IDs in your account. Select the Site / Device Name / Device ID to assign to this VM. A ‘*’ next to a DID indicates it is already allocated — select an unallocated DID. Confirm with Yes. |
|
26 |
Register — Method B: Token from CommBox Edge Cloud Portal Alternatively, generate a token from the CommBox Edge Cloud Portal: navigate to Sites → select your Site → Device Details → Generate Token icon next to the DID. The token is displayed and copied to the clipboard. In the VM console, select Register System with Token from SPORT, enter the token, confirm the displayed DID, and select Yes. |
|
27 |
Wait for Initialization to Complete After confirming registration the console displays:
The VM will reboot multiple times during this initialization period. When the console prompts for login, enter the credentials and continue — this is expected behaviour. Do not interrupt or power off the VM during this phase. |
|
28 |
Update ESXi Network Adapter Assignments Once the system is online, update the VM network adapters in ESXi to reflect the roles assigned in Phase 6. In the ESXi web UI, go to VM → Edit Settings → Network Adapters and reassign:
Click Save. |
|
✅ Registration Complete — VX System Online Once initialization is complete, the VX system is fully online and accessible via:
|
Troubleshooting
|
Problem |
Resolution |
|
Deploy OVF Template fails or times out |
Check that the .ova file is fully decompressed (no .gz extension). Ensure the datastore has 120+ GB free. Try uploading via SCP to the datastore and using a local file path. |
|
VM does not boot after deployment |
Verify the disk attached from the OVA is set as the boot disk. Check VM Settings → Boot Options to confirm the correct disk is first in boot order. |
|
Console is blank after power on |
Wait 60 seconds — CommBox EdgeOS takes time to initialise. Click inside the console window to refresh. Ensure CPU and memory meet the 4 vCPU / 16 GB requirements. |
|
Ping to 8.8.8.8 fails after interface assignment |
Verify the WAN adapter is connected to the VX-WAN port group in ESXi VM settings. Check that the VX-WAN port group uplink has internet access. |
|
LAN clients not receiving DHCP |
Confirm Promiscuous Mode and Forged Transmits are set to Accept on the VX-LAN port group security settings. This is mandatory per the KVH KB. |
|
Registration fails (credentials not accepted) |
Ensure the WAN interface has internet access (ping test first). Verify CommBox Edge Cloud Portal credentials and that an unallocated VX DID is available in the account. |
|
Device not visible in CommBox Edge Cloud Portal after registration |
Wait the full 10–15 minutes for initialization. Do not power off during reboots. Log back in to http://cloud.kognitive.net and check Inventory → Deployed tab. |
Installation Summary
The following table summarises all steps performed during the installation.
|
Step |
Action |
Details |
|
1 |
Create WAN Port Group |
ESXi Networking → VX-WAN |
|
2 |
Create Management Port Group |
ESXi Networking → VX-MGMT |
|
3 |
Create LAN Port Group |
ESXi Networking → VX-LAN — Promiscuous Mode + Forged Transmits: Accept |
|
4 |
Portal Login |
http://cloud.kognitive.net → S/W Configuration → Current EOS |
|
5 |
Download OVA |
Virtual EOS section → OVA column → vx-blank-v8.x.x.xx.ova.gz |
|
6 |
Decompress OVA |
gunzip vx-blank-v8.x.x.xx.ova.gz |
|
7 |
Deploy OVF Template |
ESXi → Actions → Deploy OVF Template → select .ova file |
|
8 |
Map Networks |
All 4 adapters → VX-WAN during wizard |
|
9 |
Select Datastore & Thin Disk |
Choose datastore with 120+ GB free, thin provisioned |
|
10 |
Review VM Settings |
4 vCPU, 16 GB RAM, OVA disk attached, all NICs on VX-WAN |
|
11 |
Power On VM |
Start VM → Open browser console |
|
12 |
Console Login |
configure / configure |
|
13 |
Assign Interfaces |
Setup Wizard → Management (1), WAN (1+), LAN (1+), edit labels |
|
14 |
Ping Test |
Ping Host → 8.8.8.8 → confirm replies |
|
15 |
Register VX System |
SPORT Login or Token method → select DID → confirm |
|
16 |
Wait for Initialization |
10–15 min, multiple reboots — do not interrupt |
|
17 |
Update ESXi NIC Assignments |
Mgmt adapter → VX-MGMT • LAN adapter(s) → VX-LAN |
|
18 |
Verify System Online |
CommBox EdgeOS Portal: http://[Mgmt_IP] • CommBox Edge Cloud Portal: Sites → Topology |