uCore

What is this?

You should be familiar with Fedora CoreOS, as this is an OCI image of CoreOS with "batteries included". More specifically, it's an opinionated, custom CoreOS image, built daily with some commonly used tools added in. The idea is to make a lightweight server image including most used services or the building blocks to host them.

Please take a look at the included modifications and help us test uCore if the project interests you.

Images & Features

The uCore project builds four images, each with different tags for different features.

The image names are:

• fedora-coreos
• ucore-minimal
• ucore
• ucore-hci

The tag matrix includes combinations of the following:

• stable - for an image based on the Fedora CoreOS stable stream
• testing - for an image based on the Fedora CoreOS testing stream
• nvidia - for an image which includes nvidia driver and container runtime
• zfs - for an image which includes zfs driver and tools

fedora-coreos

NOTE: formerly named fedora-coreos-zfs, the previous version of the image did not offer the nvidia option. If on the previous image name, please update with rpm-ostree rebase.

A generic Fedora CoreOS image image with choice of add-on kernel modules:

• nvidia versions add:
  • nvidia driver - latest driver (currently version 535) built from negativo17's akmod package
  • nvidia-container-toolkit - latest toolkit which supports both root and rootless podman containers and CDI
  • nvidia container selinux policy - allows using --security-opt label=type:nvidia_container_t for some jobs (some will still need --security-opt label=disable as suggested by nvidia)
• ZFS versions add:
  • ZFS driver - latest driver (currently pinned to 2.2.x series)

NOTE: currently, zincati fails to start on systems with OCI based deployments (like uCore). Upstream efforts are active to correct this.

ucore-minimal

Suitable for running containerized workloads on either bare metal or virtual machines, this image tries to stay lightweight but functional.

• Starts with a Fedora CoreOS image
• Adds the following:
  • cockpit (podman container and system management)
  • firewalld
  • guest VM agents (qemu-guest-agent and open-vm-tools))
  • docker-compose and podman-compose docker(moby-engine) and podman are pre-installed in CoreOS
  • tailscale and wireguard-tools
  • tmux
  • udev rules enabling full functionality on some Realtek 2.5Gbit USB Ethernet devices
• Optional nvidia versions add:
  • nvidia driver - latest driver (currently version 535) built from negativo17's akmod package
  • nvidia-container-toolkit - latest toolkit which supports both root and rootless podman containers and CDI
  • nvidia container selinux policy - allows using --security-opt label=type:nvidia_container_t for some jobs (some will still need --security-opt label=disable as suggested by nvidia)
• Optional ZFS versions add:
  • ZFS driver - latest driver (currently pinned to 2.2.x series)
  • sanoid/syncoid dependencies - see below for details
    • note: on ucore-minimal images, only pv is installed
• Disables Zincati auto upgrade/reboot service
• Enables staging of automatic system updates via rpm-ostreed
• Enables password based SSH auth (required for locally running cockpit web interface)
• Provides public key allowing SecureBoot (for ucore signed nvidia or zfs drivers)

Note: per cockpit instructions the cockpit-ws RPM is not installed, rather it is provided as a pre-defined systemd service which runs a podman container.

ucore

This image builds on ucore-minimal but adds drivers, storage tools and utilities making it more useful on bare metal or as a storage server (NAS).

• Starts with a ucore-minimal image providing everything above, plus:
• Adds the following:
  • cockpit-storaged (udisks2 based storage management)
  • distrobox - a toolbox alternative
  • duperemove
  • intel wifi firmware - CoreOS omits this despite including atheros wifi firmware... hardware enablement FTW
  • mergerfs
  • snapraid
  • usbutils(and pciutils) - technically pciutils is pulled in by open-vm-tools in ucore-minimal

ucore-hci

Hyper-Coverged Infrastructure(HCI) refers to storage and hypervisor in one place... This image primarily adds libvirt tools for virtualization.

• Starts with a ucore image providing everything above, plus:
• Adds the following:
  • cockpit-machines: Cockpit GUI for managing virtual machines
  • libvirt-client: virsh command-line utility for managing virtual machines
  • libvirt-daemon-kvm: libvirt KVM hypervisor management
  • virt-install: command-line utility for installing virtual machines

Note: Fedora now uses DefaultTimeoutStop=45s for systemd services which could cause libvirtd to quit before shutting down slow VMs. Consider adding TimeoutStopSec=120s as an override for libvirtd.service if needed.

Tips and Tricks

Immutability and Podman

These images are immutable and you probably shouldn't install packages like in a mutable "normal" distribution.

Fedora CoreOS expects the user to run services using podman. moby-engine, the free Docker implementation, is installed for those who desire docker instead of podman.

Default Services

To maintain this image's suitability as a minimal container host, most add-on services are not auto-enabled.

To activate pre-installed services (cockpit, docker, tailscaled, etc):

sudo systemctl enable --now SERVICENAME.service

Note: libvirtd is enabled by default, but only starts when triggerd by it's socket (eg, using virsh or other clients).

Docker/Moby and Podman

NOTE: CoreOS cautions against running podman and docker containers at the same time. Thus, docker.socket is disabled by default to prevent accidental activation of the docker daemon, given podman is the default.

Podman and FirewallD

Podman and firewalld can sometimes conflict such that a firewall-cmd --reload removes firewall rules generated by podman.

As of netavark v1.9.0 a service is provided to handle re-adding netavark (Podman) firewall rules after a firewalld reload occurs. If needed, enable like so: systemctl enable netavark-firewalld-reload.service

Distrobox

Users may use distrobox to run images of mutable distributions where applications can be installed with traditional package managers. This may be useful for installing interactive utilities such has htop, nmap, etc. As stated above, however, services should run as containers.

CoreOS and ostree Docs

It's a good idea to become familar with the Fedora CoreOS Documentation as well as the CoreOS rpm-ostree docs. Note especially, this image is only possible due to ostree native containers.

Sanoid/Syncoid

sanoid/syncoid is a great tool for manual and automated snapshot/transfer of ZFS datasets. However, there is not a current stable RPM, rather they provide instructions on installing via git.

ucore has pre-install all the (lightweight) required dependencies (perl-Config-IniFiles perl-Data-Dumper perl-Capture-Tiny perl-Getopt-Long lzop mbuffer mhash pv), such that a user wishing to use sanoid/syncoid only need install the "sbin" files and create configuration/systemd units for it.

NVIDIA

If you installed an image with -nvidia in the tag, the nvidia kernel module, basic CUDA libraries, and the nvidia-container-toolkit are all are pre-installed.

Note, this does NOT add desktop graphics services to your images, but it DOES enable your compatible nvidia GPU to be used for nvdec, nvenc, CUDA, etc. Since this is CoreOS and it's primarily intended for container workloads the nvidia container toolkit should be well understood.

Note the included driver is the latest nvidia driver as bundled by negativo17. This package was chosen over rpmfusion's due to it's granular packages which allow us to install just the minimal nvidia-driver-cuda packages.

Other NVIDIA Drivers

If you need an older (or different) driver, consider looking at the container-toolkit-fcos driver. It provides pre-bundled container images with nvidia drivers for FCOS, allowing auto-build/loading of the nvidia driver IN podman, at boot, via a systemd service.

If going this path, you likely won't want to use the ucore -nvidia image, but would use the suggested systemd service. The nvidia container toolkit will still be required but can by layered easily.

ZFS

If you installed an image with -zfs in the tag (or fedora-coreos-zfs), the ZFS kernel module and tools are pre-installed, but like other services, ZFS is not pre-configured to load on default.

Load it with the command modprobe zfs and use zfs and zpool commands as desired.

Per the OpenZFS Fedora documentation:

By default ZFS kernel modules are loaded upon detecting a pool. To always load the modules at boot:

echo zfs > /etc/modules-load.d/zfs.conf

ZFS and immutable root filesystem

The default mountpoint for any newly created zpool tank is /tank. This is a problem in CoreOS as the root filesystem (/) is immutable, which means a directory cannot be created as a mountpoint for the zpool. An example of the problem looks like this:

# zpool create tank /dev/sdb
cannot mount '/tank': failed to create mountpoint: Operation not permitted

To avoid this problem, always create new zpools with a specified mountpoint:

# zpool create -m /var/tank tank /dev/sdb

If you do forget to specify the mountpoint, or you need to change the mountpoint on an existing zpool:

# zfs set mountpoint=/var/tank tank

SecureBoot

For those wishing to use nvidia or zfs images with pre-built kmods AND run SecureBoot, the kernel will not load those kmods until the public signing key has been imported as a MOK (Machine-Owner Key).

Do so like this:

sudo mokutil --import /etc/pki/akmods/certs/akmods-ublue.der

The utility will prompt for a password. The password will be used to verify this key is the one you meant to import, after rebooting and entering the UEFI MOK import utility.

How to Install

Prerequisites

This image is not currently available for direct install. The user must follow the CoreOS installation guide. There are varying methods of installation for bare metal, cloud providers, and virtualization platforms.

All CoreOS installation methods require the user to produce an Ignition file. This Ignition file should, at mimimum, set a password and SSH key for the default user (default username is core).

Install and Manually Rebase

You can rebase any Fedora CoreOS x86_64 installation to uCore. Installing CoreOS itself can be done through a number of provisioning methods.

To rebase an Fedora CoreOS machine to the latest uCore (stable):

1. Execute the rpm-ostree rebase command (below) with desired IMAGE and TAG.
2. Reboot, as instructed.
3. After rebooting, you should pin the working deployment which allows you to rollback if required.

sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/IMAGE:TAG

Tag Matrix

IMAGE	TAG
fedora-coreos - stable	stable-nvidia, stable-zfs,stable-nvidia-zfs
fedora-coreos - testing	testing-nvidia, testing-zfs, testing-nvidia-zfs
ucore-minimal - stable	stable, stable-nvidia, stable-zfs,stable-nvidia-zfs
ucore-mimimal - testing	testing, testing-nvidia, testing-zfs, testing-nvidia-zfs
ucore - stable	stable, stable-nvidia, stable-zfs,stable-nvidia-zfs
ucore - testing	testing, testing-nvidia, testing-zfs, testing-nvidia-zfs
ucore-hci - stable	stable, stable-nvidia, stable-zfs,stable-nvidia-zfs
ucore-hci - testing	testing, testing-nvidia, testing-zfs, testing-nvidia-zfs

Verified Image Updates

This image now includes container policies to support image verification for improved trust of upgrades. Once running one of the ucore* images (not included in fedora-coreos), the following command will rebase to the verified image reference:

sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/IMAGE:TAG

Install with Auto-Rebase

Your path to a running uCore can be shortened by using examples/ucore-autorebase.butane as the starting point for your CoreOS ignition file.

1. As usual, you'll need to follow the docs to setup a password. Substitute your password hash for YOUR_GOOD_PASSWORD_HASH_HERE in the ucore-autorebase.butane file, and add your ssh pub key while you are at it.
2. Generate an ignition file from your new ucore-autorebase.butane using the butane utility.
3. Now install CoreOS for hypervisor, cloud provider or bare-metal. Your ignition file should work for any platform, auto-rebasing to the ucore:stable (or other IMAGE:TAG combo), rebooting and leaving your install ready to use.

Verification

These images are signed with sigstore's cosign. You can verify the signature by downloading the cosign.pub key from this repo and running the following command:

cosign verify --key cosign.pub ghcr.io/ublue-os/ucore