Provisioning Fedora CoreOS on VirtualBox

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

Requisitos previos

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 tiene un usuario core predeterminado que puede ser usado para explorar el SO. Si usted desea utilizarlo finalice su configuración proporcionando una clave SSH.

Descargar la OVA

Fedora CoreOS está diseñado para ser actualizado automáticamente, con diferentes calendarios por flujo. Una vez que haya elegido el flujo relevante, puede descargar el último OVA:

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

Alternativamente, las imágenes OVA pueden ser descargadas manualmente desde la página de descargas.

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.20241027.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 ›