Installing CoreOS on Bare Metal
This guide provides instructions to install Fedora CoreOS to bare metal. Three options are available:
-
Installing from live ISO
-
Installing from PXE
-
Installing from the container
Prerequisite
Before installing FCOS, you must have an Ignition configuration file and host it somewhere (e.g. using python3 -m http.server
). If you do not have one, see Producing an Ignition File.
If you have servers with different types and/or number of hard drives, you must create a separate customized Ignition config for each machine (or machine class). A good model is to have the common parts of the configuration factored out into a separate Ignition configuration which can be merged into (via HTTP or inline) the per-machine custom config. |
Installing from live ISO
To install FCOS onto bare metal using the live ISO interactively, follow these steps:
-
Download the latest ISO image from the download page or with podman (see documentation for options):
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \ quay.io/coreos/coreos-installer:release download -s stable -p metal -f iso
Note this is just using coreos-installer
as a tool to download the ISO.
You can boot the live ISO in either legacy BIOS or UEFI mode, regardless of what mode the OS will use once installed. |
-
Burn the ISO to disk. On Linux and macOS, you can use
dd
. On Windows, you can use Rufus in "DD Image" mode. -
Boot it on the target system. The ISO is capable of bringing up a fully functioning FCOS system purely from memory (i.e. without using any disk storage). Once booted, you will have access to a bash command prompt.
-
You can now run
coreos-installer
:
sudo coreos-installer install /dev/sda \ --ignition-url https://example.com/example.ign
Once the installation is complete, you can reboot the system using sudo reboot
. After rebooting, the first boot process begins. It is at this time that Ignition ingests the configuration file and provisions the system as specified.
For more advanced ISO installs, including automation, see below. For more about the live ISO image, see the live image reference.
Check out coreos-installer install --help for more options on how to install Fedora CoreOS.
|
Installing from the network
Booting the live PXE image requires at least 2 GiB of RAM with the coreos.live.rootfs_url kernel argument, and 4 GiB otherwise. You can install in either legacy boot (BIOS) mode or in UEFI mode, regardless of what mode the OS will use once installed.
|
Installing from PXE
To install from PXE, follow these steps:
-
Download an FCOS PXE kernel, initramfs, and rootfs image:
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \ quay.io/coreos/coreos-installer:release download -f pxe
-
Follow this example
pxelinux.cfg
for booting the installer images with PXELINUX:
DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
KERNEL fedora-coreos-40.20240920.3.0-live-kernel-x86_64
APPEND initrd=fedora-coreos-40.20240920.3.0-live-initramfs.x86_64.img,fedora-coreos-40.20240920.3.0-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://192.168.1.101:8000/config.ign
IPAPPEND 2
For more details on how to use this information, see this blog post for testing a PXE installation via a local VM and libvirt
. For other supported kernel command-line options, see the coreos-installer docs, but note that coreos-installer pxe customize
(see below) is more flexible. For more about the live PXE image, see the live image reference.
Installing from iPXE
An iPXE-capable machine needs to be provided with a relevant Boot Script to fetch and load FCOS artifacts.
The example below shows how to load those directly from Fedora infrastructure. For performance and reliability reasons it is recommended to mirror them on the local infrastructure, and then tweak the BASEURL
as needed.
#!ipxe
set STREAM stable
set VERSION 40.20240920.3.0
set INSTALLDEV /dev/sda
set CONFIGURL https://example.com/config.ign
set BASEURL https://builds.coreos.fedoraproject.org/prod/streams/${STREAM}/builds/${VERSION}/x86_64
kernel ${BASEURL}/fedora-coreos-${VERSION}-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${BASEURL}/fedora-coreos-${VERSION}-live-rootfs.x86_64.img coreos.inst.install_dev=${INSTALLDEV} coreos.inst.ignition_url=${CONFIGURL}
initrd --name main ${BASEURL}/fedora-coreos-${VERSION}-live-initramfs.x86_64.img
boot
For other supported kernel command-line options, see the coreos-installer docs, but note that coreos-installer pxe customize
(see below) is more flexible. For more about the live PXE image, see the live image reference.
Installing from the container
You can use the coreos-installer
container from an existing system to install to an attached block device. For example (substitute docker
for podman
if needed):
sudo podman run --pull=always --privileged --rm \
-v /dev:/dev -v /run/udev:/run/udev -v .:/data -w /data \
quay.io/coreos/coreos-installer:release \
install /dev/vdb -i config.ign
In this example, coreos-installer
will download the latest stable FCOS metal image and install it onto /dev/vdb
. It will then inject the Ignition file config.ign
in the current directory into the image. Use --help
to see all the available options.
Downloading and mirroring the metal image
Sometimes, it’s necessary to download the metal image ahead of time and then have it passed locally to coreos-installer
for installation. You can download the metal image directly from the FCOS download page, or you can use coreos-installer download
.
When installing via the live ISO or PXE, there is no need to download the metal image. It is already part of those environments. |
There are two metal images: one for 512b-sector disks (labeled "Raw" on the download page), and one for 4k-sector native disks (labeled "Raw (4K Native)"). Unless you know to be targeting a 4k native disk, use the 512b one, which is the most common. See this page for more information.
To download the 4kn native metal image with coreos-installer download
, use the --format 4k.raw.xz
switch.
The metal image uses a hybrid partition layout which supports both BIOS and UEFI booting. |
When you’re finally ready to install FCOS, you can point it at your downloaded image using coreos-installer install --image-url <LOCAL_MIRROR>
or coreos-install --image-file <PATH>
.
Customizing installation
The coreos-installer iso customize
and coreos-installer pxe customize
commands can be used to create customized ISO and PXE images with site-specific configuration, including the ability to perform unattended installations of Fedora CoreOS.
When booting an image created with coreos-installer pxe customize , the PXE or iPXE kernel command line must include the arguments ignition.firstboot ignition.platform.id=metal . If running in a virtual machine, replace metal with the platform ID for your platform, such as qemu or vmware .
|
For example:
# Create customized.iso which:
# - Automatically installs to /dev/sda
# - Provisions the installed system with config.ign
# - Configures the installed GRUB and kernel to use a primary graphical
# and secondary serial console
# - Uses network configuration from static-ip.nmconnection
# - Trusts HTTPS certificates signed by ca.pem
# - Runs post.sh after installing
coreos-installer iso customize \
--dest-device /dev/sda \
--dest-ignition config.ign \
--dest-console ttyS0,115200n8 \
--dest-console tty0 \
--network-keyfile static-ip.nmconnection \
--ignition-ca ca.pem \
--post-install post.sh \
-o custom.iso fedora-coreos-40.20240920.3.0-live.x86_64.iso
# Same, but create a customized PXE initramfs image
coreos-installer pxe customize \
--dest-device /dev/sda \
--dest-ignition config.ign \
--dest-console ttyS0,115200n8 \
--dest-console tty0 \
--network-keyfile static-ip.nmconnection \
--ignition-ca ca.pem \
--post-install post.sh \
-o custom-initramfs.img fedora-coreos-40.20240920.3.0-live-initramfs.x86_64.img
For details on available customizations, see the coreos-installer documentation.
ISO installation on diverse hardware
Commonly bare metal systems will have a diversity of hardware - some systems may have NVMe drives /dev/nvme*
, whereas others have /dev/sd*
for example. You will almost certainly have to template the value of /dev/sda
above.
A useful approach is to script generating a per-machine .iso
. If you have a hardware database (whether a text file in git or relational database) then it will work to generate a per-machine target-dell.ign
and target-hp.ign
for example, and specify that to --dest-ignition
alongside the appropriate --dest-device
to generate fedora-coreos-install-dell.iso
and fedora-coreos-install-hp.iso
.
Alternatively, instead of generating per-machine ISOs, you can have a --pre-install
script run a privileged container which inspects the target system and writes an appropriate installer config to /etc/coreos/installer.d
.
Installing on iSCSI
To install CoreOS on an iSCSI boot device, follow the same steps as described above to get the live environnement, and add the iSCSI-related kernel arguments.
-
Mount the iSCSI target from the live environment:
sudo iscsiadm -m discovery -t st -p 10.0.0.1 sudo iscsiadm -m node -T iqn.2023-10.coreos.target.vm:coreos -l
-
Append the necessary kargs when running
coreos-installer
:
On a completely diskless machine, the iscsi target and initiator values can be passed through iBFT. These could be supplied with an iPXE boot script for example:
---
#!ipxe
set initiator-iqn iqn.2023-11.coreos.diskless:testsetup
sanboot iscsi:10.0.0.1::::iqn.2023-10.coreos.target.vm:coreos
---
---
sudo coreos-installer install \
/dev/disk/by-path/ip-10.0.0.1\:3260-iscsi-iqn.2023-10.coreos.target.vm\:coreos-lun-0 \
--append-karg rd.iscsi.firmware=1 --append-karg ip=ibft \
--console ttyS0 \
--ignition-url https://example.com/example.ign
---
---
sudo coreos-installer install \
/dev/disk/by-path/ip-10.0.0.1\:3260-iscsi-iqn.2023-10.coreos.target.vm\:coreos-lun-0 \
--append-karg rd.iscsi.initiator=iqn.2024-02.com.yourorg.name:lun0 \
--append-karg netroot=iscsi:iqn.2023-10.coreos.target.vm:coreos` \
--console ttyS0 \
--ignition-url https://example.com/example.ign
---
All this can also be set using coreos-installer iso customize
or coreos-installer pxe customize
. (See "Customizing installation" section above).
For example using iBFT:
# Create customized.iso which:
# - Automatically mounts iSCSI target using mount-iscsi.sh
# - Provisions the installed system with config.ign
# - Configures the installed system to use iBFT
coreos-installer iso customize \
--pre-install mount-iscsi.sh \
--dest-device /dev/disk/by-path/ip-10.0.0.1\:3260-iscsi-iqn.2023-10.coreos.target.vm\:coreos-lun-0 \
--dest-ignition config.ign \
--dest-karg-append rd.iscsi.firmware=1 \
--dest-karg-append ip=ibft \
-o custom.iso fedora-coreos-40.20240920.3.0-live.x86_64.iso
The --pre-install
flag is used to run a script with iscsiadm
commands, --dest-device
targets the mounted disk and then --dest-karg-append
add the necessary kargs.
Reinstalling Fedora CoreOS
You can use any of the methods described above to reinstall Fedora CoreOS on the same machine via the live environment.
Data persistence
The installer does not completely scrub the target disk. Thanks to Ignition’s filesystem-reuse semantics, if you apply a config with the exact same partition and filesystem settings as the first install, all previously stored data in additional partitions will still be available. This can be useful for persisting e.g. /var/lib/containers
or /var/home
between reinstalls. There are some restrictions, however. See the Using persistent state section for more information. You will also want to ensure the root filesystem is a fixed number at least 8 GiB as described in Configuring Storage so that data partitions are not accidentally overwritten.
Destination drive
Fedora CoreOS requires that only a single filesystem labeled boot
exists. If multiple such filesystems are found on the first boot, provisioning will error out as a fail-safe. If reinstalling Fedora CoreOS on a different disk than the previous installation, make sure to wipe the previous disk using e.g. wipefs
. For example, if reinstalling to /dev/sdb
, but /dev/sda
still contains the previous installation of FCOS, use wipefs -a /dev/sda
in the installation environment.
Want to help? Learn how to contribute to Fedora Docs ›