Platform Reference¶

OSImager supports 11 platforms through Packer builder plugins. Each platform is defined by a JSON configuration file in the data package's platforms/ directory (osimager/data/platforms/, or a ~/.config/osimager/platforms/ override) that specifies the Packer builder type, hardware defaults, credential requirements, and template variables.

Overview¶

Platforms fall into four categories based on how they build images:

Category	Platforms	Boot Method	Where It Builds
Local ISO	virtualbox, vmware, qemu, hyperv, xenserver	Boots from ISO	Local workstation
Enterprise ISO	vsphere, proxmox	Boots from ISO	Remote hypervisor
Cloud	azure, gcp, aws	Marketplace image (no ISO)	Cloud provider
Special	none	N/A	Provisioning only

Local ISO platforms boot a VM from an ISO on the local machine, run the installer via boot commands, then provision over SSH/WinRM. The built VM stays registered on the local hypervisor.

Enterprise ISO platforms boot a VM from an ISO on a remote hypervisor (vCenter/ESXi or Proxmox VE), run the same installer flow, and store the resulting VM or template on the remote infrastructure. They require platform credentials (server, username, password) stored in your secrets or Vault.

Cloud platforms do not use ISOs or boot commands. They launch a marketplace base image, provision it over SSH (optionally through a bastion host on Azure and GCP), then capture the result as a managed image or AMI. They require cloud provider credentials (service principal, access keys, etc.).

Special -- the none platform uses Packer's null builder. It does not create a VM at all. It exists for running provisioners against an existing host.

Base Defaults (Configuration Defaults)¶

Every platform (except none) inherits baseline hardware defaults from the user's configuration file (~/.config/osimager/config.json), with built-in fallbacks in core.py:

Default	Value	Description
`cpu_sockets`	`1`	Number of CPU sockets
`cpu_cores`	`2`	Number of cores per socket
`memory`	`2048`	Memory in MB
`boot_disk_size`	`16384`	Boot disk size in MB (16 GB)

These can be overridden at any layer: platform JSON, location defs, spec defs, or CLI --define.

Template Variable Syntax¶

Platform JSON files use OSImager's template engine markers. The most common patterns found in platform configs:

Marker	Type	Example	Description
`>>var<<`	String substitution	`>>name<<`	Replaced with the value of `var` from defs
`#>expr<#`	Numeric expression	`#>cpu_sockets*cpu_cores<#`	Evaluates arithmetic on defs values, returns int
`%>var<%`	Value replacement	`%>cd_files<%`	Replaced with raw value (preserves type: list, bool, etc.)
`E>expr<E`	Python eval	`E>'text' if >>cond<< else 'other'<E`	Evaluates a Python expression after `>>var<<` substitution

See the Template Engine documentation for the complete reference.

Local ISO Platforms¶

Local ISO platforms run a hypervisor on the build machine, boot a VM from an ISO, and use Packer boot commands to drive the unattended installer. They define local: true in defs and store built VMs under >>vms_path<</<platform>/>>name<<.

Common Traits¶

All local ISO platforms share these characteristics:

Inherits: Configuration defaults (base hardware defaults)
Defs: local: true
Boot method: ISO boot with boot_command from spec
Credentials: No platform credentials required (only images/<os> for SSH/WinRM)
Location defs needed: vms_path
ISO handling: Conditional expression selects local path or download URL based on local_only

The common ISO URL pattern used across local platforms:

"iso_url": "E>'>>iso_path<</>>iso_name<<' if >>local_only<< else '>>iso_url<<'<E"

This evaluates to the local ISO path when local_only is true, or the remote download URL otherwise.

VirtualBox¶


Platform file	`platforms/virtualbox.json`
Packer builder type	`virtualbox-iso`
Packer plugin	`github.com/hashicorp/virtualbox`
Platform type	Local ISO
Architectures	i386, x86_64, aarch64

Defs¶

Def	Value	Description
`local`	`true`	Marks this as a local platform

Plus inherited from configuration defaults: cpu_sockets, cpu_cores, memory, boot_disk_size.

Config Keys¶

Key	Value	Description
`type`	`virtualbox-iso`	Packer builder type
`vm_name`	`>>name<<`	VM name from build spec
`output_directory`	`>>vms_path<</vbox/>>name<<`	Output path for VM files
`headless`	`true`	Run without GUI
`skip_export`	`true`	Do not export to OVA
`keep_registered`	`true`	Keep VM in VirtualBox after build
`disable_shutdown`	`false`	Allow graceful shutdown
`guest_additions_mode`	`disable`	Do not install guest additions
`cpus`	`#>cpu_sockets*cpu_cores<#`	Total vCPU count
`memory`	`#>memory<#`	Memory in MB
`firmware`	`>>firmware<<`	BIOS or EFI
`gfx_controller`	`vmsvga`	Graphics controller type
`gfx_vram_size`	`32`	Video memory in MB
`usb`	`true`	Enable USB controller
`iso_url`	(conditional expression)	ISO source path or URL
`iso_checksum`	(conditional expression)	ISO checksum or `none`
`iso_target_path`	(conditional expression)	Local download target
`cd_files`	`%>cd_files<%`	Files to include on CD
`cd_label`	`>>cd_label<<`	CD volume label
`hard_drive_discard`	`true`	Enable TRIM/discard
`hard_drive_nonrotational`	`true`	Advertise as SSD
`hard_drive_interface`	`virtio`	Disk bus type
`disk_size`	`#>boot_disk_size<#`	Disk size in MB

VBoxManage Commands¶

VirtualBox uses post-create vboxmanage commands to configure VM settings that cannot be set through the builder directly:

movevm -- Moves the VM to `>>vms_path<