Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
207 lines (154 sloc) 8.36 KB


coreos-installer is a script to install Fedora CoreOS (FCOS) or Red Hat Enterprise Linux CoreOS (RHCOS) to a target disk. It can be invoked as a standalone script or during bootup via a dracut module.

Kernel command line options for coreos-installer running in the initramfs

  • coreos.inst=yes - Instruct the installer to run
  • coreos.inst.install_dev - The block device on the system to install to
  • coreos.inst.image_url - The url of the coreos image to install to this device
  • coreos.inst.ignition_url - The url of the coreos ignition config (optional, enter coreos.inst.ignition_url=skip to not load an ignition config)

Using the installer on FCOS or RHCOS

This installer is incorporated into FCOS and RHCOS. There are ISO images that can be downloaded that will allow for an install to be performed on bare metal hardware either via ISO install or via a PXE install. While ISO install is supported we certainly recommend PXE if you environment supports it since it is more friendly to automation.

Grab an ISO image and bare metal image

For Fedora CoreOS you can currently grab an ISO image from the output of the current development pipeline located here.

The ISO image can install in either legacy boot (BIOS) mode or in UEFI mode. You'll have to make sure you download the appropriate related image for the mode you'd like to use. It is a good idea to download them before doing the install as the artifacts server that is being used currently has very slow download speeds.

For example download:

and one of the following two:

NOTE The artifacts output of the pipeline are development artifacts. The links above will quickly become broken because we prune builds. As we get closer to an official release we'll have stable links but for now you'll have to find your own links from the latest directory.

Test a PXE based install

Using the ISO images you can also do a PXE based install. You can mount up the ISO images and use the initramfs.img and vmlinuz for PXE boot. Here is an example pxelinux.cfg that I used to perform a PXE boot:

DEFAULT pxeboot
LABEL pxeboot
    KERNEL fedora-coreos-30.107-installer.iso/images/vmlinuz
    APPEND ip=dhcp rd.neednet=1 initrd=fedora-coreos-30.107-installer.iso/images/initramfs.img console=tty0 console=ttyS0 coreos.inst=yes coreos.inst.install_dev=sda coreos.inst.image_url= coreos.inst.ignition_url=

If you don't know how to use this information to test a PXE install you can start with something like these instructions for testing out PXE installs via a local VM + Libvirt.

Test an ISO based install

You can test an install on a bare metal machine by burning the ISO to disk and booting it or using ISO redirection via a LOM interface. Alternatively you can use a VM like so:

virt-install --name cdrom --ram 4500 --vcpus 2 --disk size=20 --accelerate --cdrom /path/to/fedora-coreos-30.107-installer.iso --network default

NOTE To test UEFI boot add --boot uefi to the CLI call

Alternatively you can use qemu directly:

Create a disk image which we can use as install target

qemu-img create -f qcow2 fcos.qcow2 10G

Now, run following qemu command

qemu-system-x86_64 -accel kvm -name fcos -m 2048 -cpu host -smp 2 -netdev user,id=eth0,hostname=coreos -device virtio-net-pci,netdev=eth0 -drive file=/path/to/fcos.qcow2,format=qcow2  -cdrom /path/to/fedora-coreos-30.107-installer.iso

Once you have booted you will see a screen press <TAB> (isolinux) or e (grub) to edit the kernel command line. Add the parameters to the kernel command line telling it what you want it to do. For example:

  • coreos.inst.install_dev=sda
  • coreos.inst.image_url=
  • coreos.inst.ignition_url=

NOTE make sure to use a metal-uefi image if booting via UEFI

Now press <ENTER> (isolinux) or <CTRL-x> (grub) to kick off the install. The install will occur on tty2 and there are very few good log statements or debug opportunities. The user experience here needs work and is tracked in #5.

The install should progress and eventually reboot the machine. After reboot the machine will boot into the installed system and the embedded ignition config should run on first boot.

Testing out the installer script by running it directly

Grab coreos-installer and execute it on an already booted system.

NOTE The installer writes directly to a block device (disk) and consumes the entire device. The device specified to the installer needs to be available and not currently in use. You cannot target a disk that is currently mounted.

The easiest way to access a disk that is not currently in use is to boot up the coreos-installer ISO. If you boot the ISO and don't provide any extra arguments you will be presented with a usage message and then a prompt where you can execute the installer via the CLI:

/usr/libexec/coreos-installer -d sdd -i -b

Afterwards you'll need to reboot the machine.

Alternatively, you can install coreos-installer on a desktop/laptop machine and write out an image to a spare disk attached to the system. This can be dangerous if you specify the wrong disk to the installer.

You'll want to make sure all of the dependencies are installed on your machine. If you are on Fedora you can install the coreos-installer rpm (and all dependencies) using DNF via dnf install coreos-installer. The path to the script will be /usr/libexec/coreos-installer.

sudo /path/to/coreos-installer -d sdg -i -b

Afterwards, remove the disk from the computer and insert it into and boot the target machine where it is desired to run CoreOS.

Testing out the installer running in the initramfs (early boot)

You can build an initramfs with the installer/dracut module by cloning this repo and building the initramfs locally like so:

git clone
cd coreos-installer
sudo dnf -y install dracut dracut-network
sudo dnf -y install $(grep inst_multiple dracut/30coreos-installer/ | sed 's|inst_multiple||' | tr '\n' ' ')
sudo cp ./coreos-installer /usr/libexec/coreos-installer
sudo rsync -avh dracut/30coreos-installer /usr/lib/dracut/modules.d/
sudo dracut --kernel-cmdline="ip=dhcp rd.neednet=1" --add coreos-installer --no-hostonly -f ./initramfs.img --kver $(uname -r)

You can then boot a system with that initrd and a kernel and see the installer run. First we will grab the kernel.

cp /usr/lib/modules/$(uname -r)/vmlinuz ./vmlinuz

Then create a treeinfo file that can be used with virt-install: This won't be necessary in the future.

cat <<'EOF' > .treeinfo
arch = x86_64
family = Fedora
platforms = x86_64
version = 29
initrd = initramfs.img
kernel = vmlinuz

Set our kernel arguments for the install and kick it off using virt-install:

args='coreos.inst=yes '
args+='coreos.inst.install_dev=vda '
args+='coreos.inst.image_url= '
args+='coreos.inst.ignition_url= '
sudo virt-install --location ./ --extra-args="${args}" --network network=default --name installer --memory 2048 --disk size=10
You can’t perform that action at this time.