Setup Guide

CICADA IR is distributed as a virtual machine image compatible with all major hypervisors. This guide covers deployment on VMware, VirtualBox, Hyper-V, and Proxmox.

Image formats

If you need a format not listed, you can convert between formats using qemu-img:

# QCOW2 to VMDK (for VMware)
qemu-img convert -f qcow2 -O vmdk cicada-ir-latest.qcow2 cicada-ir-latest.vmdk

# QCOW2 to VHDX (for Hyper-V)
qemu-img convert -f qcow2 -O vhdx cicada-ir-latest.qcow2 cicada-ir-latest.vhdx

VMware ESXi

Import via vSphere Client

1. Log in to your vSphere Client
2. Right-click your target host or cluster and select Deploy OVF Template
3. Select Local file and browse to the OVA file
4. Follow the wizard:
   • Name: cicada-ir (or your preferred name)
   • Storage: Select the appropriate datastore (minimum 40 GB free)
   • Network: Select the management network the VM should use
5. Review settings and click Finish
6. Edit the VM settings to adjust CPU/RAM (recommended: 4 vCPUs, 8 GB RAM)
7. Power on the VM

VMware Workstation

1. Open VMware Workstation
2. Go to File > Open and select the .ova file
3. Choose an import location and click Import
4. Adjust hardware settings if needed (right-click VM > Settings)
5. Start the VM

VirtualBox

Import via GUI

1. Open VirtualBox Manager
2. Go to File > Import Appliance
3. Browse to the OVA file and click Next
4. Review appliance settings:
   • Adjust CPU and RAM if needed (recommended: 4 CPUs, 8192 MB)
   • Set Network Adapter to Bridged Adapter for direct network access, or NAT if you want the VM behind the host's network
5. Click Import
6. Start the VM

Import via CLI

# Import the OVA
VBoxManage import cicada-ir-latest.ova --vsys 0 --vmname "cicada-ir"

# Optionally adjust resources
VBoxManage modifyvm "cicada-ir" --memory 8192 --cpus 4

# Set network to bridged (replace en0 with your interface)
VBoxManage modifyvm "cicada-ir" --nic1 bridged --bridgeadapter1 en0

# Start the VM
VBoxManage startvm "cicada-ir" --type headless

Hyper-V

Import via Hyper-V Manager

1. Open Hyper-V Manager
2. Click Action > New > Virtual Machine
3. Follow the wizard:
   • Name: cicada-ir
   • Generation: Generation 2 (UEFI)
   • Memory: 8192 MB (minimum 4096 MB)
   • Network: Select your management virtual switch
   • Virtual Hard Disk: Select Use an existing virtual hard disk and browse to the .vhdx file
4. Before starting, go to VM Settings:
   • Security: Disable Secure Boot (or set to Microsoft UEFI Certificate Authority template)
   • Processor: Set to 4 virtual processors
5. Start the VM

Import via PowerShell

# Create a new VM using the existing disk
New-VM -Name "cicada-ir" `
  -MemoryStartupBytes 8GB `
  -VHDPath "C:\VMs\cicada-ir-latest.vhdx" `
  -Generation 2 `
  -SwitchName "Default Switch"

# Configure CPU
Set-VMProcessor -VMName "cicada-ir" -Count 4

# Disable Secure Boot for Linux
Set-VMFirmware -VMName "cicada-ir" -EnableSecureBoot Off

# Start the VM
Start-VM -Name "cicada-ir"

# Get the VM's IP address
Get-VMNetworkAdapter -VMName "cicada-ir" | Select IPAddresses

Proxmox VE

Import via Web UI

Upload the QCOW2 file to your Proxmox storage:

# From the Proxmox host shell
scp cicada-ir-latest.qcow2 root@proxmox:/var/lib/vz/images/

Create a new VM in the Proxmox web UI:

• General: Name it cicada-ir, set VM ID
• OS: Select Do not use any media (we will import the disk)
• System: BIOS: OVMF (UEFI), Machine: q35
• Disks: Delete the default disk (we will import)
• CPU: 4 cores
• Memory: 8192 MB
• Network: Select your bridge (e.g., vmbr0)

Import the disk:

# Import the QCOW2 as the VM's primary disk (replace 100 with your VM ID)
qm importdisk 100 /var/lib/vz/images/cicada-ir-latest.qcow2 local-lvm

# Attach the imported disk
qm set 100 --scsi0 local-lvm:vm-100-disk-0
qm set 100 --boot order=scsi0

Start the VM from the web UI.

Import via CLI

# Create the VM
qm create 100 --name cicada-ir --memory 8192 --cores 4 --net0 virtio,bridge=vmbr0

# Import disk
qm importdisk 100 cicada-ir-latest.qcow2 local-lvm

# Configure boot disk
qm set 100 --scsi0 local-lvm:vm-100-disk-0
qm set 100 --boot order=scsi0
qm set 100 --scsihw virtio-scsi-single

# Start
qm start 100

Post-deployment steps

After deploying on any platform:

1. Find the IP address — Log in to the VM console with the cicada-admin user and run ip addr show
2. Access the web UI — Open https://<vm-ip> in your browser
3. Activate your license — See Getting Started
4. Replace the TLS certificate — For production deployments, replace the self-signed certificate (see TLS setup)
5. Configure firewall rules — Whitelist the FQDNs listed in Network Requirements
6. Set a static IP — For production, configure a static IP via netplan

Static IP configuration example:

sudo nano /etc/netplan/01-netcfg.yaml

network:
  version: 2
  ethernets:
    ens18:
      addresses:
        - 192.168.1.100/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

sudo netplan apply

Resource tuning