lux-engine, repositories and signing

No pacman command

LuxOS is based on Arch Linux but has no pacman command and no pacman configuration (/etc/pacman.conf, /etc/pacman.d). The package manager is lux, configured in /etc/lux/lux.conf (own format, see package-management.md). Its core is the package lux-engine: libalpm and the tools of Arch Linux's pacman, built from exactly the same sources, checksums and patches as Arch's pacman package (currently Arch tag 7.1.0.r9.g54d9411-3, LuxOS pkgver=7.1.0.r9.g54d9411, pkgrel=3.2). Honest note: the engine code is Arch's libalpm/pacman; LuxOS changes only names, paths and packaging.

Differences from Arch's pacman package:

  • The internal tools are renamed and live outside PATH in /usr/lib/lux/alpm/bin: lux-engine (the transaction tool), lux-engine-key (keyring), lux-engine-conf (prints the effective configuration) and lux-engine-db-upgrade. They are small launchers that first make sure /run/lux/engine.conf is up to date, then run the real program from /usr/lib/lux/alpm/libexec. No man pages or shell completion for them.
  • Default paths: config /run/lux/engine.conf (generated by lux-config from /etc/lux/lux.conf — never edit it; only the C tools read it, lux itself reads lux.conf directly), database /var/lib/lux/, cache /var/cache/lux/pkg/, log /var/log/lux.log, keyring /etc/lux/keyring/, admin hooks /etc/lux/hooks/. Package hooks stay in /usr/share/libalpm/hooks, keyring packages in /usr/share/pacman/keyrings (Arch's paths).
  • Mirrors: /etc/lux/mirrorlist (one address per line) is part of lux-engine; pacman-mirrorlist is not needed. pacman-contrib and expac are not needed either (lux has its own cache cleaning, update check and config merge).
  • makepkg, vercmp, repo-add, repo-remove and /etc/makepkg.conf stay as in Arch.
  • provides=(pacman libalpm.so luxos-pacman), conflicts/replaces pacman and luxos-pacman, so Arch packages depending on pacman keep working.

Who gets the internal tools in PATH:

Caller How
lux, lux_alpm.py and hooks/scriptlets of their transactions prepend /usr/lib/lux/alpm/bin to PATH; via sudo/pkexec a fixed PATH=/usr/lib/lux/alpm/bin:/usr/local/sbin:/usr/local/bin:/usr/bin
makepkg /etc/makepkg.conf.d/lux-engine.conf sets PATH, PACMAN=/usr/lib/lux/alpm/bin/lux-engine and PACMAN_AUTH (sudo with the same PATH)
archlinux-keyring-wkd-sync service drop-in archlinux-keyring-wkd-sync.service.d/lux-engine.conf (keyring /etc/lux/keyring)
LuxOS Store, LuxOS Care, Drivers, printing, installer, sandbox set the path themselves

A global systemd DefaultEnvironment is intentionally not used (user sessions would inherit it). lux-engine-config.service generates /run/lux/engine.conf at boot.

Signing keys from keyring packages (archlinux-keyring, luxos-keyring) are loaded by the hook /usr/share/libalpm/hooks/lux-engine-keyrings.hook (runs lux-engine-key --populate <keyring> after any transaction that installs or upgrades usr/share/pacman/keyrings/*.gpg), because the keyrings' own install scripts call /usr/bin/pacman-key, which does not exist in LuxOS.

For debugging only, an assistant may call /usr/lib/lux/alpm/bin/lux-engine -Q ... for read-only queries, but all changes should go through lux.

The pacman hint

Typing pacman (or lux -Syu, lux -S x …) shows the matching lux command instead of "command not found". The helper is /usr/lib/lux/pacman-hint, called from the shell's command-not-found handler (bashrc/zshrc/lsh) and by lux for pacman-style arguments. It never installs or runs anything and exits with code 1.

✦ LuxOS uses lux to manage software.
  pacman -Syu  →  lux update
  All lux commands: lux --help
pacman lux
pacman -Syu, -Su lux update
pacman -Syu foo lux update + lux install foo
pacman -Sy lux update
pacman -S foo lux install foo
pacman -U file.pkg.tar.zst lux install file.pkg.tar.zst
pacman -Ss term lux search term
pacman -Si foo lux info foo
pacman -Sc, -Scc lux clean
pacman -R… foo lux remove foo
pacman -Q lux list
pacman -Q foo, -Qi foo lux info foo
pacman -Qs term lux list term
pacman -Qu lux list --upgradable
pacman -Qdt lux list --orphans + lux autoremove
pacman -Qm lux list --aur
pacman -Qe lux list --explicit
pacman -Ql foo lux files foo
pacman -Qo file lux owns file
pacman -Qk lux doctor
pacman -V lux --version

Keeping up with Arch

pyalpm from Arch is built against Arch's libalpm.so, so lux-engine must follow Arch's pacman version. lux doctor warns The package manager core X is older than the one in Arch Linux (Y); a LuxOS update will follow. If pyalpm is unusable in the meantime, lux falls back to the internal tool lux-engine automatically. Check the backend: /usr/lib/lux/lux_alpm.py --verbose available. Force the fallback: LUX_BACKEND=engine lux ….

Migration from LuxOS 0.9

LuxOS 0.9.0 shipped luxos-pacman; since 0.9.1 the engine is lux-engine, which replaces it. lux update swaps it automatically. Since 0.9.2, lux and LuxOS Care depend on the virtual pacman so older installs update without "unresolvable package conflicts"; the new lux then replaces the engine.

Updating from the pacman layout (LuxOS 0.9.5 and older): the hook 00-lux-engine-migrate.hook (runs first, in the same transaction that installs the new lux-engine) moves /var/lib/pacman → /var/lib/lux, /var/cache/pacman/pkg → /var/cache/lux/pkg, /etc/pacman.d/gnupg → /etc/lux/keyring, /etc/pacman.d/hooks → /etc/lux/hooks, /var/log/pacman.log → /var/log/lux.log (renames on the same filesystem; each step can be repeated after a power loss). Old locations stay as links until the next restart so the still running old update can finish. Custom repositories and options of /etc/pacman.conf ([multilib], IgnorePkg → hold, …) are converted into /etc/lux/lux.conf, the ranked /etc/pacman.d/mirrorlist into /etc/lux/mirrorlist, and the lux settings of the old lux.conf (AUR=0 …) are kept. After a restart, lux (as root) removes the links and old files; copies stay in /var/lib/lux/migrated-from-pacman/. Status: /usr/share/libalpm/scripts/lux-engine-migrate status; manually: sudo /usr/lib/lux/lux_alpm.py migrate --now. pacman-mirrorlist and pacman-contrib become unneeded and are offered by lux autoremove.

Repositories

/etc/lux/lux.conf (LuxOS default, TOML):

# LuxOS Package Manager
# Configuration: /etc/lux/lux.conf

[general]
architecture = "auto"
color = true
candy = true
verbose = true
# updates: "stable" (releases) | "staging" (test builds before a release - for testers)
channel = "stable"

[downloads]
parallel = 10
check_space = true
user = "alpm"

[security]
signatures = "required"
local_signatures = "optional"
protect = ["lux-engine", "glibc"]

[packages]
aur = true
review_pkgbuild = true
flatpak = true
cache_keep = 2

# ── LuxOS repositories ────────────────────────

[repo.luxos]
server = "https://luxos.lux-ai.cz/repo/$repo/$arch"

[repo.luxos-apps]
server = "https://luxos.lux-ai.cz/repo/$repo/$arch"

[repo.luxos-drivers]
server = "https://luxos.lux-ai.cz/repo/$repo/$arch"

# ── Arch Linux repositories ───────────────────

[repo.core]
mirrors = "/etc/lux/mirrorlist"

[repo.extra]
mirrors = "/etc/lux/mirrorlist"

# ── Additional configuration ──────────────────

[include]
files = ["/etc/lux/conf.d/*.conf"]
Repository Content
[luxos] the LuxOS system: lux-engine, lux, luxos-desktop, luxos-care, luxos-drivers, luxos-installer, lsh, themes, branding, LuxDrop, … and legacy NVIDIA drivers (nvidia-580xx-*, nvidia-470xx-*, built from AUR, online only)
[luxos-apps] downloadable apps, e.g. lsl (Lux Simple Lang), lsl-ide, lux-code, luxai, luxos-docs
[luxos-drivers] verified printer and scanner drivers of manufacturers, built from checked AUR versions (see drivers.md)
[core], [extra] Arch Linux, via /etc/lux/mirrorlist (lux mirrors refreshes it)
.lux repo https://luxos.lux-ai.cz/repo/lux/ (index.json + signatures), see lux-packages.md

[multilib] is not enabled by default; the installer's Gaming template enables it (Steam needs it), manually sudo /usr/lib/lux/lux-config enable-repo multilib. Own repositories go to /etc/lux/conf.d/NAME.conf ([repo.NAME] + server = "…"). [luxos]/[luxos-apps] are listed before Arch's repos, so LuxOS versions win on name clashes. An overview page of the repos is at https://luxos.lux-ai.cz/repo/.

With channel = "staging" in [general] every server starting with https://luxos.lux-ai.cz/repo/ ([luxos], [luxos-apps], [luxos-drivers], the .lux repo, Store icons) is read from https://luxos.lux-ai.cz/staging/ instead - the test channel before a release. The file keeps the /repo/ addresses; lux, /run/lux/engine.conf (lux-engine, makepkg), lux-config json, LuxOS Care and the Store all apply the channel. Arch and own repositories are never changed. On the server staging is a second link next to current (scripts/publish-repo.sh with LUXOS_REPO_CHANNEL=staging, scripts/promote-staging.sh makes it the release).

The live ISO installs LuxOS packages from a local copy at /opt/luxos-repo (file:// servers); the installed system uses the online servers above.

lux.conf format of LuxOS 0.9

The LuxOS 0.9 format of /etc/lux/lux.conf (key value lines, indented lines under repo NAME, include …) is still read — every file (also in conf.d) is detected on its own; lux config check reports uses the old LuxOS 0.9 format. Keys map 1:1: architecture, color, candy, syslog → [general] (verbose-lists → verbose); parallel-downloads → [downloads] parallel, check-space → check_space, download-user/-timeout/-sandbox → user/timeout/sandbox; signatures, local-signatures, protect → [security]; aur, review-pkgbuild, flatpak, clean-keep → [packages] (cache_keep), and hold, ignore-group, no-upgrade, no-extract too; cache, hooks, database, log, keyring → [paths]; repo X → [repo.X] with the same keys; include X → [include] files = ["X"]. on/off become true/false, repeated lines become one list.

sudo lux config migrate converts /etc/lux/lux.conf and the conf.d files (lux config migrate --dry-run only shows the result). Values stay the same (the result is verified, otherwise the file is left alone), comments stay with the key or repository they were above, the original is kept as lux.conf.old-format. An unchanged default configuration becomes exactly the package's default file. Updating lux-engine to LuxOS 1.0 does this once automatically (hook 00-lux-engine-migrate, marker /var/lib/lux/config-format-toml) and then deletes the lux.conf.luxnew with the new default that the package left next to a changed file — the file was only converted, there is nothing to merge. A file that cannot be converted (e.g. a missing mirror list) stays in the old format and the next update tries again. A personal ~/.config/lux/lux.conf is converted with lux-config migrate ~/.config/lux/lux.conf.

Signing and luxos-keyring

  • Every package and database in [luxos]/[luxos-apps] is signed with the LuxOS key, fingerprint FD185DAB770140E89C37275E7035CFDFDCA6C991 (marked fully trusted in luxos-trusted).
  • The public key is in the package luxos-keyring: /usr/share/pacman/keyrings/luxos.gpg, luxos-trusted, luxos-revoked.
  • signatures required (engine SigLevel = Required DatabaseOptional): package signatures are mandatory; local files (lux install ./x.pkg.tar.zst) follow local-signatures optional.
  • .lux packages and the .lux index are verified with gpgv against the same luxos.gpg.
  • Keyring problems: lux fix (re-init and re-populate the keyring, reinstall keyrings).

New versions of configuration files

You never have to merge configuration files by hand. When a package ships a new default for a file you changed (for example /etc/lux/lux.conf with channel = "staging" set by Software Update), libalpm keeps your file and saves the new one as <file>.luxnew; right after the transaction LuxOS merges the two itself (/usr/lib/lux/lux_configmerge.py, hooks 90-lux-config-merge-pre / -post, also in lux update and LuxOS Care):

  • the base is the file from the old package version, kept in /var/lib/lux/pristine/<path> and always verified against the checksum in the package database (taken from disk or from the old package in the cache);
  • key = value files (TOML, INI, lux.conf): a value present in your file always stays. A key only gets a new default when your value is exactly the old default; keys written by lux-config / Software Update (channel, countme in lux.conf) are always yours. New keys, sections and comments are added; your own keys and comments stay;
  • other text files: a line-based three-way merge, applied only without conflicts;
  • no base (for example a .luxnew left before LuxOS had this): only when the new version just adds keys, comments or lines — your values never change.

On success the file is written atomically, the previous version is kept as <file>.lux-old (one backup), .luxnew is removed and lux says calmly Updated /etc/lux/lux.conf; your settings were kept. If it cannot be combined, nothing changes — the system keeps using your file — and lux says so with the command to review it: sudo lux config-diff <file>. Leftover .luxnew files are retried on every lux update, by LuxOS Care and by lux configs.