LuxOS Care and Software Update
LuxOS Care (package luxos-care) makes LuxOS maintenance-free: automatic updates, a kept
previous kernel with automatic fallback, and self-repair of known problems. The user-facing app
is Software Update (luxos-update, Czech "Aktualizace softwaru").
Modes
The mode is stored in /etc/luxos/care.conf as MODE=carefree or MODE=classic
(missing or invalid = carefree). It is chosen in the installer ("How should LuxOS be maintained?",
CARE_MODE= in unattended installs) and can be changed in Software Update.
| Mode | Behaviour |
|---|---|
| Carefree (recommended) | updates install automatically in the background, known problems are repaired by built-in rules, unknown serious problems can be repaired by an option chosen by LuxAI Flash |
| Classic (for IT professionals) | only checks and notifies ("N updates available", problems found); you decide when to update; no automatic repairs |
Change from the command line:
luxos-care mode # print the current mode
sudo luxos-care mode classic # or carefree
The app switches mode through pkexec /usr/lib/luxos/care/luxos-care-helper set-mode carefree|classic.
When automatic updates run
luxos-care-update.timer: 15 min after boot, then every hour (±10 min). The service decides whether an update is due: at most once per ~20 hours after the last success.- Conditions (skipped otherwise, with the reason saved):
- internet connectivity is full (not
none,portal,limited) — reasonoffline, - the connection is not metered (NetworkManager
Metered; Data Saver marks connections metered) — reasonmetered, - on battery: average charge at least 40 %, or charging/AC — reason
battery. - A manual "Update Now" ignores the metered and battery conditions (only needs internet).
- After a failure it backs off 1 h, 2 h, 4 h … up to 24 h; the user is notified after 3 failures in a row (or immediately for a manual update).
- In Classic mode the update timer only checks for updates (at most once per ~20 h).
- The services do not run in the live ISO (
ConditionPathExists=!/run/archiso).
How an update is done
- If another package manager is running → postponed (
busy). A staledb.lckis removed. lux_alpm.py check-updateslists pending updates (refresh into a temporary database copy, the system database is not touched).archlinux-keyring/luxos-keyringare updated first.- Everything is downloaded (
-Syuw); download is safe to interrupt (shutdown stops it). - Installation from the cache (
-Su) undersystemd-inhibit(blocks shutdown, sleep and lid switch, "Installing updates"); on shutdown the installation is allowed to finish (up to 30 min). - If a file conflict involves the kept previous kernel, it is released and the install retried.
- New versions of edited configuration files are merged automatically (your values stay, the
90-lux-config-merge-*hooks run in every transaction, leftovers are retried here); only files that cannot be combined stay as.luxnewand are recorded. Old cache cleaned, reboot flagged if the kernel changed, then a problem check runs.
Updates go through lux (libalpm) when available, otherwise the internal tool lux-engine.
The log of all transactions is /var/log/lux.log, the lock /var/lib/lux/db.lck. Network errors are
retried within one run (after 20 s and 90 s).
Software Update app
luxos-update (Settings / Launchpad "Software Update"). Shows:
- Status: "LuxOS is up to date", "N updates available", "Updating LuxOS…" with real progress (Downloading… X of Y, Installing X (n of m), "Do not turn off the computer."), "Restart to finish the update", "Updates could not be installed".
- Last update / last check, and why an automatic update is waiting ("waiting for an unmetered connection (Data Saver)", "waiting for the charger or more battery", "waiting for the internet connection").
- Buttons Update Now, Restart, Check for Problems Now.
- "When updates are installed": Carefree / Classic.
- "Available updates" list. A configuration file whose new version could not be merged automatically
is shown calmly as "New version of a configuration file: …" — your current file stays in use; review
it with
sudo lux config-diff <file>. Automatically merged files are not shown at all. - "System health": problems found, the kept previous kernel.
- "Privacy": switch Anonymously report that this computer uses LuxOS (
[general] countmein/etc/lux/lux.conf, changed through pkexecluxos-care-helper set-countme on|off), see countme.md. - "Repair and update history" with Show Full Log… (
/var/lib/luxos-care/history.jsonl).
Update Now starts luxos-care-update-now.service; Check for Problems Now starts
luxos-care-check-now.service. A polkit rule (50-luxos-care.rules) lets active local users in
group wheel start exactly these units (and luxos-care-apply@<id>-<n>.service) without a password.
Command line
luxos-care [status] [--json] status (anyone)
luxos-care history [N] audit log (JSON lines, default 30)
luxos-care mode [carefree|classic]
luxos-care scheduler [lavd|default] [--json]
CPU scheduler: show (anyone) or switch (root), see power-and-performance.md
luxos-care update [--manual] (root) what the update service runs
luxos-care check [--updates] (root) problem check (+ update check)
Useful one-liners: systemctl start luxos-care-update-now.service (needs wheel),
luxos-care status, journalctl -u luxos-care-update.service.
Update channel: stable or staging
Updates come from one of two channels, set by channel in [general] of /etc/lux/lux.conf:
"stable"(default) - released versions, for everyone."staging"- test builds before a release (for example LuxOS 1.0.0 before 1.0.1 goes to everyone). Only for testers: fixes arrive here first and may still break things.
The test ISO has "staging" in the live and the installed system. Show the channel with
lux config check. Switch it in /etc/luxos/system.lsl and apply:
"updates": {"channel": "stable"}
sudo lux system apply (or lux config channel stable). The next
lux update (or Software Update) uses the new channel; LuxOS repositories are read from
https://luxos.lux-ai.cz/staging/ instead of …/repo/, Arch repositories never change. Going
from staging back to stable never downgrades packages: newer test versions stay until the
release catches up.
Files
| Path | Content |
|---|---|
/etc/luxos/care.conf |
MODE=, PROTECT=, VERIFY= (see system-protection.md) |
/etc/luxos/scheduler.conf |
SCHEDULER=lavd\|default, ARGS= (CPU scheduler, package luxos-tweaks; system.lsl kernel.scheduler) |
/var/lib/luxos-care/boot-menu-fast |
one-time switch of GRUB GRUB_TIMEOUT 1 → 0 done (LuxOS 1.0) |
/var/lib/luxos-care/state.json |
last update/check, pending updates, problems, kept kernel |
/var/lib/luxos-care/events.json |
recent events for notifications |
/var/lib/luxos-care/history.jsonl |
audit log of updates, repairs and AI decisions |
/run/luxos-care/progress.json |
progress of the running update |
/var/lib/luxos-care/kernel/ |
kept kernel state (prev, good, kept) |
Previous kernel fallback
- libalpm hook
10-luxos-care-kernel-pre.hook: when the kernel package (KERNEL=in care.conf or/etc/luxos/esp.conf:linux-luxos;linux-zenon older installs until they switch) is replaced, the version that last booted successfully is saved. 95-luxos-care-kernel-post.hook: it is restored as a boot entry "LuxOS (previous kernel)" (systemd-boot entry, or/etc/grub.d/11_luxos_previouswith files in/boot/luxos-prev).- A new kernel gets 3 boot attempts: systemd-boot boot counting (
+3entry) or GRUB variableluxos_triesin grubenv.luxos-care-boot.serviceconfirms a successful start (display manager active, basic targets OK) beforeboot-complete.target. After 3 failed starts the boot loader uses the previous kernel automatically. - Automatic fallback works with GRUB and with a LuxOS-owned systemd-boot; with a shared ESP owned by another system the user picks "LuxOS (previous kernel)" in the boot menu manually.
- If the boot partition is full the entry cannot be prepared ("The boot partition is full.").
System snapshots and rollback
Before every transaction that changes packages (lux, Software Update, Store – all go through
libalpm) the hook /usr/share/libalpm/hooks/05-luxos-snapshot.hook runs luxos-care snapshot-pre
and takes a read-only Btrfs snapshot of the system subvolume (@):
- Snapshots are in the subvolume
@snapshotsat the top level of the Btrfs file system (next to@and@home, not mounted):@snapshots/YYYY-MM-DD_HH-MM-SSplus a descriptionYYYY-MM-DD_HH-MM-SS.json(time, kernel, packages of the transaction)./home(@home),@log,@cacheand/tmp(@tmp) are not part of system snapshots (/homehas its own hourly snapshots, see Lux Guard). - Kept: the last 5 snapshots plus the newest one with the previous kernel (the state before the
last kernel change); with little free space (< 5 % or < 2 GiB) only 2.
SNAPSHOT_KEEP=Nin/etc/luxos/care.confchanges 5,SNAPSHOTS=noturns snapshots off. - A failing snapshot never stops an update (logged as
luxos-care: snapshot … failed). - Not on other file systems than Btrfs, without a system subvolume, in the live ISO or in a chroot.
Kernel of a snapshot. /boot is not part of the system subvolume (the EFI partition, or the
separate /boot partition with GRUB), so after a kernel update a snapshot would not start with the
new kernel (its modules belong to the old one). With every snapshot LuxOS Care therefore keeps the
kernel and initramfs the system starts with now (checked against /usr/lib/modules) as a kernel
set: <kernel folder on the ESP>/luxos-snapshots/<version>-<hash>/{vmlinuz,initramfs.img}
(/boot/luxos-snapshots, with a shared ESP EFI/LuxOS/<id>/luxos-snapshots; GRUB with /boot inside
Btrfs: @snapshots/.kernels). Snapshots with the same kernel and initramfs share one set, unused
sets are removed; space on the partition is guarded (merged and oldest sets go first, see
boot-partition.md). Without space for the kernel the snapshot is kept but has no
boot entry.
Boot menu. Every snapshot with a kernel set gets an entry "LuxOS (before update of
YYYY-MM-DD HH:MM)" (a snapshot taken by lux system apply is "before system change of …",
see system-config.md; systemd-boot loader/entries/snapshot-<entry>-<name>.conf, GRUB
/boot/grub/luxos-snapshots.cfg loaded by /etc/grub.d/12_luxos_snapshots). The menu is hidden
(no waiting): hold Space (systemd-boot) or hold Shift / press Esc repeatedly (GRUB) while
the computer starts. Such an entry starts
the snapshot read-only with a temporary writable layer in memory (systemd.volatile=overlay,
initramfs hook luxos-snapshot added by /etc/mkinitcpio.conf.d/zz-luxos-snapshot.conf) – changes
disappear after a restart, /home is the normal one. In this mode package changes are refused
("LuxOS is running from a snapshot…") and LuxOS Care does not update or repair; after login a
notification offers Keep this version (runs lux rollback).
Rollback (lux rollback, or luxos-care rollback NAME --yes, or LuxOS Recovery):
- the current system subvolume is renamed to a new snapshot "LuxOS (before rollback of …)" – nothing is deleted, the rollback itself can be undone the same way;
- a writable copy of the chosen snapshot becomes
@(boot entries stay as they are); - the snapshot's kernel set is copied over the main entry's kernel and initramfs (also the safe mode initramfs); the boot attempt counter of the main entry is reset;
- automatic updates pause for 3 days (the same update would be installed again); on the first
start
luxos-care-after-rollback.servicerebuilds the initramfs and a notification says "LuxOS was restored".
lux snapshots # list (root)
lux snapshot # take one now
lux rollback # choose a snapshot; from a snapshot boot: keep the running one
sudo luxos-care boot-entries # rewrite the snapshot and recovery boot entries
LuxOS Recovery
The boot menu entry "LuxOS Recovery" (disk check, restore a snapshot, reinstall keeping /home
and accounts) starts from the newest snapshot, so it works even when the last update broke the
system; nothing runs without confirmation. After every system change the next start is watched: if it
fails, the following start shows the boot menu for 10 s by itself. How to open it, what each option
does and what a reinstall keeps or loses: recovery.md.
Switch to the LuxOS kernel
Installs from before LuxOS 0.9.7 run linux-zen. After an update (lux update runs
/usr/lib/lux/after-update.d/50-luxos-kernel, LuxOS Care after its automatic update) LuxOS Care
switches them to linux-luxos (luxos-care kernel-switch, root):
- installs
linux-luxos(andlinux-luxos-headerswhenlinux-zen-headerswas installed for DKMS drivers such as NVIDIA); - checks that the initramfs exists and every DKMS module is built for the new kernel – otherwise it
stops and the system stays on
linux-zenunchanged (statekernel_switch_errorinluxos-care status --json; it tries again after the next update); - points the boot entries (
linux/initrdlines, safe mode entry, shared ESP copy) atlinux-luxosand writesKERNEL=linux-luxosto/etc/luxos/care.conf; - removes
linux-zen; the kernel pre hook keeps it (modules, DKMS modules and the initramfs it booted with) as "LuxOS (previous kernel)", and the new kernel gets 3 boot attempts – if it does not start, the boot loader goes back tolinux-zenby itself.
A restart finishes the switch ("Restart to finish the kernel update").
Self-repair
luxos-care-check.timer runs a check 30 min after boot and every 6 hours (also after each
update and at boot). Detected serious problems:
- package database left locked (lock older than 10 min, nothing running),
- interrupted system update,
- missing kernel/initramfs files in
/boot, - DKMS module (e.g. NVIDIA) not built for the kernel,
- the newest kernel failed and the previous one was used,
- a failed critical service (display manager, NetworkManager, bluetooth, cups, polkit, …),
- disk almost full (
/under 2 GiB and 5 % free), - file system errors (reported only: "back up your data"),
- updates keep failing.
In Carefree mode built-in rules run at most once per day per problem. Only actions from a fixed
catalog are ever executed: remove stale lock, finish interrupted upgrade, refresh signing keys,
rebuild initramfs (mkinitcpio -P), dkms autoinstall, reinstall a package, restart a failed unit,
clean cache (lux_alpm.py clean + journal vacuum to 200 MB), retry the new kernel, use the previous kernel.
For unknown serious problems the session part (in luxos-hub) sends a redacted diagnosis to
LuxAI Flash with the user's LuxAI account; the AI may only pick the number of one of the prepared
options, root re-validates it, max 3 AI actions per day. Without a LuxAI account the user gets a
notification "Sign in to LuxAI to let LuxOS fix unknown problems."
Notifications
Shown by luxos-hub in the user session: "LuxOS was updated", "Restart to finish the kernel
update" (Restart / Details), "Updates are available" (Classic), "Updates could not be installed",
"Update postponed", "LuxOS fixed a problem", "LuxOS found a problem", "System files were changed"
(critical, stays in the history; see system-protection.md). Details opens Software Update.
System protection
/usr is read-only except during package changes, and a weekly check compares system files with
the package database (luxos-care protect, luxos-care verify, PROTECT= and VERIFY= in
care.conf). Everything about it is in system-protection.md.
Disabling
Prefer Classic mode. To stop the timers completely:
sudo systemctl disable --now luxos-care-update.timer luxos-care-check.timer (and
luxos-care-boot.service disables boot confirmation). The package re-enables the units on upgrade.
Processor timer (TSC) false alarm
Some laptops (for example with AMD Ryzen 5000) mark the processor timer (TSC) as unstable at
boot ("Marking clocksource tsc unstable due to frequency skew") even though the CPU has an
invariant TSC (constant_tsc + nonstop_tsc). The kernel then reads time from the slow HPET,
which makes everything that asks for the time often a little slower. After a successful boot
luxos-care boot-check detects this case and adds tsc=nowatchdog once to the LuxOS boot
entries (systemd-boot options lines of luxos*.conf, or GRUB_CMDLINE_LINUX_DEFAULT +
grub-mkconfig). It applies from the next boot; the change is logged in the Care history
(tsc_fix). Nothing changes if the parameter tsc= is already set or the alarm did not happen.
To undo it, remove tsc=nowatchdog from the entry and add tsc=unstable there instead (Care then leaves it alone).
Hidden boot menu without waiting (LuxOS 1.0)
New installs boot without a menu delay (systemd-boot timeout 0, GRUB GRUB_TIMEOUT=0 +
GRUB_TIMEOUT_STYLE=hidden). Older BIOS (GRUB) installs had a hidden 1 s timeout: after the first
successful boot with LuxOS 1.0, luxos-care boot-check sets GRUB_TIMEOUT=0 and runs
grub-mkconfig once – only if /etc/default/grub still has the LuxOS defaults
(GRUB_DISTRIBUTOR="LuxOS", GRUB_TIMEOUT=1, GRUB_TIMEOUT_STYLE=hidden); a value you changed is
kept. If grub-mkconfig fails the old file is put back and it is tried again at the next boot. Done is
recorded in /var/lib/luxos-care/boot-menu-fast (history: boot_menu). systemd-boot installs need no
change; the 3 s menu with other systems on the EFI partition stays. The previous kernel, snapshots and
LuxOS Recovery stay in the menu: hold Space (systemd-boot) or hold Shift / press Esc
(GRUB) while the computer starts.