live-booting.adoc

= Running Fedora CoreOS directly from RAM
:page-aliases: live-booting-ipxe.adoc

The Fedora CoreOS live environment is a fully functional copy of Fedora CoreOS. It can provision itself via Ignition, execute containers, and so on. The live environment can be used to xref:bare-metal.adoc[install Fedora CoreOS to disk], and can also be used to run Fedora CoreOS directly from RAM.

This guide shows how to boot a transient Fedora CoreOS (FCOS) system via ISO, PXE, or iPXE. For more about the live ISO and PXE images, see the xref:live-reference.adoc[live image reference].

== Prerequisites

Before booting FCOS, you must have an Ignition configuration file. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].

If you're booting from PXE or iPXE, you must host the Ignition config on a reachable HTTP(S) or TFTP server. Booting the live PXE image requires at least 2 GiB of RAM with the `coreos.live.rootfs_url` kernel argument, and 4 GiB otherwise.

== Booting via ISO

The live ISO image can be booted from a physical DVD disc, from a USB stick, or from a virtual CD drive via lights-out management (LOM) firmware.

To boot from the ISO image, follow these steps:

- Download the ISO image:
+
[source,bash]
----
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release download -f iso
----

- Use `coreos-installer iso customize` to customize the ISO for your needs. In this example we assume an Ignition config exists in a file `config.ign`. We also add the optional `coreos.liveiso.fromram` kernel argument to the live boot.
+
NOTE: The `coreos.liveiso.fromram` is optional and is used in cases where you want to have no references to the booted media (ISO) once the system is up and running. This enables use cases like removing the media after boot or rewriting the disk the booted media is on, but does require more memory.
+
[source,bash,subs="attributes"]
----
KERNEL_ARG='--live-karg-append=coreos.liveiso.fromram'
IGNITION_ARG='--live-ignition=./config.ign'
podman run --security-opt label=disable --pull=always --rm -v .:/data -w /data \
    quay.io/coreos/coreos-installer:release iso customize $KERNEL_ARG $IGNITION_ARG \
    -o customized.iso fedora-coreos-{stable-version}-live.x86_64.iso
----

- Burn the ISO to disk. On Linux and macOS, you can use `dd`. On Windows, you can use https://rufus.ie/[Rufus] in "DD Image" mode.
- Boot it on the target system.

== Booting via PXE

To boot from PXE, follow these steps:

- Download an FCOS PXE kernel, initramfs, and rootfs image:
[source, bash]
----
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 and running Ignition:

[source,subs="attributes"]
----
DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
    KERNEL fedora-coreos-{stable-version}-live-kernel-x86_64
    APPEND initrd=fedora-coreos-{stable-version}-live-initramfs.x86_64.img,fedora-coreos-{stable-version}-live-rootfs.x86_64.img ignition.firstboot ignition.platform.id=metal ignition.config.url=http://192.168.1.101/config.ign
IPAPPEND 2
----

== Booting via 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.

[source,subs="attributes"]
----
#!ipxe

set STREAM stable
set VERSION {stable-version}
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 ignition.firstboot ignition.platform.id=metal ignition.config.url=$\{CONFIGURL}
initrd --name main $\{BASEURL}/fedora-coreos-$\{VERSION}-live-initramfs.x86_64.img

boot
----

== Using persistent state

By default, the Fedora CoreOS live environment does not store any state on disk, and is reprovisioned from scratch on every boot. However, you may choose to store some persistent state (such as container images) in a filesystem that persists across reboots. For example, here's a Butane config that configures a persistent `/var`:

[source,yaml,subs="attributes"]
----
variant: fcos
version: 1.1.0
storage:
  disks:
    - device: /dev/sda
      wipe_table: true
      partitions:
        - label: var
  filesystems:
    - device: /dev/disk/by-partlabel/var
      label: var
      format: xfs
      wipe_filesystem: false
      path: /var
      with_mount_unit: true
----

When booting a live environment, the Ignition config runs on every boot, so it should avoid wiping LUKS volumes and filesystems that you want to reuse. Instead, configure such structures so that they're created on the first boot and preserved on subsequent boots.

In particular, note the following guidelines:

- Avoid setting `wipe_filesystem` or `wipe_volume` for https://coreos.github.io/ignition/operator-notes/#filesystem-reuse-semantics[filesystems] or LUKS volumes that you intend to reuse. (You can safely set `wipe_table` or `wipe_partition_entry` when reusing a disk, since those don't modify the contents of a https://coreos.github.io/ignition/operator-notes/#partition-reuse-semantics[partition].)
- When reusing LUKS volumes, you must configure a `key_file`. Ignition cannot reuse Clevis-backed LUKS volumes.
- Avoid writing persistent data to RAID volumes, since Ignition cannot reuse those.
- When writing files in persistent storage, set `overwrite` to `true` to avoid Ignition failures when reusing a filesystem that already has the file. Avoid using the `append` directive for persistent files, since the append operation will occur on every boot.

== Update process

Since the traditional FCOS upgrade process requires a disk, the live environment is not able to auto-update in place. For this reason, Zincati is not running there.

For PXE-booted systems, it is recommended that images referenced in the PXE configuration are regularly refreshed. Once infrastructure and configurations are updated, the live PXE instance only needs to be rebooted in order to start running the new FCOS version.

For ISO-booted systems, the ISO image used to boot the live environment should be periodically refreshed, and the instance rebooted to update the running OS.