# RakuOS documentation (full text) Generated 2026-10-28, pages fingerprint bda7e95c87cd. Published at https://rakuos.org/ai --- # Start here: helping a RakuOS user RakuOS is a Fedora desktop (Fedora 44 on the stable channel, Fedora 45 on staging) shipped as a bootc image. The base system in `/usr` is read-only and replaced whole by image updates; packages the user installs with `rum` or the Software Center live in a persistent overlay on top of it. Fedora Workstation (`dnf`) and Fedora Atomic (`rpm-ostree`) advice is often wrong here, so follow the rules below and translate generic advice before giving it. Details: [How RakuOS works](https://rakuos.org/ai/01-architecture), [repo map](https://rakuos.org/ai/repo-map), [how RakuOS differs from Fedora](https://rakuos.org/ai/components/fedora-differences). Components: [rum](https://rakuos.org/ai/components/rum), [overlay (rakuos-core)](https://rakuos.org/ai/components/rakuos-core), [Software Center](https://rakuos.org/ai/components/rakuos-software), [RakuOS System](https://rakuos.org/ai/components/rakuos-system), [installer](https://rakuos.org/ai/components/rakuos-installer), [kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). As of 2026-10-15. ## What RakuOS is - Editions: KDE, GNOME, COSMIC, niri and Hyprland, each with an install ISO (Hyprland's since 2026-10-28); the gamescope (Steam Gaming Mode) image exists but has no ISO, so a system gets it only by switching an installed system to its image. Channels: `latest` (stable, Fedora 44) and `staging` (Fedora 45). Behavior differs between them in places; the pages say where. - Images: `quay.io/rakuos/rakuos-[-nvidia|-nvidia-legacy][-v3|-v4]:`, signed, updated with `bootc`. `-nvidia-legacy` carries the 580xx driver for Maxwell/Pascal/Volta GPUs. - Packages: `rum`, RakuOS's own package manager. `dnf` and `dnf5` are shims that run rum. There is no rpm-ostree. - The overlay: `/var/lib/rakuos/overlay/upper`, mounted on `/usr` at boot. The user's packages are listed in `/var/lib/rakuos/packages.list`, and the overlay can be rebuilt from that list. - Security: AppArmor. SELinux is not installed and not built into the kernel. The kernel boots with `lockdown=integrity` and `module.sig_enforce=1`: only kernel modules signed by RakuOS load. RakuOS prebuilds and signs its out-of-tree modules (NVIDIA, Broadcom Wi-Fi, Xbox controllers, wheels, …); nothing is compiled or signed on the user's machine. - Third-party repos: Terra and RPM Fusion are both disabled by default on both channels; images from 2026-10-17 on turned RPM Fusion off on existing installs too, so users who relied on it must turn it back on. The welcome app's Third-Party Repositories page has an RPM Fusion and a Terra switch. - Anti-cheat: `rakuos eac-check` and the RakuOS System app's Anti-Cheat button check Easy Anti-Cheat Linux v2's requirements. - User documentation: https://rakuos.org/documentation has plain how-to pages for users (installing, software, updates, drivers, Secure Boot, dual boot, rescue mode, troubleshooting). Link the matching page when it covers the user's question; these AI pages stay the detailed reference. - `sudo` is sudo-rs, the core utilities are uutils, `ls` is lsd and `cat` is bat (system-wide, not aliases); the GNU versions are available as `gnu_sudo`, `gnu_ls`, `gnu_cat` and so on. On a terminal `cat` shows a framed view with line numbers and opens a pager for long files (press `q`); for text to paste, use `gnu_cat` or the `grep` commands below. ## The support contract 1. **Identify the system first.** Never assume the edition, channel or version. Have the user run the read-only block in [diagnostics](https://rakuos.org/ai/troubleshooting/diagnostics). The short form: ```bash grep -E '^(PRETTY_NAME|VERSION_ID|VARIANT_ID)=' /etc/os-release # read-only: VARIANT_ID = edition, plus -staging on staging sudo bootc status # read-only: booted and rollback image, channel tag, version date uname -r # read-only: kernel rum paths # read-only: should say "mode: split (RakuOS overlay)" ``` 2. **Find the owning component** in the [repo map](https://rakuos.org/ai/repo-map) before proposing a fix. 3. **Use RakuOS tools.** rum or the Software Center for RPM packages, `bootc` for image updates, rollback and switching, Flatpak or Distrobox for isolation. Translate Fedora or Silverblue advice into these, or explain why it does not apply. 4. **Never suggest anything on the "Do not" list** below. 5. **Read-only first.** Before any command that changes the system, say what it changes, how to undo it and whether a reboot is needed. Mention `sudo bootc rollback` before risky steps. 6. **Check [known issues](https://rakuos.org/ai/known-issues) first.** If the problem is known, give the workaround and the tracker link. 7. **New bug? Stop and help file it.** When the code is wrong rather than the user's setup, fill in the bug template from [bug reporting](https://rakuos.org/ai/bug-reporting): the right project from the repo map, redacted logs, every command already run. Have the user confirm each detail before filing at rakuos.org/bugs. 8. **When unsure, say so.** Point to the forum (rakuos.org/forum), Matrix (matrix.rakuos.org) or Discord. ## Do not | Do not | Why | Do this instead | |---|---|---| | Suggest `rpm-ostree install`, `rpm-ostree upgrade` or any `rpm-ostree` command | rpm-ostree is not installed | `sudo rum install ` for RPMs; `sudo rum system-upgrade` or `sudo bootc upgrade` for updates | | Treat `dnf` as real dnf, e.g. dnf plugins, `dnf system-upgrade download --releasever`, `dnf offline-upgrade` | `dnf` runs rum; those features do not exist or are refused on an installed system | Use rum's own commands; a new Fedora release arrives as a new image through `bootc` | | Suggest `rum list --installed` or `dnf list --installed` | rum has no `--installed`; it rejects the flag as an unknown argument (the dnf shim only translates the keyword form `dnf list installed`) | `rum list` shows the overlay packages (what the user installed); `rum list --base` shows the image's packages; `rum origin ` says which one a package is | | Check whether or where a package is installed with `rpm -q` or `rpm -qa` | rpm mixes the image's and the overlay's packages, so it can't say where a package came from | `rum list --base \| grep ` (in the image) and `rum list \| grep ` (installed into the overlay); `rum origin ` for one package. `rpm -V ` is still the way to check a package's files | | Say `rum upgrade` updates the system | It upgrades only overlay packages, never the base image | `sudo rum system-upgrade` (packages, Flatpaks and image), or the Software Center's Updates page, then reboot | | Assume Terra or RPM Fusion is enabled | Terra and RPM Fusion are disabled by default on both channels | Check with `rum repolist --all`; enable only if the user wants it, in the welcome app's Third-Party Repositories page or with `sudo rum config-manager --set-enabled terra` / `'rpmfusion-*'` (undo: `--set-disabled`) | | Write or edit `.repo` files in `/etc/yum.repos.d` or `/usr/share/…/repos.d` by hand | rum keeps repo files in its own dirs (`/etc/rum.repos.d` for the user's, `/usr/share/rum/repos.d` from packages); files under `/usr/share` belong to packages | `sudo rum config-manager --set-enabled/--set-disabled `, `sudo rum config-manager addrepo --from-repofile=`, `sudo rum copr enable` | | Delete or mask `/usr/share/rum/repos.override.d/20-rakuos.repo` (e.g. an empty `20-rakuos.repo` in `/etc/rum/repos.override.d`), or try to get around its excludes, to install Fedora's `goverlay`, RPM Fusion's NVIDIA packages or steam, or Terra's AppArmor/scx packages | Those excludes keep other repos' builds from replacing RakuOS's own (the NVIDIA driver, GOverlay, AppArmor, sched_ext); masking the file drops all of them at once | Use the RakuOS packages; for the NVIDIA driver, an `-nvidia` or `-nvidia-legacy` image. Own extra overrides go in a new file such as `/etc/rum/repos.override.d/99-local.repo`. See [rum](https://rakuos.org/ai/components/rum#repo-overrides) | | Suggest installing `akmod-*` or `dkms-*` packages, `akmods`, `dkms autoinstall`, building a module with `make`, or `rakuos setup-nvidia` / `setup-nvidia-legacy` | A module built on the machine is unsigned and the kernel refuses it; `setup-nvidia*` installs DKMS packages | The image's `rakuos-kmod-*` modules; an `-nvidia` or `-nvidia-legacy` image for NVIDIA; `rakuos-kmod-VirtualBox…` for VirtualBox. Missing module: ask RakuOS (Discord or rakuos.org/bugs). See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot) | | Suggest generating a signing key, `mokutil --import` of a self-made key, `sign-file`, or DKMS/akmods signing settings | RakuOS enrolls only its own key; `rakuos enroll-secureboot-key` deletes locally generated MOKs, and they fail the anti-cheat check | Use RakuOS-signed modules as above | | Say `rakuos enroll-secureboot-key` removes Microsoft's or other distributions' keys, or warn that it breaks Windows or Linux dual boot | It removes only unknown MOKs (machine-made keys: self-made, akmods/DKMS, the old per-machine RakuOS key) and keeps Microsoft, Linux and BSD vendor keys; it never touches the firmware's `db`/`KEK` | Run it and read its `KEEP:`/`Removing:` lines; nothing is deleted until **Delete MOK** is confirmed at the next boot | | Suggest disabling Secure Boot, or adding `module.sig_enforce=0`, `lockdown=none` or `iommu=pt`, as a fix | These are deliberate security settings and Easy Anti-Cheat requirements; RakuOS System has no switch for them | Find the RakuOS-signed alternative; for anti-cheat problems run `rakuos eac-check`. One exception: hardware the IOMMU breaks (e.g. a TPM no longer found on an older Intel laptop) gets `intel_iommu=off` in RakuOS System after a one-boot test; see [TPM not found](https://rakuos.org/ai/troubleshooting/tpm-missing-after-iommu) | | Suggest `setenforce`, `restorecon`, `chcon`, `semanage`, `audit2allow`, or "disable SELinux" | SELinux is not present; these do nothing useful | `auditd` runs, so denials are in the audit log: `sudo ausearch -m AVC -ts today` (read-only). On RakuOS an `AVC` record with an `apparmor="DENIED"` field is AppArmor, not SELinux; report it | | Suggest disabling AppArmor or `apparmor.service` as a fix | It is the system's only mandatory access control | Collect the denial lines and file a bug against the owning project | | Install packages with `rpm -i`, `rpm -U` or `rpm -e` | rum's overlay database would not record them, and the next image update overwrites the package view rpm uses | `sudo rum install ./file.rpm`, `sudo rum remove ` | | Copy files into `/usr` by hand, or run installers (`curl … \| sh`, `make install`) that write to `/usr` | Files land in the overlay untracked and can hide newer files from later images | Flatpak, Distrobox, `~/.local`, or `/usr/local` (which is `/var/usrlocal`, outside the overlay) | | Delete files under `/var/lib/rakuos/overlay/upper` | It holds every overlay package; manual edits break rum's records | `sudo rum remove `, `sudo rum restore-base-files --dry-run` then without `--dry-run`, or `sudo rakuos reset-overlay --soft` | | Run `sudo rakuos reset-overlay --confirm` as a first step | It forgets every installed RPM | Try targeted fixes first, then `--soft`; back up `/var/lib/rakuos/packages.list` before either | | Assume GNU coreutils or GNU sudo behavior | They are uutils, lsd (`ls`), bat (`cat`) and sudo-rs | If a GNU-only option fails, use the `gnu_*` binary (e.g. `gnu_ls`) | | Suggest `grub2-mkconfig`, `update-grub`, `grub2-install`, or editing `/boot/grub2/grub.cfg`, `os-prober.cfg` or the marked RakuOS blocks in `user.cfg`/`custom.cfg` | `grub.cfg` is bootupd's static config; RakuOS's scripts own those files and blocks and rewrite them | Other OSes missing: `sudo /usr/libexec/rakuos/os-entries` (`--dry-run` first). The user's own GRUB additions go outside the marked blocks in `/boot/grub2/custom.cfg`. See [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader) | | Suggest unmasking `bootloader-update.service` or running `bootupctl update` | It is masked on purpose; `rakuos-bootloader-update` does that job with RakuOS's checks | `journalctl -b -u rakuos-bootloader-update`; `sudo /usr/libexec/rakuos/bootloader-update --dry-run` | | Tell a user stuck at boot to reinstall | Images from 2026-10-16 on have a **RakuOS rescue** GRUB submenu that boots without the overlay | [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay) or [System won't boot after an update](https://rakuos.org/ai/troubleshooting/boot-stuck-after-update) | | Force a `rakuos-kmod-*` update rum doesn't offer (`rum install `, downloading the RPM), or upgrade a kmod's `*-kmod-common`/firmware on its own | A kmod update that isn't offered is built for a kernel the system isn't running yet, and its dependencies are held to match the installed kmod; forcing either leaves a module that doesn't load | Wait for the image update: `sudo rum system-upgrade` or the Software Center runs `rum kmod-upgrade` for the new kernel first. Preview with `sudo rum kmod-upgrade --dry-run` | | Expect automatic updates | No update timer is enabled by default | Tell the user to update from the Software Center or with `sudo rum system-upgrade` | --- # How RakuOS works RakuOS is a Fedora system (Fedora 44 on the stable channel, Fedora 45 on staging) shipped as a signed bootc container image. The image's `/usr` is read-only; packages the user installs with `rum` or the Software Center go into a persistent overlay on top of it, stored in `/var/lib/rakuos/overlay/upper`. Image updates, rollbacks and edition switches go through `bootc`, and at each boot the initrd decides whether the overlay can be kept as it is, needs its package database view refreshed, or must be rebuilt from the user's package list. As of 2026-10-15, image v2/v3/v4. Packages from their `main` branches (built for both releases); images from `main` (stable) and `staging`, with differences marked. ## The pieces | Piece | What it is | Where | |---|---|---| | Base image | `quay.io/rakuos/rakuos-[-nvidia\|-nvidia-legacy][-v3\|-v4]:` | the booted ostree deployment's `/usr` | | Overlay | overlayfs mounted on `/usr`, lower = image, upper = user's packages | `/var/lib/rakuos/overlay/{upper,work}` | | Package list | names the user installed; the overlay is rebuilt from it | `/var/lib/rakuos/packages.list`, local RPMs in `packages-rpm.list` and `local-rpms/` | | Overlay package database | rum's record of overlay packages, separate from the base's | `/var/lib/rakuos/rum-rpmdb` | | Markers | `current-deploy` (last `ostree=` boot argument), `os-version`, `de-name`, `overlay.state`, `overlay.dirty` | `/var/lib/rakuos/` | | rum | the package manager; `dnf` and `dnf5` are shims that run it | `/usr/bin/rum`, `/usr/bin/dnf` | | Repo files | user's repos and changes; repo files from packages | `/etc/rum.repos.d`; `/usr/share/rum/repos.d` (rum also reads `/etc/yum.repos.d` and `/usr/share/dnf5/repos.d`) | Editions: `kde`, `gnome`, `cosmic`, `niri`, `hyprland`, `gamescope`. KDE, GNOME, COSMIC, niri and Hyprland (plus a minimal image) have install ISOs; gamescope is reached by switching an installed system. Channels: `latest` (stable, built from `main`, Fedora 44) and `staging` (built from `staging`, Fedora 45). Every build also gets a dated tag: `latest.YYYYMMDD` or `staging.YYYYMMDD`. The suffix `-v3` or `-v4` selects a kernel and repos built for that x86-64 level; no suffix is v2. `-nvidia` adds the NVIDIA driver; `-nvidia-legacy` adds the 580xx driver for Maxwell, Pascal and Volta GPUs (staging only as of 2026-10-15). Each image carries the label `org.rakuos.fedora.version` with its Fedora release. To tell which one a machine runs: ```bash cat /etc/os-release # read-only: VARIANT_ID is the edition, with -staging on the staging channel (e.g. cosmic-staging) sudo bootc status # read-only: booted and rollback image refs (example from a customized test machine: quay.io/rakuos/rakuos-cosmic-v4:staging, version staging.20261013) uname -r # read-only: kernel release, e.g. 7.3.0-rakuos.2.v4.staging.fc45.x86_64 (kernel-rakuos-v4-staging) ``` `/etc/os-release` does not record the x86-64 level or NVIDIA; read those from the image name in `bootc status`. Its `VERSION_ID` is the Fedora release (44 or 45). ## Lifecycle ```mermaid flowchart TD ISO[Live ISO
Fedora kernel, overlay units masked] -->|rakuos-installer:
bootc install to-filesystem| DISK[Installed system
tracks the ISO's image ref] DISK --> BOOT subgraph BOOT[Every boot] I[initrd: rakuos-overlay-mount.service] -->|checks markers| R{Reset or change?} R -->|soft or hard reset queued,
VERSION_ID or desktop changed| W[wipe /var/lib/rakuos state] R -->|new deployment| S[reseed rpmdb view] R -->|nothing| M[mount overlay on /usr] W --> M S --> M M --> Y[rakuos-overlay-sync.service
before the login screen] Y -->|state missing or dirty| RI[rum install packages.list] end BOOT --> USE[Session: rum, Software Center,
Flatpak, Distrobox, AppImages] USE -->|rum system-upgrade,
Software Center update| UP[bootc upgrade stages new image] USE -->|bootc rollback| RB[previous deployment queued] USE -->|bootc switch| SW[other edition or channel staged] USE -->|rakuos reset-overlay| RS[reset marker set] UP --> BOOT RB --> BOOT SW --> BOOT RS --> BOOT ``` ## 1. Installing from the ISO The live ISO is built by RakuForge from the edition image. Its live session boots Fedora's signed kernel, not kernel-rakuos, and masks `rakuos-overlay-mount.service` and `rakuos-overlay-sync.service`. Boot menu entries: the default, "Basic Graphics Mode" (adds `nomodeset`) and "Text-Mode Installer". The installer (`rakuos-installer`, frontends GTK, Qt, COSMIC and text) copies the image baked into the ISO to disk and runs `bootc install to-filesystem --target-imgref `. The installed system therefore follows the same image name and channel as the ISO; there is no edition or channel choice in the installer. Defaults: Btrfs with subvolumes `@`, `@home` and `@snapshots`, GRUB, optional LUKS2 encryption unlocked by TPM2. The disk must be at least 40 GiB. The ISOs install the stable (`latest`) image. If the machine boots with UEFI and Secure Boot on, the installer queues one key for enrollment: the RakuOS certificate `/usr/share/rakuos/sb_pubkey.der`. (Installers before 2026-10-15 also queued a per-machine module signing key; `sudo rakuos enroll-secureboot-key` removes it.) ## 2. First boot 1. With Secure Boot on, MOK Manager (a blue screen) appears before RakuOS starts. Choose Enroll MOK, then Continue, type the password `rakuos`, then Reboot. If this was skipped, run `sudo rakuos enroll-secureboot-key` later and repeat the steps at the next boot. The RakuOS kernel is signed with this key, so with Secure Boot on it boots only once the key is enrolled. `enroll-secureboot-key` also queues every enrolled MOK that isn't a well-known vendor key for deletion, such as the per-machine key earlier installers created (`CN=RakuOS Machine Module Signing Key`); MOK Manager then offers Delete MOK too, completed the same way. 2. In the initrd, `rakuos-overlay-mount.service` (dracut module `90rakuos-overlay`, after `ostree-prepare-root.service`) creates the overlay directories. Because `packages.list` does not exist yet, it copies the image's prebaked overlay from `/usr/share/factory/var/lib/rakuos/` and mounts the overlay. Its messages start with `RakuOS overlay:`. 3. Before the login screen, `rakuos-overlay-sync.service` finds the prebaked state and finalizes it: "Finalizing initial package overlay..." on the boot splash. Each edition's prebaked list holds only Firefox. 4. At login, the welcome app (`rakuos-welcome`) offers a Third-Party Repositories page (RPM Fusion and Terra switches, both off) and a set of apps. It keeps opening at each login until the user clicks Finish. There is no Drivers page any more. ## 3. Every later boot `rakuos-overlay-mount` runs these checks in the initrd, in order: | Check | Result | |---|---| | `VERSION_ID` in the image differs from `/var/lib/rakuos/os-version` | soft reset queued (Fedora release changed) | | `/usr/share/rakuos/de-name` differs from `/var/lib/rakuos/de-name` | soft reset queued (edition changed) | | whiteouts hide a whole top-level `/usr` directory | soft reset queued, logged `CRITICAL — …` | | hard or soft reset queued | state wiped, see [Resetting the overlay](#7-resetting-the-overlay) | | otherwise, `ostree=` boot argument differs from `/var/lib/rakuos/current-deploy` | reseed: the base's `/usr/share/rpm` and `packages.toml` are copied into the upper dir | Then it mounts the overlay with `lowerdir=/sysroot/usr` and the upper and work dirs, unless the upper dir is empty, in which case `rakuos-overlay-sync` mounts it later. `rakuos-overlay-sync.service` then acts on the state: - prebaked state: finalize, no download; - overlay empty or `overlay.state` missing: `rum install` of everything in `packages.list`; - `overlay.dirty` present: reinstall `packages.list`, then reboot once; - otherwise: nothing. Installs need the network. Without it the boot splash shows "Connect to the internet, then reboot to finish installing default applications." and the install waits for the next boot. Logs: ```bash journalctl -b -u rakuos-overlay-sync.service # read-only journalctl -b | grep 'RakuOS overlay' # read-only: initrd messages ``` Boot menu upkeep (images from 2026-10-16 on): `rakuos-bootloader-update` updates shim and GRUB on the ESP from the booted image, `rakuos-rescue-entries` keeps the **RakuOS rescue** GRUB submenu current, and 2 minutes after the first boot of a new deployment `rakuos-os-entries` refreshes the entries for other operating systems. Details: [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader). ## 4. Installing software | Method | Where it goes | Command | |---|---|---| | rum | overlay (`/usr`), recorded in `packages.list` and `rum-rpmdb` | `sudo rum install ` | | Software Center ("Add/Remove Software") | same as rum; it runs rum | GUI | | Flatpak | `/var/lib/flatpak` or `~/.local/share/flatpak` | `flatpak install ` | | Distrobox | a podman container in the user's home | `distrobox create --name box --image fedora:44` | | Local RPM | overlay; file kept in `/var/lib/rakuos/local-rpms/` | `sudo rum install ./file.rpm` | | AppImage | the user's files; the Software Center can register it | GUI, or `chmod +x` and run | ```bash sudo rum install # changes system: adds to the overlay, takes effect immediately, no reboot. Undo: sudo rum remove rum paths # read-only: should print "mode: split (RakuOS overlay)" rum origin # read-only: Base, Overlay, Installed or NotInstalled ``` Rules rum follows on an installed system: - It never modifies the base image. Installing a package the image already provides does nothing ("already installed (base image or overlay) — skipping"); upgrading one prints "provided by the base image … skipping". - A local `.rpm` is installed from its own header without dependency resolution; missing dependencies must be installed separately. For a missing library named in an error, `rum provides '()(64bit)'` (read-only, exact capability name) shows which package to install. - Software that installs into `/opt` is moved to `/usr/lib/opt/`, and `/opt/` becomes a symlink to it, because `/opt` itself is `/var/opt`. - `/usr/local` is `/var/usrlocal` and is not part of the overlay. Third-party repos: Terra and RPM Fusion are installed but disabled by default on both channels (RPM Fusion's NVIDIA packages and steam are always excluded, as are Terra's AppArmor and scx packages and Fedora's goverlay; from 2026-10-22 these excludes come from the rum repo override `/usr/share/rum/repos.override.d/20-rakuos.repo`, see [rum](https://rakuos.org/ai/components/rum#repo-overrides)). Images from 2026-10-17 on turned RPM Fusion off on existing installs too. To use them, the welcome app's Third-Party Repositories page, or: ```bash rum repolist --all # read-only: shows which repos are enabled sudo rum config-manager --set-enabled terra # changes system: enables Terra (writes a copy of its repo file to /etc/rum.repos.d). Undo: --set-disabled terra, which removes the copy again. No reboot. sudo rum config-manager --set-enabled 'rpmfusion-*' # changes system: enables RPM Fusion's package repos (a wildcard skips -source, -debuginfo and -testing repos). Undo: --set-disabled 'rpmfusion-*'. No reboot. ``` rum reads repo files from `/etc/rum.repos.d` (the user's repos and changes), `/etc/yum.repos.d`, `/usr/share/rum/repos.d` (from packages) and `/usr/share/dnf5/repos.d`, in that order; a file in an earlier dir hides one with the same name in a later dir. Packages' repo files are installed into `/usr/share/rum/repos.d`. See [rum](https://rakuos.org/ai/components/rum#repo-files). Options from repo override files (`/etc/rum/repos.override.d`, `/usr/share/rum/repos.override.d`, and dnf5's two) are applied on top; see [Repo overrides](https://rakuos.org/ai/components/rum#repo-overrides). ### Kernel modules and Secure Boot The kernel boots with `lockdown=integrity` and `module.sig_enforce=1` (from `/usr/lib/bootc/kargs.d/10-rakuos.toml`), so it loads only signed modules. RakuOS builds and signs its out-of-tree modules: images ship them as `rakuos-kmod-` packages (`-staging` on staging; NVIDIA in `-nvidia` images, Broadcom `wl`, `v4l2loopback`, Xbox controllers, racing wheels and others). An `akmod-*` or `dkms-*` package installed with rum builds an unsigned module that will not load; `rakuos setup-nvidia` does the same. VirtualBox and OpenRazer users add `rakuos-kmod-VirtualBox` or `rakuos-kmod-openrazer` (with the image's suffix) to the overlay. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot) and [A driver won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load). The same settings, plus IOMMU without passthrough and kexec disabled, are what Easy Anti-Cheat Linux v2 requires. `rakuos eac-check` (or the Anti-Cheat button in RakuOS System) checks them; the RakuOS key is not yet on Epic's list of well-known keys, so the best result today is a yellow "Suggestions". See [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready). ## 5. Updating Nothing updates automatically: no update timer is enabled by default. The update paths: | Command or app | Overlay packages | Flatpaks | Base image | |---|---|---|---| | `sudo rum upgrade` | yes | no | no | | `sudo rum system-upgrade` | yes (on a Fedora release change: soft reset instead) | yes | `bootc upgrade` | | `sudo rakuos upgrade` (used by the apps; not in `rakuos --help`) | yes | yes | `bootc upgrade` | | `sudo rakuos system-upgrade` (same) | no | no | `bootc upgrade` | | `sudo bootc upgrade` | no | no | yes | | Software Center, Updates page | yes | yes | yes, through `rakuos-update upgrade-image` | ```bash sudo rum system-upgrade # changes system: upgrades overlay packages and Flatpaks, then stages the newest image of the current channel. Reboot to use the new image. Undo after reboot: sudo bootc rollback ``` For a normal full update, use the Software Center's Updates page or `sudo rum system-upgrade`, then reboot. `bootc upgrade` stages the new image; the running system does not change until the reboot. At shutdown, right after `ostree-finalize-staged` writes the new deployment, `rakuos-grub-theme.service` installs its GRUB theme and rewrites the rescue entries. The shell alias `update` runs `sudo rum system-upgrade`. When an update moves to a newer Fedora release (the new image's `org.rakuos.fedora.version` label is higher than `VERSION_ID`), the Software Center and `sudo rum system-upgrade` first run `/usr/libexec/rakuos/rakuos-reset-overlay --soft --releasever ` (the same as `sudo rakuos reset-overlay --soft --releasever `), which downloads the overlay packages for the new release; if that fails, the image update is not started. A plain `sudo bootc upgrade`, `sudo bootc switch` or a switch in the RakuOS System app skips this step, and the initrd queues the soft reset itself on the first boot of the new release, reinstalling from the network. ## 6. Reseed, rollback and switching After a reboot into a different deployment (update, rollback or switch), the initrd reseeds: it copies the new base's package database view into the overlay so rum sees the new base. Files in the overlay are kept as they are. ```bash sudo bootc rollback # changes system: makes the previous deployment the default for the next boot. Reboot required. Undo: sudo bootc rollback again ``` - Same Fedora release and edition: overlay packages stay installed. - Different Fedora release or edition: the overlay is soft-reset and reinstalled from `packages.list` (network needed). Stable (44) and staging (45) are different releases, so switching channel counts too. - The RakuOS System app's Deployments page can also pin a deployment (`ostree admin pin`) or pick which one boots next (`ostree admin set-default`). Switching edition, channel, x86-64 level or NVIDIA variant (Standard, Nvidia, Nvidia Legacy) uses the RakuOS System app (System page) or: ```bash sudo bootc switch quay.io/rakuos/rakuos-kde-v4:latest # changes system: stages a different image. Reboot required. Undo: sudo bootc rollback. A different edition or Fedora release soft-resets the overlay on first boot. ``` ## 7. Resetting the overlay Try the soft reset first. The hard reset cannot be undone: it forgets every RPM the user installed. Back up the package list before either one. ```bash cp /var/lib/rakuos/packages.list ~/packages.list.bak # changes only the home dir: backup of the installed-package list sudo rakuos reset-overlay --soft # changes system: at next boot wipes the overlay and reinstalls everything in packages.list. Reboot required. Cannot be cancelled after the reboot. sudo rakuos reset-overlay --confirm # changes system, destructive: at next boot wipes the overlay AND packages.list, returning to the image's defaults. Reboot required. Reinstall from the backup afterwards with sudo rum install. ``` - Soft reset first downloads every package in `packages.list`. If that fails it prints "Soft reset aborted — nothing has been changed." Keeps `packages.list`, local RPMs and the markers. `--releasever N` downloads from Fedora N's repos, for a move to an image built on Fedora N. - Hard reset removes all of `/var/lib/rakuos` except a few markers, then restores the image's prebaked overlay. - Both clear `/var/cache/libdnf5` and remove `/opt` symlinks into `/usr/lib/opt`. - Neither touches `/etc`, `/home`, Flatpaks or the rest of `/var`. - The RakuOS System app's Overlay page runs the same commands. - If the reinstall after a reset fails at every boot, boot an entry from the **RakuOS rescue** GRUB submenu (no overlay, text login) and reset from there: [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay). --- # RakuOS repo map RakuOS is built from the public repositories in the gitlab.com/rakuos group (82 as of 2026-10-13, plus signed-kmods, added 2026-10-14). For each one, this page gives its tier, what it does, what it ships, which repos it uses or feeds, and the bug tracker project to file against. Look up the owning project here before suggesting a fix or filing a bug. Facts describe each repo's `main` branch as of 2026-10-13, updated on 2026-10-15 for the repos that changed since (rum, rakuos-core, rakuos-system, rakuos-installer, rakuos-settings, rakuos-welcome, rakuos-software, rakuos-release, the kernels, signed-kmods and the images). Image, ISO, kernel and signed-kmods repos also have a `staging` branch, which builds the `staging` channel. As of 2026-10-15 the image and kernel `staging` branches are well ahead of `main`: staging images are Fedora 45, ship RakuOS-signed `rakuos-kmod-*` modules, keep RPM Fusion disabled and add `-nvidia-legacy` variants, while stable (`main`) images are Fedora 44. The ISO repos' `staging` branches are older than `main`. Tiers: - **1**: RakuOS's own behavior. Each gets a component page. - **2**: packaging of upstream software, or build tooling. Summarized per family. - **3**: reference only. - **none**: empty or template-only repo. ## Which project owns the problem | Problem | Project | |---|---| | `rum` or `dnf` errors; installing, removing or upgrading RPM packages; repo or GPG key errors on the user's machine | [rakuos-rum](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum) | | Files under `/usr` missing or wrong after an update, overlay resets, "RakuOS overlay" boot messages, "Base System Protection" notifications, the `rakuos` command | [rakuos-core](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core) | | The Add/Remove Software app, its tray icon, update notifications | [rakuos-software](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-software) | | The RakuOS System Management app: switching edition or channel, rollback, deployments, kernel arguments, zram, scheduler, AppArmor and firewall pages | [rakuos-system](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-system) | | The welcome app shown at first login | [rakuos-welcome](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-welcome) | | Installing from the ISO: disks, encryption, user account, Secure Boot key enrollment | [rakuos-installer](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-installer) | | `rakuos enroll-secureboot-key`, `rakuos eac-check` results | [rakuos-core](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core) | | The Anti-Cheat button and dialog in RakuOS System | [rakuos-system](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-system) | | A `rakuos-kmod-*` module missing, failing to load or misbehaving; requests for a new prebuilt module | signed-kmods (tracker page by the usual pattern: https://rakuos.org/bugs/p/rakuos-packages-rakuos-signed-kmods, not checked; if absent, rakuos-base), or the RakuOS Discord | | The live ISO does not boot, or misbehaves in the live session | the edition's ISO repo, for example [rakuos-cosmic-iso](https://rakuos.org/bugs/p/rakuos-iso-rakuos-cosmic-iso) | | Something every edition has: base packages, repos, services, the kernel package, image signing | [rakuos-base](https://rakuos.org/bugs/p/rakuos-images-rakuos-base) | | Packages, defaults, login screen or session of one desktop | the edition image: [rakuos-kde](https://rakuos.org/bugs/p/rakuos-images-rakuos-kde), [rakuos-gnome](https://rakuos.org/bugs/p/rakuos-images-rakuos-gnome), [rakuos-cosmic](https://rakuos.org/bugs/p/rakuos-images-rakuos-cosmic), [rakuos-niri](https://rakuos.org/bugs/p/rakuos-images-rakuos-niri), [rakuos-hyprland](https://rakuos.org/bugs/p/rakuos-images-rakuos-hyprland), [rakuos-gamescope](https://rakuos.org/bugs/p/rakuos-images-rakuos-gamescope) | | Kernel crashes or missing kernel features | [kernel](https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel); [kernel-deck](https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel-deck) on the gamescope image | | sysctl, udev, zram defaults, the image's kernel arguments (lockdown, IOMMU, module signature enforcement), sudo rules, shell aliases | [rakuos-settings](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-settings) | | AppArmor userspace or `apparmor.service` | [apparmor](https://rakuos.org/bugs/p/rakuos-packages-apparmor-apparmor) | | Logos, boot splash, GRUB theme, GTK themes, default fonts | [rakuos-branding](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-branding) | | A package missing from repo.rakuos.org, or failing its signature check | [rakurpm](https://rakuos.org/bugs/p/rakuos-packages-rpm-tools-rakurpm) | If none fits, use the edition image project, as `bug-report-template.md` says. ## How the repos fit together 1. Package repos build RPMs in GitLab CI and upload them to repo.rakuos.org, which runs RakuRPM (`packages/rpm-tools/rakurpm`). The repos are `rakuos-44`, `rakuos-45` and `rakuos-el-10`; package repos' `main` branches build for both 44 and 45. The kernel and signed-kmods also publish to `-v3` and `-v4` repos such as `rakuos-44-v4`. 2. `images/rakuos-base` builds FROM `quay.io/bootc-devel/fedora-bootc--minimal` (44 on `main`, 45 on `staging`). It swaps the Fedora kernel for `kernel-rakuos`, replaces dnf with rum, adds the rakuos-* packages and the kernel modules, and pushes `quay.io/rakuos/rakuos-base` and `quay.io/rakuos/rakuos-minimal`, each with `-nvidia`, `-v3` and `-v4` variants (staging also `-nvidia-legacy`). Every image carries the label `org.rakuos.fedora.version`. - On staging the kernel modules come from `packages/rakuos/signed-kmods`: the kernel CI triggers kernel-deck, which triggers signed-kmods to rebuild and sign every module for the new kernels. 3. The edition images build FROM rakuos-base (gamescope builds FROM rakuos-kde) and push `quay.io/rakuos/rakuos-[-nvidia|-nvidia-legacy][-v3|-v4]` (no NVIDIA variants for gamescope). Branch `main` publishes tag `latest`, branch `staging` publishes tag `staging`, and both add dated tags such as `staging.20261012`. 4. Each ISO repo runs `rakuos-forge` on its edition image. On the live ISO, `rakuos-installer` writes that image to disk with `bootc install to-filesystem`. 5. On an installed system, `rakuos-core` mounts a persistent overlay on `/usr` from the initrd and reinstalls the user's packages when needed. `rum` installs packages into that overlay. rakuos-software, rakuos-system and rakuos-welcome are GUIs that call rum, bootc and rakuos-core's helpers. ## RakuOS tools ### rakuos-core (Tier 1) `packages/rakuos/rakuos-core`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core Owns the persistent overlay on `/usr`: the initrd mount, the boot-time package replay, overlay resets, protection of base-image files, update helpers and the `rakuos` command. - Ships one RPM, `rakuos-core`: `/usr/bin/rakuos` (including `rakuos eac-check`, the anti-cheat readiness check); helpers in `/usr/libexec/rakuos/` (`rakuos-overlay-sync`, `rakuos-reset-overlay`, `rakuos-base-protect`, `rakuos-update`, `rakuos-updater`, `system-setup`, `generate-base-manifest`, `enroll-secureboot-key`, `bootloader-update`, `grub-theme-deploy`, `rescue-entries`, `os-entries`, `setup-nvidia` and other `setup-*` scripts; `sync-grub-theme` was removed on 2026-10-16; `rakuos-sign-modules` was removed on 2026-10-15); the dracut module `90rakuos-overlay` with the initrd unit `rakuos-overlay-mount.service`; the units `rakuos-overlay-sync`, `rakuos-base-protect`, `rakuos-setup`, `rakuos-flatpak-watcher`, `rakuos-grub-theme`, `rakuos-bootloader-update`, `rakuos-rescue-entries` (`.service`, `.path`), `rakuos-os-entries.timer`, `rakuos-bootc-upgrade`, `rakuos-bootc-switch`, `rakuos-updater.timer`, Flatpak and podman cleanup timers; the user unit `rakuos-user`. - Keeps its state in `/var/lib/rakuos/`. The overlay upper dir is `/var/lib/rakuos/overlay/upper`, and the user's package list is `/var/lib/rakuos/packages.list`. - Uses: rum to reinstall packages, bootc for image updates. - Used by: rakuos-base (installs it and enables its units), the edition images (run `generate-base-manifest` and prebake the overlay at build time), rakuos-software and rakuos-system (call `rakuos-update` and `rakuos-reset-overlay`). ### rakuos-rum (Tier 1) `packages/rakuos/rakuos-rum`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum `rum`, RakuOS's RPM package manager, written in Rust to replace dnf. On an installed system it installs packages into the `/usr` overlay and records them in its own database, separate from the base image's. - Ships `rakuos-rum` (`/usr/bin/rum`, `/etc/rum/rum.conf`, `rum-makecache.timer`) and `rum-dnf-shim`. The shim's `/usr/bin/dnf` and `/usr/bin/dnf5` pass their arguments to rum, rewriting a few `list`, `group` and `mark` forms, and the package obsoletes dnf, dnf5, yum and microdnf. - Reads repos from `/etc/rum.repos.d`, `/etc/yum.repos.d`, `/usr/share/rum/repos.d` and `/usr/share/dnf5/repos.d`, in that order; installs packages' repo files into `/usr/share/rum/repos.d` and writes the user's changes to `/etc/rum.repos.d`. Overlay database `/var/lib/rakuos/rum-rpmdb`, state `/var/lib/rakuos/rum-state`, cache `/var/cache/rum`. - On an installed system, `rum upgrade` upgrades overlay packages only. `rum system-upgrade` upgrades overlay packages and Flatpaks, then runs `bootc upgrade`; when the new image is a newer Fedora release it soft-resets the overlay with `--releasever` first. - Used by: rakuos-core, rakuos-software, rakuos-system, rakuos-welcome, every image build and rakuos-forge. ### rakuos-software (Tier 1) `packages/rakuos/rakuos-software`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-software The Software Center, shown as "Add/Remove Software" (`org.rakuos.Software`). It handles RPMs through rum, Flatpaks, AppImages, web apps, Distrobox containers, firmware and image updates, and includes the tray update checker. - Ships `rakuos-software-common` (`/usr/bin/rakuos-software`, the tray autostart `/etc/xdg/autostart/rakuos-software-tray.desktop`, the web app launcher) and one frontend per image: `-gtk` on GNOME, niri and Hyprland; `-qt` on KDE, COSMIC and gamescope. No image installs `-cosmic`. - Installs packages with `sudo-rs rum install -y`. Applies image updates through `/usr/libexec/rakuos/rakuos-update upgrade-image` and `rakuos-bootc-upgrade.service`. - Its System tab was removed on 2026-09-21. Those functions moved to rakuos-system. - Uses: rum, flatpak, bootc, rakuos-core helpers, the sudo rules in rakuos-settings. ### rakuos-system (Tier 1) `packages/rakuos/rakuos-system`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-system "RakuOS System Management" (`org.rakuos.System`). It switches the bootc image (edition, channel, x86-64 level, Standard/Nvidia/Nvidia Legacy), shows anti-cheat readiness (from `rakuos eac-check`), rolls back, pins and selects deployments, resets, exports and imports the overlay, and sets kernel arguments, zram size, the sched_ext scheduler, ananicy-cpp, AppArmor profile modes and firewalld. - Ships `rakuos-system-common` (`/usr/bin/rakuos-system`) and one frontend: `-gtk` on GNOME, niri and Hyprland, `-qt` on KDE and gamescope, `-cosmic` on COSMIC. It has no command-line interface. - Runs these through `pkexec`: `bootc switch`, `bootc rollback`, `ostree admin pin`, `ostree admin set-default`, `/usr/libexec/rakuos/rakuos-reset-overlay --soft|--confirm` and `bootc loader-entries set-options-for-source --source rakuos-user`. - Switches to `quay.io/rakuos/rakuos-[-nvidia|-nvidia-legacy][-v3|-v4]:latest` or `:staging`. Gamescope is not offered. - Has no upgrade button, although its README lists upgrades. ### rakuos-settings (Tier 1) `packages/rakuos/rakuos-settings`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-settings System tuning and policy shared by every image, forked from cachyos-settings: sysctl, udev rules, zram, journald and timesyncd defaults, kernel arguments, sudo rules, shell aliases and the RakuOS Secure Boot certificate (`/usr/share/rakuos/sb_pubkey.der`, which the kernels also build in). - Kernel arguments in `/usr/lib/bootc/kargs.d/10-rakuos.toml` (from 2026-10-15): `lockdown=integrity intel_iommu=on iommu.passthrough=0 iommu.strict=1 module.sig_enforce=1 sysctl.kernel.kexec_load_disabled=1`, for Easy Anti-Cheat Linux v2. The old `security=apparmor apparmor=1 selinux=0` were dropped, and so was the per-machine DKMS signing config. The sysctl file also sets `kernel.kexec_load_disabled = 1`. zram defaults to the size of RAM with zstd. - Ships the sudo rules RakuOS's GUI tools rely on, in `/etc/sudoers.d/rakuos`. rakuos-core restores RakuOS's files in `/etc/sudoers.d` at every boot, so edits to those files are lost; put local rules in a new file. - Shell alias `update` runs `sudo rum system-upgrade`. - Used by: rakuos-base installs it. ### rakuos-welcome (Tier 1) `packages/rakuos/rakuos-welcome`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-welcome The first-login app: a Third-Party Repositories page with RPM Fusion and Terra switches (both off by default), an app picker (RPMs through rum, Flatpaks, web apps, setup scripts) and Wi-Fi setup. Its Drivers page (legacy NVIDIA setup) was removed on 2026-10-15. - Ships `rakuos-welcome` (autostart `/etc/xdg/autostart/rakuos-welcome.desktop`) and one frontend: `-gtk`, `-qt` or `-cosmic`. The COSMIC frontend replaces `cosmic-initial-setup`. - Autostarts at every login until the user clicks Finish, which writes `~/.config/rakuos/welcome-done`. `rakuos-welcome --force` opens it again. - Runs `pkexec rum config-manager --set-enabled terra` (or `--set-disabled`), for RPM Fusion `pkexec rum config-manager --set-enabled` with the repos listed in `/usr/share/rakuos/rpmfusion-default-repos` (fallback `'rpmfusion-*'`) and `--set-disabled 'rpmfusion-*'`, `sudo-rs rum install -y`, `sudo-rs rum remove -y` and `sudo-rs flatpak install`. ### rakuos-installer (Tier 1) `packages/rakuos/rakuos-installer`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-installer The live-ISO installer. It copies the image baked into the ISO to disk with `bootc install to-filesystem`, then creates the user, sets locale and timezone, and queues Secure Boot keys. - Ships `rakuos-installer-common` (`/usr/libexec/rakuos/rakuos-bootc-installer`) and frontends `-gtk`, `-qt`, `-cosmic` and `-cli`. - Defaults: Btrfs with subvolumes `@`, `@home` and `@snapshots`, GRUB, SELinux disabled, optional LUKS2 encryption with TPM2. It needs a disk of at least 40 GiB. - When Secure Boot is on, it queues the RakuOS certificate with `mokutil --import` (no per-machine key since 2026-10-15). On the next boot the user enrolls it at the blue MOK screen with the password `rakuos`. - Used by: each ISO repo installs it into the live session. Installed systems do not have it. ### rakuos-release (Tier 2) `packages/rakuos/rakuos-release`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-release Identity packages that write `/usr/lib/os-release` and provide `fedora-release`. `VARIANT_ID` names the edition and channel: `kde`, `gnome`, `cosmic`, `niri`, `hyprland`, `gamescope`, or `rakuos` for the base image, with `-staging` added on the staging channel. The x86-64 level and NVIDIA are not recorded there. - Ships `rakuos-release[-][-staging]` and `rakuos-release-common`, which every variant requires: it obsoletes Fedora's `fedora-release`, `-common` and `-identity-*` packages, provides `system-release(N)` and ships the files of Fedora's `fedora-release-common` (added 2026-10-14 so the packages install on Fedora 45). Each image installs the matching variant. ### rakuos-forge (Tier 2) `packages/rakuos/rakuos-forge`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-forge RakuForge, the ISO builder: it turns a bootc image into a hybrid BIOS/UEFI live ISO. It started as a Rust port of Universal Blue's Titanoboa. - Ships `rakuos-forge`, used on build machines only. - Writes the live boot menu: the default entry, "Basic Graphics Mode" (adds `nomodeset`) and "Text-Mode Installer". Boots through Fedora's signed shim and GRUB. - Used by: every ISO repo. ### kernel (Tier 1) `packages/rakuos/kernel`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel The RakuOS kernel, `kernel-rakuos-v2`, `-v3` or `-v4` (with `-staging` on the staging channel): the CachyOS kernel with the BORE scheduler, built once per x86-64 level, with SELinux compiled out and the LSM order `lockdown,yama,integrity,apparmor,bpf,landlock`. Both branches build CachyOS 7.3.0 (`main` since 2026-10-23); a release string looks like `7.3.0-rakuos.1.v4.fc44` (stable) or `7.3.0-rakuos.2.v4.staging.fc45` (staging). - Subpackages `-core`, `-modules`, `-devel`, `-devel-matched`. The RPMs are not signed for Secure Boot; the image build signs `vmlinuz` with the RakuOS key. In-tree modules are signed with a per-build key. - The RakuOS certificate is built in as a trusted key (`CONFIG_SYSTEM_TRUSTED_KEYS`; `staging` since 2026-10-14, `main` since 7.3.0 on 2026-10-23), so RakuOS-signed out-of-tree modules load without relying on the MOK keyring; the build fails if it's missing. CI triggers kernel-deck after a build. - Used by: rakuos-base installs it in place of Fedora's kernel. ### kernel-deck (Tier 2) `packages/rakuos/kernel-deck`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel-deck A fork of `kernel` with the CachyOS "deckify" config and handheld patches, packaged as `kernel-rakuos-deck-v2|v3|v4[-staging]`. Only the gamescope image uses it. Same SELinux-free LSM order; on `staging` it also builds in the RakuOS certificate, and its CI triggers signed-kmods once both kernels are published. ### signed-kmods (Tier 1) `packages/rakuos/signed-kmods` (work on `staging`; `main` holds only the initial commit as of 2026-10-15). Bugs: report to RakuOS (Discord or https://rakuos.org/bugs). Builds the out-of-tree kernel modules listed in `modules.list` (from akmod or DKMS packages in the Fedora, RPM Fusion, Terra and RakuOS repos) for every RakuOS kernel in CI, signs each `.ko` with the RakuOS key (`build-kmods.sh`, private key from rakuos-base's secure files) and packages them with `rakuos-kmod.spec`. - Packages: `rakuos-kmod-`, `-staging`, `-deck`, `-deck-staging`, per ISA repo. Each provides `-kmod`, `kmod-` and the source package's provides, and conflicts with `akmod-`, `dkms-` and the other channel's build. - Modules: nvidia, nvidia-580xx, wl, v4l2loopback, xone, xpadneo, xpad-noone, hid-fanatecff, hid-tmff2, t150-driver, new-lg4ff, logitech-trueforce, openrazer, ayaneo-leds, mediatek-mt7927, xtables-addons, intel-ipu6, intel-vision, sc0710, nct6687d, ryzen_smu, zenergy, VirtualBox. Patches for modules that lag the kernel live in `patches//`. - Used by: rakuos-base's `drivers*.sh` and `nvidia*.sh` and rakuos-gamescope's `drivers.sh` install them. Since 2026-10-23 the images install only `wl`, `v4l2loopback` and (NVIDIA images) nvidia/nvidia-580xx; every other module is left to users, who install it from RakuOS System's Drivers page. ### rakuos-branding (Tier 2) `packages/rakuos/rakuos-branding`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-branding Logos (it replaces `fedora-logos`), the Plymouth theme `rakuos-logo`, the GRUB theme, the fastfetch preset, OrigamiPaper GTK themes, Colloid icons and the default fonts Inter and Maple Mono NF. At every boot, rakuos-core's `rakuos-grub-theme.service` runs `sync-grub-theme`, which copies the GRUB theme into `/boot` and overwrites `/boot/grub2/user.cfg`. ### rakuos-wallpapers (Tier 3) `packages/rakuos/rakuos-wallpapers`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-wallpapers Default wallpapers in `/usr/share/wallpapers/` and `/usr/share/backgrounds/rakuos/`. ### rakuos-kde-settings (Tier 3) `packages/rakuos/rakuos-kde-settings`. An unpackaged copy of Fedora's kde-settings files. No image or spec uses it. ### rakuos-parental-controls (none) `packages/rakuos/rakuos-parental-controls`. Template README only. ## Images ### rakuos-base (Tier 1) `images/rakuos-base`. Bugs: https://rakuos.org/bugs/p/rakuos-images-rakuos-base The base every edition builds on, FROM `quay.io/bootc-devel/fedora-bootc-44-minimal`. - Removes the Fedora kernel, `selinux-policy`, dnf (replaced by `rum-dnf-shim`) and `zram-generator-defaults`. rpm-ostree is not installed. Fedora 44 on `main`, Fedora 45 on `staging`. - Installs `kernel-rakuos-*`, rum, rakuos-core, rakuos-settings, rakuos-release, rakuos-branding, rakuos-wallpapers, the AppArmor userspace, Flatpak (the installer adds the Flathub remote on the installed system), Distrobox, podman, `fuse-libs`, sudo-rs as the default `sudo` and uutils-coreutils as the default coreutils. The GNU tools are kept as `gnu_sudo`, `gnu_su` and so on. `/etc/default/useradd` makes fish the default shell. - Repos: Fedora, repo.rakuos.org, RPM Fusion (its NVIDIA packages and steam excluded) and Terra. Terra is installed but left disabled. On `staging` RPM Fusion ships disabled too (its default repo ids are recorded in `/usr/share/rakuos/rpmfusion-default-repos`), and all repo files live in rum's shipped dir `/usr/share/rum/repos.d`, toggled with `rum config-manager --default`. - Variants: `-v3` and `-v4` use the matching kernel and repos; `-nvidia` adds the NVIDIA driver (rebuilt from negativo17's packages); `-nvidia-legacy` (staging) the 580xx driver; `rakuos-minimal` has the same packages plus a prebaked overlay. - Kernel modules: installs the prebuilt `rakuos-kmod-*` packages (`-staging` on `staging`): every signed-kmods module except NVIDIA, which the nvidia scripts add, VirtualBox, openrazer, mediatek-mt7927, xtables-addons, intel-ipu6 and intel-vision (the last three since 2026-10-23). The build fails if one has no modules for the image's kernel. (Stable switched from building NVIDIA with DKMS and `broadcom-wl`/`v4l2loopback` with akmods on 2026-10-17.) Both sign `vmlinuz` with the RakuOS key. - Enables `rakuos-overlay-sync`, `rakuos-base-protect`, `rakuos-setup`, `rakuos-flatpak-watcher` and `rakuos-grub-theme`, and from 2026-10-16 `rakuos-bootloader-update`, `rakuos-rescue-entries` (`.service`, `.path`) and `rakuos-os-entries.timer`. bootupd's `bootloader-update.service` stays masked. No automatic update timer is enabled. - Images are pushed to `quay.io/rakuos/` and signed with cosign. `/etc/containers/policy.json` requires a valid signature for `quay.io/rakuos` images. ### Edition images (Tier 1) Each edition builds FROM rakuos-base, except gamescope, which builds FROM rakuos-kde. On `staging` each edition except gamescope also builds `-nvidia-legacy[-v3|-v4]` from `rakuos-base-nvidia-legacy`, and each build enables Terra and RPM Fusion while installing packages, then disables both with `rum config-manager --default`. Each prebakes its `packages.list` (only `firefox`) into the overlay at build time and writes its desktop name to `/usr/share/rakuos/de-name`. Booting an image whose desktop name differs from the last one triggers an overlay soft reset. | Repo | Desktop and login | RakuOS app frontends | ISO | |---|---|---|---| | `images/rakuos-kde` | Plasma, plasma-login-manager | Qt | rakuos-kde-iso | | `images/rakuos-gnome` | GNOME, GDM | GTK | rakuos-gnome-iso | | `images/rakuos-cosmic` | COSMIC, cosmic-greeter | Software: Qt; System and Welcome: COSMIC | rakuos-cosmic-iso | | `images/rakuos-niri` | niri with DankMaterialShell, dms-greeter on greetd; Noctalia shell and greeter optional through `rakuos-niri shell` and `rakuos-niri greeter` | GTK | rakuos-niri-iso | | `images/rakuos-hyprland` | Hyprland under uwsm with the Noctalia shell and noctalia-greeter | GTK | none | | `images/rakuos-gamescope` | Steam Gaming Mode with a Plasma desktop session, `kernel-rakuos-deck` with the `-deck` builds of the RakuOS-signed modules (staging), Steam Deck support packages; no NVIDIA variant | Qt, from KDE | none | Bugs: [rakuos-kde](https://rakuos.org/bugs/p/rakuos-images-rakuos-kde), [rakuos-gnome](https://rakuos.org/bugs/p/rakuos-images-rakuos-gnome), [rakuos-cosmic](https://rakuos.org/bugs/p/rakuos-images-rakuos-cosmic), [rakuos-niri](https://rakuos.org/bugs/p/rakuos-images-rakuos-niri), [rakuos-hyprland](https://rakuos.org/bugs/p/rakuos-images-rakuos-hyprland), [rakuos-gamescope](https://rakuos.org/bugs/p/rakuos-images-rakuos-gamescope). ## Live ISOs ### Edition ISO repos (Tier 2) `iso/rakuos-cosmic-iso`, `iso/rakuos-gnome-iso`, `iso/rakuos-kde-iso`, `iso/rakuos-niri-iso`, `iso/rakuos-minimal-iso`, `iso/rakuos-hyprland-iso` CI configuration and hooks that build each live ISO with rakuos-forge from `quay.io/rakuos/rakuos-`. The live session boots Fedora's signed kernel instead of kernel-rakuos so that it starts with Secure Boot on; the installed system runs kernel-rakuos. ISOs are published to dl.rakuos.org and SourceForge, with file names like `rakuos-kde-YYYY.MM.DD-amd64.iso`. - `rakuos-minimal-iso` runs its live session from rakuos-kde, installs `rakuos-minimal` and adds a text-mode installer. - `rakuos-hyprland-iso` builds the Hyprland ISO from `quay.io/rakuos/rakuos-hyprland` (since bdf2236, released 2026-10-28). Its live session (greetd autologin into Hyprland with Noctalia, installer started from a Hyprland autostart hook, passwordless polkit for liveuser, an `oci` transport in the live policy.json) is set up by rakuos-forge's livesys step. Bugs: [cosmic](https://rakuos.org/bugs/p/rakuos-iso-rakuos-cosmic-iso), [gnome](https://rakuos.org/bugs/p/rakuos-iso-rakuos-gnome-iso), [kde](https://rakuos.org/bugs/p/rakuos-iso-rakuos-kde-iso), [niri](https://rakuos.org/bugs/p/rakuos-iso-rakuos-niri-iso), [minimal](https://rakuos.org/bugs/p/rakuos-iso-rakuos-minimal-iso), [hyprland](https://rakuos.org/bugs/p/rakuos-iso-rakuos-hyprland-iso). ### iso-base (Tier 3) `iso/iso-base`. Bugs: https://rakuos.org/bugs/p/rakuos-iso-iso-base Shared files that the ISO builds clone: an Anaconda profile, dock pins for the installer and live-session tweaks. Most of it is no longer used. ## Kernel modules, drivers and handheld hardware ### akmods (Tier 2) `packages/drivers/akmods`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-drivers-akmods A fork of akmods 0.6.2 that can build with clang. Image builds no longer use akmods or DKMS on either channel (signed-kmods replaces them; stable stopped on 2026-10-17). `akmods.service` does not run on an installed RakuOS system, and modules built there would not load. ### mesa (Tier 2) `packages/drivers/mesa`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-drivers-mesa Fedora rawhide's mesa rebuilt for RakuOS, with i686 libraries. rakuos-base installs it over Fedora's. ### NVIDIA RakuOS rebuilds the NVIDIA driver from negativo17's SRPMs. Its repo is not public, but NVIDIA bugs go to the tracker project https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers. The `-nvidia` image variants (`quay.io/rakuos/rakuos--nvidia[-v3|-v4]`) install it from repo.rakuos.org; on `main` the kernel module is built with DKMS during the image build, on `staging` it is the prebuilt `rakuos-kmod-nvidia-staging`. `-nvidia-legacy` images (staging) use the 580xx driver and `rakuos-kmod-nvidia-580xx-staging`. The `setup-nvidia` and `setup-nvidia-legacy` scripts in rakuos-core install DKMS packages into the overlay, whose modules the kernel now refuses. ### Handheld packages (Tier 2) `packages/handheld/jupiter-fan-control`, `jupiter-hw-support`, `steamdeck-dsp`, `steamdeck-firmware`, `galileo-mura`, `noise-suppression-for-voice` Steam Deck support for the gamescope image: fan control, hardware support scripts and firmware updaters, the audio DSP profiles, OLED Wi-Fi and Bluetooth firmware, display correction tools and noise suppression. The image installs the first four; the other two come in as dependencies. ## Security model and core system packages RakuOS removes SELinux and uses AppArmor. These repos rebuild Fedora packages to make that work. apparmor, systemd, ostree and rpm share one component page on how RakuOS differs from Fedora. ### apparmor (Tier 1) `packages/apparmor/apparmor`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-apparmor-apparmor AppArmor 5.0.2 userspace, which Fedora does not ship: parser, `aa-*` tools, libraries and upstream sample profiles in `/etc/apparmor.d`. Its preset enables `apparmor.service`. It obsoletes `setroubleshoot`. RakuOS patches the avahi-daemon and dnsmasq profiles. ### apparmor.d-rakuos (Tier 2) `packages/apparmor/apparmor.d-rakuos`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-apparmor-apparmor-d-rakuos A fork of apparmor.d (1500+ profiles) packaged as `apparmor.d-fedora`, in complain mode by default. No image installs it as of 2026-10-13, although its README calls it RakuOS's default policy. ### systemd (Tier 1) `packages/system/systemd`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-system-systemd Fedora rawhide's systemd rebuilt with AppArmor support switched on, so `AppArmorProfile=` and `ConditionSecurity=apparmor` work. The build also applies a patch meant to remove upstream's age and user-session data collection. ### ostree (Tier 1) `packages/system/ostree`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-system-ostree Fedora's ostree built without SELinux support, released as `100.rakuos` so it outranks Fedora's build. Without this, finalizing a staged deployment failed while trying to refresh the SELinux policy. ### rpm (Tier 1) `packages/rpm-tools/rpm`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rpm-tools-rpm Fedora rawhide's rpm built without the SELinux plugin, plus i686 `rpm-libs`. Removing `selinux-policy` no longer pulls out rpm-build and akmods. ### build-reproducibility-srpm-macros (Tier 2) `packages/rpm-tools/build-reproducibility-srpm-macros`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rpm-tools-build-reproducibility-srpm-macros Fedora's build-reproducibility macros rebuilt without `Requires: selinux-policy-any`, so rpm-build and akmods install without SELinux. ### scx-scheds and scx-tools (Tier 2) `packages/system/scx-scheds`, `packages/system/scx-tools`. Bugs: [scx-scheds](https://rakuos.org/bugs/p/rakuos-packages-system-scx-scheds), [scx-tools](https://rakuos.org/bugs/p/rakuos-packages-system-scx-tools) sched_ext CPU schedulers and `scx_loader`. The image sets `scx_cosmos` in Auto mode in `/etc/scx_loader.toml` but does not enable `scx_loader.service`; rakuos-system enables it when the user picks a scheduler. ### fastfetch (Tier 3) `packages/system/fastfetch`. Fedora's fastfetch spec built from the latest upstream release. The RakuOS look comes from the preset in rakuos-branding. ### audit (none) `packages/system/audit`. Template README only. Images use Fedora's audit. ## Package repository and build tooling ### rakurpm (Tier 2) `packages/rpm-tools/rakurpm`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-rpm-tools-rakurpm RakuRPM, the Rust server behind repo.rakuos.org. Its `/rakuos.repo` defines `[rakuos]`, plus `[rakuos-v3]` (priority 10) and `[rakuos-v4]` (priority 5), which only the v3 and v4 images enable. The signing key is served at `/pubkey.gpg`. It can also mirror upstream releases and COPR projects and re-sign them. ### specs (Tier 3) `packages/specs`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-specs Third-party and repackaged specs: cemu, ryujinx, lsfg-vk, gpu-screen-recorder, obs-studio-plugin-vkcapture, printer-driver-oki, `fedora-logos` with RakuOS art for the Anaconda installer, and `webkit2gtk3-compat`, a shim for Cloudflare WARP. Only webkit2gtk3-compat has a build pipeline. ### copr, templates/package-template, builder, repo.rakuos.org/zed (none) `packages/copr` is an older copy of `packages/specs`. The other three hold only a template README. ## Retired repos Archived on GitLab and not cloned. Steer users on these off them. - `images/rakuos-scripts`: superseded; its helper scripts now ship in rakuos-core (`/usr/libexec/rakuos/`). - `packages/rakuos/kernel-p03` and `packages/rakuos/kernel-p03-deck`: the P03 kernels (release strings containing `p03raku`). Images dropped them on 2026-10-06. Users still on a P03 image should switch to the matching current image, for example from the RakuOS System app. ## Other packaged software ### firefox (Tier 2) `packages/browsers/firefox`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-browsers-firefox Fedora's Firefox rebuilt to allow the OpenH264 codec download, drop Fedora's start page and new-tab pin, and identify as "Mozilla Firefox for RakuOS". Every edition lists it in `packages.list`, so it lives in the overlay and `rum upgrade` updates it. ### ollama (Tier 2) `packages/ai-tools/ollama`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-ai-tools-ollama Upstream ollama binaries packaged with `ollama.service` and GPU backend subpackages (`-cuda`, `-vulkan`, `-rocm`). No image includes it; `rakuos setup-ollama`, also offered in the welcome app, installs it. ### cosmic-greeter (Tier 2) `packages/cosmic/cosmic-greeter`. Bugs: https://rakuos.org/bugs/p/rakuos-packages-cosmic-cosmic-greeter Fedora's cosmic-greeter rebuilt without its `greetd-selinux` dependency. The rest of COSMIC comes from Fedora and Terra at image build time. ### cosmic-ext-applet-sysinfo, goverlay, streamcontroller (Tier 3) `packages/cosmic/cosmic-ext-applets/cosmic-ext-applet-sysinfo` (a COSMIC panel applet the COSMIC image installs), `packages/gaming/goverlay` (GOverlay, offered in the welcome app) and `packages/gaming/tools/streamcontroller` (StreamController for Elgato Stream Deck). ### Other COSMIC repos (none) 23 repos under `packages/cosmic/` hold only a template README: cosmic-applets, cosmic-app-library, cosmic-bg, cosmic-comp, cosmic-edit, cosmic-files, cosmic-icon-theme, cosmic-idle, cosmic-launcher, cosmic-notifications, cosmic-osd, cosmic-panel, cosmic-player, cosmic-randr, cosmic-screenshot, cosmic-session, cosmic-settings, cosmic-settings-daemon, cosmic-term, cosmic-wallpapers, cosmic-workspaces, cutecosmic and xdg-desktop-portal-cosmic. --- # How RakuOS differs from Fedora RakuOS is built on Fedora packages (Fedora 44 on the stable channel, Fedora 45 on staging), but several core pieces are replaced or rebuilt: `dnf` is rum, rpm-ostree is absent, SELinux is removed in favor of AppArmor, the kernel and its out-of-tree modules are RakuOS's own and signed with the RakuOS key, and `sudo` and the core utilities are Rust rewrites. This page lists the differences an assistant or user is most likely to trip over, with what to do instead of the Fedora habit. As of 2026-10-15: stable images from `main` (Fedora 44), staging images from `staging` (Fedora 45). For the overlay and update model, see [How RakuOS works](https://rakuos.org/ai/01-architecture). ## Quick translation from Fedora advice | Fedora or Silverblue advice | On RakuOS | |---|---| | `sudo dnf install ` | Works, because `dnf` runs rum, but say `sudo rum install `. It installs into the overlay. | | `sudo dnf upgrade` / `sudo dnf update` | Upgrades overlay packages only. Full update: `sudo rum system-upgrade`, then reboot. | | `sudo dnf system-upgrade download --releasever=45` | Refused on an installed system. A new Fedora release arrives as a new image through `bootc upgrade` or `bootc switch`. | | `rpm-ostree install ` / `rpm-ostree upgrade` / `rpm-ostree rollback` | rpm-ostree is not installed. Use `sudo rum install `, `sudo rum system-upgrade`, `sudo bootc rollback`. | | `rpm-ostree kargs --append=` | `sudo bootc loader-entries set-options-for-source --source rakuos-user --options ""`, or the RakuOS System app's Kernel Parameters. | | `sudo rpm -i file.rpm` | `sudo rum install ./file.rpm`. Plain rpm writes outside rum's records. | | `setenforce 0`, `restorecon`, `chcon`, `semanage`, `audit2allow` | Not applicable: SELinux is not used. See [Security](#security-apparmor-instead-of-selinux). | | "Enable RPM Fusion" | Already configured. Enabled by default on stable; disabled by default on staging (like Terra on both). Turn it on in the welcome app's Third-Party Repositories page or with `sudo rum config-manager --set-enabled 'rpmfusion-*'`. Its NVIDIA packages and steam are excluded on purpose. | | "Drop a `.repo` file into `/etc/yum.repos.d`" | rum's own dirs: `/etc/rum.repos.d` for the user's repos, `/usr/share/rum/repos.d` for package-shipped ones. Add with `sudo rum config-manager addrepo --from-repofile=`; enable or disable with `--set-enabled`/`--set-disabled`. See [rum](https://rakuos.org/ai/components/rum#repo-files). | | "Install akmod-nvidia from RPM Fusion" / the NVIDIA `.run` installer | Do not. Use an `-nvidia` image, or `-nvidia-legacy` for Maxwell, Pascal and Volta GPUs. | | "Install `akmod-` / `dkms-`", "sign the module with your own MOK" | Do not: a module built or signed on the machine is refused (`module.sig_enforce=1`, lockdown). Use the image's RakuOS-signed `rakuos-kmod-*` package or ask RakuOS to add the module. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). | | "Disable Secure Boot" or "add `module.sig_enforce=0`/`lockdown=none`" to get a driver working | Not a fix on RakuOS, and it breaks anti-cheat readiness. Same page. | | "Install the kernel-devel for your kernel" | The kernel package is `kernel-rakuos-v2/v3/v4` (`-staging` on staging); the image ships its `-devel`, but locally built modules will not load. | | `flatpak remote-add flathub …` | Flathub is set up by the installer on a normal install; check with `flatpak remotes` first. | ## Packages - **`dnf` and `dnf5` are rum.** The `rum-dnf-shim` package provides `/usr/bin/dnf` and `/usr/bin/dnf5` and replaces dnf, dnf5, yum and microdnf. dnf plugins and `dnf-automatic` are not installed. See [rum](https://rakuos.org/ai/components/rum). - **No rpm-ostree.** Package layering is the `/usr` overlay managed by rum. - **rpm** is rebuilt from Fedora rawhide (RPM 6) without the SELinux plugin. - **ostree** is rebuilt without SELinux support, release `100.rakuos`, so it outranks Fedora's build. - **Repos**: Fedora, `rakuos` (repo.rakuos.org; images built for v3 or v4 also enable `rakuos-v3`/`rakuos-v4`), RPM Fusion free and nonfree (NVIDIA packages and steam excluded; **disabled** by default), and Terra (installed, **disabled**; AppArmor and scx packages excluded), the same on both channels. Fedora's own `goverlay` is excluded too (RakuOS builds it). From 2026-10-22 the excludes are a rum repo override shipped by `rakuos-rum-repo-overrides` (`/usr/share/rum/repos.override.d/20-rakuos.repo`) instead of edits in the repo files; see [rum](https://rakuos.org/ai/components/rum#repo-overrides). Current images keep these files in `/usr/share/rum/repos.d` (stable images before 2026-10-17 in `/etc/yum.repos.d`); rum reads both, and user changes go to `/etc/rum.repos.d`. - **`rakuos-release`** replaces Fedora's release packages: its `rakuos-release-common` subpackage obsoletes `fedora-release`, `-common` and `-identity-*` and provides `system-release(N)`, so `rum list --base | grep '^fedora-release'` finding nothing is expected. - **Rebuilt Fedora packages** from repo.rakuos.org include mesa (from rawhide, with i686), Firefox (allows the OpenH264 download, no Fedora start page, branded "Mozilla Firefox for RakuOS"), and cosmic-greeter (without its greetd-selinux dependency). - rum removes SELinux requirements from repo packages while resolving (`selinux-policy`, `policycoreutils`, `rpm-plugin-selinux`), because they can never be satisfied here. ## Security: AppArmor instead of SELinux - SELinux is off at every level: the RakuOS kernels are built without SELinux and with the LSM order `lockdown,yama,integrity,apparmor,bpf,landlock`, `selinux-policy` is removed, the installer installs with SELinux disabled, and `setroubleshoot` is obsoleted. `libselinux` stays because many programs link against it. The old kernel arguments `selinux=0 security=apparmor apparmor=1` were dropped from `/usr/lib/bootc/kargs.d/10-rakuos.toml` on 2026-10-14 because they no longer change anything. - That file now sets `lockdown=integrity intel_iommu=on iommu.passthrough=0 iommu.strict=1 module.sig_enforce=1 sysctl.kernel.kexec_load_disabled=1`: only signed modules load, and `/dev/mem`, CPU MSR writes and hibernation are blocked. These meet Easy Anti-Cheat Linux v2's requirements; check with `rakuos eac-check`. - AppArmor 5.0.2 from RakuOS's own package (Fedora ships none) is the only mandatory access control. `apparmor.service` is enabled. The active profiles are the upstream AppArmor profiles in `/etc/apparmor.d`, with RakuOS patches for avahi-daemon, dnsmasq (including Waydroid) and curl reading `/etc/pki`. - The larger apparmor.d profile collection (`apparmor.d-fedora`) is built by RakuOS but not installed on any image as of 2026-10-14. - systemd is rebuilt with AppArmor support, so units can use `AppArmorProfile=`. - Denials: `auditd` runs, so AppArmor denials are written to the audit log as `AVC` records with an `apparmor="DENIED"` field. They are not SELinux events. ```bash sudo aa-status # read-only: loaded profiles and their modes sudo ausearch -m AVC -ts today | grep apparmor # read-only: today's AppArmor denials ``` Do not disable `apparmor.service` as a fix. Report denials against the project that owns the program. ## Kernel and drivers - The kernel is `kernel-rakuos-v2`, `-v3` or `-v4` (the x86-64 level of the image; `-staging` on the staging channel): the CachyOS kernel with the BORE scheduler, no SELinux. Both channels are on CachyOS 7.3.0 (stable since 2026-10-23); example releases: `7.3.0-rakuos.1.v4.fc44` (stable), `7.3.0-rakuos.2.v4.staging.fc45` (staging). Fedora's `kernel` package is removed. The gamescope image uses `kernel-rakuos-deck`. Both channels' kernels have the RakuOS certificate built in as a trusted key (stable since 7.3.0, 2026-10-23). - The old P03 kernels (release strings containing `p03raku`) are retired; images with them are no longer built. - **Out-of-tree modules** are built and signed by RakuOS, never on the user's machine. They are `rakuos-kmod-` packages (`-staging` on staging). Images built from 2026-10-23 on ship only Broadcom `wl` and `v4l2loopback` (plus NVIDIA on `-nvidia` images); every other module (Xbox `xone`/`xpadneo`/`xpad-noone`, racing wheels, capture cards, sensors, VirtualBox, OpenRazer, MT7927, xtables-addons, Intel IPU6, Intel Vision) is an opt-in overlay package, installed from RakuOS System's Drivers page. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). - **NVIDIA**: `-nvidia` images (`quay.io/rakuos/rakuos--nvidia[-v3|-v4]`) ship the NVIDIA driver, rebuilt by RakuOS from negativo17's packages, with a RakuOS-signed kernel module. `-nvidia-legacy` images ship the 580xx driver for Maxwell, Pascal and Volta GPUs. Switch with the RakuOS System app. `rakuos setup-nvidia`/`setup-nvidia-legacy` still exist but install DKMS packages whose modules the kernel refuses; do not use them. NVIDIA bugs go to https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers. - **Secure Boot**: the image build signs the kernel with the RakuOS key. Users enroll that key once in MOK Manager with password `rakuos` (see [installer](https://rakuos.org/ai/components/rakuos-installer#after-the-install-secure-boot-enrollment)); there is no per-machine key. - akmods and DKMS are not used on installed systems: `akmods.service` does not run, and an `akmod-*` or `dkms-*` package installed with rum produces an unsigned module the kernel refuses. ## Command-line tools - `sudo` is **sudo-rs**. GNU sudo, su and visudo are kept as `gnu_sudo`, `gnu_su`, `gnu_visudo`. `sudo rakuos setup-sudo ` changes the default. - Core utilities (`cp`, `mv`, `echo`, …) are **uutils-coreutils**, and `ls` is **lsd** and `cat` is **bat**. These are real replacements set system-wide through `alternatives` (`/usr/bin/ls` → `/etc/alternatives/ls` → `/usr/bin/lsd`), not shell aliases, so scripts get them too. Their output and options differ from GNU's; on a terminal, `cat` draws a frame with line numbers and opens a pager for long files (press `q`). GNU versions are kept as `gnu_ls`, `gnu_cat`, `gnu_cp` and so on. If a GNU-only option fails, use the `gnu_*` binary, or `sudo rakuos setup-uutils gnu` to make GNU the default (`sudo rakuos setup-uutils uutils` switches back). - The default shell for new users is **fish**. `rakuos shell ` changes it. ## Filesystem layout - `/usr` is the image plus the overlay; see [rakuos-core](https://rakuos.org/ai/components/rakuos-core). - `/opt` is a symlink to `/var/opt`; packages that install into `/opt` are moved by rum to `/usr/lib/opt/`. - `/usr/local` is a symlink to `/var/usrlocal`, outside the overlay, so it survives resets and is the right place for hand-installed tools. - Home directories are under `/var/home`. ## Updates - No automatic updates are enabled by default: no `bootc-fetch-apply-updates.timer`, no dnf-automatic. - `rpm-ostreed-automatic.timer` is masked. - Normal full update: Software Center Updates page, or `sudo rum system-upgrade`, then reboot. ## Tuning defaults (rakuos-settings) zram sized to all of RAM with zstd (`/usr/lib/systemd/zram-generator.conf`); `vm.swappiness=100`; the journal capped at 50 MB; NTP from time.cloudflare.com; default service start timeout 15 s and stop timeout 10 s. Override with files in `/etc` (`/etc/sysctl.d/`, `/etc/systemd/zram-generator.conf`, `/etc/systemd/journald.conf.d/`). --- # Kernel modules, Secure Boot and the RakuOS key RakuOS builds its kernels and its out-of-tree kernel modules (NVIDIA, Broadcom Wi-Fi, Xbox controllers, wheels and others) itself and signs them with the RakuOS key. Nothing is compiled or signed on the user's machine any more: there is no per-machine signing key, and the kernel only loads signed modules. Users enroll the RakuOS key once in MOK Manager so a RakuOS kernel can boot with Secure Boot on. As of 2026-10-17: stable (`latest`, RakuOS 44) and staging (`staging`, RakuOS 45) now work the same way here; they differ only in package and image suffixes. Bugs: kernel https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel; enrollment and `rakuos enroll-secureboot-key` https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core; a missing or broken `rakuos-kmod-*` module: the signed-kmods project, or rakuos-base if that project is not listed on the tracker. ## Stable and staging Both channels run the RakuOS kernel (`kernel-rakuos-v2/v3/v4`, with `-staging` on staging; the gamescope image runs `kernel-rakuos-deck-…`), signed with the RakuOS key and with the RakuOS certificate built in as a trusted key, and both ship the prebuilt, signed `rakuos-kmod-*` modules. Package names on staging end in `-staging`. Stable switched over on 2026-10-17 (rakuos-base `main` `8551844`); stable images built before that compiled NVIDIA with DKMS and `broadcom-wl`/`v4l2loopback` with akmods during the image build. ## What ships where - **Kernel image (`vmlinuz`)**: signed with the RakuOS key during the image build (`sbsign`). Fedora's shim and GRUB accept it only once the RakuOS key is enrolled as a MOK. The kernel's own in-tree modules are signed with a per-build key from the kernel build. - **shim and GRUB** on the ESP are Fedora's signed builds. From 2026-10-16 `rakuos-bootloader-update` updates them from the booted image (upgrade only); with Secure Boot on it does so only if the firmware trusts the Microsoft UEFI CA 2023, otherwise it skips and a firmware update is needed. See [rakuos-core](https://rakuos.org/ai/components/rakuos-core#shim-and-grub-on-the-esp). - **Out-of-tree modules**: the signed-kmods repo builds every module in its `modules.list` in CI from the akmod or DKMS package in the Fedora, RPM Fusion, Terra or RakuOS repos, signs each `.ko` with the RakuOS key and checks the signature. Package names: `rakuos-kmod-` (stable kernel), `-staging`, `-deck` (gamescope's `kernel-rakuos-deck`), `-deck-staging`. Each ISA level has its own build in its own repo under the same name. - Each `rakuos-kmod-` provides `-kmod`, `kmod-` and whatever the source akmod/DKMS package provided, so companion packages (`broadcom-wl`, `xone`, `nvidia-kmod-common`, …) install against it, and it **conflicts with `akmod-` and `dkms-`**. - **Modules every image ships** (images built from 2026-10-23 on): only `wl` (Broadcom Wi-Fi) and `v4l2loopback`. The gamescope image ships their `-deck` builds. An image build fails if one of these packages has no modules for the image's kernel. `-nvidia` images add `rakuos-kmod-nvidia`, `-nvidia-legacy` images `rakuos-kmod-nvidia-580xx`. - **Every other module is opt-in** from those images on, installed into the overlay by the user (RakuOS System's Drivers page, or `rum install`). Images built before 2026-10-23 also shipped the modules below, so **after updating to a newer image they are gone** until the user installs them; an Xbox controller, racing wheel or sensor tool that stopped working after an update is almost always this. Each package requires its `*-kmod-common` (or companion) package from the repo its source comes from, so that repo must be on first (Terra and RPM Fusion are off by default): | Module | For | Needs | |---|---|---| | `xone` | Xbox wireless adapter, wired Xbox One / Series pads | Terra | | `xpadneo` | Xbox One / Series pads over Bluetooth | Terra | | `xpad-noone` | Xbox 360 and original Xbox pads | Terra | | `hid-fanatecff` | Fanatec wheels and bases (force feedback) | Terra | | `hid-tmff2` | Thrustmaster T300RS, T248, TX, TS-XW, T-GT II | Terra | | `t150-driver` | Thrustmaster T150 / TMX | Terra | | `new-lg4ff` | Logitech G25, G27, G29, G920, G923 | Terra | | `logitech-trueforce` | Logitech TrueForce haptics (G PRO, G923 TrueForce) | Terra | | `ayaneo-leds` | AYANEO handheld RGB LEDs | Terra | | `sc0710` | YUAN SC0710 capture cards (e.g. Elgato 4K60 Pro) | Terra | | `nct6687d` | Nuvoton NCT6687 fan/temperature sensors (MSI and other boards) | Terra | | `ryzen_smu` | AMD Ryzen SMU access (ryzenadj, monitoring tools) | Terra | | `zenergy` | AMD Zen CPU power/energy readings | Terra | ```bash sudo rum config-manager --set-enabled terra # changes system: enables Terra. Undo: --set-disabled terra. No reboot. sudo rum install rakuos-kmod-xone # changes system: installs into the overlay; add the system's suffix (-staging, -deck, -deck-staging). Reboot. Undo: sudo rum remove ``` - **VirtualBox is the exception**: `rakuos-kmod-VirtualBox` is built but not in any image, because it pulls in VirtualBox itself. Users who want VirtualBox install it into the overlay (see below). - **OpenRazer is left out too** (images built from 2026-10-16 on; earlier ones still ship it): `rakuos-kmod-openrazer` is still built, but the module misbehaved with Razer's RGB hub. Users who want OpenRazer install it into the overlay (see below). - **MediaTek MT7927 is opt-in too** (images built from 2026-10-17 on; earlier ones ship it): `rakuos-kmod-mediatek-mt7927` is still built, but a user reported problems with a MediaTek USB Wi-Fi adapter with it loaded. Users whose MT7927 hardware needs it install it into the overlay: `sudo rum install rakuos-kmod-mediatek-mt7927` (add the system's suffix, e.g. `-staging`; changes system; reboot; undo with `sudo rum remove`). - **xtables-addons, Intel IPU6 and Intel Vision are opt-in too** (images built from 2026-10-23 on; earlier ones ship them). Their `rakuos-kmod-*` packages are still built, but each requires the `*-kmod-common` package from the repo its source comes from, so that repo has to be enabled first: | Module | Package | Needs | For | |---|---|---|---| | `xtables-addons` | `rakuos-kmod-xtables-addons` | `xtables-addons-kmod-common` (RPM Fusion) | extra iptables/nftables matches and targets (`xt_geoip` etc.) | | `intel-ipu6` | `rakuos-kmod-intel-ipu6` | `intel-ipu6-kmod-common` (Terra) | Intel IPU6 laptop cameras (psys and sensor drivers) | | `intel-vision` | `rakuos-kmod-intel-vision` | `intel-vision-kmod-common` (RPM Fusion) | Intel Vision Sensing Controller (camera on some IPU6 laptops) | ```bash sudo rum config-manager --set-enabled 'rpmfusion-*' # changes system: enables RPM Fusion (use terra for intel-ipu6). Undo: --set-disabled. No reboot. sudo rum install rakuos-kmod-xtables-addons # changes system: installs into the overlay; add the system's suffix (-staging, -deck, -deck-staging). Reboot. Undo: sudo rum remove ``` Don't suggest `akmod-xtables-addons`, `akmod-intel-ipu6` or `akmod-intel-vision`: they build an unsigned module the kernel refuses, and they conflict with the `rakuos-kmod-*` package. ```bash rum list --base | grep rakuos-kmod # read-only: signed module packages the image ships, and their suffix (none on stable, -staging, -deck, …) rum list | grep rakuos-kmod # read-only: opt-in signed modules the user installed into the overlay (everything but wl, v4l2loopback and NVIDIA) rum search rakuos-kmod # read-only: which rakuos-kmod packages the enabled repos offer modinfo -F signer # read-only: who signed a module; RakuOS modules show the RakuOS key ``` RakuOS System has a **Drivers** page listing the opt-in `rakuos-kmod-*` packages for the running kernel's channel (packages the image ships are left out, NVIDIA is never listed), with what each driver is for and the repo it needs. Install puts the package into the overlay (`sudo-rs -n rum install -y`) and asks to reboot; Remove runs `rum remove`. With the overlay turned off the page warns and its buttons are disabled. ## Keeping installed modules in step with the kernel Modules the image ships come with the image. Modules the user installed into the overlay (`rum list | grep rakuos-kmod`) are built for one kernel each, so they have to follow kernel changes: - **Each image says its kernel.** Every image carries the label `org.rakuos.kernel.release` (the `uname -r` it boots). - **Each kmod build says its kernels.** `rakuos-kmod-*` packages provide `rakuos-kmod-kernel = ` once per kernel they're built for (one per ISA level). Builds from signed-kmods `ed5a103` on have it, on both channels; older builds don't. - **`rum kmod-upgrade` moves them to a new kernel.** It reads the label of the image `bootc upgrade` would pull (or takes `--kernel R`; with neither, the running kernel). Kmods built for another channel are swapped in one transaction, e.g. `rakuos-kmod-xone` to `rakuos-kmod-xone-staging` when moving to staging, or to `-deck`/`-deck-staging` for the gamescope image's kernel; `packages.list` is renamed to match even when the install can't happen yet. The rest are upgraded to their builds for that kernel, with whatever newer dependencies they need. A module with no build for that kernel yet prints `warning: no build for kernel yet: ` and the image update goes on. - **It runs before every image update:** `rum system-upgrade` (first, before the overlay upgrade and before a release soft reset, so `packages.list` names the right builds), the Software Center (before each image update), RakuOS System's update (before it) and image switch (after `bootc switch`). - **Outside image updates, kmod updates must match the running kernel.** `rum upgrade` and `rum check-upgrade` (and so the Software Center's update list) only offer a `rakuos-kmod-*` build whose `rakuos-kmod-kernel` provides include the running kernel. A rebuild for the same kernel shows and installs as usual; a build for a newer kernel waits for `kmod-upgrade`. Builds without the provide (older ones) aren't filtered. - **Their dependencies wait for them.** While an installed kmod has no update for the kernel, the overlay packages it requires (`*-kmod-common`, firmware, companions such as `VirtualBox` or `openrazer`) stay at their installed versions; `rum upgrade` prints `Kept at the versions the installed kernel modules need: …`. They update together with the kmod. - **The Software Center hides kmod updates the image update will handle:** when the available image update runs another kernel, `rakuos-kmod-*` rows are left out of the package updates. ```bash rum repoquery --provides rakuos-kmod--staging | grep rakuos-kmod-kernel # read-only: kernels a build is for rum repoquery --whatprovides "rakuos-kmod-kernel = $(uname -r)" # read-only: every kmod build for the running kernel sudo rum kmod-upgrade --dry-run # read-only preview of the swaps and upgrades for the incoming image's kernel sudo rum kmod-upgrade # changes system: moves overlay kmods to the incoming image's kernel builds. Takes effect after the image update and reboot. Undo: sudo rum history undo ``` A kmod that "has an update in the repo" but isn't offered is usually built for a kernel the system isn't running yet; it arrives with the image update. Don't suggest `rum install ` or downloading the RPM to force it: the module would be for a kernel that isn't booted. ## Kernel arguments rakuos-settings ships the image's kernel arguments in `/usr/lib/bootc/kargs.d/10-rakuos.toml`: ``` lockdown=integrity intel_iommu=on iommu.passthrough=0 iommu.strict=1 module.sig_enforce=1 sysctl.kernel.kexec_load_disabled=1 ``` - `module.sig_enforce=1` and `lockdown=integrity`: only signed modules load. RakuOS's commit message for this change lists what else lockdown integrity blocks: writing to `/dev/mem` or CPU MSRs (undervolting and TDP tools), and hibernation. - `intel_iommu=on`, `iommu.passthrough=0`, `iommu.strict=1`: IOMMU on, no DMA passthrough. - `sysctl.kernel.kexec_load_disabled=1`: kexec is off from boot; `/usr/lib/sysctl.d/70-rakuos-settings.conf` also sets `kernel.kexec_load_disabled = 1`. - `selinux=0`, `security=apparmor` and `apparmor=1` are no longer passed: the RakuOS kernels are built without SELinux and with the LSM order `lockdown,yama,integrity,apparmor,bpf,landlock`. - The DKMS signing config (`/etc/dkms/framework.conf.d/rakuos.conf`) is gone. Users add their own arguments in **RakuOS System > System > Kernel Parameters…** (source `rakuos-user`); that does not remove the image's arguments, but the user's come after them on the command line, so for a parameter that can be set either way the user's value wins (the maintainer has tested this). That makes it the per-machine override for the IOMMU arguments: `intel_iommu=off` there turns the Intel IOMMU off, and `iommu.passthrough`/`iommu.strict` then have no effect. It does not work for the other two: `module.sig_enforce` can only be switched on (`module.sig_enforce=0` is ignored once it's 1), and lockdown can only be raised, so `lockdown=none` changes nothing. RakuOS System has no switch to turn lockdown or signature enforcement off. Use the IOMMU override only for hardware the IOMMU breaks, never as an anti-cheat or driver fix: with it, `rakuos eac-check` fails the IOMMU item and EAC v2 games won't start. See [TPM not found or TPM unlock stopped](https://rakuos.org/ai/troubleshooting/tpm-missing-after-iommu). ```bash gnu_cat /proc/cmdline # read-only: arguments in effect gnu_cat /sys/kernel/security/lockdown # read-only: [integrity] when lockdown is on gnu_cat /sys/module/module/parameters/sig_enforce # read-only: Y when only signed modules load ``` ## Enrolling the RakuOS key (MOK) The installer queues only the RakuOS certificate (`/usr/share/rakuos/sb_pubkey.der`, subject `CN=RakuOS Secure Boot`) when it runs with UEFI and Secure Boot on. Earlier installs also enrolled a per-machine module signing key; that key is no longer generated or used. ```bash mokutil --sb-state # read-only: SecureBoot enabled/disabled mokutil --list-enrolled | grep -E 'Subject|Issuer' # read-only: enrolled MOKs sudo rakuos enroll-secureboot-key # changes system: queues the RakuOS key for enrollment and queues every other MOK that isn't well known for deletion; deletes /var/lib/rakuos-user-MOK. Finish in MOK Manager at the next boot. UEFI only. ``` What `enroll-secureboot-key` keeps: the RakuOS key, keys from Universal Blue (`O = Universal Blue`, including its akmods key), and keys from Microsoft and Linux/BSD vendors (Red Hat/Fedora, CentOS, AlmaLinux, Rocky, Oracle, Canonical/Ubuntu, Debian, SUSE/openSUSE/Novell, Proxmox, FreeBSD, NetBSD, OpenBSD). What it queues for deletion: every other MOK, including locally generated ones that name a vendor (subjects containing "Machine Module Signing", "akmods", "DKMS", "local signing" or "Module Signature key"), such as the old per-machine key (`CN=RakuOS Machine Module Signing Key`) that installers before 2026-10-15 enrolled. It prints `KEEP:`, `Removing:` or `SKIP:` per key, and "Nothing to do" when nothing needs changing. In short, it removes only **unknown keys**, in practice keys made on a machine (self-made signing keys, akmods/DKMS keys, the old per-machine RakuOS key), whichever distribution enrolled them. Microsoft's keys and other Linux and BSD distributions' vendor keys are left in place. It edits only the MOK list (shim's `MokList`); the firmware's own Secure Boot databases (`db`/`KEK`, which hold Microsoft's keys) are never touched, so Windows and other installed systems keep booting. Nothing is deleted until the user confirms **Delete MOK** at the next boot. At the next boot, in MOK Manager (blue screen): choose **Enroll MOK** and/or **Delete MOK**, then **Continue**, type the password `rakuos`, confirm with **Yes**, then **Reboot**. Undo a deletion only by re-importing that key's certificate with `mokutil --import`, which needs the certificate file; a deleted local akmods/DKMS key is not needed on RakuOS. The RakuOS kernel is signed only with the RakuOS key, so with Secure Boot on it boots only after that key is enrolled. To turn Secure Boot on later: queue the key first with `sudo rakuos enroll-secureboot-key`, then reboot into the firmware settings, enable Secure Boot, and complete MOK Manager on that boot. ## Installing VirtualBox VirtualBox and its `VirtualBox-kmod-common` come from RPM Fusion, which is disabled by default on both channels. ```bash rum list --base | grep rakuos-kmod | head -n 1 # read-only: shows which suffix this system uses (none on stable, -staging on staging) sudo rum config-manager --set-enabled 'rpmfusion-*' # changes system: enables RPM Fusion's package repos (off by default). Undo: --set-disabled 'rpmfusion-*'. No reboot. sudo rum install VirtualBox rakuos-kmod-VirtualBox # changes system: installs into the overlay; add the suffix shown above (-staging, -deck, -deck-staging). Reboot so the module loads cleanly. Undo: sudo rum remove VirtualBox rakuos-kmod-VirtualBox ``` Name the `rakuos-kmod-VirtualBox…` package explicitly; `akmod-VirtualBox` would build an unsigned module that cannot load. ## Installing OpenRazer Its companion package `openrazer` (which provides `openrazer-kmod-common`) comes from Terra, which is disabled by default. ```bash rum list --base | grep rakuos-kmod | head -n 1 # read-only: shows which suffix this system uses (none on stable, -staging on staging) sudo rum config-manager --set-enabled terra # changes system: enables Terra. Undo: --set-disabled terra. No reboot. sudo rum install rakuos-kmod-openrazer # changes system: installs the signed module and Terra's openrazer package into the overlay; add the suffix shown above (-staging, -deck, -deck-staging). Reboot so the module loads cleanly. Undo: sudo rum remove rakuos-kmod-openrazer openrazer ``` Name the `rakuos-kmod-openrazer…` package explicitly; `akmod-openrazer` would build an unsigned module that cannot load. If a Razer RGB hub stops working with it installed, remove it again. ## Locally built modules (akmod, DKMS) - An `akmod-*` or `dkms-*` package installed with rum builds a module on the machine without a RakuOS signature, so it is refused at load time while `module.sig_enforce=1` and lockdown are on. For modules RakuOS builds, the matching `rakuos-kmod-*` package conflicts with the akmod/DKMS package. - `rakuos setup-nvidia` and `setup-nvidia-legacy` still install `dkms-nvidia` / `dkms-nvidia-580xx` (as of rakuos-core `e08616c`), so they produce exactly such a module. Use an `-nvidia` or `-nvidia-legacy` image instead. - A module RakuOS does not build yet: ask for it in the RakuOS Discord or at https://rakuos.org/bugs (signed-kmods adds it to `modules.list`). See [A driver, akmod or DKMS module won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load). --- # rakuos-core, the /usr overlay rakuos-core owns the persistent overlay on `/usr` that holds the user's packages. It mounts the overlay from the initrd, reinstalls the user's packages when the overlay needs rebuilding, protects base-image files from being shadowed, provides overlay resets, and ships the `rakuos` command with its setup and update helpers. As of 2026-10-16 (rakuos-core `65dae17`, built for Fedora 44 and 45). Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core For the boot sequence step by step, see [How RakuOS works](https://rakuos.org/ai/01-architecture). ## What it ships One RPM, `rakuos-core`. | Kind | Name | Job | |---|---|---| | initrd unit | `rakuos-overlay-mount.service` (dracut module `90rakuos-overlay`, binary `/usr/lib/rakuos/rakuos-overlay-mount`) | checks markers, runs queued resets, reseeds, mounts the overlay before the root switch | | unit | `rakuos-overlay-sync.service` → `/usr/libexec/rakuos/rakuos-overlay-sync` | before the login screen: installs or reinstalls `packages.list` when needed | | unit | `rakuos-base-protect.service` → `/usr/libexec/rakuos/rakuos-base-protect` | watches the overlay and removes entries that would hide or replace base-image files | | unit | `rakuos-setup.service` → `/usr/libexec/rakuos/system-setup boot` | routine boot maintenance, e.g. removing module trees of kernels no longer installed | | unit | `rakuos-flatpak-watcher.service` | applies RakuOS fixes when certain Flatpaks are installed | | unit | `rakuos-grub-theme.service` → `grub-theme-deploy`, `rescue-entries` | at shutdown, right after `ostree-finalize-staged` writes a staged update or switch: installs that image's GRUB theme and rewrites the rescue entries | | unit | `rakuos-bootloader-update.service` → `bootloader-update` | at boot: updates shim and GRUB on the ESP from the booted image | | units | `rakuos-rescue-entries.service` and `.path` → `rescue-entries` | at boot and whenever the boot entries change (e.g. `bootc rollback`): keeps the "RakuOS rescue" GRUB submenu current | | timer | `rakuos-os-entries.timer` (2 min after boot) → `os-entries --if-new-deployment` | on the first boot of each new deployment: GRUB entries for other operating systems | | unit | `rakuos-bootc-upgrade.service`, `rakuos-bootc-switch.service` | run `bootc upgrade` or `bootc switch` in the background for the Software Center and RakuOS System apps | | timer | `rakuos-updater.timer` (Thursday 03:00) → `rakuos-updater check` | checks Quay for a newer image; **not enabled by default**, the Software Center can enable it | | timers | `flatpak-cleanup.timer` (every 12 h), `flatpak-repair.timer` (Sunday 04:00), `podman-prune.timer` (Sunday 03:30) | removes unused Flatpak runtimes, repairs the system Flatpak install, prunes podman | | user unit | `rakuos-user.service` | per-user login tasks; shows queued notifications from `/var/lib/rakuos/update-notify.pending` | | command | `/usr/bin/rakuos` | see below | State lives in `/var/lib/rakuos/`: | Path | Meaning | |---|---| | `overlay/upper`, `overlay/work` | the overlay; upper holds every overlay package's files | | `packages.list` | package names the user installed | | `packages-rpm.list`, `local-rpms/` | local `.rpm` files, kept for reinstall | | `rum-rpmdb`, `rum-state/` | rum's overlay database and history | | `current-deploy` | the `ostree=` boot argument last seen; a change triggers a reseed | | `os-version`, `de-name` | Fedora `VERSION_ID` and edition last seen; a change triggers a soft reset | | `overlay.state`, `overlay.dirty` | sync state; `overlay.dirty` means "reinstall `packages.list` at next boot" | | `overlay.reset`, `soft-reset.marker` | a hard or soft reset is queued for the next boot | ## The `rakuos` command `rakuos --help` lists these: ```bash sudo rakuos reset-overlay --soft [--releasever N] # changes system at next boot; see below sudo rakuos reset-overlay --confirm # changes system at next boot, destructive; see below rakuos eac-check [--json] # read-only: anti-cheat (EAC Linux v2) readiness; run with sudo to include the measured-boot check sudo rakuos enroll-secureboot-key # changes system: queues the RakuOS Secure Boot key for MOK enrollment and only unknown (machine-made) MOKs for deletion, at next boot; Microsoft and Linux/BSD vendor keys are kept, firmware db/KEK untouched (UEFI only) sudo rakuos reenroll-tpm2 # changes system: re-binds TPM2 disk unlock, e.g. after a firmware update sudo rakuos setup-uutils # changes system: uutils (default; ls is lsd, cat is bat) or GNU coreutils. Undo: run again with the other mode sudo rakuos setup-sudo # changes system: which program answers to `sudo`. Undo: run again with the old choice rakuos shell # changes the user's login shell ``` Also listed: `setup-gaming`, `setup-virtualization` (KVM/QEMU), `setup-lsfg-vk`, `setup-ollama`, `setup-g733zm-audio` (each changes the system), and `setup-stoat`, which as of `e08616c` has no handler: it prints the usage text and exits with an error. `setup-nvidia` and `setup-nvidia-legacy` are still listed ("Install and configure NVIDIA drivers via DKMS"), but do not suggest them: they install `dkms-nvidia` or `dkms-nvidia-580xx` into the overlay, which builds an unsigned module the kernel refuses (`module.sig_enforce=1`), and they replace the user's kernel arguments (source `rakuos-user`) with the nouveau blacklist. Use an `-nvidia` or `-nvidia-legacy` image instead; see [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). `eac-check` checks Secure Boot, the enrolled MOKs, signed modules, TPM 2.0, measured boot, IOMMU, lockdown, kexec and the BPF LSM, prints `[ OK ]`, `[NOTE]`, `[FAIL]` or `[ ?? ]` with a fix for each, and exits non-zero if any fails. The RakuOS System app shows the same result. See [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready). `enroll-secureboot-key` no longer creates a per-machine key: it removes the old one in `/var/lib/rakuos-user-MOK`, and `rakuos-sign-modules` is gone. Not in `--help`, but real subcommands that the Software Center and RakuOS System app use; they also work from a terminal: ```bash rakuos update check # read-only: overlay packages with updates (JSON) rakuos update check-image # read-only: is a newer image on the current channel? (JSON) rakuos update check-flatpak # read-only sudo rakuos upgrade # changes system: rum upgrade, Flatpak update, then bootc upgrade. Reboot to use the new image. Undo: sudo bootc rollback sudo rakuos system-upgrade # changes system: bootc upgrade only (despite the name). Reboot required. Undo: sudo bootc rollback ``` Installing, removing and listing packages is rum's job; `rakuos` has no commands for it. Note the two upgrade commands: `rum system-upgrade` and `rakuos upgrade` update packages, Flatpaks and the image; `rakuos system-upgrade` updates only the image. ## Resetting the overlay Try targeted fixes first (`sudo rum remove`, `sudo rum restore-base-files`). Back up the package list before any reset: ```bash cp /var/lib/rakuos/packages.list ~/packages.list.bak # changes only the home dir ``` **Soft reset**: `sudo rakuos reset-overlay --soft` - First downloads everything in `packages.list`. If that fails: `ERROR: could not resolve/download all packages in packages.list: …` and `Soft reset aborted — nothing has been changed.` Fix the named package (remove it from the list with `sudo rum remove`, or wait for the repo) and retry. - On success: `RakuOS: soft reset scheduled.` At the next boot the initrd wipes `/var/lib/rakuos` except `packages.list`, local RPMs and the markers, and `rakuos-overlay-sync` reinstalls everything from the downloaded cache. - `--releasever N` downloads the packages from Fedora N's repos, for a reboot into an image built on Fedora N. The Software Center does this automatically before an update to a newer Fedora release. **Hard reset**: `sudo rakuos reset-overlay --confirm`. This cannot be undone. - At the next boot it removes all of `/var/lib/rakuos`, including `packages.list`, except the markers `current-deploy`, `os-version`, `de-name`, `user-sudo`, `user-uutils`, `install-id`, `countme-last-ping`. It then restores the image's prebaked overlay from `/usr/share/factory/var/lib/rakuos/` (Firefox). - Reinstall packages afterwards from the backup: `sudo rum install $(cat ~/packages.list.bak)`. Both resets clear `/var/cache/libdnf5` and remove `/opt` symlinks that point into `/usr/lib/opt`. Neither touches `/etc`, `/home`, Flatpaks or the rest of `/var`. Both need a reboot to finish. Do not try to cancel one by deleting the marker files: the command has already cleared caches (hard reset: also the saved local RPMs) or rum's overlay database (soft reset), so the system is only consistent again after the reboot completes the reset. ## Automatic soft resets The initrd queues a soft reset by itself when: - the image's Fedora release (`VERSION_ID`) differs from `/var/lib/rakuos/os-version`: `version change detected (44 → 45) — scheduling soft reset.` - the edition (`/usr/share/rakuos/de-name`) changed: `DE change detected (kde → gnome) — scheduling soft reset to rebuild overlay from packages.list.` - whiteouts in the overlay hide an entire top-level `/usr` directory: `CRITICAL — …` then `auto-recovering — scheduling soft reset to rebuild overlay from packages.list.` - an older install is migrated (`legacy bash overlay detected`, `pre-rum install detected`). These reinstall from the network on the following boot. ## Base-file protection `rakuos-base-protect` watches `/var/lib/rakuos/overlay/upper`. When an overlay write would delete or replace a file that belongs to the base image (listed in `/usr/share/rakuos/base-manifest.txt`, built from `/usr/share/rakuos/protected-packages.txt` at image build), it removes that overlay entry and shows a desktop notification: "Base System Protection — A modification to a base system file was blocked: … Base files are managed by bootc update." It pauses while rakuos-core's own overlay operations run (`/run/rakuos-overlay.lock`). Journal lines start with `rakuos-base-protect: BLOCKED`. The notification is expected when a program tries to overwrite part of the base image. Base files change only through image updates. ## Boot menu and bootloader `/boot/grub2/grub.cfg` is bootupd's static config, written once at install. It reads `user.cfg` before the RakuOS (BLS) entries and `custom.cfg` after them, and it is never regenerated: `grub2-mkconfig` does not apply. rakuos-core keeps the files around it current. `/boot` is mounted read-only; each script below makes `/boot` (and an ESP) writable only inside its own mount namespace. Each takes `--dry-run`. This applies to images built from 2026-10-16 on (rakuos-core `7cbc891` and later, with the units enabled by rakuos-base). GRUB menu order: RakuOS entries (newest first), other operating systems, the **RakuOS rescue** submenu, **UEFI Firmware Settings**. Files RakuOS writes, and what stays the user's: | File | Written by | User's own edits | |---|---|---| | `/boot/grub2/themes/` | `grub-theme-deploy` | replaced as a whole | | `/boot/grub2/user.cfg` | `grub-theme-deploy`: a block between `### BEGIN RakuOS …` and `### END RakuOS ###` | kept outside the block, e.g. `GRUB2_PASSWORD` from `grub2-setpassword` | | `/boot/grub2/custom.cfg` | `os-entries` and `rescue-entries`: one marked block each | kept outside the blocks | | `/boot/grub2/os-prober.cfg` | `os-entries`, rewritten whole | none | | `/boot/grub2/grub.cfg` | `os-entries`, once: moves the `30_uefi-firmware.cfg` block below `41_custom.cfg` | not supported | ### shim and GRUB on the ESP `rakuos-bootloader-update.service` does the job of bootupd's `bootloader-update.service`, which the image masks. It uses bootupd's data and rules: the payload is `/usr/lib/efi/{shim,grub2}//EFI` as listed in `/usr/lib/bootupd/updates/EFI.json`; the record of what is on the ESP is `/boot/bootupd-state.json`, kept current so `bootupctl status` stays right. It only upgrades (booting an older deployment never downgrades the ESP), replaces only files bootupd installed, and writes GRUB before shim. With Secure Boot on it updates only if the firmware trusts the Microsoft UEFI CA 2023; otherwise it logs why and skips, and a firmware update (`fwupdmgr update` or the PC maker's tool) is the fix. Earlier installs kept the shim and GRUB they were installed with. ```bash journalctl -b -u rakuos-bootloader-update # read-only: "bootloader updated to …", "up to date", or why it skipped sudo bootupctl status # read-only: what is on the ESP vs in the image sudo /usr/libexec/rakuos/bootloader-update --dry-run # read-only: what it would write ``` ### GRUB theme Installed at shutdown from the image being deployed, so a new theme shows on that image's first boot. A password set with `grub2-setpassword` now survives; before 2026-10-16 the theme sync rewrote `user.cfg` at every boot and removed it. The first update onto rakuos-core `7cbc891` is still applied by the older code. ### Rescue entries The **RakuOS rescue (text console, user packages off)** submenu has one entry per deployment. Each boots that deployment's kernel and arguments, without `rhgb quiet`, plus `rakuos.rescue`, `rd.systemd.mask=rakuos-overlay-mount.service`, `systemd.mask=` for `rakuos-overlay-sync`, `rakuos-overlay-update`, `rakuos-base-protect` and `rakuos-setup`, `systemd.unit=multi-user.target` and `plymouth.enable=0`. The result is the plain image `/usr` without the overlay, no reset or package sync at boot, and a text login on tty1; `/var/lib/rakuos` is left as it was. The masks are ordinary systemd arguments, so the entries work for deployments built before this feature too. Use: [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay). ### Other operating systems `os-entries` runs 2 minutes after the first boot of each new deployment (stamp: `/var/lib/rakuos/os-entries.deployment`), at idle priority. It combines os-prober's EFI results (Windows) with a scan of every ESP on non-removable disks for other vendors' loaders (`EFI//shimx64.efi`, `grubx64.efi`, `systemd-bootx64.efi`, FreeBSD's `loader.efi`, rEFInd and so on) and chainloads each. Other Linux distributions are started through their own loader because booting their kernels from RakuOS's GRUB fails under Secure Boot. With Secure Boot on, a loader without a signature is labelled "(needs Secure Boot off)". A run that finds nothing keeps the existing entries. The installer runs the same script (`--root`) on a new install. ```bash journalctl -b -u rakuos-os-entries # read-only: what was found (2 minutes after boot) sudo /usr/libexec/rakuos/os-entries --dry-run # read-only: what it would write sudo /usr/libexec/rakuos/os-entries # changes system: rewrites os-prober.cfg and its custom.cfg block now; shows at the next boot; nothing to undo (menu entries only) ``` ## Logs ```bash journalctl -b | grep 'RakuOS overlay' # read-only: initrd mount, resets, reseed journalctl -b -u rakuos-overlay-sync.service # read-only: package install at boot journalctl -b -u rakuos-base-protect.service # read-only: blocked writes journalctl -b -u rakuos-setup.service # read-only journalctl -u rakuos-bootc-upgrade.service # read-only: background image updates started from the apps journalctl -b -1 -u rakuos-grub-theme # read-only: theme and rescue entries written at the last shutdown after an update journalctl -b -u rakuos-bootloader-update -u rakuos-rescue-entries -u rakuos-os-entries # read-only: boot menu and bootloader upkeep findmnt /usr # read-only: should show an overlay with upperdir=…/var/lib/rakuos/overlay/upper ls /var/lib/rakuos/ # read-only: markers ``` ## Messages and what they mean | Message | Meaning | Safe action | |---|---|---| | `RakuOS overlay: deployment changed (A → B) — reseeding /usr/share/rpm view from new base...` then `reseed complete.` | normal after an update, rollback or switch | none | | `RakuOS overlay: soft reset marker found — wiping all rakuos state (preserving packages.list, local RPMs, and user markers)...` | a queued or automatic soft reset ran | wait for the reinstall; keep the network connected | | `RakuOS overlay: var directory not found — not an installed system, skipping.` | live session or container | none | | `RakuOS overlay: FATAL: …` | the initrd could not set up the overlay; the system boots without overlay packages | collect `journalctl -b`, file a bug against rakuos-core | | `RakuOS overlay sync: no internet — deferring install.`; boot splash "Connect to the internet, then reboot to finish installing default applications." | a reinstall needs the network | connect, reboot | | `RakuOS overlay sync: sync complete — rebooting.` | reinstall after a change finished; one automatic reboot | none | | `RakuOS overlay sync: FATAL — …` | the boot-time install failed | `journalctl -b -u rakuos-overlay-sync`; a package in `packages.list` may no longer exist | | `ERROR: rakuos reset-overlay must be run as root` | | use `sudo` | | `bootloader-update: Secure Boot is on and the firmware doesn't trust the Microsoft UEFI CA 2023; …` | shim/GRUB update skipped on purpose | update the firmware (`fwupdmgr update` or the PC maker's tool); don't force it | | `bootloader-update: not downgrading the bootloader; nothing done` | booted an older deployment than the one that last updated the ESP | none | | `os-entries: found nothing this time; keeping the existing …/os-prober.cfg` | a disk didn't probe; existing entries kept | none | ## Interaction with image updates - The overlay's lower layer is the booted image's `/usr`; a new image changes everything below the overlay at once. - On the first boot of a new deployment the initrd copies the new base's package database view into the overlay (reseed). Overlay files are not compared with the new image: an overlay copy of a file that the new image also ships keeps taking precedence. `rakuos-base-protect` and `rum restore-base-files` handle the common cases. - A Fedora release change or edition change soft-resets the overlay so packages are rebuilt for the new base. --- # Installer (rakuos-installer) and the live ISO The RakuOS installer runs in the live session of every RakuOS ISO. It partitions the disk, copies the image baked into the ISO onto it with `bootc install to-filesystem`, creates the user, sets up Flatpak and Flathub, and, when Secure Boot is on, queues the RakuOS key for enrollment at the next boot. The installed system follows the same image and channel the ISO was built from. As of 2026-10-15 (rakuos-installer `f93ef72`, rakuos-forge `612f66a`, ISO repos `main`). ISOs are built from the stable (`latest`, Fedora 44) images. Bugs: installer problems https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-installer; a live ISO that will not boot goes to the edition's ISO project, e.g. https://rakuos.org/bugs/p/rakuos-iso-rakuos-cosmic-iso. ## The live ISO - Built by RakuForge (`rakuos-forge`) from `quay.io/rakuos/rakuos-:latest`. ISOs exist for KDE, GNOME, COSMIC, niri, Hyprland (from 2026-10-28) and a minimal image. gamescope is reached by switching an installed system to its image (see [RakuOS System](https://rakuos.org/ai/components/rakuos-system)). - The live session runs Fedora's signed kernel, not kernel-rakuos, so the ISO boots with Secure Boot on. The installed system runs kernel-rakuos. - The overlay units are masked in the live session; nothing is written to `/var/lib/rakuos` on the target until it boots. - Boot menu: the default entry, "Basic Graphics Mode" (adds `nomodeset`; try this when the live ISO shows a black screen or hangs on graphics), and "Text-Mode Installer" (boots to a console). ## Frontends | Package | Used on | |---|---| | `rakuos-installer-gtk` | GNOME and niri ISOs | | `rakuos-installer-qt` | KDE and minimal ISOs | | `rakuos-installer-cosmic` | COSMIC ISO | | `rakuos-installer-cli` | minimal ISO's text-mode installer | | `rakuos-installer-common` | `/usr/libexec/rakuos/rakuos-bootc-installer`, the backend all of them run | GTK pages: Welcome, Locale, Keyboard, Timezone, Disk, User, Confirm, then progress and Done. The live session pre-selects locale from a network location lookup. ## What it does 1. Checks for the tools it needs: `required tools not found: …` if any is missing. 2. Partitions the chosen disk with GPT: - UEFI: 512 MiB ESP (`EFI-SYSTEM`), 1 GiB `/boot` (ext4), root. - BIOS: 1 MiB BIOS-boot partition, 1 GiB `/boot`, root. - Optional: a second disk formatted as `/var` (XFS). 3. Root filesystem: Btrfs (recommended; subvolumes `@`, `@home`, `@snapshots`, mounted with `compress=zstd:1,noatime`), Ext4 or XFS. Minimum disk size 40 GiB. 4. Encryption, optional: LUKS2 with a passphrase, or TPM2 auto-unlock plus a recovery passphrase (offered when a TPM2 chip is present). TPM2 unlock is bound to PCR 7 and written to `/etc/crypttab`. 5. Copies the image from the ISO and runs `bootc install to-filesystem` with `--target-imgref` set to the ISO's image, SELinux disabled. Later `bootc upgrade` runs follow that image name and channel. 6. Installs GRUB. The firmware boot entry is renamed "RakuOS" and set to boot next; its files stay in `\EFI\fedora\`, which is normal. It adds other operating systems to the menu by running the installed image's `/usr/libexec/rakuos/os-entries --root ` (installer `484ace5` and later; older images fall back to os-prober entries written straight into `custom.cfg`), and copies the GRUB theme. 7. Copies the live session's Flatpaks and Flatpak remotes (Flathub) to the target and makes sure a base runtime is installed. 8. Writes hostname, locale, keyboard and timezone; creates the user in `/var/home/`, in group `wheel`, with fish as the shell when the image has it; copies Wi-Fi and Bluetooth settings. 9. With UEFI and Secure Boot on: queues the RakuOS certificate (`/usr/share/rakuos/sb_pubkey.der`) with `mokutil --import`, unless keys are already pending enrollment. No per-machine key is generated any more (installers before `f93ef72` also queued a per-machine module signing key). ## After the install: Secure Boot enrollment If Secure Boot was on during the install, MOK Manager (a blue screen) appears before RakuOS starts on the first boot: 1. Choose **Enroll MOK**, then **Continue**. 2. Type the password `rakuos`. 3. Choose **Reboot**. If the install ran with Secure Boot off, or under BIOS, nothing is queued. To enroll later on a UEFI machine: ```bash sudo rakuos enroll-secureboot-key # changes system: queues the RakuOS certificate, and deletion of unknown (machine-made) MOKs only, for MOK Manager at the next boot; Microsoft and Linux/BSD vendor keys stay. Reboot required, then follow the steps above (choose Delete MOK as well if it is offered). ``` On a system installed before 2026-10-15 this also queues the old per-machine key for deletion; see [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot#enrolling-the-rakuos-key-mok). The enrollment password `rakuos` comes from the installer's defaults and from `enroll-secureboot-key`. ## Logs The installer writes no log file. On failure, the GTK and Qt frontends show an "Install log" on the Done page; the Qt frontend has "Copy Log". The text installer prints `Installation failed. See the log output above for details.` Ask the user to copy that log before rebooting, because the live session forgets it. ## Errors and what to do | Message | Meaning | Safe action | |---|---|---| | `Image '' is not present in local container storage. The live ISO should already contain the image — reinstall from a fresh ISO.` | the image inside the ISO is missing or damaged | download the ISO again, check its `.sha256`, rewrite the USB stick | | `required tools not found: …` | the live session is missing an installer tool | report against the edition's ISO project | | `bootc exited with status …` | the image copy or `bootc install` failed | copy the install log; report against rakuos-installer | | `Secure Boot key not found at ` | the image lacks `/usr/share/rakuos/sb_pubkey.der` | report against rakuos-installer; installing with Secure Boot off avoids the step | | `encryption.type "luks" is not valid` (or `"tpm2"`) | text-mode installer only, as of `f93ef72`: its encryption choices are rejected | use a graphical installer for an encrypted install, or install unencrypted in text mode | | The install says complete but the user cannot log in | creating the user failed; the installer only warns about this | check the install log for user creation messages; report against rakuos-installer | | Live ISO shows a black screen or freezes while starting | graphics driver problem in the live session | boot "Basic Graphics Mode" | | The disk is not listed | only NVMe, `sd*` and `vd*` disks are offered, and never the disk the live ISO booted from | install to an internal NVMe or SATA disk | | "⚠ Selected disk is smaller than 40 GiB required." | the disk is below the minimum | choose a disk of 40 GiB or more | --- # Software Center (rakuos-software) The Software Center, shown in app launchers as "Add/Remove Software", installs and removes RPM packages (through rum), Flatpaks, AppImages, web apps and Distrobox containers, and applies package, Flatpak and image updates. It also runs a tray icon that checks for updates. RPM packages it installs go into the same `/usr` overlay as `sudo rum install`. As of 2026-10-15 (rakuos-software `7096eb2`). Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-software ## Packages and frontends | Package | Contents | |---|---| | `rakuos-software-common` | `/usr/bin/rakuos-software` (launcher), desktop entry `org.rakuos.Software.desktop`, tray autostart `/etc/xdg/autostart/rakuos-software-tray.desktop`, web app launcher `/usr/bin/rakuos-webapp-launcher` with a bundled Electron runtime, AppStream data in `/usr/share/rakuos/appstream/` | | `rakuos-software-gtk` | GTK frontend, installed on GNOME, niri and Hyprland | | `rakuos-software-qt` | Qt frontend, installed on KDE, COSMIC and gamescope | | `rakuos-software-cosmic` | COSMIC frontend; no image installs it | The frontend binaries live in `/usr/libexec/rakuos/software/`. The launcher starts the first one it finds, in the order gtk, qt, cosmic. It also opens `.rpm`, `.flatpak`, `.flatpakref` and `.AppImage` files ("Open With Add/Remove Software"). Searching the launcher for "Software Center" may not find it; search for "software" or "Add/Remove Software". ## Pages (GTK frontend) Page names and on-screen labels on this page are from the GTK frontend. The Qt (KDE, COSMIC, gamescope) and COSMIC frontends run the same backend actions listed under "What each action runs"; their labels were not checked and may differ. The COSMIC frontend has Home, Distrobox, Web Apps, Updates and Settings pages. Home, Explore, Extensions (GNOME only: GNOME Shell extensions), Distrobox, Web Apps, Installed, Updates, plus Settings. The System page was removed on 2026-09-21: switching images, rollback, overlay reset, kernel arguments and zram moved to the separate [RakuOS System](https://rakuos.org/ai/components/rakuos-system) app. ## What each action runs | Action | Command run | |---|---| | Install or remove an RPM | `sudo-rs rum install -y ` / `sudo-rs rum remove -y ` | | Install a local `.rpm` | `rum install -y ` | | Install a Flatpak | `flatpak install --system` or `--user`, `--noninteractive -y ` | | Add a Flatpak remote, bundle or `.flatpakref` | through `pkexec` | | Enable or disable a repo (repository settings; lists repos from the same four dirs rum reads, in rum's order) | `pkexec rum config-manager --set-enabled|--set-disabled ` | | Enable a COPR | `pkexec rum copr enable /` | | Check for updates | `rum check-upgrade --json`, Flatpak, and the image: `bootc status --json` plus a Quay tag lookup | | Update overlay packages | `sudo-rs rum upgrade -y` | | Update the image | `rakuos-update upgrade-image` or `rakuos-bootc-upgrade.service`, both `bootc upgrade` | | Firmware | `fwupdmgr` | How the Software Center asks for authentication is being moved to polkit (pending). Do not tell users whether they will see a password prompt. ## Updates page and image updates - Image updates are staged by `bootc upgrade`; the new image runs after a reboot. The tray then shows "System Update Ready … Reboot to apply the changes." - If the update moves to a newer Fedora release (the image's `org.rakuos.fedora.version` label is higher than `VERSION_ID`; `sudo rum system-upgrade` does the same check), it first shows "This update moves to Fedora N. Preparing your installed packages for the new release…" and runs `rakuos-reset-overlay --soft --releasever N`. If that fails: "Couldn't prepare packages for Fedora N; the image update was not started." Nothing has changed in that case; check the network and retry, or see which package failed with `sudo rakuos reset-overlay --soft --releasever N` in a terminal. - Before every image update it runs `sudo-rs rum kmod-upgrade -y`, which moves overlay `rakuos-kmod-*` packages to the new image's kernel builds; a failure only warns ("Warning: couldn't upgrade kernel modules for the new kernel; updating the system image anyway."). While the available image update runs another kernel (its `org.rakuos.kernel.release` label differs from `uname -r`), `rakuos-kmod-*` rows are left out of the package updates, since the image update handles them. - If an image update is already running when the app starts, the page reattaches to it by following `journalctl -u rakuos-bootc-upgrade.service`. ## Tray and settings - The tray starts at login 10 seconds after the desktop (`rakuos-software --tray`); it runs inside the frontend process, not as a separate daemon. Menu: "Open RakuOS Software", "Check for Updates", "Quit". - Left-clicking the tray icon opens the window only on COSMIC; elsewhere use the menu. - Settings are stored in `~/.config/rakuos/software-settings.json`. Defaults: check every 1440 minutes (daily) for packages, Flatpaks, the image and AppImages; automatic updates off. - "Automatically install package and Flatpak updates when found" installs overlay package and Flatpak updates from the tray. - "Automatically apply bootc image updates (rakuos-updater.timer)" enables `rakuos-updater.timer`. As of rakuos-core `e08616c` that timer only checks for a new image (Thursdays 03:00); it does not apply it. - The tray is off when `~/.config/rakuos/disable-tray` exists. Choosing the Noctalia shell on niri creates that file. ```bash rm ~/.config/rakuos/disable-tray # changes the user's settings: re-enables the tray at next login. Undo: touch the file again ``` ## AppImages - Installing (`.AppImage`, or an archive containing one: `.zip`, `.7z`, `.tar`, `.tar.gz`/`.tgz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tar.lz`, `.tar.lzma`) copies it to `~/.local/share/rakuos/appimages/.AppImage` (mode 0755), its icon to `~/.local/share/rakuos/appimages/icons/`, a launcher to `~/.local/share/applications/rakuos-appimage-.desktop`, and its record to `~/.local/share/rakuos/appimages/.json`. All per user; no root. Uninstall (Installed → AppImages) removes those. - **Update settings** (the app's page from Installed → AppImages, "Update Settings"; stored in `.json`): | Field | Meaning | |---|---| | Source (`update_source`) | `github`, `gitlab`, `url` or `none` | | `update_url` | GitHub: `owner/repo`, the `https://github.com/owner/repo` URL, or the API URL. GitLab: `group/project` (subgroups allowed), the gitlab.com URL, or the API URL. url: a direct download link that always points at the newest file | | `update_pattern` | glob for the release asset's file name: only `*` is a wildcard, case-insensitive, must match the whole name (e.g. `MyApp-*-x86_64.AppImage`, `StabilityMatrix-linux-x64.zip`) | | `version` | installed version; taken from the AppImage's `X-AppImage-Version`, or typed in. A value without any digit (some AppImages ship the placeholder `AppVersion`) counts as unknown | An AppImage's embedded `gh-releases-zsync` update information pre-fills Source, `update_url` and `update_pattern` at install. - **Checks**: GitHub uses `releases/latest` (pre-releases ignored), GitLab the first entry of the project's releases. The tag (leading `v` dropped) is compared with `version` by its numbers; an unknown version always counts as older. The asset whose name matches the pattern is the download. `url` compares the link's `ETag`/`Last-Modified` with the stored values instead, so it has no version. Checks run from the tray and the Updates page in all three frontends. - **Updating** downloads the matching asset, unpacks it when it's an archive, replaces the AppImage (atomic rename; 0755) and records the release version when the new AppImage carries none, so the same update isn't offered again. - An update that never appears usually means a wrong `owner/repo`, no release asset matching the pattern, or a `version` that's newer than (or numbered differently from) the release tags. Read-only check: `jq '{version, update_source, update_url, update_pattern}' ~/.local/share/rakuos/appimages/.json`. ## Logs The app writes to standard error; start it from a terminal to see messages. The Qt frontend also writes `/tmp/rakuos-software-qt.log`. ```bash RUST_LOG=debug rakuos-software 2>&1 | tee ~/software-debug.log # read-only for the system; reproduces the problem with logging journalctl -u rakuos-bootc-upgrade.service # read-only: image updates started from the app ``` ## Problems and what they mean | Symptom or message | Meaning | Safe action | |---|---|---| | The window flashes and closes the first time, then reopens a few seconds later | expected: the first launch per user starts, stops and restarts the app (about 6 s) | wait | | "Loading software catalog…" for a while | the catalog loads before the main view | wait; check the network | | Closing the window does not quit the app | closing hides it; the process stays for the tray | use "Quit" in the tray menu | | "Package database update in progress" | an overlay operation holds `/run/rakuos-overlay.lock` (boot-time sync, reset or update) | wait for it to finish | | An install looks successful in the GTK app but the package is missing | the GTK install queue does not check the exit status of rum | confirm with `rum origin `; run `sudo rum install ` in a terminal to see the real error | | "Installation failed." / "Error starting install process." (local package page) | rum failed; the page shows rum's output | read the output; see [rum errors](https://rakuos.org/ai/components/rum#errors-and-what-to-do) | | "System update failed", "Update check failed", "Failed to start rakuos-bootc-upgrade.service" | the image update or check failed | `journalctl -u rakuos-bootc-upgrade.service`; `sudo bootc status` | | "Electron runtime missing. Please reinstall RakuOS." | web app runtime missing from `/usr/lib/rakuos-electron` | report it against rakuos-software | | `rakuos-software: no frontend installed` | no `rakuos-software-*` frontend package | report it against the edition image | | An app is listed but installing it fails with `nothing provides ''` | the catalog always includes Terra's apps (shown as "RakuOS Linux", or "Terra" in GTK search), but installs run plain `rum install`, which only sees enabled repos; Terra is disabled by default | check with `rum repolist --all`; enable Terra only if the user wants it: `sudo rum config-manager --set-enabled terra`, then retry. On staging RPM Fusion is off by default too; `rum repolist --all` shows it | | A package in `packages.list` that rum has no record of is hidden from Installed but shown as installed elsewhere | the overlay and `packages.list` disagree | `sudo rum install ` from a terminal reinstalls it | --- # RakuOS System Management (rakuos-system) "RakuOS System Management" is the GUI for changes to the system as a whole: switching to another edition, channel, CPU level or NVIDIA image, showing anti-cheat readiness, rolling back and choosing deployments, resetting or exporting the overlay package list, and setting kernel arguments, zram size, the CPU scheduler, ananicy-cpp, AppArmor profile modes and the firewall. It has no command-line interface; every action has a terminal equivalent given below. As of 2026-10-15 (rakuos-system `fc07607`). Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-system ## Packages | Package | Contents | Installed on | |---|---|---| | `rakuos-system-common` | `/usr/bin/rakuos-system`, desktop entry `org.rakuos.System.desktop` | all editions | | `rakuos-system-gtk` | GTK frontend | GNOME, niri, Hyprland | | `rakuos-system-qt` | Qt frontend | KDE, gamescope | | `rakuos-system-cosmic` | COSMIC frontend | COSMIC | `rakuos-system --ui=gtk|qt|cosmic` picks a frontend; without it the first installed one starts. The Software Center's tray opens this app from some of its notifications. Changes go through `pkexec`, which asks for the user's password ("pkexec will prompt for your password"). ## Pages The GTK frontend's sidebar: System, Overlay, Deployments, Drivers, Scheduler, Ananicy, AppArmor, Firewall. The COSMIC frontend has the same pages and also offers rollback on its System page. Messages quoted below are from the GTK frontend; the Qt (KDE, gamescope) and COSMIC frontends run the same commands, but their labels were not checked and may differ. ### System: what is running, and switching images Shows the booted image, version, digest, timestamp and NVIDIA status, and lets the user switch Desktop Environment (KDE Plasma, GNOME, COSMIC, Niri, Hyprland), Branch (Stable = `latest`, Staging = `staging`), ISA level (v2, v3, v4; only levels the CPU supports are offered) and Nvidia: "Standard" (no suffix), "Nvidia" (`-nvidia`) or "Nvidia Legacy" (`-nvidia-legacy`, the 580xx driver, the last for Maxwell, Pascal and Volta GPUs). A booted legacy image shows as " (Nvidia Legacy)" with Nvidia "Yes (legacy 580xx driver)". "Switch Image" runs: ```bash pkexec bootc switch quay.io/rakuos/rakuos-[-nvidia|-nvidia-legacy][-v3|-v4]: # changes system: stages the other image; reboot required. Undo after reboot: sudo bootc rollback ``` - A change of desktop: "Overlay Rebuild on Next Boot". The overlay is soft-reset on the first boot of the new image and every package in `packages.list` is reinstalled; this needs the network. - A change of channel, ISA level or NVIDIA variant: the app says "Your overlay stays as it is, since the desktop and Fedora release don't change." It only treats a move onto or off Rawhide as a release change. Since staging moved to Fedora 45 while stable is Fedora 44, a Stable ↔ Staging switch does change the release: the first boot soft-resets the overlay and reinstalls `packages.list` from the network, and the app does not pre-download the packages as the Software Center does for updates. Keep the network connected for that boot. - Success: "Image switch staged — reboot to apply." Failure: "Image switch failed. Check system logs." - gamescope is not offered here. - Kernel choice: only RakuOS kernels are built now. If the booted image is an old P03 image, the Switch button is enabled straight away to move it to the matching current image. ### Anti-Cheat readiness The "Anti-Cheat" button next to "Kernel Parameters…" runs `rakuos eac-check --json` when the page loads and on every click, and shows a colored dot: green "Anti-Cheat: Ready", yellow "Anti-Cheat: Suggestions" (nothing failed, but something needs attention or couldn't be checked), red "Anti-Cheat: Not Ready" (a requirement failed) or grey "Anti-Cheat: Unavailable" (rakuos-core without `eac-check`). Clicking it opens "Anti-Cheat Readiness" with each requirement, its details and fix. "Items marked ? need root to check; run `sudo rakuos eac-check` in a terminal to include them." The app runs the check without root, so measured boot is always "?", and the MOK item is a note while the RakuOS key awaits Epic's well-known list: yellow is the best result today. See [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready). ### Overlay Lists the overlay packages ("Packages installed on top of the base OS image") from `/var/lib/rakuos/packages.list`. - **Export List…** writes those names to a file of the user's choice. Use it before any reset. - **Import List…** installs every name in a chosen file with `rum install -y` (one name per line; blank lines and `#` comments are ignored). - **Reset Overlay…** offers "Soft Reset (Rebuild)" (`rakuos-reset-overlay --soft`) and "Full Reset (Stock)" (`rakuos-reset-overlay --confirm`: "Completely wipes the overlay and your packages list. … All installed packages will be removed."). Both need a reboot. See [rakuos-core](https://rakuos.org/ai/components/rakuos-core#resetting-the-overlay). - After a reset, the GTK frontend shows "Reset scheduled — reboot to apply." unless the reset returned a specific error code, so it can show this message even when the reset failed or the password dialog was cancelled (as of `fc07607`). Confirm in a terminal: `ls /var/lib/rakuos/overlay.reset /var/lib/rakuos/soft-reset.marker` (read-only; one of them exists when a reset is queued). ### Deployments Lists deployments from `ostree admin status` with their image, version and Fedora release. "#0 is the newest deployment." ```bash pkexec bootc rollback # "Roll Back…": changes system, next boot uses the previous deployment. Reboot required. Undo: roll back again pkexec ostree admin pin # pin: changes system, keeps that deployment when new updates are staged. Undo: ostree admin pin --unpin pkexec ostree admin set-default # "Boot This Next": changes system, that deployment boots next. Refused while an update is staged ``` - "Rollback staged. Reboot to apply." / "Rollback failed or was cancelled." - "Boot This Next" is refused while an update is staged: "An update is staged. Reboot into it or roll back first." - Choosing a deployment on another Fedora release warns that installed apps will be reinstalled for that release on the next boot. ### Kernel Parameters Shows the current kernel command line and the user-managed arguments. Applying runs: ```bash pkexec bootc loader-entries set-options-for-source --source rakuos-user --options "" # changes system: adds kernel arguments; reboot required. Undo: apply an empty field ("Clear All") ``` "Kernel args staged — reboot to apply." Only arguments the user set here are managed; the image's own arguments (in `/usr/lib/bootc/kargs.d/`: `lockdown=integrity intel_iommu=on iommu.passthrough=0 iommu.strict=1 module.sig_enforce=1 sysctl.kernel.kexec_load_disabled=1`) are not touched. Do not add arguments that weaken those (`iommu=pt`, `lockdown=…`, `module.sig_enforce=0`); they break anti-cheat readiness. `rakuos setup-nvidia` writes this same source and replaces what the user set here. ### Zram Shows "Current zram size". Presets are 25, 50, 75 and 100 % of RAM ("Full RAM"). Applying copies `/usr/lib/systemd/zram-generator.conf` to `/etc/systemd/zram-generator.conf` and sets `zram-size` there; reboot to apply. Applying replaces any earlier hand edits in `/etc/systemd/zram-generator.conf`. Undo: delete `/etc/systemd/zram-generator.conf` (changes system; the image default, the size of RAM, returns after a reboot). ### Drivers Lists the opt-in `rakuos-kmod-*` packages for the running kernel's channel (images ship the rest; NVIDIA is never listed), with a description, the package version and the repo it needs ("needs Terra" / "needs RPM Fusion"). Install runs `sudo-rs -n rum install -y ` (plus `VirtualBox` for the VirtualBox kmod) and then asks "Reboot required"; if it fails because the repo is off, it says which to turn on in the Welcome app. Remove runs `rum remove`. While the overlay is turned off the page warns and the buttons are disabled. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). The System page's image update and image switch also run `sudo-rs -n rum kmod-upgrade -y` (before the update, after `bootc switch`), so installed kmods move to the new image's kernel builds; a failure only adds a warning to the log. ### Scheduler, Ananicy, AppArmor, Firewall - **Scheduler**: picks a sched_ext scheduler and mode, writes `/etc/scx_loader.toml` and enables `scx_loader.service`. The image default config selects `scx_cosmos` in Auto mode, but the service is not enabled until the user applies a choice here. - **Ananicy**: rules in `/etc/ananicy.d/rakuos`; turns `ananicy-cpp.service` on or off. - **AppArmor**: shows profile status (`aa-status --json`) and switches individual profiles between enforce and complain. Putting a profile into enforce mode can stop the app it confines from working. - **Firewall**: firewalld zones, services, ports and on/off, through `firewall-cmd`. ## Logs The app logs to standard error; start it from a terminal (`rakuos-system`) to see messages. System-side results: ```bash sudo bootc status # read-only: staged, booted and rollback deployments after a switch or rollback journalctl -b -u scx_loader # read-only cat /proc/cmdline # read-only: kernel arguments in effect ``` ## Problems and what they mean | Symptom | Meaning | Safe action | |---|---|---| | "Image switch failed. Check system logs." | `bootc switch` failed (network, wrong image name, disk space) | run the shown `bootc switch` in a terminal with `sudo` to see the error | | After switching desktop, the first boot takes long and shows "Installing user applications..." | expected soft reset and reinstall | keep the network connected | | "Reset scheduled — reboot to apply." but nothing happened after reboot | the GTK frontend reported success for a failed or cancelled reset | run `sudo rakuos reset-overlay --soft` in a terminal and read its output | | "Boot This Next" refused | an update is staged | reboot into it, or roll back first | | "Anti-Cheat: Not Ready" or "Suggestions" | a readiness requirement failed or needs attention | see [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready) | | After a Stable ↔ Staging switch, the first boot reinstalls every app although the dialog said the overlay stays | stable is Fedora 44 and staging Fedora 45; the app only counts Rawhide as a release change | expected; keep the network connected. Report the wrong dialog against rakuos-system | | Gamescope shows only "RakuOS" as the edition, or is missing from the list | gamescope is not in this app's lists | not covered yet; ask on the forum before switching a gamescope system | --- # rum, the package manager `rum` is RakuOS's RPM package manager, written in Rust; it replaces dnf. On an installed system it installs packages into the `/usr` overlay and records them in its own database, so the base image is never modified. `dnf` and `dnf5` are shim commands that run rum, and rum's command line follows dnf5's closely. As of 2026-10-15 (rakuos-rum `87388ff`, built for Fedora 44 and 45); [Repo overrides](#repo-overrides) as of 2026-10-22 (`cdc2850`). Bugs: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum ## What it ships | Package | Files | |---|---| | `rakuos-rum` | `/usr/bin/rum`; `/etc/rum/rum.conf` (all options commented out, so built-in defaults apply); the repo dirs `/etc/rum.repos.d` and `/usr/share/rum/repos.d`; `rum-makecache.service` and `rum-makecache.timer`; man pages `rum(1)`, `rum.conf(5)` | | `rum-dnf-shim` | `/usr/bin/dnf` and `/usr/bin/dnf5`. It obsoletes dnf, dnf5, yum and microdnf, so those packages are not installed | | `rakuos-rum-repo-overrides` | `/usr/share/rum/repos.override.d/20-rakuos.repo`, RakuOS's excludes for the Fedora, RPM Fusion and Terra repos (see [Repo overrides](#repo-overrides)). Installed by base images built from 2026-10-22 on | Paths on an installed system: | Path | Contents | |---|---| | `/etc/rum.repos.d/*.repo` | the user's repos and changed copies of shipped repo files (standard `.repo` format) | | `/usr/share/rum/repos.d/*.repo` | repo files that came with packages (Fedora, RakuOS, RPM Fusion, Terra, and vendor repos such as Google Chrome's) | | `/usr/share/rum/repos.override.d/*.repo`, `/etc/rum/repos.override.d/*.repo` | repo overrides: options applied on top of matching repos (shipped, and the user's) | | `/var/lib/rakuos/rum-rpmdb` | overlay package database | | `/var/lib/rakuos/rum-state/` | history (`history.jsonl`), install reasons, versionlocks, imported repo keys | | `/var/lib/rakuos/packages.list` | names the user installed; the overlay is rebuilt from this list after a reset | | `/var/lib/rakuos/packages-rpm.list`, `/var/lib/rakuos/local-rpms/` | local `.rpm` files the user installed, kept for reinstall | | `/var/cache/rum/` | repo metadata and downloaded packages | `rum-makecache.timer` (refresh metadata 10 min after boot, then every 3 h) is shipped but not enabled by default. ## Repo files rum reads four directories, highest precedence first. A file in an earlier directory hides a file with the same name in a later one: 1. `/etc/rum.repos.d`: the user's own repos and changed copies (written by `config-manager`, `addrepo`, `copr enable`). 2. `/etc/yum.repos.d`: dnf's directory, read as a fallback (files put there by hand, by dnf during an image build, or by older rum). 3. `/usr/share/rum/repos.d`: shipped defaults. rum installs every package's repo files here (it relocates `/etc/yum.repos.d` and `/usr/share/dnf5/repos.d` with `rpm --relocate`), and after each transaction it moves repo files that package scriptlets created in those two places (for example Google Chrome's) here too. 4. `/usr/share/dnf5/repos.d`: dnf5's shipped directory (Fedora 45's `fedora-repos` and `terra-release` use it), read last. Images from 2026-10-14 on keep their repo files in `/usr/share/rum/repos.d`, so `/etc/rum.repos.d` starts empty. On older stable images the files are still in `/etc/yum.repos.d`; rum reads them there. Do not edit files under `/usr/share`; change repos with `config-manager`. ## Repo overrides From rakuos-rum `cdc2850` (2026-10-22), rum reads repo override files like dnf5's `repos.override.d`. An override file is a `.repo` file whose section names are repo ID globs (`[rpmfusion-*]`, `[terra]`); after the repo files are read, each section's options are applied to every repo whose ID matches. `excludepkgs=`/`exclude=` and `includepkgs=` add to the repo's own lists; any other option (`enabled=`, `priority=`, …) replaces the repo's value. Override dirs, highest precedence first: `/etc/rum/repos.override.d`, `/etc/dnf/repos.override.d`, `/usr/share/rum/repos.override.d`, `/usr/share/dnf5/repos.override.d`. A file in an earlier dir hides a file with the same name in a later dir; the remaining files apply in file-name order, so `99-local.repo` applies after `20-rakuos.repo`. Overrides are only read with the default repo dir (not with `--repo-dir`/`reposdir` pointing elsewhere). `rakuos-rum-repo-overrides` ships `/usr/share/rum/repos.override.d/20-rakuos.repo`, which excludes: | Repos | Excluded | Why | |---|---|---| | `fedora`, `updates`, `updates-testing`, `updates-archive` | `goverlay` | RakuOS builds GOverlay in the `rakuos` repo | | `rpmfusion-*` (every RPM Fusion repo) | `akmod-nvidia* kmod-nvidia* xorg-x11-drv-nvidia* nvidia-* steam` | the NVIDIA driver comes from RakuOS (the `-nvidia`/`-nvidia-legacy` images), and RPM Fusion ships packages under the same names; Steam is available from Terra instead | | `terra` | AppArmor (`apparmor*`, `mod_apparmor`, `pam_apparmor`, `python3-apparmor`, `python3-LibAppArmor`) and sched_ext (`scx-scheds*`, `scx-tools*`) | RakuOS builds these itself | Base images built before 2026-10-22 wrote the RPM Fusion and Terra excludes into the repo files themselves instead; newer images leave the repo files as their packages ship them and install `rakuos-rum-repo-overrides`. A copy of an RPM Fusion or Terra repo file in `/etc/rum.repos.d` made from an older image still carries its own `excludepkgs=` line; with the override the same patterns are listed twice, which is harmless. ```bash ls /usr/share/rum/repos.override.d /etc/rum/repos.override.d # read-only: the override files in use cat /usr/share/rum/repos.override.d/20-rakuos.repo # read-only: RakuOS's excludes rum list --base | grep rakuos-rum-repo-overrides # read-only: is the package in the image ``` Users add their own overrides as a new file in `/etc/rum/repos.override.d` (e.g. `sudo tee /etc/rum/repos.override.d/99-local.repo` with a `[repo-id-glob]` section; no reboot; undo by deleting the file). A file named `20-rakuos.repo` there replaces RakuOS's whole file, dropping all of its excludes; don't suggest that, since RPM Fusion's NVIDIA packages would then replace the RakuOS driver. Excludes can't be removed for one repo by another override (they only add); to get Fedora's GOverlay or RPM Fusion's NVIDIA packages anyway, the user would have to mask the whole file, which is not supported. ## Modes rum picks its mode automatically: - **Split mode**, on an installed RakuOS system (the file `/var/lib/rakuos/current-deploy` exists). The base image's database at `/usr/share/rpm` is read-only to rum; every install, remove and upgrade acts on the overlay and its database. - **Standalone mode**, everywhere else: Distrobox or podman containers, image builds. rum behaves like a normal package manager on a single database. ```bash rum paths # read-only: mode and paths rum origin # read-only: Base, Overlay, Installed or NotInstalled ``` Expected `rum paths` output on an installed system: ``` mode: split (RakuOS overlay) base snapshot rpmdb: /usr/share/rpm overlay rpmdb: /var/lib/rakuos/rum-rpmdb overlay upperdir: /var/lib/rakuos/overlay/upper ``` ## Everyday commands Commands that change the system need root (`sudo`); without it rum prints `rum requires root — try: sudo rum `. `--dry-run` previews `install`, `remove`, `upgrade`, `reinstall`, `downgrade`, `distro-sync` and `autoremove` without root. How `sudo rum` and the Software Center ask for authentication is being moved to polkit (pending). Do not tell users whether they will or will not see a password prompt. ```bash sudo rum install # changes system: adds and its dependencies to the overlay, live immediately, no reboot. Undo: sudo rum remove sudo rum remove # changes system: removes it from the overlay. Undo: sudo rum install sudo rum upgrade # changes system: upgrades overlay packages only, NOT the base image. Undo: sudo rum history undo sudo rum system-upgrade # changes system: kmod-upgrade if the new image has another kernel, overlay upgrade, then Flatpaks, then `bootc upgrade` stages a new image (a newer Fedora release: soft reset instead of the overlay upgrade). Reboot to use it. Undo: sudo bootc rollback after the reboot sudo rum kmod-upgrade # changes system: moves overlay rakuos-kmod-* packages to the incoming image's kernel builds (--kernel R for another, --dry-run to preview). Undo: sudo rum history undo rum search # read-only rum info # read-only rum list # read-only: overlay packages, i.e. what the user installed. NOT `--installed` (no such flag) rum list --base # read-only: the base image's packages rum check-upgrade # read-only: overlay packages with updates (kernel modules: only builds for the running kernel) rum history list # read-only rum repolist --all # read-only: repos and whether each is enabled ``` Aliases: `in`/`pour` = install, `rm`/`erase` = remove, `up`/`update` = upgrade, `rei` = reinstall, `dg` = downgrade, `se` = search, `ls` = list, `if` = info, `rq` = repoquery, `mc` = makecache, `check-update` = check-upgrade. Other commands: `reinstall`, `downgrade`, `distro-sync`, `autoremove`, `swap`, `mark install|dependency`, `check`, `provides`, `repoquery`, `leaves`, `restore-base-files`, `makecache`, `clean all|packages|metadata`, `download` (with `--releasever N` and `--alldeps`, which the soft reset uses to cache a newer release's packages), `changelog`, `needs-restarting`, `repo list|info`, `repoinfo`, `history list|info|undo|redo|rollback`, `versionlock add|delete|list|clear`, `config-manager`, `copr enable|disable`, `group`, `environment`, `module`, `advisory`, `reposync`, `repomanage`, `repoclosure`, `builddep`, `debuginfo-install`, `automatic`, `completions`. `offline`, `offline-upgrade`, `offline-distrosync`, `replay` and `do` exist only as names and report an error. Repositories: ```bash rum repolist --all # read-only: every repo and whether it is enabled sudo rum config-manager --set-enabled terra # changes system: enables Terra (disabled by default). Undo: --set-disabled terra. No reboot sudo rum config-manager --set-enabled 'rpmfusion-*' # changes system: enables RPM Fusion's package repos (disabled by default on staging). Undo: --set-disabled 'rpmfusion-*' sudo rum copr enable / # changes system: writes a COPR .repo file to /etc/rum.repos.d. Undo: sudo rum copr disable / ``` How `config-manager --set-enabled` / `--set-disabled` change a repo: - A repo defined in a shipped file is copied into `/etc/rum.repos.d` and the copy is edited; the shipped file is never touched. When a later change puts the copy back to the shipped default, rum deletes the copy, so package updates to the shipped file apply again. A copy with other edits (e.g. an added `excludepkgs=`) is kept. - Both flags take several ids and `*`/`?` wildcards (quote them). A wildcard matches every repo rum reads and fails with `no repo matches ''` if none does. An enabling wildcard skips source (`-source`, `-srpms`), debuginfo (`-debuginfo`, `-debug`) and testing (`-testing`) repos unless `--with-source`, `--with-debuginfo` or `--with-testing` is given, and says which it skipped. Ids named exactly are always enabled; a disabling wildcard matches everything. - `--default` (and `config-manager addrepo --default`) changes the shipped file in place or adds the repo to `/usr/share/rum/repos.d`. It is for image builds; users should not use it. - The welcome app's Third-Party Repositories page and the Software Center's repository settings run the same `rum config-manager` through `pkexec`. ## How it differs from dnf - **`rum list` has no `--installed`.** Plain `rum list` already lists the installed overlay packages; `--base` lists the image's. `rum list --installed` and `dnf list --installed` are rejected as an unknown argument; the shim turns the keyword form `dnf list installed` into `rum list`. The other dnf filters exist: `--available`, `--extras`, `--obsoletes`, `--upgrades`, `--autoremove`. - **`dnf` is rum.** The shim runs `rum` with the same arguments. It rewrites `dnf list `, dnf4 verbs `groupinstall`, `groupremove`, `grouplist`, `groupinfo`, and refuses `dnf mark remove`. `dnf reinstall` is `rum reinstall`. - **Base packages are off limits.** `rum install` of a package the image provides prints ` is already installed (base image or overlay) — skipping`. `upgrade`, `reinstall`, `downgrade` and `distro-sync` print `'' is provided by the base image; rum will not layer a copy into the overlay to it — skipping.` A newer version arrives only with a new image. - **`rum upgrade` never touches the image.** Use `sudo rum system-upgrade`. - **Kernel modules follow the running kernel.** `upgrade` and `check-upgrade` only offer `rakuos-kmod-*` builds whose `rakuos-kmod-kernel` provides include the running kernel, and hold what an installed kmod requires at its installed version until the kmod updates ("Kept at the versions the installed kernel modules need: …"). Builds for a new kernel are installed by `kmod-upgrade`, which `system-upgrade`, the Software Center and RakuOS System run before an image update. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot#keeping-installed-modules-in-step-with-the-kernel). - **No offline system upgrade.** On an installed system `rum system-upgrade download|reboot|execute|…` is refused: "system-upgrade subcommands are Standalone-only — this is a RakuOS overlay system." A new Fedora release arrives as a new image. - **`rum system-upgrade` prepares a Fedora release change.** Before upgrading it reads the `org.rakuos.fedora.version` label of the image `bootc upgrade` will pull (`skopeo inspect`). When that release is higher than the running `VERSION_ID`, it prints "The new base image is built on Fedora N; skipping the overlay upgrade…", updates Flatpaks, runs `rakuos-reset-overlay --soft --releasever N` ("Preparing installed packages for Fedora N...") and only then `bootc upgrade`. If the soft reset fails: "soft reset for Fedora N failed …; the new base image was not staged". A failed label lookup leaves the normal path in place. - **Repo files go to rum's own dirs**, not `/etc/yum.repos.d`; see [Repo files](#repo-files). - **`--nodeps` is automatic.** rum resolves dependencies with libsolv, then runs rpm with `--nodeps`, because rpm sees only one half of the system. - **Local `.rpm` files** are installed from their own header, without dependency resolution. Install missing dependencies by name first. The file is kept in `/var/lib/rakuos/local-rpms/` so it can be reinstalled after a reset. - **Software that installs into `/opt`** is moved to `/usr/lib/opt/` and `/opt/` becomes a symlink (`Relocated /opt/ -> /usr/lib/opt/`), because `/opt` is `/var/opt`, outside the overlay. - **After an install** rum runs `ldconfig`, refreshes icon, MIME, desktop, font and GSettings caches, and reloads systemd. - **Installing an already-tracked package again** reinstalls it and its overlay dependencies: `Already tracked — reinstalling …`. - **Protected packages** (rum itself, the running kernel, `/etc/dnf/protected.d/*.conf`, `protected_packages=` in `rum.conf`) cannot be removed. ## Configuration `/etc/rum/rum.conf`, `[main]` section, dnf-style keys. Defaults when unset: `gpgcheck=1`, `best=1`, `retries=10`, `timeout=30`, `minrate=1000`, `max_parallel_downloads=3`, `metadata_expire=172800` (48 h), `installonly_limit=3`, `install_weak_deps=1`, `clean_requirements_on_remove=1`, `skip_if_unavailable=0`. `--setopt key=value` overrides one key for one command. `.repo` sections default to `enabled=1`, `gpgcheck=1`, `priority=99`. ## Logs rum writes no log file. Output goes to the terminal; set `RUST_LOG=debug` for detail: ```bash sudo RUST_LOG=debug rum install 2>&1 | tee ~/rum-debug.log # changes system as install does; also saves the output for a bug report rum history info # read-only: what one transaction did ``` Every error ends with `If you think this is a bug, please report it: https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum`. ## Errors and what to do | Message | Meaning | Safe fix | |---|---|---| | `rum requires root — try: sudo rum ` | changing command run without root | rerun with `sudo` | | `nothing provides ''` | no enabled repo has the package | check spelling with `rum search`; check `rum repolist --all`; it may live in Terra or RPM Fusion (both disabled by default) | | `could not resolve: …` | dependency conflict | read the listed problems; try `--skip-broken` only for the named package set, or report | | ` is already installed (base image or overlay) — skipping` | the base image or overlay already has it | nothing to do; `rum origin ` shows which | | `'' is provided by the base image; … skipping` | upgrades of base packages come with the image | `sudo rum system-upgrade` and reboot | | `package '' is not installed` | `reinstall` of a package neither base nor overlay has | install it instead | | `Nothing to reinstall — no matching candidate found.` | the repo has no build matching the installed version | `sudo rum upgrade `, or remove and install | | `signature verification failed during rpm transaction: …` then `Re-downloading the affected package(s) and retrying once...` | a downloaded package failed rpm's signature check; rum retries once | if the retry fails too, do not turn off signature checking; run `sudo rum clean packages`, retry, then report with the full message | | `checksum mismatch for …` | a download was corrupted or the mirror changed | `sudo rum clean metadata` and retry | | `Error: Not enough free space in …` | the disk is full | free space in `/var`; the check can be turned off with `diskspacecheck=0` but the install may then fail midway | | `'' is a protected package and cannot be removed` | listed as protected | do not force it | | `'' is the currently running kernel and cannot be removed` | | reboot into another kernel first | | `no enabled repos found in /etc/rum.repos.d` | every repo in all four repo dirs is disabled or none exist (the message names only the first dir) | `rum repolist --all`; re-enable `rakuos` and `fedora` with `config-manager --set-enabled` | | `no repo matches ''` / `no repo section named '[]' found under …` | a `config-manager` wildcard or id matched nothing | check the id with `rum repolist --all` | | `system-upgrade subcommands are Standalone-only …` | dnf-style offline upgrade on an installed system | `sudo rum system-upgrade` with no subcommand | ## Files missing after an update If a package shows as installed but some of its files under `/usr` are missing, an old overlay entry may be hiding the base image's copy. ```bash sudo rum restore-base-files --dry-run # read-only in effect: lists base-image files that are hidden sudo rum restore-base-files --dry-run # same, for one base package sudo rum restore-base-files # changes system: copies the missing files back from the booted image. No reboot. ``` It skips paths that an overlay package still owns. Removing an overlay package also restores base files it had replaced: `Restored N base-image file(s) the removed packages had replaced`. ## Interaction with the overlay and image updates - Files land in `/var/lib/rakuos/overlay/upper` through the mounted `/usr`. - After a reboot into a new image, the initrd refreshes the base package view; rum's overlay database is unaffected. See [How RakuOS works](https://rakuos.org/ai/01-architecture). - A soft reset (`sudo rakuos reset-overlay --soft`) pre-downloads `packages.list` with `rum install --downloadonly` (with `--releasever N`: `rum download --releasever N --alldeps`, the whole dependency closure from release N's repos) and reinstalls it on the next boot with `rum install --cacheonly`. See [rakuos-core](https://rakuos.org/ai/components/rakuos-core). --- # Diagnostics Run this read-only block before giving any advice. It avoids `cat`, which on RakuOS is bat: on a terminal it adds a frame and line numbers and opens a pager for long output (press `q` to leave it); use `gnu_cat` when plain file contents are needed. It identifies the edition, channel, image build, kernel and overlay state, and shows the boot-time overlay log. Nothing in it changes the system. As of 2026-10-15. Example output on this page comes from a customized COSMIC staging v4 test machine taken on 2026-10-14, while staging was still Fedora 44; staging is now Fedora 45, and values on a user's machine will differ. ## The block ```bash grep -E '^(PRETTY_NAME|VERSION_ID|VARIANT_ID)=' /etc/os-release # read-only sudo bootc status # read-only uname -r # read-only rum paths # read-only findmnt /usr # read-only journalctl -b -u 'rakuos-*' --no-pager | tail -n 60 # read-only journalctl -b -p err --no-pager | tail -n 60 # read-only: errors from any service this boot ``` When the problem involves a specific package, add: ```bash rum origin # read-only rum list --base | grep # read-only: in the base image? rum list | grep # read-only: installed into the overlay? rpm -V # read-only: lists missing or changed files ``` When a driver, kernel module or Secure Boot is involved, add: ```bash gnu_cat /proc/cmdline # read-only: kernel arguments in effect mokutil --sb-state # read-only: Secure Boot on or off rum list --base | grep rakuos-kmod # read-only: RakuOS-signed module packages in the image (none on stable images before 2026-10-17) rum list | grep rakuos-kmod # read-only: opt-in signed modules installed into the overlay rum list | grep -i -E 'akmod|dkms|kmod|nvidia' # read-only: module or driver packages in the overlay journalctl -k -b | grep -i -E 'rejected|verification failed' # read-only: modules the kernel refused ``` When a game's anti-cheat is involved, add `sudo rakuos eac-check` (read-only). When an app is blocked or fails with "permission denied", add: ```bash sudo ausearch -m AVC -ts today | grep apparmor # read-only ``` ## Reading the output ### os-release ``` PRETTY_NAME="RakuOS COSMIC Staging" VERSION_ID=44 VARIANT_ID=cosmic-staging ``` - `VARIANT_ID` is the edition: `kde`, `gnome`, `cosmic`, `niri`, `hyprland`, `gamescope`, or `rakuos` for the plain base. A `-staging` suffix means the staging channel; no suffix means stable (`latest`). - `VERSION_ID` is the Fedora release: 44 on stable, 45 on staging as of 2026-10-15. - The x86-64 level and NVIDIA are not here; read them from the image name below. ### sudo bootc status ``` spec: image: image: quay.io/rakuos/rakuos-cosmic-v4:staging status: staged: null booted: image: image: image: quay.io/rakuos/rakuos-cosmic-v4:staging version: staging.20261013 timestamp: 2026-10-13T20:37:04Z imageDigest: sha256:8399… rollback: … ``` - **Image name**: `quay.io/rakuos/rakuos-[-nvidia|-nvidia-legacy][-v3|-v4]:`. `-nvidia` means the NVIDIA image, `-nvidia-legacy` the 580xx NVIDIA image; `-v3`/`-v4` the x86-64 level (none = v2); the tag `latest` is stable, `staging` is staging. - **booted**: what is running now. **staged**: an update or switch waiting for the next reboot; `null` means none. **rollback**: what `sudo bootc rollback` would return to. - **version** is `.`. Several builds can share one date, so tell deployments apart by `imageDigest`, not by `version`. - `composefs: null` (in `sudo bootc status --json`) is normal on RakuOS, for booted and rollback entries alike. It is not a fault. - `usrOverlay: null` is also normal. bootc's own temporary `/usr` overlay is not used; the RakuOS overlay shows up in `findmnt /usr` instead. - If `bootc status` shows an image that is not under `quay.io/rakuos/`, the user has switched away from RakuOS images; most of this knowledge base then does not apply. ### uname -r `7.3.0-rakuos.2.v4.staging.fc45.x86_64` is `kernel-rakuos-v4-staging`, build 2, kernel 7.3.0, built for Fedora 45; a stable kernel has no `.staging` (e.g. `7.3.0-rakuos.1.v4.fc44.x86_64`), a gamescope kernel is `kernel-rakuos-deck-…`. A release containing `p03` (for example `7.2.8.p03raku…`) is a retired P03 kernel: update the system before troubleshooting further. ### rum paths ``` mode: split (RakuOS overlay) base snapshot rpmdb: /usr/share/rpm overlay rpmdb: /var/lib/rakuos/rum-rpmdb overlay upperdir: /var/lib/rakuos/overlay/upper ``` `mode: split` is correct on an installed system. `mode: standalone` on an installed system means the overlay is not active; see [Packages won't install or update; rum says standalone mode](https://rakuos.org/ai/troubleshooting/rum-standalone-mode). ### findmnt /usr Expected: `FSTYPE` `overlay` with `lowerdir=/sysroot/usr` and `upperdir=…/var/lib/rakuos/overlay/upper`. No overlay on `/usr` means overlay packages are not visible. ### journalctl -b -u 'rakuos-*' A healthy boot after an update looks like: ``` rakuos-overlay-mount: RakuOS overlay: pre-pivot hook starting... rakuos-overlay-mount: RakuOS overlay: deployment changed (…) — reseeding /usr/share/rpm view from new base... rakuos-overlay-mount: RakuOS overlay: reseed complete. rakuos-overlay-mount: RakuOS overlay: mounting persistent overlay over /sysroot/usr... rakuos-overlay-mount: RakuOS overlay: mounted. rakuos-base-protect: rakuos-base-protect: watching /var/lib/rakuos/overlay/upper rakuos-overlay-sync: RakuOS overlay sync: nothing to do. ``` - No `deployment changed` line: the boot used the same deployment as before (normal when nothing was updated). - `soft reset marker found`, `version change detected`, `DE change detected`: an overlay rebuild ran; `rakuos-overlay-sync` then reinstalls packages (network needed). - `CRITICAL — …`: whiteouts hid a whole `/usr` directory; a soft reset was queued automatically. - `RakuOS overlay: FATAL: …` or `RakuOS overlay sync: FATAL — …`: a bug; collect the full log and see [bug reporting](https://rakuos.org/ai/bug-reporting). - `rakuos-base-protect: BLOCKED …`: something tried to overwrite a base-image file; see [rakuos-core](https://rakuos.org/ai/components/rakuos-core#base-file-protection). - `bootloader-update: …`, `rescue-entries: …`, `os-entries: …`: boot menu and bootloader upkeep; see [rakuos-core](https://rakuos.org/ai/components/rakuos-core#boot-menu-and-bootloader). For one unit: `journalctl -b -u rakuos-overlay-sync.service`. If the problem happened before the last reboot, use `-b -1` instead of `-b`. An update that was staged but isn't running after the reboot (`booted` unchanged, `staged: null`) failed while being written at shutdown; its error is in `journalctl -b -1 -u ostree-finalize-staged.service` and `journalctl -b -u ostree-boot-complete.service`, not in any rpm-ostree log. See [Update not applied after reboot](https://rakuos.org/ai/troubleshooting/update-not-applied-after-reboot). ### rum origin and rpm -V - `rum origin `: `Base` (from the image), `Overlay` (installed by the user), `NotInstalled`. - `rpm -V ` lines starting `missing` name files the package should have but the system does not show. For a `Base` package this usually means something in the overlay hides the image's file; see [Package installed but its files are missing](https://rakuos.org/ai/troubleshooting/files-missing-after-update). ### Kernel modules and Secure Boot - `/proc/cmdline` on a current image contains `lockdown=integrity`, `module.sig_enforce=1`, `intel_iommu=on`, `iommu.passthrough=0`, `iommu.strict=1` and `sysctl.kernel.kexec_load_disabled=1`. Images built before rakuos-settings `65ffdaf` (2026-10-15) lack some of them. - `Key was rejected by service` from `modprobe`, or `Loading of unsigned module is rejected` in the kernel log: a locally built (akmod/DKMS) module; see [A driver won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load). - `rakuos eac-check` lines: `[ OK ]`, `[NOTE]`, `[FAIL]`, `[ ?? ]` (needs root); see [Anti-cheat not ready](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready). ### ausearch `AVC` records with `apparmor="DENIED"` are AppArmor denials, not SELinux. Note the `profile=`, `operation=` and `name=` fields and include them in a bug report against the project that owns the program. ## Before sharing output Remove user names, host names, IP and MAC addresses, e-mail addresses and serial numbers. See [bug reporting](https://rakuos.org/ai/bug-reporting#redacting-logs). --- # Anti-cheat games won't run, or the Anti-Cheat status isn't green Epic's Easy Anti-Cheat (EAC) Linux v2 only runs on a system with a locked-down, verifiable boot chain. RakuOS checks those requirements with `rakuos eac-check`, and the RakuOS System app shows the result as the "Anti-Cheat" button on its System page. Work through the failed items, safest first. Two limits apply to every system: the RakuOS key is not yet on Epic's list of well-known keys, and Epic does not support EAC Linux v2 on the Steam Deck yet. Whether a particular game runs is decided by Epic and the game's publisher, not by RakuOS. As of 2026-10-15 (rakuos-core `e08616c`, rakuos-system `fc07607`, rakuos-settings `65ffdaf`). ## Symptoms - A game protected by Easy Anti-Cheat refuses to start or reports an anti-cheat error. - RakuOS System > System shows "Anti-Cheat: Not Ready" (red) or "Anti-Cheat: Suggestions" (yellow). Clicking it opens "Anti-Cheat Readiness" with each requirement, its details and how to fix it. ## Confirm ```bash sudo rakuos eac-check # read-only: each requirement as [ OK ], [NOTE], [FAIL] or [ ?? ], with a "Fix:" line; root is needed for the measured-boot check rakuos eac-check --json # read-only: the same as JSON ({"ready": …, "checks": [{id, title, status, detail, fix}]}) ``` Without root, "Measured boot" shows `[ ?? ]` (the app shows "?"): the app runs the check as the user, so it shows yellow at best. The command exits non-zero when any item fails. ## Cause `rakuos eac-check` tests nine requirements: Secure Boot on, every enrolled MOK well known, no unsigned module loaded and signatures enforced, TPM 2.0, measured boot, IOMMU on without passthrough, lockdown set at boot, kexec disabled at boot, and the BPF LSM active. Firmware settings, an old image without the current kernel arguments, a leftover local signing key, or a locally built module are the usual reasons one fails. ## What to expect on a healthy RakuOS system - "Enrolled MOKs are well-known" is a `[NOTE]` even when everything is right: "… all well-known; the RakuOS key is awaiting Epic's well-known list." The best result the app can show today is therefore yellow "Suggestions", and `rakuos eac-check` ends with "This system meets the EAC Linux v2 requirements RakuOS can check." - On a Steam Deck (product name Jupiter or Galileo), the IOMMU item is a `[NOTE]`: "Steam Deck: Epic doesn't support EAC Linux v2 on it yet." Nothing on the Deck fixes this. ## Fix each failed item | Item (`id`) | Failure | Fix, safest first | |---|---|---| | Secure Boot (`secure_boot`) | "Booted in legacy BIOS mode, not UEFI." | Needs a reinstall booted in UEFI mode. Back up first; there is no in-place conversion. | | Secure Boot | "Disabled in firmware." | Queue the RakuOS key first: `sudo rakuos enroll-secureboot-key` (changes system: queues MOK changes for the next boot). Reboot into the firmware settings, enable Secure Boot, and complete MOK Manager on that boot (password `rakuos`). The RakuOS kernel boots with Secure Boot on only once its key is enrolled. Undo: disable Secure Boot in the firmware again. | | Enrolled MOKs (`mok`) | "Not well-known: …" | A locally generated key (old per-machine RakuOS key, akmods or DKMS key) is enrolled. `sudo rakuos enroll-secureboot-key` queues it for deletion; at the next boot choose **Delete MOK**, **Continue**, password `rakuos`, **Yes**, **Reboot**. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot#enrolling-the-rakuos-key-mok). | | Enrolled MOKs | "No MOKs are enrolled" / "The RakuOS key isn't enrolled." (`[NOTE]`) | `sudo rakuos enroll-secureboot-key`, then **Enroll MOK** at the next boot. | | Signed kernel & modules (`signed_modules`) | "An unsigned kernel module has been loaded since boot." | Find and remove the locally built module package from the overlay (see below), then reboot. | | Signed kernel & modules | "… signature enforcement is off." (`[NOTE]`) | Update to an image that boots with `module.sig_enforce=1`: Software Center Updates page or `sudo rum system-upgrade`, then reboot. | | TPM 2.0 (`tpm`) | "No TPM found." / "TPM version 1.2, not 2.0." | Enable the TPM (fTPM on AMD, PTT on Intel) in the firmware settings. A TPM 1.2-only machine cannot meet this. | | Measured boot (`measured_boot`) | "No TPM event log." / "The TPM event log has no boot loader measurements." | Usually follows from a missing TPM or Secure Boot off; fix those first and recheck. No RakuOS-side fix otherwise; report it with the `eac-check` output. | | IOMMU (`iommu`) | "The IOMMU is off." | Enable VT-d (Intel) or AMD-Vi/IOMMU in the firmware settings. | | IOMMU | "IOMMU passthrough is enabled on the kernel command line." / "Every device uses passthrough (identity) mapping." | RakuOS System > System > Kernel Parameters…: remove `iommu=pt` or `iommu.passthrough=1`, apply, reboot (changes system; undo by adding it back). | | Kernel lockdown (`lockdown`) | "Lockdown is off." / "… not set explicitly at boot" | Update to a current image, which boots with `lockdown=integrity`. On a current image, remove any `lockdown=` argument from Kernel Parameters…, apply, reboot. | | Kexec disabled (`kexec`) | "Kexec is allowed." / "… by sysctl after boot" (`[NOTE]`) | Update to an image that boots with `sysctl.kernel.kexec_load_disabled=1`, then reboot. | | BPF LSM (`bpf_lsm`) | "Not in the active LSMs (…)" | The RakuOS kernels list `bpf` in their built-in LSM order. Check Kernel Parameters… for an `lsm=` argument the user added; otherwise report it with `uname -r`. | Updating, when a fix says so: Software Center Updates page, or `sudo rum system-upgrade` (changes system: overlay packages, Flatpaks, then stages the new image; reboot; undo `sudo bootc rollback`). Check the result with `gnu_cat /proc/cmdline` (read-only). ### Finding a locally built module ```bash gnu_cat /proc/sys/kernel/tainted # read-only: non-zero; bit 13 (8192) set means an unsigned module was loaded journalctl -k -b | grep -i -E 'verification failed|tainting kernel' # read-only: names the module rum list | grep -i -E 'akmod|dkms|kmod' # read-only: overlay packages that build or carry modules ``` Remove the akmod/DKMS package with `sudo rum remove ` (changes system; undo `sudo rum install `) and reboot. If the hardware still needs that driver, install the matching `rakuos-kmod-*` package, or use an `-nvidia`/`-nvidia-legacy` image for NVIDIA; see [A driver, akmod or DKMS module won't load](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load). ## Do not - Do not turn Secure Boot off, add `lockdown=none`, `module.sig_enforce=0` or `iommu=pt`, or remove the image's kernel arguments as a fix: each one is an EAC requirement. - Do not install akmod or DKMS packages, or sign modules with a local key; a locally generated MOK fails the "well-known" check. - Do not promise that a game will run: the RakuOS key is not yet on Epic's list. ## Escalate - Wrong results from `rakuos eac-check` itself: [rakuos-core](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-core), with the full `sudo rakuos eac-check` output. - The Anti-Cheat button or dialog: [rakuos-system](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-system). - `enroll-secureboot-key` keeps a vendor key (for example Oracle, Proxmox, a BSD, or a Red Hat key not named "Fedora Secure Boot CA") that `eac-check` still lists as not well-known: the two lists differ as of `e08616c`. Report it against rakuos-core; do not delete vendor keys by hand. --- # System won't boot after an update Every update keeps the previous image as a second boot entry, so a system that hangs after an update can be started from the previous one. A known case: the niri stable v3 image of 2026-09-02 hung at the boot splash; the 2026-09-04 image fixed it. Status: https://rakuos.org/bugs/b/20260902-niri-stable-v3-standard-image-get-stuck-during-boot-5f544825 (rakuos-niri, open). As of 2026-10-14. ## Symptoms The boot splash flickers and freezes, or boot never reaches the login screen, right after an update. ## Confirm At power-on, the GRUB menu is shown for 5 seconds and lists two RakuOS entries, `(ostree:0)` (newest) and `(ostree:1)` (previous). ## Fix 1. In the GRUB menu, pick the `(ostree:1)` entry. This boots the previous image once and changes nothing. 2. Once booted, make it the default until a fixed image is out: ```bash sudo bootc rollback # changes system: the previous image boots by default. Reboot required. Undo: sudo bootc rollback again ``` 3. Later, update again (Software Center or `sudo rum system-upgrade`); a newer image replaces the broken one. The overlay is kept unless the two images are on different Fedora releases or editions. If the boot gets to the splash but stops at "Installing user applications..." or similar every time, the overlay reinstall is failing: see [Stuck at boot after a reset](https://rakuos.org/ai/troubleshooting/stuck-at-boot-overlay). If the machine boots fine but is still on the old image, the update was never written: see [Update not applied after reboot](https://rakuos.org/ai/troubleshooting/update-not-applied-after-reboot). ## Escalate File against the edition's image project with the image names and dates of both entries (`sudo bootc status`) and `journalctl -b -1 --no-pager | tail -n 100` from the failed boot if it got that far. --- # App installed from a downloaded .rpm won't start rum installs a downloaded `.rpm` file without resolving its dependencies. If the package needs a library the system does not have, it installs but fails to start. As of 2026-10-14 (rum `87388ff`). Reported in https://rakuos.org/bugs/b/some-packages-doesn-t-update-on-rakuos-software-niri-45f8117f. ## Symptoms - The app appears in the launcher but nothing happens when clicked. - From a terminal: `error while loading shared libraries: libwebkit2gtk-4.1.so.0: cannot open shared object file: No such file or directory`. ## Confirm ```bash # read-only: start it from a terminal to see the error rum provides 'libwebkit2gtk-4.1.so.0()(64bit)' # read-only: which package provides the missing library (use the exact name from the error) ``` `rum provides` matches capability names exactly; add `()(64bit)` for 64-bit libraries. It does not search file paths. ## Cause Local `.rpm` files are installed from their own header without dependency resolution. The vendor's package may also expect libraries Fedora 44 does not ship. ## Fix 1. Install the package that provides the missing library: ```bash sudo rum install # changes system: adds it to the overlay; no reboot. Undo: sudo rum remove ``` 2. If no package provides it, use the app's Flatpak, or run it in a Distrobox container with a distribution it supports. 3. Remove the broken app: `sudo rum remove ` (changes system; undo by reinstalling the file). ## Escalate Not a RakuOS bug unless a RakuOS repo package has the same problem. Missing dependencies in a vendor's `.rpm` belong to the vendor. --- # Encrypted install fails in the text-mode installer The text-mode installer offers "TPM2" and "Passphrase" encryption, but the installer backend rejects both values, so an encrypted text-mode install always fails. The graphical installers are not affected. As of 2026-10-14 (rakuos-installer `f93ef72`). Found in code; no tracker issue yet. ## Symptoms Installing from "Text-Mode Installer" (minimal ISO) with disk encryption stops with: ``` fatal: … encryption.type "luks" is not valid ``` (or `"tpm2"`). ## Cause The text installer sends `tpm2` or `luks`; the backend accepts only `none`, `tpm2-luks`, `luks-passphrase` and `tpm2-luks-passphrase`. ## Fix 1. Use a graphical installer (KDE, GNOME, COSMIC or niri ISO), which sends valid values. 2. Or install unencrypted in text mode. ## Escalate Bug against rakuos-installer. --- # Package installed but its files are missing after an update A package the user had installed with rum, and which a later image then also shipped, can end up showing as installed while its files are missing: the overlay hides the image's copies. rum refuses to reinstall it because the image provides it. Seen with `xrdb` and `fuse-libs` after the `staging.20261003` update. Status: open bug, https://rakuos.org/bugs/b/overlay-whiteouts-hide-base-image-files-after-layered-packages-moved-into-the-base-image-xrdb-fuse-libs-4d54a1a8 (rakuos-base; fix planned in rakuos-core's base-file protection). As of 2026-10-14. ## Symptoms - "Command not found" for a program that rum lists as installed (`rum list --base | grep ` or `rum list | grep `; e.g. `xrdb`). - AppImages stop starting because `libfuse.so.2` is missing. - COSMIC logs `` `xrdb` not found, cannot update Xresources `` at login. - `sudo dnf reinstall ` or `sudo rum reinstall ` prints `'' is provided by the base image; rum will not layer a copy into the overlay to reinstall it — skipping.` and `Nothing to reinstall — no matching candidate found.` ## Confirm ```bash rum origin # read-only: Base rpm -V # read-only: "missing" lines for files under /usr sudo rum restore-base-files --dry-run # read-only in effect: lists the hidden base files rum can put back rpm --dbpath /var/lib/rakuos/rum-rpmdb -q # read-only: whether the overlay database still records the package ``` ## Cause The package's files were removed from the overlay through the merged `/usr`, which makes overlayfs record "deleted" markers (whiteouts) in `/var/lib/rakuos/overlay/upper`. Those markers now hide the image's copies of the same files. The boot-time reseed refreshes only the package database view, so nothing clears the markers. ## Fix Safest first. Note the current image first: `sudo bootc status` (rollback is the fallback if anything goes wrong). 1. Restore the hidden files from the booted image. No reboot needed. ```bash sudo rum restore-base-files # changes system: copies the missing files from the booted image into /usr (the overlay). Undo: not needed; the copies are identical to the image's files rpm -V # read-only: should no longer list missing files ``` If the dry run listed nothing although `rpm -V` shows missing files, the overlay database still records the package (the last command in Confirm prints a version). Go to step 2. 2. Soft reset: rebuilds the overlay from the package list, which removes all the markers. Needs the network and a reboot; every overlay package is reinstalled. ```bash cp /var/lib/rakuos/packages.list ~/packages.list.bak # changes only the home dir: backup sudo rakuos reset-overlay --soft # changes system: at next boot wipes the overlay and reinstalls packages.list; reboot required ``` If it prints `Soft reset aborted — nothing has been changed.`, a package in the list can no longer be installed; fix that first (see [rum errors](https://rakuos.org/ai/components/rum#errors-and-what-to-do)). Do not delete files under `/var/lib/rakuos/overlay/upper` by hand. ## Escalate Known bug; add details to the tracker issue above instead of filing a new one. If files are still missing after a soft reset, file a new bug against rakuos-core with `rpm -V ` output and `journalctl -b -u 'rakuos-*'`. --- # KDE file search finds nothing KDE's file search uses the Baloo indexer. One report shows `balooctl6 status` failing with "Unable to open Baloo index". Nothing in the RakuOS KDE image changes Baloo's configuration, and the cause is not known yet. Status: open, https://rakuos.org/bugs/b/file-search-in-kde-isn-t-working-d55d7792 (rakuos-kde). As of 2026-10-14. ## Symptoms - Searching for files in the launcher or Dolphin finds nothing. - `balooctl6 status` prints `Unable to open Baloo index`. ## Confirm ```bash balooctl6 status # read-only sudo ausearch -m AVC -ts today | grep -i baloo # read-only: any AppArmor denials for baloo ``` ## Cause Unknown. The KDE image does not disable or configure Baloo. ## Fix No verified fix yet. ## Escalate Add `balooctl6 status`, the image date from `sudo bootc status`, and any denial lines to the issue above. --- # No printer settings on KDE KDE images built before 2026-10-09 had no graphical printer setup. `system-config-printer` was added to the KDE image on 2026-10-07 (staging only) and on 2026-10-09 (stable). Printing itself (CUPS) is in every image. Status: open, https://rakuos.org/bugs/b/no-gui-for-printer-management-75736374 (rakuos-kde; maintainer reply 2026-10-13: "this is getting added"). As of 2026-10-14. ## Symptoms There is no app or settings page for adding a printer on a fresh KDE install. ## Confirm ```bash rum list --base | grep -E '^(system-config-printer|cups)-[0-9]' # read-only: in the image? rum list | grep -E '^(system-config-printer|cups)-[0-9]' # read-only: installed into the overlay? sudo bootc status # read-only: image date ``` ## Fix 1. Update the system and reboot: Software Center, or `sudo rum system-upgrade` (changes system; reboot required; undo `sudo bootc rollback`). Images from 2026-10-09 (stable) or 2026-10-07 (staging) include `system-config-printer`; start it from the launcher or with `system-config-printer`. 2. Before updating, install it into the overlay: ```bash sudo rum install system-config-printer # changes system: adds it to the overlay; no reboot. Undo: sudo rum remove system-config-printer ``` After a later update that includes it in the image, rum treats it as part of the image. ## Escalate Add to the issue above if the package is still missing on a newer image. --- # KDE asks for a password when going to standby On KDE, putting the system to sleep with the power button asked for the root password. The reporter found that a reboot fixed it. The cause is not known from the code. Status: open, https://rakuos.org/bugs/b/putting-the-system-into-standby-mode-requires-the-root-password-0b12103b (rakuos-kde; reporter said on 2026-10-13 that a reboot fixed it). As of 2026-10-14. ## Symptoms Pressing the power button or choosing Sleep shows an authentication dialog asking for a password. ## Confirm ```bash id # read-only: is the user in group wheel? systemd-inhibit --list # read-only: programs currently blocking sleep sudo bootc status # read-only: image date, for the report ``` ## Cause Unknown. No RakuOS repo ships a rule for sleep authentication. Possibilities to check: a program holding a sleep inhibitor (the `systemd-inhibit --list` output), or a user account outside the `wheel` group. ## Fix 1. Reboot, then try again. (No change.) 2. If a program in `systemd-inhibit --list` holds a sleep lock (for example a game or a `game-performance` session), close it and retry. ## Escalate If it continues after a reboot, add `id` and `systemd-inhibit --list` output to the issue above. --- # A driver, akmod or DKMS module won't load RakuOS kernels load only signed modules (`module.sig_enforce=1`, `lockdown=integrity`), and RakuOS signs the out-of-tree modules it ships with its own key. A module built on the user's machine by an `akmod-*` or `dkms-*` package, or by `make`, has no RakuOS signature and is refused. The fix is the RakuOS-built package for that driver, an image that ships it, or asking RakuOS to build it, never building or signing locally. As of 2026-10-15 (rakuos-settings `65ffdaf`, signed-kmods `f0bd68c` on `staging`, rakuos-core `e08616c`). ## Symptoms - `modprobe ` fails with `Key was rejected by service`; the kernel log says `Loading of unsigned module is rejected` or `Loading of module with unavailable key is rejected` (upstream kernel messages). - Hardware that needs an out-of-tree driver (NVIDIA, Broadcom Wi-Fi, Xbox wireless, a racing wheel, a capture card, VirtualBox) doesn't work after installing an akmod or DKMS package, or after `rakuos setup-nvidia`. - `rum install akmod-` or `dkms-` fails with a conflict against `rakuos-kmod-`. ## Confirm ```bash gnu_cat /proc/cmdline | tr ' ' '\n' | grep -E 'sig_enforce|lockdown' # read-only: module.sig_enforce=1 and lockdown=integrity journalctl -k -b | grep -i -E 'rejected|verification failed' # read-only: which module was refused rum list | grep -i -E 'akmod|dkms|kmod' # read-only: module packages in the overlay rum list --base | grep rakuos-kmod # read-only: RakuOS-signed modules the image ships rum list | grep rakuos-kmod # read-only: opt-in RakuOS-signed modules installed into the overlay rum search rakuos-kmod- # read-only: is there a RakuOS build of this module? sudo bootc status | grep 'image:' # read-only: image name (-nvidia, -nvidia-legacy) and channel ``` ## Cause The image's kernel arguments make the kernel refuse unsigned modules. RakuOS ships its out-of-tree modules prebuilt and signed: as `rakuos-kmod-` packages (`-staging` on staging) built by the signed-kmods repo. Locally built modules are not signed with the RakuOS key, and RakuOS no longer creates a per-machine signing key. `rakuos setup-nvidia` and `setup-nvidia-legacy` still install DKMS NVIDIA packages as of rakuos-core `e08616c`, so they run into the same refusal. ## Fix 1. **NVIDIA**: use the NVIDIA image instead of installing a driver. Remove what was installed into the overlay first: `rum list | grep -i nvidia` (read-only), then `sudo rum remove ` (changes system; undo by installing them again). Then switch in RakuOS System > System (Nvidia: "Nvidia", or "Nvidia Legacy" for Maxwell, Pascal and Volta GPUs), or: ```bash sudo bootc switch quay.io/rakuos/rakuos--nvidia[-v3|-v4]: # changes system: stages the NVIDIA image of the same edition, level and channel; reboot; undo sudo bootc rollback sudo bootc switch quay.io/rakuos/rakuos--nvidia-legacy[-v3|-v4]: # same, 580xx driver for Maxwell, Pascal and Volta GPUs ``` Keep the edition, `-v3`/`-v4` and channel from the current image name. `setup-nvidia` also replaced the user's kernel arguments with `rd.driver.blacklist=nouveau modprobe.blacklist=nouveau`; review RakuOS System > System > Kernel Parameters… afterwards. 2. **A module RakuOS already builds** (see the lists in [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot)): remove the akmod/DKMS package (`sudo rum remove akmod-`; changes system; undo by reinstalling). Images built from 2026-10-23 on ship only `wl` and `v4l2loopback`; every other module (`xone`, `xpadneo`, `xpad-noone`, the racing wheel drivers, `ayaneo-leds`, `sc0710`, `nct6687d`, `ryzen_smu`, `zenergy`, …) is opt-in: install its `rakuos-kmod-` package from RakuOS System's Drivers page or with `sudo rum install rakuos-kmod-` (add the system's suffix; most need Terra on first; changes system; undo `sudo rum remove`), then reboot. **A module that worked and stopped after an update** is most likely one of these: images before 2026-10-23 shipped it, newer ones don't. If the module is still missing after installing, report it. 3. **OpenRazer** and **MediaTek MT7927** (opt-in since 2026-10-17: `rakuos-kmod-mediatek-mt7927` with the system's suffix): built but no longer in the images; install `rakuos-kmod-openrazer` with the system's suffix into the overlay, see [Installing OpenRazer](https://rakuos.org/ai/components/kernel-modules-secure-boot#installing-openrazer). Remove `akmod-openrazer` first if it was installed. **xtables-addons, Intel IPU6 and Intel Vision** (opt-in since 2026-10-23): remove the akmod/DKMS package, enable RPM Fusion (Terra for IPU6), install `rakuos-kmod-` with the system's suffix and reboot; see [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). 4. **VirtualBox**: install the RakuOS build into the overlay together with VirtualBox; see [Installing VirtualBox](https://rakuos.org/ai/components/kernel-modules-secure-boot#installing-virtualbox). Remove `akmod-VirtualBox` first if it was installed. For virtual machines without a kernel module, `sudo rakuos setup-virtualization` installs KVM/QEMU. 5. **Any other module**: ask for it in the RakuOS Discord or at https://rakuos.org/bugs, naming the akmod or DKMS package it comes from; RakuOS adds it to signed-kmods' `modules.list`. Meanwhile remove the local package so it doesn't fail at every boot. ## Do not - Do not suggest disabling Secure Boot, adding `module.sig_enforce=0` or `lockdown=none`, or removing the image's kernel arguments: RakuOS System has no setting for this, and these are also anti-cheat requirements. - Do not suggest generating a signing key, `mokutil --import` of a self-made key, `kmodgenca`, `sign-file`, or `dkms` signing settings: locally generated MOKs are removed by `rakuos enroll-secureboot-key` and fail the anti-cheat check. - Do not suggest `akmods --force`, `dkms autoinstall`, `insmod` of a self-built `.ko`, or RPM Fusion's `akmod-nvidia`. ## Escalate A `rakuos-kmod-*` module that is installed but fails to load or misbehaves: report it to RakuOS (signed-kmods project, or rakuos-base if that project is not listed), with `uname -r`, `rum list --base | grep rakuos-kmod` and `rum list | grep rakuos-kmod`, and the kernel log lines. NVIDIA driver problems on an `-nvidia` image: [nvidia-drivers](https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers). --- # Removing Brave or Chromium leaves a broken /opt link Apps that install into `/opt` (Brave, Chromium and others) are moved by rum to `/usr/lib/opt/`, and `/opt/` becomes a link to it. When the app is removed, the link can stay behind, pointing at nothing. Status: open bug, https://rakuos.org/bugs/b/when-removing-a-package-that-puts-files-in-usr-lib-opt-brave-chromium-rum-does-not-properly-remove-the-symlink-located-in-opt-965525d1 (rakuos-rum). As of 2026-10-14. ## Symptoms - After `sudo rum remove brave-browser`, `/opt/brave.com` still exists. - Older rum versions then failed to reinstall the app with `warning: rpm exited with exit status: 1 (a package scriptlet failed)`. ## Confirm ```bash ls -l /opt/ # read-only: lists links such as brave.com -> /usr/lib/opt/brave.com test -e /opt/brave.com || echo "broken link" # read-only: prints "broken link" if the target is gone rum origin brave-browser # read-only: NotInstalled after removal ``` ## Cause `/opt` is `/var/opt`, outside the overlay. On removal rum deletes the `/opt/` link only if `/usr/lib/opt/` still exists and is empty after the removal; if the directory is already gone, or something is left in it, the link stays. ## Fix 1. If you plan to reinstall the app: just reinstall it. Current rum clears a stale `/opt/` before installing ("Clearing stale /opt/ … before install"). ```bash sudo rum install brave-browser # changes system: installs into the overlay; no reboot. Undo: sudo rum remove brave-browser ``` 2. If the app should stay removed and the link is broken (confirmed above): remove only the link. ```bash sudo rm /opt/brave.com # changes system: deletes the broken link only (not a directory). Undo: sudo ln -s /usr/lib/opt/brave.com /opt/brave.com ``` Use `rm` without `-r`: if `/opt/` is a real directory rather than a link, stop and report it. A soft or hard overlay reset also removes these links, but is far more than this needs. ## Escalate Known bug; add details to the issue above. --- # Packages won't install or update; rum says standalone mode On an installed system rum must run in split mode, writing into the `/usr` overlay. If it reports standalone mode instead, the overlay is not active, and installs or upgrades fail, often with a full or read-only `/`. As of 2026-10-14 (rum `87388ff`, rakuos-core `e08616c`). Reported in https://rakuos.org/bugs/b/rakuos-updates-cannot-be-upgraded-39b15302 (open, August 2026). ## Symptoms - `Error: Not enough free space in / (need 3.7 GiB, have 0 B available)`. - fastfetch shows `disk … overlay [Read-only]` and `overlay 0 (Packages)`. - Packages the user installed are gone or not listed. ## Confirm ```bash rum paths # read-only: "mode: standalone (…)" is the problem; "mode: split" is correct ls -l /var/lib/rakuos/current-deploy # read-only: rum uses split mode only when this file exists findmnt /usr # read-only: should be an overlay with upperdir=…/var/lib/rakuos/overlay/upper journalctl -b -u rakuos-overlay-mount -u rakuos-overlay-sync --no-pager # read-only ``` ## Cause rum chooses split mode when `/var/lib/rakuos/current-deploy` exists. The initrd writes that file at every boot from the `ostree=` boot argument. It can be missing, or the overlay unmounted, after a failed boot step or after commands that bypassed rum (for example running real dnf or rpm against the system). ## Fix 1. Reboot once. The initrd recreates `current-deploy` and mounts the overlay; then check `rum paths` again. (No change beyond the reboot.) 2. If the journal shows `RakuOS overlay: FATAL` or the overlay still does not mount, do not run more package commands. Collect the outputs from Confirm and report it. 3. If the system booted fine before the last update, roll back: `sudo bootc rollback` (changes system: next boot uses the previous image; reboot required; undo: `sudo bootc rollback` again). Do not set `diskspacecheck=0` to get past the free-space error: the error is a symptom of the overlay not being active, and turning the check off does not fix that. ## Escalate Bug against rakuos-core (overlay not mounted) with the Confirm outputs. In the August report, a reinstall was the only fix the maintainer had found; ask on the tracker before reinstalling. --- # Install fails with "signature verification failed" rum checks every package's signature through rpm. When the check fails, rum deletes the download, fetches it again and retries once; if it fails again, the install stops. The usual causes are a third-party repository that publishes unsigned packages, or a key that was never imported. Status: open report, https://rakuos.org/bugs/b/failed-signature-verification-for-some-rpm-packages-after-trying-to-reinstall-some-apps-that-doesn-t-appear-on-the-overlay-92b56449 (rakuos-rum, in progress; the original Zen/Discord case was reported fixed by later updates on 2026-08-26). As of 2026-10-14. ## Symptoms ``` warning: signature verification failed for (repo ''): … Re-downloading the affected package(s) and retrying once... Error: applying rpm transaction: signature verification failed during rpm transaction: package does not verify: no signature ``` The welcome app or Software Center shows the install as failed. ## Confirm ```bash sudo bootc status # read-only: note the image version; older images had this bug rum info # read-only: which repo the package comes from rum repolist --all # read-only: was a third-party repo added? ``` ## Cause - `does not verify: no signature`: the repository publishes unsigned packages. Seen with a third-party repo added by the user (rpmsphere). - A NOKEY or "public key" error: the repo's key is not imported. rum imports keys only for repos with `gpgcheck=1` and a `gpgkey=` line. - On images from August 2026, reinstalling apps after an overlay rebuild failed this way for packages from the `rakuos` repo; later images fixed it. ## Fix 1. Update the system, then retry: `sudo rum system-upgrade` (changes system; reboot to use the new image; undo with `sudo bootc rollback`). 2. Clear the cached download and retry: ```bash sudo rum clean packages # changes system: deletes downloaded packages in /var/cache/rum; they are fetched again when needed sudo rum install # changes system: installs into the overlay. Undo: sudo rum remove ``` 3. For an unsigned third-party package, use the app's Flatpak, or run it in a Distrobox container, instead. Do not turn off signature checking. `rpm-ostree install --nogpgcheck`, suggested in the tracker thread, does not apply: rpm-ostree is not installed. ## Escalate If a package from the `rakuos` repo fails after an update and a cache clean, add the full error to the issue above. Problems with third-party repos belong to that repo's maintainers. --- # Software Center's System tab is gone The System tab was removed from the Software Center on purpose on 2026-09-21. Image switching, rollback, deployments, overlay reset, kernel arguments and zram are now in the separate **RakuOS System Management** app. Status: closed (by design), https://rakuos.org/bugs/b/260930-rakuos-niri-image-lost-the-system-tab-in-rakuos-software-3df8d05a. As of 2026-10-14. ## Symptoms The Software Center has no System page after an update, on any edition. ## Confirm ```bash rum list --base | grep rakuos-system- # read-only: one of rakuos-system-gtk, -qt or -cosmic should be in the image ``` ## Fix Open "RakuOS System Management" from the app launcher, or run `rakuos-system`. See [RakuOS System](https://rakuos.org/ai/components/rakuos-system). ## Escalate If no `rakuos-system-*` package is installed, report it against the edition's image project. --- # Software Center updates hang, show "Retry", or never say to reboot The Software Center's Updates page has three open or in-progress reports: "Update All" switching to "Retry" without updating, the Updates page reloading during an image update, and no progress or reboot message when the only update is a new image. The same updates can be done from a terminal. As of 2026-10-14. Tracker: https://rakuos.org/bugs/b/some-packages-doesn-t-update-on-rakuos-software-niri-45f8117f (in progress), https://rakuos.org/bugs/b/why-is-rakuos-software-reloading-during-update-a6b0f08c (in progress, fix announced for the next stable update), https://rakuos.org/bugs/b/no-progress-bar-or-indication-for-reboot-when-using-full-update-0a8b6f89 (open). ## Symptoms - "Update All" changes to "Retry" and nothing updates. - The Updates page keeps reloading a few seconds into an image update. - After "Update All" with only an image update, it says "updating" and never says to reboot. ## Confirm ```bash sudo bootc status # read-only: "staged:" not null means an image update is already waiting for a reboot journalctl -u rakuos-bootc-upgrade.service -n 50 # read-only: progress of an image update started from the app rum check-upgrade # read-only: overlay packages with updates flatpak remote-ls --updates # read-only: Flatpak updates ``` ## Fix 1. If `bootc status` shows a staged image, the image update finished: reboot. 2. Otherwise update from a terminal: ```bash sudo rum system-upgrade # changes system: overlay packages, Flatpaks, then stages the new image. Reboot to use it. Undo after reboot: sudo bootc rollback ``` 3. Flatpaks only: `flatpak update` (changes system: updates installed Flatpaks; no reboot; RakuOS tools offer no undo for this step). ## Escalate Add details to the matching issue above. Include the edition, which frontend (GTK, Qt or COSMIC), and the `journalctl` output. --- # Software Center won't open "Add/Remove Software" can appear to do nothing when launched: a hidden instance started by the tray at login already holds the app's single-instance name. This was reported on the niri image and marked fixed on 2026-09-27. Status: fixed, https://rakuos.org/bugs/b/rakuos-software-center-rakuos-software-gtk-fails-to-open-on-niri-image-82a07770 (rakuos-software). As of 2026-10-14. ## Symptoms - Clicking "Add/Remove Software" does nothing. - The first launch shows a window that closes, then nothing for several seconds (that part is normal: the first launch per user starts, stops and restarts the app). ## Confirm ```bash sudo bootc status # read-only: image date; images built after 2026-09-27 have the fix pgrep -af rakuos-software # read-only: a running rakuos-software-gtk with no visible window is the hidden instance ``` ## Cause On affected images the tray autostart (`/etc/xdg/autostart/rakuos-software-tray.desktop`, `rakuos-software --tray`) left a windowless instance that owned the `org.rakuos.Software` name, so later launches only signalled it. ## Fix 1. Wait about 10 seconds after the first click; the first launch per user restarts the app on purpose. 2. Quit the hidden instance from the tray menu ("Quit"), or end it, then launch again: ```bash pkill -f rakuos-software-gtk # changes nothing permanent: ends the running Software Center for this session ``` 3. Update the system to a fixed image: Software Center if it opens, otherwise `sudo rum system-upgrade` (changes system; reboot to use the new image; undo `sudo bootc rollback`). 4. On an old image that cannot be updated yet, stop the tray from autostarting for this user: ```bash touch ~/.config/rakuos/disable-tray # changes the user's settings: no tray at the next login. Undo: rm ~/.config/rakuos/disable-tray ``` ## Escalate If it still happens on an image newer than 2026-09-27, file a new bug against rakuos-software with `pgrep -af rakuos-software`, the edition, and output from starting `rakuos-software` in a terminal. --- # Stuck at boot after a reset or package reinstall After a soft reset, a Fedora release change or an edition switch, `rakuos-overlay-sync` reinstalls the user's packages at boot, before the login screen. If that fails every time, the machine never reaches the desktop. Every RakuOS GRUB menu built from 2026-10-16 on has a **RakuOS rescue** submenu that boots without the overlay and without that step, so the user can log in and reset. As of 2026-10-16 (rakuos-core `1878829`). ## Symptoms - Every boot stops at the splash with "Installing user applications...", "Finalizing initial package overlay..." or "Connect to the internet, then reboot to finish installing default applications.", or reboots on its own and starts over. - It began right after `sudo rakuos reset-overlay --soft`, an update to a new Fedora release, or switching edition or channel. If the boot hangs before that (kernel or splash freeze right after an update), see [System won't boot after an update](https://rakuos.org/ai/troubleshooting/boot-stuck-after-update) instead. ## Boot the rescue entry 1. In the GRUB menu (shown 5 seconds), open **RakuOS rescue (text console, user packages off)** and pick the first entry (the newest image). 2. Log in on the text console with the normal user name and password. No submenu (an image older than 2026-10-16): highlight the normal top entry, press `e`, go to the end of the line that starts with `linux`, add ``` rakuos.rescue rd.systemd.mask=rakuos-overlay-mount.service systemd.mask=rakuos-overlay-sync.service systemd.unit=multi-user.target ``` and press Ctrl+X (or F10) to boot it once. Nothing is saved. ## Confirm ```bash grep -o rakuos.rescue /proc/cmdline # read-only: rakuos.rescue = this is a rescue boot findmnt /usr # read-only: no "overlay" line, the plain image /usr journalctl -b -1 -u rakuos-overlay-sync --no-pager | tail -n 50 # read-only: why the reinstall failed on the previous boot cat /var/lib/rakuos/packages.list # read-only: the packages it tries to reinstall ``` Typical causes: no network at boot, or a package in `packages.list` that no repo offers any more (often from a third-party repo, Terra or RPM Fusion turned off, or a Fedora release change). ## Fix 1. Back up the package list: `cp /var/lib/rakuos/packages.list ~/packages.list.bak` (changes only the home dir). 2. Queue a full reset, which drops every user-installed RPM and returns to the image's own packages: ```bash sudo rakuos reset-overlay --confirm # changes system, destructive: at the next boot wipes the overlay and packages.list. Reboot required. Cannot be undone; reinstall packages from the backup afterwards with sudo rum install ``` `sudo rakuos reset-overlay --soft` keeps the list and reinstalls it, so it only helps if the cause is gone (for example, the network now works). It first downloads every package with rum; if it refuses or fails in the rescue boot, use `--confirm`. 3. Reboot normally (`sudo systemctl reboot`) and let the default entry start. The reset runs in the initrd; the desktop comes up with the image's packages. 4. Reinstall what is needed from `~/packages.list.bak` with `sudo rum install …`, skipping the package that failed. ## Do not - Do not install or remove packages with rum in the rescue boot: the overlay isn't mounted there. - Do not delete files under `/var/lib/rakuos` by hand, and do not disable `rakuos-overlay-sync.service` permanently. - Do not suggest reinstalling RakuOS, or Fedora/Silverblue fixes such as `rpm-ostree reset`. ## Escalate If the full reset also fails to boot, or the sync failed on a package RakuOS ships, report it against rakuos-core with `journalctl -b -1 -u rakuos-overlay-sync`, `journalctl -b -1 | grep 'RakuOS overlay'` and `sudo bootc status`. --- # System freezes or kernel panics Start from the diagnostics: which kernel and image the system runs, and what the kernel logged before the freeze. Freezes reported in September 2026 came from systems still on the retired P03 kernel, and updating is the first fix. Switching to an NVIDIA image is a separate, narrower step that applies only when NVIDIA hardware runs on a non-NVIDIA image. Status: open report https://rakuos.org/bugs/b/kernel-panics-aa284459 (filed under rakuos-cosmic-iso, about an installed COSMIC v2 system with NVIDIA graphics; maintainers suspected the P03 kernel and suggested updating). As of 2026-10-15 (tracker read 2026-10-14). ## Symptoms - The desktop freezes while browsing or reading mail; only a hard reset helps. - A kernel panic screen. ## Confirm Run the [diagnostics block](https://rakuos.org/ai/troubleshooting/diagnostics), then: ```bash journalctl -b -1 -k --no-pager | tail -n 80 # read-only: kernel messages from the boot that froze ``` Note from the diagnostics: the kernel release (`uname -r`; one containing `p03` is retired) and the image name in `sudo bootc status`. ## Cause Several possible causes; the code does not settle which. The September reports pointed at the retired P03 kernel. ## Fix 1. Update and reboot: Software Center, or `sudo rum system-upgrade` (changes system; reboot required; undo `sudo bootc rollback`). 2. If the freezes started with a particular update, roll back: `sudo bootc rollback` (changes system; reboot required; undo: roll back again). ## Only if the machine has an NVIDIA GPU and runs a non-NVIDIA image This step is based on one user report (NVIDIA graphics on a non-NVIDIA image) and on the existence of the `-nvidia` images. It is not a code-confirmed fix for freezes. Check both conditions first: ```bash lspci -nn | grep -i -E 'vga|3d' | grep -i nvidia # read-only: prints a line only if an NVIDIA GPU is present sudo bootc status | grep 'image:' # read-only: the image name must NOT contain "-nvidia" ``` If both hold, switching to the matching `-nvidia` image is reasonable to try: in the RakuOS System app (System page, NVIDIA), or ```bash sudo bootc switch quay.io/rakuos/rakuos--nvidia[-v3|-v4]: # changes system: stages the NVIDIA image of the same edition, level and channel; reboot required; undo: sudo bootc rollback. The overlay stays as it is. ``` Keep the edition, the `-v3`/`-v4` level and the channel from the current image name. If the image already has `-nvidia`, or there is no NVIDIA GPU, skip this step. For a Maxwell, Pascal or Volta GPU (GeForce 900 and 10 series, Titan V), the matching image is `-nvidia-legacy` (580xx driver); RakuOS System offers it as "Nvidia Legacy". Do not install a driver with `rakuos setup-nvidia`, akmods or DKMS: such modules are unsigned and do not load. ## Escalate Kernel panics with current images: file against [kernel](https://rakuos.org/bugs/p/rakuos-packages-rakuos-kernel) with `uname -r` and the kernel log; NVIDIA-specific problems against [nvidia-drivers](https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers). --- # App shows in the Software Center but fails with "nothing provides" The Software Center's catalog includes apps from the Terra repository, but Terra is disabled by default. Installing a Terra-only app then fails because rum cannot see that repository. As of 2026-10-15 (rakuos-software `7096eb2`, rakuos-rum `87388ff`). ## Symptoms - The Software Center lists an app (shown as from "RakuOS Linux", or "Terra" in GTK search), but installing it fails. - From a terminal, `sudo rum install ` prints `nothing provides ''`. ## Confirm ```bash rum repolist --all | grep -i terra # read-only: shows whether terra is enabled rum search # read-only: no result while Terra is disabled ``` ## Cause The image ships Terra's app catalog for the Software Center, and the Software Center installs with plain `rum install`, which only uses enabled repositories. ## Fix Ask whether the user wants Terra, a third-party repository. If yes: ```bash sudo rum config-manager --set-enabled terra # changes system: enables Terra by writing a copy of its repo file to /etc/rum.repos.d; no reboot. Undo: sudo rum config-manager --set-disabled terra (removes the copy) sudo rum install # changes system: installs into the overlay. Undo: sudo rum remove ``` The welcome app's Third-Party Repositories page (Terra switch) does the same. If not, look for the app as a Flatpak instead. On staging, RPM Fusion is disabled by default too; an app that needs it fails the same way until RPM Fusion is enabled (same page, or `sudo rum config-manager --set-enabled 'rpmfusion-*'`). ## Escalate Not a bug in the user's setup. Listing apps from a disabled repo is a Software Center issue; report it against rakuos-software if it confuses users. --- # TPM not found or TPM unlock stopped after an update Images from 2026-10-15 on boot with `intel_iommu=on iommu.passthrough=0 iommu.strict=1` (rakuos-settings `65ffdaf`, for Easy Anti-Cheat Linux v2). On some older Intel machines the IOMMU breaks a device. Reported 2026-10-19: a ThinkPad X250 booting in legacy (BIOS) mode no longer found its TPM after the update, so its LUKS TPM2 auto-unlock stopped working. The IOMMU is the suspected cause, not yet confirmed by the one-boot test below. ## Symptoms - The disk asks for the LUKS passphrase at every boot although it used to unlock with the TPM. - `rakuos eac-check` says "No TPM found.", or `sudo rakuos reenroll-tpm2` says "Error: no TPM2 device found." - Other devices on older Intel hardware stopped working after the same update (less common). ## Confirm ```bash ls /sys/class/tpm/ # read-only: empty when no TPM is detected gnu_cat /sys/class/tpm/tpm0/tpm_version_major # read-only: 2 for TPM 2.0, 1 for TPM 1.2 journalctl -k -b | grep -i -E 'tpm|tis|MSFT0101|DMAR' # read-only: TPM driver probe errors, IOMMU (DMAR) faults gnu_cat /proc/cmdline # read-only: intel_iommu=on and any user override sudo systemd-cryptenroll /dev/ # read-only: lists the key slots; a tpm2 slot means TPM unlock was set up sudo bootc status # read-only: image date ``` A TPM that reports version 1 is in TPM 1.2 mode; TPM2 unlock can't work until the firmware's security chip setting is switched to 2.0. That is not this problem. ## Fix 1. **Test for one boot (changes nothing on disk).** At the GRUB menu press `e` on the RakuOS entry, delete `intel_iommu=on iommu.passthrough=0 iommu.strict=1` from the `linux` line, and boot with Ctrl+X. If `ls /sys/class/tpm/` now shows `tpm0` and the disk unlocks, the IOMMU is the cause. 2. **Make it permanent for this machine.** In **RakuOS System > System > Kernel Parameters…** add `intel_iommu=off`, then reboot (changes system: adds a `rakuos-user` kernel argument; it comes after the image's arguments and overrides `intel_iommu=on`; survives image updates; undo by removing it there). Effect: the IOMMU is off, `rakuos eac-check` fails the IOMMU item, and EAC v2 games won't start; nothing else changes. 3. **If the TPM is back but the disk still asks for the passphrase:** `sudo rakuos reenroll-tpm2` (changes system: replaces the tpm2 key slot of every LUKS partition the passphrase unlocks, bound to PCR 7; asks for the passphrase; the passphrase slot stays; no reboot needed). Normally not needed: kernel arguments don't change PCR 7. 4. **If step 1 didn't bring the TPM back,** boot the previous image from the GRUB menu (the `(ostree:1)` entry) and compare `ls /sys/class/tpm/` and `journalctl -k -b | grep -i tpm` there. If the TPM works on the previous image, the cause is in the newer image (kernel or other arguments); report it. Do not suggest `iommu=pt`, `iommu.passthrough=1` or removing the image's arguments for anything other than hardware the IOMMU breaks, and never as an anti-cheat or driver fix. ## Escalate Report against [rakuos-settings](https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-settings) with the machine model, firmware boot mode (UEFI or legacy), the Confirm output, and whether step 1 fixed it. --- # Update was staged, but after reboot the old image is still running An image update or switch (Software Center, `rum system-upgrade`, `bootc upgrade`, `bootc switch`, RakuOS System) only stages the new image. It becomes a boot entry at shutdown, when `ostree-finalize-staged.service` writes the deployment and the bootloader entries. If that step fails, the machine reboots into the same image and the update is lost. RakuOS has no rpm-ostree, so `rpm-ostree status` and rpm-ostree's logs show nothing here; the ostree units below are where the error is. As of 2026-10-16 (ostree `2026.4-100.rakuos`). ## Symptoms - The update said "reboot to apply", but after the reboot `sudo bootc status` shows the same `booted` image (same `imageDigest`) and `staged: null`. - RakuOS System's Deployments page or the Software Center offers the same update again. ## Confirm ```bash sudo bootc status # read-only: booted imageDigest unchanged, staged: null journalctl -b -1 -u ostree-finalize-staged.service --no-pager | tail -n 40 # read-only: the shutdown that should have written the new deployment journalctl -b -u ostree-boot-complete.service --no-pager # read-only: this boot's report of a finalize failure ``` `ostree-finalize-staged` runs while the previous boot shuts down, so its log is in that boot (`-b -1`, the previous boot; `-b 1` would be the oldest boot in the journal). A successful run ends with: ``` ostree[…]: Bootloader updated; bootconfig swap: yes; bootversion: boot.1.1, deployment count change: 1 ostree[…]: Finished writing deployment systemd[1]: ostree-finalize-staged.service: Deactivated successfully. ``` An `error:` line, a timeout, or no run at all means the update was not written. `ostree-boot-complete.service` only runs when the last finalize left `/boot/ostree/finalize-failure.stamp`; it then fails and prints that error, so the cause shows up on the next boot. "skipped, no trigger condition checks were met" is normal: the last finalize did not fail. To watch either unit live while reproducing (for example in a second terminal before rebooting), add `-f`: `journalctl -f -u ostree-finalize-staged.service`. ## Cause Whatever the error line says. Common ones are no space left on `/boot` or the EFI partition, a forced power-off or a shutdown that timed out before finalize finished, and an image pull that never completed (then nothing was staged and finalize has nothing to do). ## Fix 1. No space on `/boot`: `df -h /boot /boot/efi` (read-only; `/boot/efi` may not be mounted on bootc systems). Old deployments are pruned when a new one is written; report it if `/boot` is full with only two deployments. 2. Stage the update again, then reboot normally (not a forced power-off): ```bash sudo rum system-upgrade # changes system: stages the newest image again (plus overlay and Flatpak updates). Reboot to use it. Undo after reboot: sudo bootc rollback ``` 3. Check the result with `sudo bootc status` after the reboot. ## Do not - Do not use rpm-ostree commands or `rpm-ostree cleanup`: rpm-ostree is not installed, and Silverblue advice about it does not apply. - Do not delete files under `/boot/ostree`, `/boot/loader` or `/ostree` by hand. ## Escalate Report against rakuos-base (or the edition's image project) with `sudo bootc status`, the `ostree-finalize-staged` lines from `-b -1` and the `ostree-boot-complete` output. If the machine doesn't boot at all after an update, see [System won't boot after an update](https://rakuos.org/ai/troubleshooting/boot-stuck-after-update) instead. --- # Automatic image updates are on, but nothing updates The Software Center setting "Automatically apply bootc image updates (rakuos-updater.timer)" turns on a weekly timer that only checks for a new image. It does not download or apply it. No other automatic update runs by default. As of 2026-10-14 (rakuos-core `e08616c`, rakuos-software `7096eb2`). Found in code; no tracker issue yet. ## Symptoms The setting is enabled, but `sudo bootc status` keeps showing the same image and `staged: null` week after week. ## Confirm ```bash systemctl is-enabled rakuos-updater.timer # read-only: "enabled" if the setting is on systemctl list-timers rakuos-updater.timer # read-only: next run (Thursdays 03:00) journalctl -u rakuos-updater.service -n 20 # read-only: output of the last check ``` ## Cause `rakuos-updater.service` runs `/usr/libexec/rakuos/rakuos-updater` with no argument, which defaults to `check`: it compares the booted image's digest with Quay and prints the result. ## Fix Update by hand: the Software Center's Updates page, or ```bash sudo rum system-upgrade # changes system: overlay packages, Flatpaks, then stages the new image. Reboot to use it. Undo after reboot: sudo bootc rollback ``` ## Escalate The setting's label promises more than the timer does: report it against rakuos-software (label) or rakuos-core (timer behavior). --- # MediaTek MT7921 Wi-Fi drops and the system hangs on reboot On laptops with the MediaTek MT7921 (Filogic 330) Wi-Fi chip, Wi-Fi can stay "connected" without internet, toggling it does nothing, and reboot hangs until the power button is held. The reporter traced it to a long-standing upstream Linux driver bug (`mt7921e`). Status: open, https://rakuos.org/bugs/b/wifi-hang-requiring-hard-reset-occurred-2x-19e9f320 (rakuos-base). As of 2026-10-14. ## Confirm ```bash lspci -nn | grep -i 14c3:7961 # read-only: the MT7921 chip journalctl -b -1 --no-pager | grep -E "mt7921e.*(driver own failed|chip reset failed|Timeout for driver own)" # read-only: the boot before the hang uname -r # read-only ``` ## Cause Upstream `mt7921e` driver or firmware hang ("driver own failed", "chip reset failed"). The report noted it happened with the ASPM workaround already in place. ## Fix No RakuOS fix. Update to the newest image and kernel (Software Center or `sudo rum system-upgrade`; changes system; reboot required; undo `sudo bootc rollback`). A USB Wi-Fi adapter or Ethernet avoids the chip. ## Escalate Add `journalctl` lines and kernel version to the issue above. The underlying bug is upstream (Linux `mt7921e`). --- # Known issues Open RakuOS bugs that users run into, each with its workaround and tracker link. Check here before troubleshooting; if the problem is listed, give the workaround and the link instead of improvising, and suggest adding details to the existing report rather than filing a new one. Last checked against https://rakuos.org/bugs on 2026-10-14; entries marked "found in code" were checked against the source on 2026-10-15. Status words are the tracker's. Playbook links give more detail where needed. ## Packages and the overlay ### Package shows as installed but its files are missing after an update Open, rakuos-base (fix planned in rakuos-core): https://rakuos.org/bugs/b/overlay-whiteouts-hide-base-image-files-after-layered-packages-moved-into-the-base-image-xrdb-fuse-libs-4d54a1a8. Seen with `xrdb` and `fuse-libs` after they moved into the image (`staging.20261003`); `rum reinstall` refuses with "'' is provided by the base image … skipping". ```bash rpm -V # read-only: "missing" lines confirm it sudo rum restore-base-files --dry-run # read-only in effect: lists the hidden files sudo rum restore-base-files # changes system: copies them back from the booted image; no reboot ``` If the dry run lists nothing while files are still missing: back up the package list (`cp /var/lib/rakuos/packages.list ~/packages.list.bak`), then `sudo rakuos reset-overlay --soft` (changes system: reinstalls all overlay packages at the next boot; network and reboot needed). Do not delete files in `/var/lib/rakuos/overlay/upper` by hand. [Playbook](https://rakuos.org/ai/troubleshooting/files-missing-after-update). ### Removing Brave, Chromium or another /opt app leaves a broken link Open, rakuos-rum: https://rakuos.org/bugs/b/when-removing-a-package-that-puts-files-in-usr-lib-opt-brave-chromium-rum-does-not-properly-remove-the-symlink-located-in-opt-965525d1 (duplicate: …-2c2451d4). - Reinstalling works: current rum clears the stale `/opt/` first. - To keep the app removed, check that the link is broken (`test -e /opt/ || echo broken`, read-only), then `sudo rm /opt/` (changes system: deletes the link only; undo `sudo ln -s /usr/lib/opt/ /opt/`). Never use `rm -r` here. ### "signature verification failed" when installing or reinstalling In progress, rakuos-rum: https://rakuos.org/bugs/b/failed-signature-verification-for-some-rpm-packages-after-trying-to-reinstall-some-apps-that-doesn-t-appear-on-the-overlay-92b56449. 1. Update: `sudo rum system-upgrade`, reboot (undo `sudo bootc rollback`). 2. `sudo rum clean packages`, then retry the install. 3. `does not verify: no signature` from a third-party repo: that repo publishes unsigned packages; use the app's Flatpak or a Distrobox container. Do not turn off signature checking. rpm-ostree, suggested in the thread, is not installed. ### rum says "standalone mode"; updates fail with no free space on / Open, rakuos-rum (August 2026): https://rakuos.org/bugs/b/rakuos-updates-cannot-be-upgraded-39b15302. `rum paths` (read-only) should say `mode: split`. If it says standalone: reboot once (the initrd re-creates `/var/lib/rakuos/current-deploy` and mounts the overlay), then check again. If it persists, stop running package commands and report it with `rum paths`, `findmnt /usr` and `journalctl -b -u rakuos-overlay-mount -u rakuos-overlay-sync`. Do not set `diskspacecheck=0`. [Playbook](https://rakuos.org/ai/troubleshooting/rum-standalone-mode). ## Software Center ### "Update All" turns into "Retry" and nothing updates In progress: https://rakuos.org/bugs/b/some-packages-doesn-t-update-on-rakuos-software-niri-45f8117f. Update from a terminal instead: `sudo rum system-upgrade` (changes system: overlay packages, Flatpaks, then stages the new image; reboot to use it; undo `sudo bootc rollback`). Flatpaks alone: `flatpak update`. ### The Updates page keeps reloading during an image update In progress, fix announced for the next stable update: https://rakuos.org/bugs/b/why-is-rakuos-software-reloading-during-update-a6b0f08c. Restart the Software Center and run the update again, or use `sudo rum system-upgrade`. ### No progress or reboot message when the only update is a new image Open: https://rakuos.org/bugs/b/no-progress-bar-or-indication-for-reboot-when-using-full-update-0a8b6f89. Run `sudo bootc status` (read-only): if `staged:` is not `null`, the update is done; reboot. ### "Check for updates: Manual only" goes back to "Daily" after a reboot In progress (Qt frontend, KDE): https://rakuos.org/bugs/b/update-schedule-setting-resets-on-reboot-8e22fd2d. Set it again after each reboot until fixed. ### "Automatically apply bootc image updates" never applies anything Found in code (rakuos-core `e08616c`), not on the tracker. The setting enables `rakuos-updater.timer`, which only checks for a new image on Thursdays. Update by hand: Software Center Updates page or `sudo rum system-upgrade`, then reboot. ### An app is listed but fails with "nothing provides ''" Found in code (rakuos-software `7096eb2`), not on the tracker. The catalog includes Terra's apps, but Terra is disabled by default. If the user wants Terra: `sudo rum config-manager --set-enabled terra` (changes system; undo `--set-disabled terra`; no reboot), then install again. Otherwise look for the app as a Flatpak. ### `rakuos setup-nvidia` installs a driver that won't load Found in code (rakuos-core `e08616c`), not on the tracker. `setup-nvidia` and `setup-nvidia-legacy` (still in `rakuos --help`) install `dkms-nvidia` / `dkms-nvidia-580xx` into the overlay. The kernel now loads only RakuOS-signed modules (`module.sig_enforce=1`, `lockdown=integrity`), so the DKMS-built module is refused. Both scripts also replace the user's kernel arguments (source `rakuos-user`) with the nouveau blacklist. Instead: remove the DKMS packages (`rum list | grep -i nvidia`, read-only; then `sudo rum remove `), switch to the `-nvidia` image, or `-nvidia-legacy` for Maxwell/Pascal/Volta, and recheck RakuOS System > System > Kernel Parameters…. [Playbook](https://rakuos.org/ai/troubleshooting/kernel-module-wont-load). ## RakuOS System app ### Switching Stable ↔ Staging says "Your overlay stays as it is", then every app is reinstalled Found in code (rakuos-system `fc07607`), not on the tracker. Staging images are Fedora 45, stable images Fedora 44, but the app only treats Rawhide as a Fedora release change. The first boot after the switch soft-resets the overlay and reinstalls `packages.list` from the network (no pre-download). Keep the network connected for that boot; nothing else is needed. Undo: `sudo bootc rollback` (another reinstall). ### Anti-Cheat check: a kept vendor MOK still shows "Not well-known" Found in code (rakuos-core `e08616c`). `rakuos enroll-secureboot-key` keeps keys from vendors such as Oracle, Proxmox, the BSDs or Red Hat, but `rakuos eac-check` accepts only Epic's list (Canonical, "Fedora Secure Boot CA", Universal Blue, Debian, openSUSE, SUSE, Rocky, Microsoft UEFI CA, AlmaLinux), so it keeps failing the MOK item and keeps suggesting `enroll-secureboot-key`. Do not delete vendor keys by hand; report it against rakuos-core with the `sudo rakuos eac-check` output. [Playbook](https://rakuos.org/ai/troubleshooting/anti-cheat-not-ready). ## Editions, installer and hardware ### KDE: going to standby asks for a password Open, rakuos-kde: https://rakuos.org/bugs/b/putting-the-system-into-standby-mode-requires-the-root-password-0b12103b. The reporter says a reboot fixed it. Reboot; if it returns, add the output of `id` and `systemd-inhibit --list` (both read-only) to the report. ### KDE: no app for setting up printers Open, rakuos-kde: https://rakuos.org/bugs/b/no-gui-for-printer-management-75736374. `system-config-printer` is in KDE images from 2026-10-09 (stable) and 2026-10-07 (staging only): update and reboot. On an older image: `sudo rum install system-config-printer` (changes system; undo `sudo rum remove system-config-printer`; no reboot). CUPS itself is in every image. ### KDE: file search finds nothing ("Unable to open Baloo index") Open, rakuos-kde: https://rakuos.org/bugs/b/file-search-in-kde-isn-t-working-d55d7792. No verified workaround. Add `balooctl6 status` output and the image date (`sudo bootc status`) to the report. ### Xbox controller, racing wheel or sensor stopped working after an update By design, found in code (no tracker entry): images built from 2026-10-23 on ship only the `wl` and `v4l2loopback` modules. `xone`, `xpadneo`, `xpad-noone`, the racing wheel drivers (`hid-fanatecff`, `hid-tmff2`, `t150-driver`, `new-lg4ff`, `logitech-trueforce`), `ayaneo-leds`, `sc0710`, `nct6687d`, `ryzen_smu` and `zenergy` came with earlier images and are now opt-in, so updating removes them. ```bash rum list --base | grep rakuos-kmod # read-only: what the image ships (wl, v4l2loopback, NVIDIA) rum list | grep rakuos-kmod # read-only: what the user installed ``` Fix: RakuOS System › Drivers › Install (the page names the repo each driver needs; most need Terra, turned on in the Welcome app's Third-Party Repositories page), then reboot. Terminal: `sudo rum config-manager --set-enabled terra` and `sudo rum install rakuos-kmod-` with the system's suffix (changes system; undo `sudo rum remove`; reboot). Never `akmod-*`/`dkms-*`. See [Kernel modules and Secure Boot](https://rakuos.org/ai/components/kernel-modules-secure-boot). ### Older Intel laptop: TPM not found, TPM disk unlock stopped (IOMMU) Reported to the maintainer 2026-10-19 (no tracker issue yet): a ThinkPad X250 booting in legacy mode lost its TPM after the images started booting with `intel_iommu=on iommu.passthrough=0 iommu.strict=1` (2026-10-15), so LUKS TPM2 unlock stopped. Suspected cause, not yet confirmed. Workaround: a one-boot test without those arguments, then `intel_iommu=off` in RakuOS System's Kernel Parameters (EAC v2 games won't start with it). Playbook: [TPM not found or TPM unlock stopped](https://rakuos.org/ai/troubleshooting/tpm-missing-after-iommu). ### Freezes or kernel panics Open: https://rakuos.org/bugs/b/kernel-panics-aa284459 (reported on COSMIC v2 with NVIDIA graphics, during the P03 kernel period). Update and reboot (`sudo rum system-upgrade`); if freezes began with an update, `sudo bootc rollback`. Only when `lspci` shows an NVIDIA GPU and the image name has no `-nvidia`, consider the matching `-nvidia` image; see the [playbook](https://rakuos.org/ai/troubleshooting/system-freezes) for the checks. - The -nvidia switch is based on one user report, not a confirmed fix. - Keep the same edition, x86-64 level and channel when switching. Undo with sudo bootc rollback. - The NVIDIA driver comes from the -nvidia image (-nvidia-legacy for Maxwell/Pascal/Volta). Do not use RPM Fusion akmod-nvidia, rakuos setup-nvidia or the NVIDIA .run installer. ### System won't boot after an update (niri v3 image of 2026-09-02) Open: https://rakuos.org/bugs/b/20260902-niri-stable-v3-standard-image-get-stuck-during-boot-5f544825; the 2026-09-04 image works. In the GRUB menu (shown 5 seconds) pick the `(ostree:1)` entry to boot the previous image, then `sudo bootc rollback` (changes system; reboot; undo: roll back again) and update later. ### NVIDIA images lack XWayland driver libraries Open, nvidia-drivers: https://rakuos.org/bugs/b/packages-for-xwayland-1ec13121. `xorg-x11-drv-nvidia-libs` and `xorg-x11-drv-nvidia-cuda` are missing; some XWayland apps and games need them. Maintainer will add them. No verified workaround. ### MediaTek MT7921 Wi-Fi hangs; reboot freezes Open, rakuos-base (upstream `mt7921e` driver bug): https://rakuos.org/bugs/b/wifi-hang-requiring-hard-reset-occurred-2x-19e9f320. Confirm with `journalctl -b -1 | grep -E "driver own failed|chip reset failed"` (read-only). Update to the newest image; use a USB Wi-Fi adapter or Ethernet meanwhile. ### Encrypted install fails in the text-mode installer Found in code (rakuos-installer `f93ef72`), not on the tracker: the text installer's encryption choices are rejected (`encryption.type "luks" is not valid`). Use a graphical installer (KDE, GNOME, COSMIC or niri ISO) for an encrypted install. ## Recently fixed | Issue | Marked fixed or closed (tracker date) | Tracker | |---|---|---| | "Nvidia Legacy" offered on Stable with no image to switch to | 2026-10-17: stable now builds `-nvidia-legacy` images (image repos `main`), found in code, no tracker entry | image CI | | Staging on kernel 7.2.10: Xbox controllers (`xone`, `xpadneo`, `xpad-noone`), `v4l2loopback` and MT7927 Wi-Fi modules missing | 2026-10-15, found in CI (no tracker entry): signed-kmods build 7 covers 7.2.10; update to the newest staging image and reboot | signed-kmods `727282b` | | Software Center does nothing when opened (niri) | 2026-09-27; on older images quit it from the tray and update | [82a07770](https://rakuos.org/bugs/b/rakuos-software-center-rakuos-software-gtk-fails-to-open-on-niri-image-82a07770) | | Software Center lost its System tab | 2026-09-30: moved to the RakuOS System Management app | [3df8d05a](https://rakuos.org/bugs/b/260930-rakuos-niri-image-lost-the-system-tab-in-rakuos-software-3df8d05a) | | Option to turn off the Software Center tray | 2026-09-27 (Settings, Tray Icon) | [e4ffd2b6](https://rakuos.org/bugs/b/feature-request-add-a-toggle-in-rakuos-software-to-disable-tray-app-and-background-operation-e4ffd2b6) | | Portal "Save As" dialog dropped the file name | 2026-09-27 (rakuos-settings) | [9ff3c7b7](https://rakuos.org/bugs/b/portal-save-as-dialog-drops-download-filename-saves-only-the-extension-9ff3c7b7) | --- # Reporting a bug Help the user file a bug only when RakuOS code is wrong, not when the problem is the user's setup or a question about how something works. RakuOS bugs are filed at https://rakuos.org/bugs under the project that owns the broken part; filing needs an account on rakuos.org. As of 2026-10-14. ## Bug, support question, or upstream? | It is… | When | Send the user to | |---|---|---| | A **known issue** | It matches an entry in [known issues](https://rakuos.org/ai/known-issues) | that tracker issue: add details there instead of filing a new one | | A **support question** | RakuOS behaves as documented, but the user expected something else, or their own change caused it (an edited config file, a repo they added, a hand-installed file in `/usr`) | the documented fix; otherwise the forum (rakuos.org/forum), Matrix (matrix.rakuos.org) or Discord | | An **upstream bug** | The fault is in software RakuOS only packages unchanged (a Flatpak app, a Fedora package, a vendor's `.rpm`, a Linux driver) and happens the same on Fedora | that project's tracker; mention it on the RakuOS tracker only if RakuOS packaging is involved | | A **RakuOS bug** | A RakuOS tool or image does something wrong: a crash, a wrong result, an error message from rum, rakuos-core, the Software Center, the RakuOS System app, the installer, or an image missing something it should have | file it, as below | Stop troubleshooting once it is clearly a RakuOS bug. More fixes change the system away from the state the developers need to see. ## Pick the project Use the table "Which project owns the problem" in the [repo map](https://rakuos.org/ai/repo-map#which-project-owns-the-problem). Common cases: - `rum` or `dnf` errors: rakuos-rum. - Files missing under `/usr`, overlay resets, "RakuOS overlay" boot messages: rakuos-core. - The Software Center: rakuos-software. The RakuOS System Management app: rakuos-system. - Installing from the ISO: rakuos-installer; a live ISO that won't boot: the edition's ISO project. - Something one desktop edition does or lacks: that edition's image project (rakuos-kde, rakuos-gnome, rakuos-cosmic, rakuos-niri, rakuos-hyprland, rakuos-gamescope). - NVIDIA driver problems: nvidia-drivers (https://rakuos.org/bugs/p/rakuos-packages-drivers-nvidia-drivers). - Not sure: the edition's image project. Project pages are `https://rakuos.org/bugs/p/rakuos-` plus the repo path with `/` replaced by `-`, for example `https://rakuos.org/bugs/p/rakuos-packages-rakuos-rakuos-rum`. Check the project's open issues for a duplicate first. ## Collect the information 1. Run the read-only [diagnostics block](https://rakuos.org/ai/troubleshooting/diagnostics) and keep the output. The template's own block starts with `cat /etc/os-release`; on RakuOS `cat` is bat, which adds line numbers and may open a pager (press `q`), so use `gnu_cat /etc/os-release` for text to paste. If the problem happened before the last reboot, use `-b -1` in the `journalctl` lines. 2. For a package problem, add `rum origin ` and `rpm -V `. 3. Write down every command already run, including commands an AI assistant suggested, and what each did. 4. Note the exact error text, copied, not paraphrased. ## Redacting logs Before the user pastes anything, remove or replace: - user names (also in paths such as `/var/home/`), - host names, - IP and MAC addresses, - e-mail addresses, - serial numbers and machine IDs. Keep image names, versions, digests, kernel versions, package names and error messages: they are what the developers need. ## Fill in the template The report format is in `bug-report-template.md`. Fill in each section with the user: - **Title**: the symptom and when it happens, e.g. "Overlay packages lose their files after an image update". - **Summary**: one or two sentences: what is broken and since when. - **Environment**: edition and channel (from `VARIANT_ID`), booted and rollback image with version (from `sudo bootc status`), kernel (`uname -r`), hardware, recent changes. - **Steps to reproduce**, **What happened** (exact errors in code blocks), **What I expected**. - **Logs**: the redacted diagnostics output. - **What I already tried**: every command run and its effect. - **Workaround**, if any; **Suggested fix**, only with a link to the RakuOS source file and line. - **Checklist**: searched for duplicates; removed personal information; and, if an AI helped, that the user checked every detail. Have the user confirm every detail before filing. The user files the report themselves while logged in to rakuos.org.