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
PATHin/usr/lib/lux/alpm/bin:lux-engine(the transaction tool),lux-engine-key(keyring),lux-engine-conf(prints the effective configuration) andlux-engine-db-upgrade. They are small launchers that first make sure/run/lux/engine.confis 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 bylux-configfrom/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 oflux-engine;pacman-mirrorlistis not needed.pacman-contribandexpacare not needed either (lux has its own cache cleaning, update check and config merge). makepkg,vercmp,repo-add,repo-removeand/etc/makepkg.confstay as in Arch.provides=(pacman libalpm.so luxos-pacman),conflicts/replacespacmanandluxos-pacman, so Arch packages depending onpacmankeep 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, fingerprintFD185DAB770140E89C37275E7035CFDFDCA6C991(marked fully trusted inluxos-trusted). - The public key is in the package
luxos-keyring:/usr/share/pacman/keyrings/luxos.gpg,luxos-trusted,luxos-revoked. signatures required(engineSigLevel = Required DatabaseOptional): package signatures are mandatory; local files (lux install ./x.pkg.tar.zst) followlocal-signatures optional..luxpackages and the.luxindex are verified withgpgvagainst the sameluxos.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 bylux-config/ Software Update (channel,countmeinlux.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
.luxnewleft 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.