Skip to main content

Proxmox

This guide walks you through installing Barbara OS on a KVM virtual machine managed by Proxmox VE. Barbara ships two different ISO images for virtualized environments, and the one you pick determines the firmware your VM must use:

  • kvm_amd64_bios-pro-*.iso → the VM must boot in BIOS (SeaBIOS) mode.
  • kvm_amd64-pro-*.iso → the VM must boot in UEFI (OVMF) mode.

This page covers the BIOS variant. The UEFI procedure is documented further below (coming soon).

Pre-requisites​

  1. A working Proxmox VE cluster or standalone node, with administrative access to the web UI.
  2. The Barbara OS ISO image corresponding to your chosen firmware, downloaded from your Barbara Panel and uploaded to a Proxmox storage that accepts ISO images (typically the local storage, under ISO Images).
  3. A Proxmox storage backend available for the VM disk (for example local-lvm).

General Hardware Requirements​

Strict minimum​

  • RAM: 1024 MB
  • Hard Drive: 32 GB
  • Processor: 1 socket / 2 cores
  • Network: 1 × Ethernet interface
  • RAM: 2048 MB
  • Hard Drive: 32 GB
  • Processor: 1 socket / 2 cores
  • Network: 1 × Ethernet interface
  • RAM: 4096 MB
  • Hard Drive: 64 GB
  • Processor: 2 sockets / 2 cores
  • Network: 2 × Ethernet interfaces
note

CPU and RAM values below are orientative and can be adapted to the workload you plan to run on the node. Do not go below the strict minimum of 1024 MB of RAM, or Barbara OS will not boot reliably.

Creating the Virtual Machine (BIOS)​

From the Proxmox VE web UI, click Create VM in the top-right corner and walk through the wizard as described below.

1. General​

Pick the Proxmox node that will host the VM, assign a free VM ID and give the machine a descriptive Name (for example kvm-bios). Leave Add to HA unchecked unless you want the VM to be managed by the Proxmox HA manager.

2. OS​

Select Use CD/DVD disc image file (ISO) and pick the Barbara ISO you previously uploaded. For the BIOS path this is the kvm_amd64_bios-pro-*.iso file (do not select the kvm_amd64-pro-*.iso image, which is intended for UEFI).

Set Guest OS Type to Linux and Version to 6.x - 2.6 Kernel.

warning

Make sure the ISO name includes _bios. Booting the BIOS image under UEFI (or the UEFI image under SeaBIOS) will leave the VM stuck at boot.

3. System​

Configure the virtual hardware as follows:

  • Graphic card: Default
  • Machine: q35
  • BIOS: Default (SeaBIOS)
  • SCSI Controller: VirtIO SCSI single
  • Qemu Agent: enabled
  • Add TPM: disabled

4. Disks​

Keep the default scsi0 disk and configure it as:

  • Bus/Device: SCSI 0
  • SCSI Controller: VirtIO SCSI single (inherited from the previous step)
  • Storage: a local storage available on the node, for example local-lvm
  • Disk size (GiB): 32
  • IO thread: enabled
  • Cache: Default (No cache)

5. CPU​

Assign the CPU resources the node will need. A reasonable starting point is:

  • Sockets: 1
  • Cores: 2
  • Type: x86-64-v2-AES
tip

The x86-64-v2-AES CPU type is a good default for modern Intel/AMD hosts: it exposes AES-NI to the guest (useful for Barbara's cryptographic workloads) while remaining compatible with live-migration between heterogeneous hosts. If your cluster is fully homogeneous, host will give you the best performance.

6. Memory​

Set the VM memory to at least 2048 MiB. For production workloads we recommend 4096 MiB or more, depending on the apps and models you plan to deploy on the node.

7. Network​

Select the Proxmox bridge that provides connectivity to the network where your Barbara Panel is reachable (typically vmbr0). The VirtIO paravirtualized model is a good default.

8. Confirm​

Review the summary and click Finish. Do not tick Start after created yet — we want to review the VM configuration before the first boot.

Creating the Virtual Machine (UEFI)​

If you prefer (or require) UEFI boot, walk through the same wizard as above and change only the steps described below. Everything not mentioned here (General, CPU, Memory, Network, Confirm) is identical to the BIOS variant.

OS​

Select the kvm_amd64-pro-*.iso image (without the _bios suffix). This is the image built to boot through OVMF.

Keep Guest OS Type as Linux and Version as 6.x - 2.6 Kernel.

System​

Configure the virtual hardware as follows:

  • Graphic card: Default
  • Machine: q35
  • BIOS: OVMF (UEFI)
  • Add EFI Disk: enabled
  • EFI Storage: a local storage available on the node, for example local-lvm
  • Format: Raw disk image (inherited from the chosen storage)
  • Pre-Enroll keys: disabled
  • SCSI Controller: VirtIO SCSI single
  • Qemu Agent: enabled
  • Add TPM: disabled
warning

Leave Pre-Enroll keys unchecked. Enrolling the Microsoft Secure Boot keys will cause Barbara OS to be rejected at boot, because its bootloader is not signed against those keys. Barbara OS is designed to boot with Secure Boot disabled.

Disks​

In the UEFI variant we recommend using the VirtIO Block bus directly instead of SCSI, which matches how the kvm_amd64 image is built:

  • Bus/Device: VirtIO Block 0
  • Storage: local-lvm (or the storage you prefer)
  • Disk size (GiB): 32
  • IO thread: enabled
  • Cache: Default (No cache)

The primary disk will appear as virtio0 in the summary, alongside the EFI disk you added in the System tab.

First boot​

  1. Select the newly created VM in the Proxmox sidebar and click Start.
  2. Open the Console tab to watch the boot process. Barbara OS will install itself to the virtual disk on first boot.
  3. When the installation finishes, the console stays idle waiting for you to reboot the VM manually. Before doing so, detach the ISO from the virtual CD/DVD drive in Hardware → CD/DVD Drive → Edit → Do not use any media, so that the next boot comes from the internal disk and not from the installer.
  4. Reboot the VM from More → Reboot (or power it off and start it again). Barbara OS will now come up from the internal disk.

Next steps​

After Barbara OS is up and running, locate the Barbara ID of your new node and register it against your Barbara Panel: