Provisioning Fedora CoreOS on VirtualBox

This guide shows how to provision new Fedora CoreOS (FCOS) nodes on the VirtualBox hypervisor.

Prerequisites

Before importing an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see Producing an Ignition File.

Fedora CoreOS has a default core user that can be used to explore the OS. If you want to use it, finalize its configuration by providing e.g. an SSH key.

Downloading the OVA

Fedora CoreOS is designed to be updated automatically, with different schedules per stream. Once you have picked the relevant stream, you can download the latest OVA:

STREAM="stable"
coreos-installer download -s "${STREAM}" -p virtualbox -f ova

Alternatively, OVA images can be manually downloaded from the download page.

Booting a new VM on VirtualBox

You can set up a VirtualBox virtual machine through the GUI or via the VBoxManage CLI. This guide will use the CLI for setting up the VM.

Importing the OVA

To import the OVA, use VBoxManage import:

VM_NAME=my-instance
VBoxManage import --vsys 0 --vmname "$VM_NAME" fedora-coreos-41.20241109.3.0-virtualbox.x86_64.ova

Setting the Ignition config

Ignition reads its configuration from the /Ignition/Config guest property of the virtual machine. At present, guest properties can only be set from the host command line, and not via the GUI. To set the Ignition config for a VM:

IGN_PATH="/path/to/config.ign"
VM_NAME=my-instance
VBoxManage guestproperty set "$VM_NAME" /Ignition/Config "$(cat $IGN_PATH)"

Ignition config size limitations

The length of the /Ignition/Config guestinfo property is constrained by the maximum length of a command line on your host operating system. The OS-specific limits are approximately:

Limit

Linux

128 KiB

macOS

256 KiB

Windows shells

8 KiB

If your Ignition config is larger than this limit, you can host the config on an HTTPS server and refer to it from a small pointer config, as follows:

Upload your Ignition config to an HTTPS server.

Create a Butane pointer config that specifies the URL of your full Ignition config:

variant: fcos
version: 1.5.0
ignition:
  config:
    replace:
      source: https://example.com/config.ign

Use Butane to convert the Butane config to an Ignition config.
Set the /Ignition/Config guest property to the contents of the pointer Ignition config, following the instructions in Setting the Ignition config.

Configuring networking

By default, the VM will use NAT networking. This will share the IP address of your host. Alternatively, if you want the VM to use a different IP address than your host, you can set the VM’s network adapter to "Bridged networking".

NAT networking

By default, NAT networking does not allow inbound connections to the VM. To allow inbound SSH connections, you can forward connections to e.g. port 2222 on the host to the SSH server in the VM:

VM_NAME=my-instance
VBoxManage modifyvm "$VM_NAME" --natpf1 "guestssh,tcp,,2222,,22"

After booting the VM, you can SSH to the VM from your host:

ssh core@localhost -p 2222

Bridged networking

If you want the VM to use a different IP address than your host, you can set the VM’s network adapter to "Bridged networking".

Determine the network adapter that should be bridged to the VM. To get the name of your host’s default network adapter, you can run:
```
ip route ls default | grep -Po '(?<= dev )(\S+)'
```

Modify the VM’s network adapter settings:

VM_NAME=my-instance
ADAPTER=adapter-name
VBoxManage modifyvm "$VM_NAME" --nic1 bridged --bridgeadapter1 "$ADAPTER"

Starting the VM

You can now boot the VM you have configured:

VM_NAME=my-instance
VBoxManage startvm "$VM_NAME"

Troubleshooting first-boot problems

You may encounter problems with your Ignition config that require access to the console log messages which appear during the first boot. To obtain a copy of the console log you can attach a serial device to the VM before booting.

To attach a serial device to a powered-off VM:

VM_NAME=my-instance
VM_LOG=$(realpath .)/$VM_NAME.log
VBoxManage modifyvm "$VM_NAME" --uart1 0x3F8 4
VBoxManage modifyvm "$VM_NAME" --uartmode1 file "$VM_LOG"

When you power on the VM, console output will be logged to the file you specified.

Want to help? Learn how to contribute to Fedora Docs ›