LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
System apps (M9)
The native system apps that ship preinstalled with LordOS: Disks (Discos), Backups (Copias
de seguridad), Logs (Registros), Clock (Reloj) and Help (Ayuda). All of them use t()
with es/en/pt, work right to left and have their own icon. Anything that needs root goes through
closed admin.c actions, with arguments validated on the root side and programs at fixed paths.
Disks (apps/disks)
The LordOS disk utility, like GNOME Disks.
- On the left: disks grouped into Internal, External (USB and cards) and Images (
loopdevices backed by a file), each with its partitions. A dot marks the mounted ones. - On the right:
- a usage bar: the disk's partitions to scale, or used and free space of a mounted partition;
- the actions;
- the details: device, model, serial number, capacity, connection, type, partition table, file system, label, UUID, mount point;
- the Disk health (SMART) card and, with smartmontools, the self-tests, the error log, the temperature history and every attribute (see "SMART with smartmontools").
- Refresh without polling: the list updates by itself on mount, unmount, plug-in or format.
![]() |
![]() |
| The system disk and its partitions (protected: no format, erase or unmount) | Health of the SATA disk: our own SMART over SG_IO, with the attributes |
![]() |
![]() |
Format: FAT32, exFAT, ext4 or NTFS (if mkfs.ntfs is present), with the label |
The confirmation says what gets erased and asks to type the disk name |
![]() |
![]() |
| Create a bootable USB: copying, with "Cancel" | Copied and verified (SHA-256 by reading the disk back); the image's partition shows up on its own |
How it is built
| Piece | What it does |
|---|---|
server/src/disk/disk.c |
The list, without root, from three sources. /sys/block: size, removable, read-only, rotational, model. The udev database (/run/udev/data/b<major>:<minor>): file system, label, UUID, partition table and bus; udev already probed them, so the device is never opened. /proc/self/mountinfo: where each one is mounted. It also recognizes the system disk and watches for changes. |
server/src/disk/smart.c |
ATA SMART and NVMe health log parsers: pure functions, no I/O |
server/src/disk/disk_admin.c |
The helper's disk-* actions (root) |
server/src/disk/smartctl_admin.c, smartctl.c |
The helper's smart-* actions (smartmontools, root) and their pure checks |
sdk/smart.js, sdk/smartparse.js |
smart.info/health/test/abort/install, the summaries the Monitor shows, and smartctl's JSON turned into one model |
server/src/ui/js_disk.c, sdk/disks.js |
lord.disks.list(), tools(), watch(on); in the SDK, useDisks() and disks |
apps/disks/ |
The app: index.jsx, health.jsx (SMART), dialogs.jsx (format, rename, erase, bootable USB), icons.jsx |
Notifications without polling. While the app is open (useDisks), lord.disks.watch(true)
opens an epoll with two things. That single fd goes into the lord-server main loop (main.c),
and JS gets __lordDisks('change'), coalesced into one every 150 ms. Closing the app closes
everything.
/proc/self/mountinfo, which signalsPOLLPRIwhen mounts change.- A
NETLINK_KOBJECT_UEVENTsocket on the udev group (2). When the event arrives, udev has already finished updating its database.
mountinfo has a catch: its event is consumed by polling it, and the main loop's poll on the
epoll already consumes it, so epoll_wait afterwards does not report it. So on every event a
fingerprint of the mountinfo content (a few KB) is compared with the previous one.
Actions (admin.run('disk-…', arg))
All are in the closed table of admin.c (macro DISK_ADMIN_ACTIONS in disk/disk.h).
| Action | Argument | What it does |
|---|---|---|
disk-smart |
disk |
Reads health. LOG smart {…} (summary), one LOG attr {…} per ATA attribute and OK <ms> |
disk-mount |
device |
Mounts at /media/<user>/<label> with mount(2): nosuid,nodev, and on FAT, exFAT and NTFS (ntfs3) with the user's uid=/gid=. ISO 9660 and UDF are read-only. OK <folder> |
disk-unmount |
device or disk |
Unmounts whatever is under /media or /run/media (umount2) and removes the empty folder |
disk-eject |
disk |
Unmounts everything, flushes caches (BLKFLSBUF) and sends START STOP UNIT (eject). Over USB it also powers the device off (/sys/block/<d>/device/delete), like "Power Off" in GNOME Disks |
disk-format |
device\nfat32|exfat|ext4|ntfs\nlabel |
Whole disk: wipes the signatures (first and last MiB) and writes our own MBR table with one partition from 1 MiB. A loop image without partscan gets it turned on. Then the fixed-path mkfs runs. On ext4 the root belongs to the user (-E root_owner=uid:gid) |
disk-label |
partition\nlabel |
fatlabel, exfatlabel, e2label or ntfslabel. FAT, exFAT and NTFS must be unmounted |
disk-erase |
device\nquick|zero |
quick: wipes the signatures (first and last MiB) and rereads the table. zero: writes zeros everywhere, with progress, cancellable |
disk-write-image |
disk\npath |
Copies an ISO/IMG image to the whole disk and verifies it |
disk-cancel |
disk |
Stops a zero erase or a copy in progress. Only whoever started it, or an administrator |
smart-info |
disk |
(0.8.2) smartctl -j -x: the full report. Anyone |
smart-health |
disk |
(0.8.2) smartctl -j -n standby -i -H -A -c -l selftest: the summary, without waking a resting disk. Anyone |
smart-test |
disk\nshort|long |
(0.8.2) smartctl -j -t short|long: starts a self-test. Internal disks: an administrator; removable: any session user |
smart-abort |
disk |
(0.8.2) smartctl -j -X: stops a running self-test. Same rule as smart-test |
Long actions send LOG progress phase=<table|mkfs|erase|write|verify> done=<n> total=<n>, which
the app shows as a bar.
Since 0.8.5 Files' sidebar lists every disk too and uses the same actions:
disk-mount when an unmounted one is clicked (an internal disk asks for an administrator, as here),
and disk-eject or disk-unmount from its ⏏ (FILES.md).
Security
The same rules for all of them, on the root side (
target()indisk_admin.c):- the name must be a real block device (
sd*,vd*,hd*,xvd*,nvme*,mmcblk*,loop*, lowercase letters and digits only); /dev/<name>is checked withlstat: a block device with the same major:minor as sysfs;- a "whole disk" action refuses partitions, and vice versa.
- the name must be a real block device (
The system disk is never touched (
disk_is_system). It is the disk of any partition that holds/,/usr,/var,/home,/boot,/boot/efi,/efi, the live medium (/run/live/medium…) or an active swap. For a dm/md (LVM, LUKS, RAID),slaves/is followed down to the real disks. Onlydisk-smartand thesmart-*actions accept it: they only read, or start the disk's own self-test, which does not change data.Who can:
- internal disks, only an administrator (groups
sudo,adminorwheel); - removable ones (USB,
removable=1,mmccards), any session user, like udisks with active sessions; - reading SMART, anyone.
- internal disks, only an administrator (groups
Only
/mediaand/run/mediaare unmounted. If something is mounted elsewhere, the action refuses. Format, erase and the image copy open the device withO_EXCL: if it is still in use (mounted or opened by another program), the kernel answersEBUSYand nothing is done.disk-ejectdoes not eject with an erase or a copy in progress either.Fixed-path programs, no shell:
/usr/sbin/mkfs.fat,/usr/sbin/mkfs.exfat,/usr/sbin/mkfs.ext4and/usr/sbin/mkfs.ntfs;/usr/sbin/fatlabel,/usr/sbin/exfatlabel,/usr/sbin/e2labeland/usr/sbin/ntfslabel;/usr/bin/udevadm settle.
Labels are validated per format and cannot start with
-:- FAT32: up to 11 characters,
A-Z 0-9 space _ -, uppercased; - exFAT: up to 15;
- ext4: up to 16 bytes;
- NTFS: up to 32;
- in all of them, no control characters and none of
/ \ : * ? " < > |.
Mount, unmount, partition, erase, copy and eject are system calls: no program is launched.
The image is read with the user's permissions.
- The helper does
setfsuid/setfsgidto the user beforerealpathandopen(O_NOFOLLOW). Root reads nothing the user could not read. - It only accepts regular files from the home folder,
/media/<user>or/run/media/<user>. A link to/etc/shadowor a..is refused (tested). - It also refuses an image stored on the disk that is about to be written.
- The helper does
Verification.
- The SHA-256 (
pkg/crypto.c) is computed while copying, withO_DIRECT, followed byfsync. - Then the cache is dropped (
BLKFLSBUF), the disk is read back withO_DIRECTand compared. - The result includes the hash, to compare with the one the distribution publishes.
- The SHA-256 (
Keeping the desktop smooth: zero erase and image copy lower their priority (
nice 10and best-effortioprio7). The copy usesO_DIRECTso it does not fill the page cache with dirty pages. The erase callsfdatasyncevery half second.Cancelling. The job leaves
/run/lordos/disk-<disk>.jobwith its pid and uid.disk-cancelchecks that the pid is alord-admin(not a recycled pid) and that the request comes from the same user or an administrator.The app's confirmation: everything that erases (format, erase, bootable USB) ends in the same step.
- It says exactly what is lost: disk, model and size, and each partition with its name, label, file system, size, mount point and how much data it holds.
- For a whole disk you have to type its name (
sdc). - The red button does nothing until it matches.
- Either way, the real validation is the one on the root side.
SMART: our own reader over ioctl (not smartctl)
We chose to read it with our own code:
- No dependencies or external programs. The dependency policy asks not to add programs when
avoidable, and
smartmontools(smartctl) would bring another root binary with its drive database. - What is needed is small: three commands and two well-defined 512-byte formats.
- The parsing stays in pure functions with their own test: the data the disk sends is outside data.
| Disk | How it is read (in the helper, root) |
|---|---|
SATA / ATA (sd*, hd*) |
SG_IO with ATA PASS-THROUGH (16) (0x85). Three commands: SMART READ DATA (B0h/D0h, PIO data-in, 1 sector); READ THRESHOLDS (D1h); RETURN STATUS (DAh, non-data, with ck_cond). The last one is read from the "ATA Status Return" descriptor (09h) of the sense data: LBA mid/high 4Fh/C2h = good, F4h/2Ch = threshold exceeded |
NVMe (nvme*) |
NVME_IOCTL_ADMIN_CMD: Get Log Page 02h (SMART / Health Information), 512 bytes |
The parsing (smart.c, tested in tests/smart_test.c):
ATA:
- the 30 attributes of 12 bytes, with their 48-bit raw value and their threshold;
- the checksum;
- temperature (194, or 190 if missing), hours (9), power cycles (12), reallocated (5), pending (197) and uncorrectable (198).
ATA health:
- failing if RETURN STATUS says threshold exceeded, or if a pre-fail attribute is at or below its threshold;
- warning if there are reallocated, pending or uncorrectable sectors, or if the checksum does not add up;
- otherwise good.
An "old-age" (non-pre-fail) attribute below its threshold is shown in red but does not make it fail.
NVMe:
- reads critical warning, temperature (kelvin → °C), spare and its threshold, % life used, data read and written (units of 512 000 bytes), cycles, hours, unsafe shutdowns and media errors;
- counters are 128-bit: if they don't fit in 64, they saturate;
- failing with the spare, reliability or read-only bits;
- warning with the temperature bit, more than 100 % life used, spare below its threshold or media errors.
Only on request. The "Check health" button reads once and the result stays in memory while the app is open. It is never read in the background: a sleeping disk is not woken up and nothing stalls.
Over USB, many adapters don't pass ATA PASS-THROUGH, and the app explains that. Virtual disks (virtio, loop) have no SMART.
SMART with smartmontools (0.8.2)
![]() |
![]() |
| The full report through smartmontools, dark | The same, light |
![]() |
![]() |
| First use: "Install smartmontools" (an administrator) | A short self-test running, with its progress |
Our own reader (above) stays: it needs nothing installed and gives the basic health. The rest — the
self-tests, the error log, the SCT temperature history, the drive database that names each
vendor's attributes, USB bridges — is what Debian's smartmontools (smartctl) already does well,
so 0.8.2 uses it instead of growing our own:
- Installed on first use. If
/usr/sbin/smartctlis missing (lord.disks.tools().smartctl), the card offers Install smartmontools, which goes through the Store's package engine (admin.run('pkg-install', 'smartmontools'), fetching the package lists first if there are none), exactly like Settings → Sharing installs the SSH server. Only an administrator can. Once installed, the full report is read right away. - Four closed actions in the root helper (
server/src/disk/smartctl_admin.c, table above).- The disk name must be a whole disk smartctl understands:
sd<letters>,hd<letters>ornvme<N>n<M>(smartctl_valid_disk). Partitions,loop,dm-*,md*,zram*,mmcblk*,sr*and anything with a path character are refused before anything runs. - Then the same
target()check as thedisk-*actions: it exists in sysfs, it is not a partition, and/dev/<disk>is a block device (lstat) with the same major:minor. - One program at a fixed path,
/usr/sbin/smartctl, with an argument list built in C; the only variable parts are the validated/dev/<disk>andshort/long. No shell, no generic runner, no options from the app. - A USB disk whose bridge smartctl does not know ("Unknown USB bridge") is retried once with
-d sat. - The JSON (
-j) is compacted (whitespace outside strings dropped,smartctl_compact) and sent asLOGlines of at most 900 bytes cut on UTF-8 boundaries, likeproc-info;OK <lines> <exit status>ends it (smartctl's exit status is a bit mask the app reads: bit 3 is "disk failing"). Output is capped at 1 MiB.
- The disk name must be a whole disk smartctl understands:
- Parsing in the session, not as root:
sdk/smartparse.jsturns smartctl's JSON into one model (every number checked, every string cut and only shown as text):- overall health and why, in plain words: Failing if the disk says so (overall status, a pre-fail attribute below its threshold now, NVMe "reliability degraded" or "read-only"); Check (shown as "With warnings") with reallocated, pending or uncorrectable sectors, grown defects, NVMe spare below its threshold, temperature or backup warnings, media errors, a pre-fail attribute that failed in the past, or more than 90 % of the rated life used. A device that says it has no SMART gets no verdict;
- temperature and the drive's limits, power-on hours, power cycles, data read and written;
- SSD wear (% of the rated life used): the NVMe health log, the ATA device statistics ("Percentage Used Endurance Indicator"), or attributes 231/233/202/177 counting down from 100;
- every attribute with a plain name (by smartctl's attribute name, not by id: vendors reuse ids and smartctl's drive database already knows them), with smartctl's own name under it;
- for NVMe, the whole health log (spare, % used, data units, commands, busy time, unsafe shutdowns, media errors, time above the warning and critical temperatures);
- the error log (NVMe drives also log harmless events, so its count does not change the health), the SCT temperature history (ATA) as a small bar chart, and the self-test log;
- self-tests: Short and Long buttons with the drive's own estimate in minutes; while one runs,
smart-healthevery 15 s gives the progress (ATA: "remaining percent"; NVMe: "completion percent"), with Stop the test; when it ends, the full report is read again.
- The result also updates the Monitor's cached summary (see
MONITOR.md). - Tests:
tests/smart_parse_test.mjs(92 checks, inmake testwhen node is there) with real smartctl 7.4 output captured on VM 119 (tests/smart/: a QEMU SATA disk before and after two self-tests, the health command, a virtio-scsi disk, a USB gadget with an unknown bridge and the-d satretry, a started test) and, in the same schema with edited values, a worn SSD, a failing disk, a running self-test, a disk in standby and NVMe drives (healthy, and failing with a test running).build/smartctl-testchecks the names (48 cases) and the compaction.
smartd: the package also brings Debian's smartd monitoring daemon. Its maintainer script
enables smartmontools.service, which starts at the next boot (on VM 119 it was enabled but not
started right after the install). Debian's default configuration checks each disk every 30
minutes with -n standby (a resting disk is not woken) and mails root, which goes nowhere on a
desktop. LordOS's own notices (MONITOR.md) don't need it, so since 0.8.3 it stays off: the
lordos package ships /usr/lib/systemd/system/smartmontools.service.d/lordos.conf with
ConditionPathExists=/etc/lordos/smartd-enabled, and migration 004-0.8.3-smartd-off.sh stops a
smartd already running from an earlier install. An administrator who wants it creates that file
and runs systemctl start smartmontools.
Measured on VM 119
| Reading SMART (QEMU SATA, ATA PASS-THROUGH: 3 commands) | 0.4–0.6 ms in the helper (OK <ms>); with the round trip through the helper, less than a frame |
lord.disks.list() (4 disks, 5 partitions) |
~3 ms (100 lists in 0.58 s including the test process start; the start alone, 1.3 ms) |
| Change notifications with the app closed | no fd and no timer |
300 MB image to an emulated USB stick (dummy_hcd + g_mass_storage) |
4.8–5.6 s writing (56–65 MB/s, with SHA-256 on the fly), plus the verification; 10.3 s in total |
| Our own SHA-256 | ~150 MB/s (4.1 s of CPU for 2 × 300 MB) |
How to test it
make -C server build/smart-test && ./server/build/smart-test # `make -C server test` runs it too
make -C server build/disk-cli
./server/build/disk-cli list # the same as lord.disks.list()
sudo ./server/build/disk-cli -u lord -n disk-format 'sdc\nexfat\nPendrive' # -n: as a non-administrator
disk-cli runs the actions with an admin_say that prints. It is for manual testing: it needs
root and real devices, so it is not in make test.
Tested on VM 119:
- A USB stick that is real for the kernel, built with
modprobe dummy_hcdandmodprobe g_mass_storage file=/var/tmp/usb-disk-sistema-119.img removable=1(sdc,TRAN usb,RM 1), as a non-administrator user:- format the whole disk as FAT32, exFAT (label with a space and ñ), ext4 (the root belongs to the user) and NTFS;
- mount and write on all four;
- mounting twice (refused);
- renaming while mounted (refused on FAT) and unmounted;
- quick erase, and zero erase with cancellation (refused for another user);
- eject with an erase in progress (refused) and without one (the device disappears);
- create the bootable USB from
~/Descargas: the SHA-256 matchessha256sumof the image and of the disk, and the image's partition table shows up; - the refused images:
/etc/shadow,../../etc/passwd, a link to/etc/shadow, an image inside the same stick, a partition as target and the system disk.
- The SATA test disk (
sdb, 8 GB, added assata1in Proxmox; QEMU with AHCI answers ATA SMART):- SMART: 7 attributes and RETURN STATUS "good";
- as a non-administrator, format and erase are refused.
- The system disk (
sda, virtio-scsi):- format, erase or unmount are refused, also as administrator;
- SMART answers "this disk does not report SMART", because QEMU's
scsi-hddoes not do ATA PASS-THROUGH.
Packages
| Package | For | In the ISO |
|---|---|---|
dosfstools |
FAT32 (mkfs.fat, fatlabel) |
already there (the installer uses mkfs.vfat for the EFI partition) |
exfatprogs |
exFAT (mkfs.exfat, exfatlabel) |
added to the ISO list |
e2fsprogs |
ext4 (mkfs.ext4, e2label) |
already in Debian base |
ntfs-3g |
NTFS (mkfs.ntfs, ntfslabel) |
optional: without it, the app does not offer NTFS |
smartmontools |
the full SMART report and self-tests (smartctl) |
no: installed from the app the first time (0.8.2) |
Mounting needs no package: vfat, exfat, ntfs3, ext4 and iso9660 are Debian kernel
modules.
Pending
- Disks over 2 TiB: our table is MBR. GPT has to be written (with its CRC32 and the backup at the end).
- Manual partitioning: create, delete and resize partitions. Today the whole disk is formatted with one partition, or an existing partition without changing its type in the table.
- LUKS, LVM and RAID:
- their disks are shown, and protected if the system sits on them;
- they are not unlocked or assembled from the app.
- Test NVMe with a real disk. The parser has a test, but the VM has no NVMe: Proxmox does not
offer it without
args. SMART over a USB adapter that passes it through (SAT) was not tested either. - SMART on real hardware (0.8.2): the smartctl path is tested on VM 119 (QEMU SATA, virtio-scsi, a USB gadget). A real NVMe drive, a real SATA SSD and HDD, a self-test that takes minutes and a USB enclosure that passes SAT through are still to be checked. Health history over time is not kept.
- Pick the image with the system file picker: today there is a list of the
.iso/.imgfiles in the home folder and a field for the path.
Backups (apps/backup)
Scheduled backups of the home folder to an external disk or a folder. The
engine is our own code (no rsync) and runs as the user, inside lord-server: backing up the
home folder needs no root, so no new action was added to admin.c.
![]() |
![]() |
| Settings: destination (the user's mounted disks or a folder), schedule, battery and exclusions | "Back Up Now": progress by files and bytes, with Pause and Stop |
![]() |
![]() |
| Backups by date and the tree of each one | Restoring a deleted file: session notification when done |
![]() |
![]() |
| Turning on encryption for a new destination | Encrypted and locked destination: a wrong passphrase is rejected |
On-disk layout
<destination>/LordOS-Backups/<host>-<user>/
├── 2026-10-17-235656/ a snapshot: the whole home folder, as it was
├── 2026-10-18-001432/ what did not change is a hard link to the previous one
├── .inprogress-<stamp>/ the run in progress (renamed when it finishes)
└── encryption.json only if the destination is encrypted: salt and key check
- Hard-linked snapshots (
server/src/backup/engine.c): a file with the same size, modification time and mode as in the previous snapshot is hard-linked (link); otherwise it is copied (copy_file_range, orread/writeacross filesystems). Every snapshot looks complete (it can be opened in Files) but only takes the space of what changed. On FAT/exFAT (no hard links) every backup takes full space; the app warns about it next to the disk. - Atomic: a run writes to
.inprogress-<stamp>and renames it at the end, aftersyncfs. Each file is first written to<name>.bkpart~and renamed, so a final name is always a complete file. - Interrupted runs (power off, unplugged disk, "Stop"): the next run uses the leftover
.inprogressas another link source (what was already copied is not copied again) and then deletes it. A file that changes while being copied is copied again (up to 3 times). - Symbolic links are stored as links (their text) and never followed. The walk uses
lstatand opens withO_NOFOLLOW; it does not cross into other filesystems (a disk mounted inside the home folder) and skips fifos, sockets and devices. - Exclusions: always
.cache,.local/share/Trash,.local/share/lordos/apps,.local/share/lordos/trashand.thumbnails; theLordOS-Backupsfolder itself when the destination is inside the home folder (by device and inode); and the folders the user adds (validated relative paths: no.., leading/or control characters).
Retention
bk_retention is a pure function (tested with made-up dates):
- every snapshot from the last 24 hours;
- the newest of each day up to 30 days;
- the newest of each week (Monday to Sunday, local time) after that;
- the newest snapshot always stays.
When space runs low (less than 512 MiB free before starting, or ENOSPC while copying), the
oldest snapshots are deleted, never the newest, and the copy is retried. Deleting a snapshot first
renames it to .deleting-<id> (it leaves the list at once) and then removes it; only inside the
machine folder and with validated names (YYYY-MM-DD-HHMMSS).
Restore
In the Backups tab: snapshots by day, the tree of each one (with real sizes), and Restore "file", Restore This Folder or Restore All (with confirmation).
- Nothing is overwritten by accident: if the current file differs, the backed-up one is saved next to it as "name (restored).ext" (then "… 2", "… 3"; the suffix is translated). With "Replace if it exists" it is replaced (written to a temporary file and renamed). If it is identical, nothing happens.
- The same rules as
lord.fs: it only writes in the home folder and the user's disks (fsops_allowed, on the resolved folder), never in protected places (fsops_protected:~/.local/share/applications,~/.config/autostart,~/.local/share/lordos/apps,settings.json,permisos.json,backup.json, and alsofirewall.json, the blocklists, the Mail accounts and cache and the Passwords vaults, the whole list inserver/src/fsops.c). A.desktopfile planted in a backup is not restored, not even through a link in the home folder that points to a protected folder. - No escapes through the backup: the requested path is validated (
bk_rel_valid) and its resolved folder must stay inside the snapshot. - Restore All brings the home folder back as it was that day; whatever changed since then is kept alongside (or replaced). Newer files are not deleted.
- "Open in Files" shows the snapshot in Files (it is a regular folder).
Scheduling, priority and battery (server/src/backup/backup.c)
- A
lord-serverthread, not a separate process, so no new way to run programs is added. The thread sets nice 19 (setpriorityon its own tid) and idle I/O (ioprio_set, class 3) and blocks all signals. What it copies is dropped from the page cache (posix_fadvise(DONTNEED)), so it does not evict what the desktop uses. - No polling: the thread sleeps in
pthread_cond_timedwaituntil the next backup (newest snapshot + interval). The first scheduled backup waits 5 minutes after the session starts; after an error, 15; if the disk is missing, it checks again every 5 minutes. - Battery: with "Pause on battery" (on by default), if a battery is discharging and no power
source is connected (
/sys/class/power_supply), the backup does not start, or pauses between files, and checks again every 60 s. While copying, the battery is read every 2 s. - The status is pushed to JS: an
eventfdin the main loop (backup_fd/backup_dispatch) calls__lordBackup(status)when something changes (at most twice a second with progress). The app never polls. - Notifications (
sdk/notify.js), even with the app closed: when a backup fails; when a "Back Up Now" run succeeds; when a restore finishes; and once per session when backups are encrypted and locked. - Configuration:
~/.config/lordos/backup.json(dest,interval:hourly|daily|weekly|manual,pauseOnBattery,encrypt,exclude). Onlylord.backup.configurewrites it, and it validates the destination (real path, inside thelord.fsroots, writable). It is on thefsops_protectedlist: it decides where the data goes, so an app cannot change it withlord.fs.write. - Errors that reach the UI as codes (
wrong-passphrase,not-encrypted,plain-backups-exist,setup-failed,no-destination,locked,interrupted) are translated by the app (backup.err.*); other engine messages are in English.
Encryption (optional)
With Monocypher 4.0.2 (vendored in third_party/monocypher, the same copy Passwords uses; see
server/src/backup/crypt.c):
- Per file:
LBK1+ a 24-byte nonce + 64 KiB chunks of XChaCha20-Poly1305. Each chunk's nonce carries its number and the associated data says whether it is the last one: chunks cannot be changed, reordered, removed or truncated without failing verification. Restore writes to a temporary file and discards it if anything fails to verify. - The key is derived from the passphrase with Argon2id (64 MiB, 3 passes, a 16-byte salt per
destination).
encryption.jsonstores the salt and a key check (BLAKE2b keyed with the key), never the key. - Memory only: the key lives in the session process (
mlock) and never on disk. At login, encrypted backups are locked: the passphrase has to be entered in Settings (a notification reminds the user). Argon2 runs in the backup thread, never in the compositor. - Hard links still work: an encrypted file's size is computed from the original's, so unchanged files are still linked.
- Not encrypted: file and folder names, symlink targets, approximate sizes and dates.
- It can only be turned on for a destination without backups (encrypted and unencrypted backups are never mixed). If the passphrase is lost, the backups cannot be recovered.
- Pending: storing the passphrase in the session keyring (Passwords) so scheduled backups do not wait for the user to type it.
API (lord.backup, server/src/ui/js_backup.c; in the SDK, backup and useBackup())
| Call | |
|---|---|
status() / useBackup() |
{ state: idle|running|paused|nodest|restoring|deleting|locked|unlocking, battery, userPause, dest, destAvailable, destFree, next, lastOk, progress: { files, totalFiles, bytes, totalBytes, file }, last: { ok, files, copied, linked, bytes, errors, secs, error }, restore: {…}, encrypted, destEncrypted, locked, unlock: {…} } |
config() / configure(obj) |
read and save the configuration (validated in C) |
runNow(), pause(on), cancel() |
|
list() |
[{ id, time }] |
ls(id, rel) |
[{ name, dir, link, size, mtime }] (sizes already decrypted) |
restore(id, rel, { replace, suffix, to }) |
empty rel: everything |
remove(id), path(id) |
delete a snapshot; its real path for Files |
unlock(passphrase, create), lock() |
encryption |
Tests and measurements
make -C server test → build/backup-test (server/tests/backup_test.c), 220 checks:
snapshot, exclusions, fifo, symlinks stored as links, the destination inside the home folder, hard
links (same inode), a run interrupted in the middle of a 40 MB file and resumed (already copied
files are linked, no leftovers), restore (keep both, numbering, replace, creating folders, a
planted .desktop, settings.json, escapes through a link in the backup and in the home folder,
.., a destination outside the roots), pruning for space, retention over 90 days of hourly
backups, and encryption (sizes, round trips from 0 B to 1 MiB, a tampered byte, missing chunks,
the wrong key, a wrong passphrase, an encrypted snapshot with hard links, and a restore that
discards a tampered backup).
Measured on VM 119 (4 vCPU Xeon Silver 4108, virtio disk on SSD), backing up the home folder (3.8 GB, 13,436 files) to an ext4 image on a loop device:
| First full backup | 24 s; the thread used 0.3 s of user CPU and 8 s of system CPU (≈34 % of one core) |
| Next backup with no changes | 1.0 s (13,403 linked, 29 copied) |
| After changing 1.8 GB | 12.8 s (42 copied, 14,372 linked) |
| First encrypted backup (1.8 GB, 10,704 files) | 18.3 s |
| Wakeup latency of a thread every 10 ms during the backup | p50 0.1 ms, p99 0.2–2 ms (no backup: p99 0.26 ms) |
Cold 64 KiB read during the backup, with mq-deadline |
p95 59–75 ms at idle priority, 121 ms without it |
Same with the none scheduler (the VM's) |
p95 44–70 ms at idle, 61–74 ms without: none ignores priorities |
ioprio only has an effect with a scheduler that honours it (mq-deadline, BFQ); with none
(NVMe and the VM, by default) what protects the desktop is nice 19, dropping the page cache and
the thread not competing with the compositor for CPU (wakeup p99 of 2 ms at most). Setting
LORD_BACKUP_NOPRIO=1 in the session environment turns off nice and ioprio, for measuring only.
Pending
- Test "Pause on battery" on a laptop (the VM has no battery).
- Notice when the backup disk is plugged in (today it checks again every 5 minutes).
- Store the encryption passphrase in the session keyring.
- File versions (every backup of one file, browsable in Backups).
- RTL was reviewed in code (rows the engine mirrors, text with
start/end, the progress bar inltr); there is no Arabic screenshot.
Logs (apps/logs)
LordOS's log viewer.
- Sources (sidebar):
- My logs: the user's own systemd journal (
user-<uid>.journaland its archived files); - System: the system journal. If the user can read it directly (group
systemd-journaloradm) it is read like the user's own; otherwise an administrator gets it through the closed actionlogs-system; anyone else is told it needs an administrator; - Kernel: the kernel's messages (
_TRANSPORT=kernel) from the readable journal; - LordOS: the session's own logs,
~/.cache/lordos/<name>.log(session.log,greeter.log…).
- My logs: the user's own systemd journal (
- Filters: level (all, info and above, warnings and above, errors), time range (15 min, 1 hour,
24 h, everything), process or unit (
[A-Za-z0-9@._:-], the same check as the C side), and free-text search in the message. - Live: follows new entries as they arrive (see below) and keeps the view pinned to the bottom until the user scrolls up.
- Detail: the selected entry with its time, level, process, PID, UID, unit and boot id.
- Export: the filtered view as text, to the user's Documents folder (
userDirs(), so~/Documentosin Spanish) throughfs.write. - A virtualized list (only the visible rows are drawn); at most 3000 entries per query and 10,000 kept while following (older ones are dropped). The status bar shows counts and query time.
Our own journal reader (server/src/logs/journal.c)
No libsystemd and no journalctl. The files are read with pread and a small block cache, never
mmap: journald can shrink or rewrite a file and mmap would turn that into SIGBUS inside
lord-server.
- Format: header
LPKSHHRH, the entry-array chain, ENTRY and DATA objects, in both the regular and the compact layout (Debian 13's systemd 257 writes compact files). Fields used:MESSAGE,PRIORITY,SYSLOG_IDENTIFIER,_COMM,_PID,_UID,_SYSTEMD_UNIT,_SYSTEMD_USER_UNIT,_BOOT_ID,_TRANSPORT; the time comes from the entry header. - Compression: XZ through our own decoder (
server/src/pkg/xz.c) and LZ4 with a small block decoder of its own. ZSTD is not decoded yet: those fields show as[zstd-compressed]. journald compresses only fields over 512 bytes, so it is rare (8 of 39,504 entries on VM 119). - Hostile input: every offset and size is checked against the file size, the entry-array chain must always move forward (no loops), and sizes are capped (1 MiB per object, 16 KiB per message).
- Several files: active and archived (
*.journal~,@…) files from/var/log/journaland/run/log/journal, merged by time.
Permissions
- The user's own logs are read by lord-server as the user: the kernel and journald's ACLs
decide.
user-<uid>.journalis readable by its owner; the system journal only bysystemd-journal/adm. - System logs for administrators go through
logs-system(server/src/logs/logs_admin.c,LOGS_ADMIN_ACTIONS, administrators only,A_FORK):- the argument is
key=valuelines validated as root (jq_parse):since/until(seconds or µs),prio0–7,kernel0/1,match([A-Za-z0-9@._:-], up to 95),grep(no control characters),limit1–5000; - the paths don't come from the user:
/var/log/journal/<machine-id>/system*.journal*; - it runs no program; it streams one JSON
LOGline per entry andOK <n>.
- the argument is
lord.logs.tail(name)only reads~/.cache/lordos/<name>.logwith a validated name.
Live follow without polling
lord.logs.follow(true) adds inotify watches on the journal directories and ~/.cache/lordos.
Queries run in a lord-server thread; the thread and inotify share one epoll fd in the main loop
(logs_fd()), so the compositor never waits for a read. When something changes, JS gets
__lordLogs('journal') or __lordLogs('file', name) and asks only for the entries after the
newest one it has (at most about once a second). With the app closed there is no watch and no
thread work.
API (lord.logs, sdk/logs.js)
| Call | Returns |
|---|---|
logs.sources() |
{ user, system, uid }: how many user files, whether the system journal is readable directly |
logs.query({ scope: 'user'|'system', since, until, prio, kernel, match, grep, limit }) |
promise of [{ t (µs), s, p, pid, uid, k, id, u, b, m }], oldest first |
logs.system(query) |
the same through logs-system (administrators) |
logs.files(), logs.tail(name, bytes) |
the LordOS logs and the end of one of them (up to 1 MB) |
logs.follow(on), logs.onChange(fn) |
live follow ('journal' or 'file', name) |
Tests and measurements
make -C server test→build/journal-test: synthetic journal files written by the test (regular and compact, an LZ4 field and an XZ field, a ZSTD field that must show the marker), queries and filters, JSON, every truncation of a file, 3000 random corruptions and an entry-array loop; none may crash or read out of bounds.Against
journalctlon VM 119 (build/journal-test dump <file>vsjournalctl --file <file> -o json), all the real journal files: 39,504 entries, 0 differences in count, time and message; 8 messages compressed with ZSTD show the marker.File Entries Differences system.journal+ 2 archived12,394 + 7,733 + 10,361 0 (8 ZSTD) user-1000.journal+ 2 archived3,639 + 2,427 + 2,950 0 Speed (
build/journal-test bench):system.journalwith 12,403 entries opens in 0.6 ms, decodes all in 14 ms (~880,000 entries/s) and returns the newest 1000 in 3.1 ms; the user journal (3,655 entries) in 0.3 / 5.5 / 3.5 ms.
Screenshots (VM 119)
![]() |
![]() |
| My logs: the user's journal, read as the user (164 entries in 5 ms) | System, 24 h, through logs-system (lord is in sudo but not in adm): 3000 entries in 109 ms, with the detail of an entry |
![]() |
![]() |
| Search "lord-netd": its DHCP renewals every ~4.5 min (T1 of a 10 min lease) | Live: logger lines sent over ssh after the view opened (7 and 8) appear without reloading |
Export of the "lord-netd" view: ~/Documentos/Registros-20261018-035235.txt, 203 lines.
Pending
- A ZSTD decoder of our own (or showing those fields in full).
- RTL screenshot (the layout uses
start/end; checked in code only).
Clock (apps/clock)
World clock, alarms, timer and stopwatch, like GNOME Clocks.
| Tab | What it does |
|---|---|
| World clock | Local time plus the cities you add (search over tzdata's zone1970.tab), with an analog face, "today/tomorrow/yesterday", the hour difference and the zone abbreviation (CEST, AEDT…) |
| Alarms | Time, repeat days (or just once), label, on/off, edit and delete. Shows how long until the next one |
| Timer | Hours, minutes and seconds or presets (1–30 min), pause and resume, progress bar |
| Stopwatch | Laps with split and total; the fastest in green and the slowest in red |
Another city's time: our own TZif reader
The process time zone is never touched to compute another city's time: setenv("TZ") would change
the Date of the whole theme (the bar, the other apps). Instead:
server/src/ui/tzif.creads the TZif files in/usr/share/zoneinfo(RFC 8536, versions 1 to 4: the 64-bit block, binary search for the transition, and the footer with the POSIX TZ rule for dates after the last transition) and evaluates POSIX rules (CET-1CEST,M3.5.0,M10.5.0/3,Jn,n,Mm.w.d, negative or >24 h times,<+0545>names).- Validated: zone names only allow
[A-Za-z0-9/_+-], no..and no leading/; the real path (tzdata uses links) must stay inside/usr/share/zoneinfo/; regular files up to 1 MB; every count and index in the file is checked before reading. - JS:
lord.time.zoneOffset(zone, unixSeconds)→{ offset, abbr, dst }ornull(server/src/ui/js_help.c, which adds it to thelord.timeobject created byjs_sys.c). - Test (
make -C server test→build/tzif-test,tests/tzif_test.c): POSIX rules at known instants (Europe, Australia, the US, Nepal, zones without DST), a TZif v2 built inside the test with every truncated prefix (each must fail without over-reading) and an invalid type index, and a comparison against glibc (localtime_rwithTZ) in 24 tricky zones (Lord Howe, Chatham, Casablanca, Gaza, Santiago, Kathmandu, St Johns…) every ~3 days from 1970 to 2045: 216,168 instants, 0 differences on VM 119.
Alarms with the app closed (sdk/alarms.js)
Alarms, the timer and the stopwatch live in the SDK, not in the window: startShell calls
startAlarms() once per session. So they ring with Clock closed and also with the session in the
background (fast user switching, or viewed only from the browser): the lord-server session keeps
running, and so does its JS.
- Storage:
settings.clock = { alarms: [{ id, h, m, days, label, on, snooze, fired }], cities: [...] }in~/.config/lordos/settings.json.firedis the instant it last rang, so it does not ring again when the session restarts. - No polling: a single
setTimeoutuntil the next thing due (alarm, snooze or end of the timer). It is re-armed when the alarms change (settings subscription). - Clock changes and suspend:
lord-servertimers useCLOCK_MONOTONIC, which does not advance while suspended. So the wait is cut into slices —1 minute if something is due within the hour, 10 minutes otherwise— and each wake-up recomputes with the real time. Anything that should have rung less than 10 minutes ago still rings; older ones are dropped (yesterday's alarm does not ring after a long suspend). With no alarms and no timer there is no timer at all. - When it rings: a sticky notification with "Stop" and
"Snooze 9 min", plus the
notifysound fromlord.sound.playevery 2.5 s for one minute or until the notification is touched. One-time alarms switch themselves off. The timer notifies the same way, with "Repeat". - Menu bar:
registerStatusItem('clock', …)shows ⏱ with the time left on the timer (redrawn every second only while it runs) or ⏰ with the time of the next alarm if it rings within 24 h. A click opens Clock on that tab.
Menu bar status items (sdk/statusitems.js)
registerStatusItem(id, Component, order) and <StatusItems color />: an optional registry so
system apps can show something in the theme's bar, like the "menu extras" of popular desktop systems. The default theme
(next to the privacy indicators) and classic (in the taskbar) draw it; a theme that does not draw
it simply doesn't show them.
Session notifications (sdk/notify.js)
LordOS had no notifications (only the short clipboard toast). Now there is one shared by every app,
mounted by startShell, so it shows with any theme:
import { notify, dismissNotification, notifyHistory } from '@lordos/sdk';
const id = notify({
app: 'backup', // its icon and name (appName) in the banner
title: t('backup.notify.doneTitle'), // texts arrive already translated
body: '1234 files',
actions: [{ id: 'open', label: t('backup.notify.open'), primary: true, run: () => wm.open('backup') }],
sound: true, // the "notify" sound (lord.sound.play)
sticky: false, timeout: 6000, // sticky: stays until an action or the × is pressed
onClose: (reason) => {}, // 'closed', 'action' or the action id
});
dismissNotification(id);
- At the top, on the end side of the line (right; left in Arabic or Hebrew), below the theme's
workArea; up to four at a time, newest on top. - Clicking the banner runs the first action; the × closes it.
notifyHistory: the last 50 of the session, in memory only.- Up to three actions per notification. The API is stable: Clock and Backups use it.
- Linux apps reach the same banners through the session's
org.freedesktop.Notificationsserver (server/src/hw/notifyd.c), with per-app settings in Settings → Notifications (SETTINGS.md).
Screenshots
![]() |
![]() |
| World clock with several cities | The alarm rings with Clock closed: notification with Stop and Snooze, ⏰ in the bar |
Help (apps/help)
LordOS help and tips: a help viewer and a tips app.
- Articles: one per app and per feature (desktop, windows, Search, clipboard, keyboard and
input methods, Linux apps, touchpad, network, VPN, users and sessions, remote desktop, privacy,
printing, sound, updates, settings, appearance, language, and the system apps). 44 articles in
assets/help/{en,es,pt}/<id>.md, written from the documents indocs/. English is the default; es and pt are translations. - Sidebar by section (Getting started, The desktop, Apps, System, Settings), with each app's icon, and search over titles, keywords and text, with a snippet of the match.
- Rendered with the SDK's
<Markdown>(the same as Notes): headings, lists, tables, code. - Custom links in the text:
[Settings → Network](settings:network)opens that Settings section (wm.open('settings', { args: { section } }), which Settings already accepted);[Files](app:files)opens an app;[VPN](help:vpn)another article. An app's article has an "Open " button. - Help menu in the
defaulttheme: "LordOS Help" and "Welcome to LordOS".
Article format
---
title: Clock
app: clock # the app it explains ("Open" button and icon)
section: apps # start | desktop | apps | system | settings
order: 41
keywords: alarm, timer, stopwatch
---
# Clock
Markdown text…
Fallback to English: the list is the English one plus any extra articles of the interface
language; each article is read in the interface language and, if that file is missing, in English.
To add a language, copy the en folder and translate.
Reading: lord.help (server/src/ui/js_help.c)
| Call | Returns |
|---|---|
lord.help.list(lang) |
[{ id, title, app, section, order, keywords }] (each .md header) |
lord.help.read(lang, id) |
the article text or null |
Read-only, like lord.locale.catalog: language and id only allow [a-z0-9-] (no dots or
slashes), so nothing outside <assets>/help/ can be reached; O_NOFOLLOW, regular files up to
256 KB. In the SDK, help (sdk/help.js): list, read, search, open(id), startTour() and
link(url).
Search
sdk/spotlight.js now has a source registry, registerSpotlightSource(id, fn). Help registers
its own: articles appear in the "Help" section with a snippet in the preview, and Enter opens the
article. The section title comes from shell.spotlight.section.<id>.
"Welcome to LordOS"
A six-step tour (welcome, the desktop, Search, Settings with buttons to Appearance, Network and Users, the system apps, and where help is), with "Skip", "Back" and "Next".
- It opens by itself the first time the session starts:
startShellcallsmaybeStartTour(), which writeswelcomeShown: trueto the settings before opening it (it doesn't come back even if the window is closed). It doesn't appear on the live system, where the installer opens instead. - It can be watched again from the Help sidebar or the Help menu.
- Its texts live in
assets/locales/<lang>/help.json(help.tour.<n>.title|body).
Screenshots
![]() |
![]() |
| "Welcome to LordOS" on first login | An article opened from Search, with links to other articles |
![]() |
|
| Search finds Help articles |
Pending
- Images inside articles (
<Markdown>already draws them; per-language screenshots are missing). - A table of contents in long articles (
markdownHeadingsalready exists).
























