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-40.20240920.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:
OS |
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"
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 ›