coreos-installer
coreos-installer is a program to assist with installing Fedora CoreOS (FCOS) and Red Hat Enterprise Linux CoreOS (RHCOS). It can do the following:
- Download and install the operating system to a target disk, optionally
customizing it with an Ignition config or first-boot kernel parameters
(
coreos-installer install
) - Download and verify an operating system image for various cloud,
virtualization, or bare metal platforms (
coreos-installer download
) - List Fedora CoreOS images available for download
(
coreos-installer list-stream
) - Embed an Ignition config in a live ISO image to customize the running
system that boots from it (
coreos-installer iso
)
The options available for each subcommand are available via the --help
option. This documentation will focus on how to obtain and run
coreos-installer.
On Fedora CoreOS or RHEL CoreOS
coreos-installer is included in Fedora CoreOS and RHEL CoreOS. Just run
coreos-installer
from the command line. Fedora CoreOS provides
live CD and network boot images
you can run from RAM; you can use these to run coreos-installer to install
Fedora CoreOS or RHEL CoreOS to disk.
On other Fedora editions
On other Fedora editions, you can install coreos-installer with DNF in the usual way:
Build and install from source tree
To build from the source tree:
To install the binary and systemd units to a target rootfs (e.g. under a coreos-assembler workdir):
Install with Cargo
You can also install just the coreos-installer binary with Rust's Cargo package manager:
Run from a container
You can run coreos-installer from a container. You'll need to bind-mount
/dev
and /run/udev
, as well as a data directory if you want to access
files in the host. For example:
Run from a live image using kernel command-line options
If you want a fully automated install, you can configure the Fedora CoreOS
live CD or netboot image to run coreos-installer and then reboot the system.
You do this by passing coreos.inst.<arg>
arguments on the kernel command
line.
Kernel command line options for coreos-installer running as a service
coreos.inst.install_dev
- The block device on the system to install to, such as/dev/sda
. Mandatory.coreos.inst.stream
- The Fedora CoreOS stream to install. Optional; defaults tostable
unlesscoreos.inst.image_url
is specified.coreos.inst.image_url
- The URL of the CoreOS image to install, overridingcoreos.inst.stream
. Optional.coreos.inst.ignition_url
- The URL of the Ignition config. Optional. If missing, no Ignition config will be embedded, which is probably not what you want.coreos.inst.platform_id
- The Ignition platform ID of the platform the CoreOS image is being installed on. Optional; defaults tometal
. Normally this should be specified only if installing inside a virtual machine.coreos.inst.insecure
- Permit the OS image to be unsigned. Optional.coreos.inst.skip_reboot
- Don't reboot after installing. Optional.
Installing from ISO
Download a Fedora CoreOS ISO image. The ISO image can install in either legacy boot (BIOS) mode or in UEFI mode. You can boot it in either mode, regardless of what mode the OS will boot from once installed.
Burn the ISO to disk and boot it, or use 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.20191014.1-live.x86_64.iso --network default
Alternatively you can use qemu
directly. Create a disk image to use as
install target:
qemu-img create -f qcow2 fcos.qcow2 8G
Now, run the 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.20191014.1-live.x86_64.iso
Once you have reached the boot menu, 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=/dev/sda
coreos.inst.stream=testing
coreos.inst.ignition_url=http://example.com/config.ign
coreos.inst.platform_id=qemu
Now press <ENTER>
(isolinux) or <CTRL-x>
(grub) to kick off the
install.
The install will complete and eventually reboot the machine. After reboot the machine will boot into the installed system and the embedded Ignition config will run on first boot.
Installing from PXE
Download a Fedora CoreOS PXE kernel and initramfs image. The PXE image can install in either legacy boot (BIOS) mode or in UEFI mode. You can boot it in either mode, regardless of what mode the OS will boot from once installed.
Here is an example pxelinux.cfg
for booting the installer images with
PXELINUX:
DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
KERNEL fedora-coreos-30.20191014.1-live-kernel-x86_64
APPEND ip=dhcp rd.neednet=1 initrd=fedora-coreos-30.20191014.1-live-initramfs.x86_64.img console=tty0 console=ttyS0 coreos.inst.install_dev=/dev/sda coreos.inst.stream=testing coreos.inst.ignition_url=http://192.168.1.101:8000/config.ign
IPAPPEND 2
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.
Build and test the installer for development
NOTE: The install
subcommand 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.
Build coreos-installer and use it to install a Fedora CoreOS testing
image to a partitionable loop device: