# The daemons KDOS has no logind and no polkit agent on the path between the desktop and the kernel. In their place are five small root daemons, each answering a few fixed questions on a Unix socket in `/run`: suspend the machine, mount a USB stick, say which application is spending the battery, kill a runaway program before the desktop freezes, and mount application packs. This chapter describes each of them, together with three programs that sit close to privilege without being root daemons: the per-box Wayland socket `kdos-boxsock`, the portal backend and the lock screen, and the two login-record services, `utmpd` and `wtmpd`. It is written for two readers: - **An administrator** who wants to know what each daemon allows, who may ask it, which file configures it and how to find out why something was refused. Read [At a glance](#at-a-glance) and [The shape they share](#the-shape-they-share), then the section for the daemon in question. - **A contributor** changing a daemon or adding one. Read the whole chapter, then [Adding a root daemon](#adding-a-root-daemon). Why the authorisation is shaped this way, and what it defends against, is argued in [The security model](../03-architecture/security-model.md). How init starts services is in [Boot and init](../03-architecture/boot-and-init.md). Every socket path and verb on the system is listed in [Filesystem and IPC](../06-reference/filesystem-and-ipc.md). ## At a glance Each root daemon is one binary in `/usr/sbin`, started at boot by a script in `/etc/init.d` and kept running by `ksvc`, the service supervisor in `kdos-tools`. | Daemon | Socket | Command-line client | Other clients | Init script | Skipped at boot when | |---|---|---|---|---|---| | `kdos-powerd` | `/run/kdos-powerd.sock` | `kdos-power` | The panel's and the Start menu's power items, the power and sleep keys, the compositor's lid handler `kdos-lid`, the `kdos-firewall`, `kdos-time` and `kdos-users` [surfaces](../06-reference/glossary.md) (windows and pop-ups drawn by `kdos-shell`), `kdos theme`, `kdos doctor` (checks that the socket exists) | `55_powerd.sh` | The binary is missing | | `kdos-energyd` | `/run/kdos-energyd.sock` | `kdos-energy` | `kdos-res` (the Energy and Boxes pages), `kdos doctor` (checks that the socket exists) | `56_energyd.sh` | The binary is missing, or no `/sys/class/powercap/*/energy_uj` is readable | | `kdos-oomd` | `/run/kdos-oomd.sock` | — | `kdos doctor` (checks that the socket exists) | `57_oomd.sh` | The binary is missing, or `/proc/pressure/memory` is not writable (the kernel has PSI off) | | `kdos-mountd` | `/run/kdos-mountd.sock` | `kdos-mount` | The `kdos-devices`, `kdos-disks` and `kdos-connect` surfaces, and the session helper `kdos-mediad` | `58_mountd.sh` | The binary is missing | | `kdos-packd` | `/run/kdos-packd.sock` | — | `kdos-appbox` (and `kdos app`, which runs it), `kdos doctor` | `59_packd.sh` | The binary is missing, or `erofs` is absent from `/proc/filesystems` even after `modprobe erofs` | `kdos-powerd`, `kdos-energyd` and `kdos-mountd` are each one binary with two names. Run under the daemon's name it serves the socket; run under the client's name (`kdos-power`, `kdos-energy`, `kdos-mount`) it sends one request and prints the answer. ### Starting and stopping one by hand The `service` command (a second name for `ksvc`) takes the verb first and then the **service name**, which is the init script's name without its two-digit prefix and `.sh` suffix: ```sh service status powerd service restart mountd service stop packd service start energyd service list # every service, whether it starts at boot, and its state service disable oomd # do not start it at boot ``` `rcS` and `rcK` are the boot and shutdown scripts in `/etc/init.d` that run every numbered service script in order (see [Boot and init](../03-architecture/boot-and-init.md)). `disable` creates `/etc/service.disabled/`, which both skip; `enable` removes it. A name that matches no script exactly is matched as a substring, so `service status mount` also reaches `58_mountd.sh`. The daemon's full name (`kdos-powerd`) matches nothing: it contains the service name rather than the other way round. The substring match finds the script for `status`, `start`, `stop` and `restart` only. `enable` and `disable` check that some script matches, then write or remove the marker under the name exactly as typed, while `rcS` and `rcK` look for the marker under the script's own service name. They therefore need the exact service name: `service disable mount` reports success, creates `/etc/service.disabled/mount`, and disables nothing. ### Who may ask for what | Daemon | root | `wheel` (administrators) | `seat` (the person at the machine) | Anyone else | |---|---|---|---|---| | `kdos-powerd` | Every verb | Every verb | `ping`, `suspend`, `poweroff`, `reboot` | Refused | | `kdos-energyd` | Every verb | Every verb | Refused | Refused | | `kdos-oomd` | Every verb | Every verb | Every verb | Refused | | `kdos-mountd` | Every verb | Every verb | Every verb | Refused | | `kdos-packd` | Every verb | Every verb | Refused | Refused | `seat` is the group seatd hands the display to. The installer keeps the desktop account in `seat` on every install and takes a non-administrator out of `wheel`; see [kinstall](kinstall.md#what-the-rest-of-the-tree-provides). Such an account keeps the lid, the power keys and removable media, and loses sudo and every configuration verb. ## The shape they share Every root daemon here is built the same way. Knowing the pattern once tells you how to run, diagnose and review all five. ### Supervision and logging A daemon runs in the foreground and never forks into the background. The init script calls `supervise ` from `/etc/init.d/service_helper`; the supervisor leads its own process group, writes `/run/.pid`, and restarts the daemon five seconds after it exits. `service stop ` sends SIGTERM to the whole group, waits a second, then sends SIGKILL to whatever is left. The daemon's output goes to syslog and to a small file in `/run`. The supervisor points the daemon's standard output and error, and its own *Starting* and *Exited* lines, at a forwarder process. Each line becomes a daemon-facility syslog message tagged with the daemon's full name, and is also appended to `/run/kdos-svc..log`: for example `/run/kdos-svc.kdos-powerd.log`, tagged `kdos-powerd`. Files and tags use the full name; only the `service` command takes the short one. The file holds at most 64 KiB; when it would grow past that it is renamed to `/run/kdos-svc..log.old` and a fresh one starts. The file is what you read before `syslogd` is up or while it restarts. The daemon never keeps the descriptors it inherited. Under `rcS` those point at the boot step's capture file on the `/run` tmpfs, so a daemon that crash-looped would fill memory until the next reboot, and a daemon that logs only to standard error would never reach `/var/log/messages`. The forwarder ignores the SIGTERM that `service stop` sends the group and exits only when the daemon's end of the pipe closes, so what a daemon prints while shutting down is kept and it never writes into a pipe with no reader. The init script checks the machine first and skips with a reason. A daemon that cannot do its job on this machine (no energy counter, no PSI, no EROFS) is skipped and prints `[SKIP] : ` at boot, because a daemon that refuses to start under a respawn loop is restarted every five seconds for as long as the machine is up. `service_helper` also offers `supervise --final-exit `, which stops the respawn on an exit status restarting cannot change. None of these five daemons uses it: each one's usual refusal is caught by its init script, and a refusal the script cannot see (`kdos-energyd` finding no usable energy domain after the script's glob matched) is restarted every five seconds. ### The socket and the identity check Each daemon owns one socket in `/run`, named after the daemon, and removes a stale one before binding so that a socket file left by a crash cannot hold the name. The socket is mode 0666, and anyone may connect; the real check is the caller's identity. The daemon asks the kernel for the connecting process's user id (`SO_PEERCRED`, which the caller cannot forge) and answers `err not permitted` to anyone it does not admit. The file mode is left open on purpose: a mode that looked like the authorisation is a mode somebody eventually loosens. There is one implementation of that check, `kb_uid_allowed()` in `libkbase`. It admits uid 0 outright; otherwise it looks the uid up in the password database and reads `/etc/group`, and admits the account when the group's id is its primary group or its name is in the group's member list. Membership is therefore read at the moment of the request, not from the caller's process credentials, and a group change applies to the next request without a new login. No daemon keeps its own copy of the rule: a copy per daemon is a rule that gets tightened on one socket and stays loose on the others. A daemon that needs a different rule states the difference beside its own call. The client never names a path. Every verb takes an identifier from a list the daemon itself published: a row number, a pack id, a service name. ### One request per connection The client connects, writes one short line, reads the answer and the connection closes. There is no session state. The one exception is `kdos-mountd`'s `subscribe`, which keeps its connection open and is written to when something changes; even then the daemon remembers only a file descriptor. Each daemon serves one request at a time. `kdos-energyd` and `kdos-oomd` give a connection two seconds to send its request, because the same loop drives their sampler and their pressure trigger, and a client that connected and said nothing would otherwise stop them. `kdos-mountd` sets no such limit although its loop also forwards hotplug events, so a connection that never speaks holds back every `changed` notification until it closes. `kdos-powerd` and `kdos-packd` set none either, so a connection that never speaks delays every later request until it closes. ### Fixtures, skips and test sockets `kdos-energyd`, `kdos-oomd`, `kdos-mountd` and `kdos-packd` each have a fixture mode: the daemon can be pointed at a recorded copy of the system state and made to print what it would do without doing it. This is how the selection logic, which decides what gets mounted, formatted or killed, is tested without a machine to lose. `kdos-powerd` has none; its `--explain` and `--set-*` flags run the same rules against a scratch `/etc` instead (see [Diagnosis and testing](#diagnosis-and-testing)). Each daemon reads another socket path from an environment variable (`KDOS_POWERD_SOCKET`, `KDOS_ENERGYD_SOCKET`, `KDOS_OOMD_SOCKET`, `KDOS_MOUNTD_SOCKET`, `KDOS_PACKD_SOCKET`) so the test suite can run it unprivileged. Moving the socket grants nothing: the check is the caller's identity, never the path. `kdos-powerd`, `kdos-oomd`, `kdos-mountd` and `kdos-packd` refuse to start on their real socket unless they are root, because an unprivileged daemon would answer `ok` to work it cannot do. `kdos-energyd` has no such check; it refuses to start when it cannot read the energy counter, which without root it cannot. A socket address holds at most 107 bytes of path. `kdos-packd` refuses to start on a longer path, because truncating would bind a socket at a path nobody asked for, and the next start would fail with "address already in use" for a file that appears not to exist. `kdos-powerd`, `kdos-energyd`, `kdos-oomd` and `kdos-mountd` cut an over-long path to fit and bind at the shortened one. ## kdos-powerd Suspend, power-off and reboot for a desktop that does not run as root, plus the few `/etc` writes that belong to an administrator: the time zone, the autologin account, the firewall's open services and the accent colour of the boot menu and text console. A setuid helper would put an argument-parsing root process within every user's reach for three verbs. polkit is installed, but its answer is to ask for a password, which a closing lid cannot do. There is no logind. The daemon is the smallest thing that can sit between the desktop and `/sys/power/state`. | Verb | Who | Does | |---|---|---| | `ping` | root, `seat`, `wheel` | Answers `ok`. Also tells a client whether it would be allowed to suspend | | `suspend` | root, `seat`, `wheel` | Suspend to RAM | | `poweroff` | root, `seat`, `wheel` | Power off | | `reboot` | root, `seat`, `wheel` | Reboot | | `timezone ` | root, `wheel` | Point `/etc/localtime` and `TZ` at a zone, and set the Wi-Fi country from it | | `autologin \|off` | root, `wheel` | Choose which account tty1 logs in without asking, or none | | `firewall list` | root, `wheel` | One row per named service: name, `on` or `off`, and a short description of what the service is for (the For column below, in the daemon's words; no port appears), tab-separated, then `ok` | | `firewall on\|off` | root, `wheel` | Open or close one named service | | `accent ` | root, `wheel` | Recolour the boot menu, the text console and the boot splash | The daemon checks the list the other way round: a `seat` member may use exactly the four words `ping`, `suspend`, `poweroff` and `reboot`, and every other verb is an administrator's. A verb added later is therefore an administrator's unless someone deliberately adds it to that list. Every refusal is written to the daemon's log with the caller's uid, so a dead power key can be attributed. ### The client ```sh kdos-power [--no-lock] suspend|poweroff|reboot|ping kdos-power timezone kdos-power autologin |off kdos-power firewall list| on|off kdos-power accent ``` The request is one line of at most 62 bytes plus its newline (63 in all); the daemon reads nothing past that. | Exit status | Means | |---|---| | 0 | The daemon answered `ok`, or closed the connection without answering any verb other than `ping` (for `suspend`, `poweroff` and `reboot` that is the machine going away) | | 1 | The daemon answered `err …`, or is not running (`kdos-power: no kdos-powerd — ` followed by the hint ``service kdos-powerd start``, which ksvc rejects; see below) | | 2 | Bad usage, or an argument too long for the request line | When the daemon is not running, start it with `service start powerd`. The command the client suggests puts the daemon's full name where the verb goes, so ksvc answers `Error: Unknown command 'kdos-powerd'` and starts nothing (see [Starting and stopping one by hand](#starting-and-stopping-one-by-hand)). For every verb except `firewall`, an error is printed to standard error as `kdos-power: `. `firewall` prints the daemon's whole reply on standard output, the `err` line included, because `kdos-firewall` reads it through a capture that discards standard error. ### Suspend locks the screen first `kdos-power suspend` locks the session before the machine sleeps, so a resume never hands back an unlocked desktop. The order is: 1. Send `ping`. This runs the same identity check as `suspend`, so a caller who is not allowed to suspend, or a machine with no `kdos-powerd`, is refused before the screen is locked. Locking and then not suspending would be a password prompt in exchange for nothing. 2. If no process named `kdos-lock` is running, start one in its own session and wait up to two seconds for it to print `locked`, which it does once the compositor confirms the session is locked. An existing lock client is left alone, because the compositor refuses a second one. 3. Send `suspend`. If the lock did not confirm in time, the client prints `kdos-power: no lock confirmation within 2s — suspending anyway` and suspends regardless: a broken lock screen must not turn the suspend key into a no-op. `--no-lock`, or a non-empty `KDOS_NO_LOCK_ON_SUSPEND` in the environment for a caller that cannot change its own arguments, skips steps 1 and 2. The daemon answers `ok` before the machine goes down, so the client is not left waiting for a reply from a suspended kernel. ### What happens around a suspend The daemon is the only thing on the machine that knows a suspend is happening (there is no logind to announce one), so it tells the two programs that must act around it: 1. `sync`. 2. NetworkManager's `Sleep(true)`, through `dbus-send --system --print-reply`, waited for with a five-second reply timeout so the devices are down before the kernel freezes them. 3. `tlp suspend`. 4. Write `mem` to `/sys/power/state` (suspend to RAM). Hibernation is not offered, because the initramfs sets up no resume device. 5. After waking, or at once if the kernel refused the write: `tlp resume`, then NetworkManager's `Sleep(false)`. NetworkManager sleeps first and wakes last, so the radios TLP restores are back before it rescans. Without step 2, NetworkManager wakes trusting a Wi-Fi association and DHCP lease that the time asleep has ended. Without `tlp resume`, the radio states TLP saved, and the settings the firmware resets across suspend, are not restored. Each hook is skipped when `/usr/bin/dbus-send` or `/usr/sbin/tlp` is not installed, and none of them can stop the suspend. ### Power-off and reboot `poweroff` and `reboot` ask init first, by running `/sbin/telinit 0` or `/sbin/telinit 6` through the argument-vector builder. Init ends the consoles, and then `/etc/init.d/rcK`, its first runlevel 0 and 6 entry, stops every service in reverse order, `kdos-powerd` among them, before anything is unmounted. Only if the daemon is still alive sixty seconds later, which means init never acted on the request, does it call `reboot(2)` directly. The wait is that long because init gives the consoles up to three seconds and `rcK` then stops every supervised service numbered above `55_powerd.sh` first, at a cost of about a second each; a shorter wait would cut the power mid-shutdown. No signal can stand in for `telinit`: sysvinit ignores `SIGTERM`, and `SIGUSR2` closes `/run/initctl`, its request channel, for the rest of the boot. ### accent `accent ` takes one of the eight scheme names compiled into `libkcolor`: `phosphor`, `amber`, `ice`, `bone`, `norton`, `borland`, `perfect` or `paper`. The name is matched by `kcol_find()`; anything else is refused with `err not an accent`. There is no path to aim and nothing to traverse, which is why this verb is safe to reach from a session. It writes only root-owned files: - `/etc/kdos/accent`, which `rcS` reads to recolour the boot splash that is already running; - the boot menu (`limine.conf` on the EFI system partition, the ESP) and the text-console palette (`/etc/vtrgb`), by running `kdos-bootctl theme `, which owns both files. `kdos-bootctl` is found through the daemon's inherited `PATH`, as `iw` is for the [timezone](#timezone) verb; every other program the daemon runs is named by absolute path. It recolours nothing on the desktop. That is `kdos theme`'s job, which runs as the user and touches only the user's own files; `kdos theme` calls this verb for the parts that need root. A machine with no writable ESP is not a failure. The live medium is read-only, and a machine may have no `/boot/efi` at all. When `kdos-bootctl` fails or is absent, the verb answers `ok (boot menu unchanged)` and succeeds, because refusing would make `kdos theme` look broken on the ISO, where everything else recolours correctly. ### timezone The time zone is set here rather than by a separate daemon because it is the same question: the files are root's, the person changing them is the one administering the machine, and `wheel` is already the answer to who that is. A zone name is checked twice: 1. **As characters.** Letters, digits, `+`, `-`, `_` and `/` only; no dot at all; no leading, trailing or doubled slash; at most 64 characters. A zone is `Area/City` or `Area/Sub/City`, so a slash must be allowed, which makes `../../etc/shadow` look legal; this rule is what stops it. Failure answers `err not a zone name`. 2. **As a file.** It must exist under `/usr/share/zoneinfo`. Failure answers `err no such zone`. Then both halves are written, each to a temporary name and renamed into place: - `/etc/localtime` becomes a symlink to the zone file. Programs that read the zoneinfo tree follow it. - `/etc/profile.d/20-timezone.sh` exports `TZ=':/etc/localtime'`. musl reads `TZ`, and it takes precedence where it is set, which is on every KDOS login. The colon form points musl at the same file, so the two can never name different rules. Writing only the symlink would leave `date` reporting the old zone in every shell that had already read the profile. **The Wi-Fi country follows the zone.** The kernel's wireless layer starts in the "world" regulatory domain, which keeps every 5 GHz DFS channel (one shared with radar) closed and caps transmit power until something names a country, and some drivers never take one from an access point. The verb looks the zone up in `zone.tab`, which maps each zone to exactly one country code, then: - writes `options cfg80211 ieee80211_regdom=` to `/etc/modprobe.d/kdos-regdom.conf`, which takes effect from the next boot; - runs `iw reg set ` for the running boot, when an `iw` is found through the daemon's inherited `PATH`; `kdos-bootctl` for [accent](#accent) is the other program looked up that way. A zone with no country, such as `UTC`, removes the file. Neither step failing fails the verb: a machine with no radio still has a time zone. The installer writes the same file from the zone chosen during installation. ### autologin `autologin ` sets the `autologin` key in `/etc/kdos/login.conf`, which decides whether tty1 logs straight into the desktop. `autologin off` turns it off. - The account must be one that can log in. `kb_users()` in `libkbase` decides that; a name it would not list is refused with `err no such account`. Pointing autologin at a service account with `nologin` would give a machine that boots to a login nobody can complete. - `off` replaces the key line with the fixed text `#autologin = kdos`, whatever account was set, rather than emptying the value. The login program only hands `agetty --autologin` a non-empty name, so an empty value would read as a setting and behave as none. - Only the key line changes. A line counts as the key when it starts with `autologin`, or with one `#` then `autologin`, and contains `=`. Prose that merely mentions the key is left alone. - A file too large to rewrite safely is refused (`err login.conf is too large`) rather than truncated: half a configuration file is a machine whose login settings are whatever survived. The file is written to `login.conf.new`, flushed, and renamed over the original. ### firewall `firewall` names services, never ports, and the table of what each name means belongs to the daemon. A client that could name a port could open any port; a client that can only name `ssh` opens exactly what the daemon's table says `ssh` is. `kdos-firewall` asks for the list rather than carrying its own copy. | Service | Opens | For | |---|---|---| | `ssh` | TCP 22 | Incoming SSH (`70_sshd.sh`). Turning it on also removes `/etc/service.disabled/sshd` and starts `sshd`; turning it off puts the marker back and stops `sshd` | | `http` | TCP 80 | A web server on this machine | | `https` | TCP 443 | A TLS web server on this machine | | `ipp` | TCP 631 | Sharing a printer with CUPS | | `smb` | TCP 445 | Sharing files over SMB | | `kiwix` | TCP 8080 | `kiwix-serve` | | `mdns` | UDP 5353 | mDNS beyond the default rule | | `mqtt` | TCP 1883, 8883 | An MQTT broker for LAN devices (`73_mosquitto`) | | `xmpp` | TCP 5222 | XMPP clients (`74_prosody`) | | `nfs` | TCP 2049 | Sharing files over NFSv4 (`72_nfsd`) | | `babel` | UDP 6696 | Babel mesh routing (`31_babeld`) | | `nut` | TCP 3493 | UPS status for other machines (`56_nut`) | | `snmp` | UDP 161 | SNMP queries of this machine (`71_snmpd`) | | `mumble` | TCP 64738, UDP 64738 | A Mumble voice server (`75_mumble-server`) | | `caldav` | TCP 5232 | Shared calendars and contacts (`77_radicale`) | | `mail` | TCP 25, 143, 465, 587, 993 | A LAN mail server (`78_maddy`) | | `irc` | TCP 6667, 6697 | An IRC server (`79_ngircd`) | | `dlna` | TCP 8200, UDP 1900 | A DLNA media server (`84_minidlna`) | | `tryton` | TCP 8000 | Tryton clients of GNU Health (`85_gnuhealth`) | | `caddy` | TCP 8443 | Caddy's shipped site (HTTPS) | | `mosh` | UDP 60000–61000 | Incoming mosh sessions (needs `ssh` on as well) | | `syncthing` | TCP 22000, UDP 22000, UDP 21027 | Syncthing sync and local discovery | | `kdeconnect` | TCP 1714–1764, UDP 1714–1764 | KDE Connect with a phone on the LAN | | `vnc` | TCP 5900 | This desktop over VNC (`wayvnc`, which listens on 127.0.0.1 until its config or `wayvnc 0.0.0.0` says otherwise) | | `xonotic` | UDP 26000 | Hosting a Xonotic game for the LAN | How a change is applied: 1. The daemon reads which names are on by looking for each rule's exact text in `/etc/nftables.d/50-kdos-services.nft`. 2. It rewrites that file **whole** from the names that are on, as additions to the `input` chain of the `inet filter` table. It never merges, because merging means parsing nftables syntax, and a parser that got it wrong would leave a port open that the surface showed as closed. Anything you write by hand belongs in another file under `/etc/nftables.d`, which the daemon never reads or touches. The new file is renamed into place before anything checks it. 3. It runs `nft --check -f /etc/nftables.conf`. If the ruleset would not load, it answers `err the ruleset would not load; nothing changed` and the kernel keeps the previous rules, but the rewritten file stays on disk: `firewall list` then reports the requested state, and the next boot loads that file. Turning the service back to its previous state rewrites the file as it was. 4. It runs `nft -f /etc/nftables.conf`. That file deletes and rebuilds only its own `inet filter` table, so the NAT that netavark (the container network backend) sets up for rootful containers and NetworkManager's for a hotspot survive a toggle. If the load itself fails, it answers `err the ruleset did not apply`. A successful toggle answers `ok on|off`. An unknown name answers `err no service called that`; a state other than `on` or `off` answers `err a service is on or off`. ### Diagnosis and testing ```sh kdos-powerd --explain kdos-powerd --set-timezone kdos-powerd --set-autologin kdos-powerd --firewall list kdos-powerd --firewall ``` `--explain` answers "would this user be allowed, and why". It is the first thing to run when the power key or the panel's power item does nothing, because a refusal otherwise shows up only in the daemon's log. It asks `libkbase` the same question the socket asks, needs no privilege, and prints one line, for example: ```text alice: uid 1001, primary gid 1001, in seat only — permitted to suspend, power off and reboot; refused the configuration verbs ``` It exits 0 when the user is allowed anything and 1 when refused. The other flags run a verb's own rules without the socket, which is the only way to test them: the socket's check needs two different users to exercise. They grant nothing, because the binary is writing to an `/etc` the person running it could already write to. Three environment variables point them at a scratch tree: `KDOS_POWERD_ETC` replaces `/etc` (and then skips `nft` and `iw`), `KDOS_POWERD_ZONEDIR` replaces `/usr/share/zoneinfo`, and `KDOS_POWERD_SOCKET` moves the socket. ## kdos-energyd Per-application energy attribution: which application is using the processor's power. Measuring the processor's energy is routine: the kernel exposes the counter under `/sys/class/powercap`. Attribution is the hard part on an ordinary Linux desktop: an application is dozens of processes in scattered groups, and nothing owns enough of the system to name them. On KDOS every boxed application (one running in its own [box](../06-reference/glossary.md), a rootless container) runs under a known name, listed in `/usr/share/kdos/alien-apps`, so the attribution starts from an identity rather than a guess. | Verb | Answers | |---|---| | `ping` | `ok` | | `report` | The text report | | `report-json` | The same report as one JSON object | ```sh kdos-energy [--json|ping] ``` `kdos-energy` prints the report (or JSON with `--json`) and exits 0. It exits 1 when the daemon is not running or answered `err`, and 2 on bad usage. An `err` answer goes to standard error. The Energy page in `kdos-res` shows the same report, and its Boxes page shows each box's share. When the daemon is not running the client suggests `service kdos-energyd start`, which ksvc rejects as an unknown command; the command is `service start energyd` (see [Starting and stopping one by hand](#starting-and-stopping-one-by-hand)). This is the report the test fixture in `testing/fixtures/energy` produces (thirty seconds of recorded samples) when replayed with the fixture's own application table, as the test suite runs it: ```sh KDOS_ALIEN_APPS=testing/fixtures/energy/alien-apps kdos-energyd --fixture testing/fixtures/energy ``` Without that table the host's `/usr/share/kdos/alien-apps` names the processes instead, and the rows differ. ```text KDOS energy — 30 s of samples, RAPL package-0 firefox-esr (appbox kdos-apps) 75.5% ███████████████ gpu 75.0% kdos-comp 15.4% ███ gpu 25.0% gimp (appbox kdos-apps) 0.4% gpu 0.0% short-lived and exited processes 8.7% shares are of ATTRIBUTABLE energy — 57% of the package total; the rest is the idle floor idle floor 15.00 W, the lowest average power seen in 3 samples (still falling — early shares read low) an uncore domain is present, so the integrated GPU's energy is already counted the gpu column is engine TIME from drm fdinfo, never energy relative only. RAPL cannot see the panel, the radio or the disk, so there are no watt-hours here. ``` Answers go to root and `wheel` only: on a multi-user machine this list is what everyone else is running. Figures are shares, never watt-hours. The counter (Intel RAPL, read from `/sys/class/powercap`) measures the processor package. It cannot see the screen, which is the largest single draw on a laptop, nor the radio, the storage or a discrete graphics card. "This application was 41% of attributable CPU energy today" is a measurement; "this application used 12% of your battery" would be a guess presented as a unit. The daemon samples every ten seconds. The interval is fixed and not configurable, for the reason given below, and it is short enough to stay far inside the counter's wrap period. A machine that wakes from a long suspend resumes sampling from the wake rather than catching up on the missed windows. Six rules each change the answer: - Nested domains are dropped. The power interface lists a package beside that package's own sub-domains, so summing the list counts the cores twice (in the fixture, a 15 W idle floor becomes 26.25 W). A domain inside another's directory is a sub-domain and is skipped. The platform-wide `psys` domain goes the other way: it contains the packages, so where it exists it replaces them. - The counter wraps, roughly every half hour at a laptop's power draw. A naive subtraction would produce one enormous negative reading with nothing in the output saying so. The daemon reads each domain's `max_energy_range_uj` and corrects a single wrap per window. - The idle floor is subtracted before anything is attributed. A processor draws power with nothing running, and a share model that ignored this would report a machine sitting at a login prompt as 90% one process. The floor is the lowest average power seen, and it is printed with the answer; with fewer than 30 samples the report says the floor is still falling. - The floor is applied when the report is made, not per sample window. The floor can only fall, so charging each window the floor as it stood then would throw away the first window, which is usually the busiest because something has been launched. Each application carries weighted sums and the report subtracts once, with the floor as it finally stands. - The denominator is the whole system's energy, not the sum of surviving processes. A build that starts and exits inside one window is gone by the next sample, and dividing by the survivors would hand its energy to them. That difference gets its own line: *short-lived and exited processes*. - The graphics column is engine time, never energy. Nothing on the machine says what GPU time cost in joules. On integrated graphics it is already inside the package figure (the report says so when an `uncore` domain exists); on a discrete card it is outside the counter entirely, and the report says that instead. A driver that publishes no per-client statistics gets no column rather than a column of zeroes. **Why a daemon rather than a one-shot command.** The counter runs freely, so a one-shot command could only report what happened while it was watching. The counter is also readable only by root since Linux 5.10, because the PLATYPUS side-channel attack showed that fine-grained unprivileged reads can recover cryptographic keys. What leaves this daemon is a per-application percentage over minutes; the raw counter and the sampling interval are never republished, and no client can ask for a shorter interval. There is no write path into the power interface at all. The init script skips the daemon when no `/sys/class/powercap/*/energy_uj` is readable, which covers most virtual machines and every non-x86 processor. The daemon itself also refuses to start there, naming the powercap path in its log, because a daemon sampling an unreadable counter would report a machine that uses no energy, which reads as "nothing is draining the battery". `kdos doctor` tells the two cases apart: a machine with no energy domain at all, and a daemon that is not running. `kdos-energyd --fixture [--json]` replays recorded snapshots (`/0`, `/1`, … each holding a `proc` tree, a `powercap` tree and an optional `dt` in seconds) through the same sampler and report, and prints the result. `KDOS_ENERGY_PROC` and `KDOS_ENERGY_POWERCAP` point the reader at other `/proc` and powercap trees, and `KDOS_ALIEN_APPS` at another application-name table. ## kdos-oomd Kills the process that is starving the machine of memory, before the desktop freezes. The kernel has its own out-of-memory killer, but it fires when an *allocation fails*. On a machine with swap that is often minutes after the desktop stopped responding, the whole session spent thrashing while the kernel still had pages to hand out. The kernel's pressure interface (PSI, in `/proc/pressure/memory`) reports instead that the machine is *stalling* on memory, which is what a frozen desktop feels like. Boxed applications make this likely: a browser and a 3D slicer on one modest machine. ### How it decides - It waits on the kernel; it does not poll. It writes the trigger `full 150000 1000000` into the pressure file (150 ms of full stall within a one-second window, meaning every runnable thread was stuck on memory for 15% of the last second) and sleeps until the kernel signals it. A sampling loop would itself compete for processor time with the stall it is trying to notice. - The desktop is never a victim. Protected are process 1, kernel threads, the daemon itself, anything whose `oom_score_adj` is -500 or lower (the opt-out other user-space killers honour), and these by process name: `kdos-comp`, `kdos-shell`, `kdos-desk`, `kdos-notifyd`, `Xwayland`, `dbus-daemon`, `seatd`, `ksvc`, `kdos-powerd`, `kdos-energyd`, `kdos-oomd`, `wireplumber`, and every process whose name starts with `pipewire`. Killing the compositor to save the desktop is not a trade, and killing the audio session manager leaves a machine whose sound stopped for no visible reason. - A box over its declared memory budget goes first. A box profile's `memory` key is passed to the container, but a rootless container on a machine with no cgroup delegation accepts the limit and ignores it; this rule is what makes the key mean something. The daemon adds up the resident memory of each box's processes, and when a box is over its budget the largest process in that box is the victim. Budgets come from each user's own box profiles, `/home//.config/kdos/boxes/.conf`; `KDOS_BOX_PROFILES`, when set, replaces that search with one directory (the test suite uses it). - Otherwise boxed processes are preferred, but not absolutely. A boxed application is the likely culprit, is supervised, and relaunches in seconds, while a host process is more often session state. The largest boxed process is chosen when it holds at least half the resident memory of the largest eligible process overall; otherwise the largest process overall goes. An absolute preference would kill a small boxed helper while a host process many times its size kept the machine stalled. - The victim is named by its box. Identity comes from the same container-supervisor walk in `libkproc` that `kdos-res` and `kdos-energyd` use. - The memory comes back immediately. The daemon takes a handle on the process first (a pidfd, so the next step cannot land on a recycled process id), sends SIGKILL, then calls `process_mrelease` to free the victim's memory at once rather than whenever it is reaped. On a kernel without that call the release is skipped and the kill stands. - At most one scan every ten seconds. The cool-down starts when the trigger fires, not when a kill succeeds, so a trigger that finds nothing killable does not rescan every entry in `/proc` once a second on a machine that is already stalling. The daemon shields itself from the emergency it watches: at start-up it sets its own `oom_score_adj` to -1000 and locks its memory with `mlockall`. Each kill is logged with the victim and the ten-second pressure averages that caused it, in the form `kdos-oomd: killed [(appbox )] (pid , MB) — memory pressure avg10 full= some=`. ### The socket Nothing in the protocol names a process, so there is nothing to aim. The socket takes no argument and answers root, `seat` and `wheel`: | Verb | Answers | |---|---| | `ping` | `ok` | | `status` | `ok trigger 'full 150000 1000000', kills ` and, after the first kill, `, last: [(appbox )] (pid , MB)` | `kdos doctor` reports whether its socket is present. ### Testing it `kdos-oomd --fixture ` reads a recorded `/proc` tree, prints the process it would kill as `would kill … (pid , kB)` with the recorded pressure, and signals nobody. It exits 0 when there is a candidate and 1 (printing `no candidate`) when there is none. `testing/oomd-fire.sh` exercises the real path in a booted virtual machine: it allocates and touches memory until the trigger fires, then asks the socket what happened rather than watching the allocating process die (the kernel's own killer would also have got it, later). A passing run shows `status` going from `kills 0` to `kills 1, last: (pid , MB)` while the script that started the allocation keeps running; the recorded run on a 4 GB guest answered `kills 1, last: python3 (pid 1615, 3644 MB)`. That run has one large process to choose; which process the daemon picks on a busy desktop is what `--fixture` tests. ## kdos-mountd Removable media, encrypted volumes, SMART health and network shares for a desktop that is not root. udisks2 serves the natively ported toolkit applications (see [Administration](../02-user-guide/administration.md)); for the desktop's own surfaces this daemon is the whole of what stands between them and `mount`. Both read `/proc/mounts`, so a device udisks2 mounted under `/run/media/` is listed here as mounted, with its mountpoint. The client never names a path or a mountpoint. It asks for a row out of a list the daemon published, and the daemon decides the device, the mountpoint and the options. A design that takes "a path and a mountpoint" ends with someone mounting a stick over `/etc` from a shell. ### Verbs A **row** below is a number from the daemon's own `list`; a **share row** is a number from `shares`. `` is the byte length of a second frame, described under [The request format](#the-request-format). | Request | Does | Answer | |---|---|---| | `list` | The eligible devices | One row each: index, kernel name, label, filesystem, size in GiB (`28.7G`), mountpoint, tab-separated, with `-` for an empty label or mountpoint; then `ok` | | `mount ` | Mount the device | `ok `; a device already mounted answers with its mountpoint | | `unmount ` | Unmount it and remove the mountpoint the daemon made | `ok ` | | `eject ` | Power the medium down. An optical disc ejects its own drive; any other device ejects its **parent disk**, because a stop command sent to one partition means nothing to the hardware | `ok ` | | `unlock ` | Open a LUKS volume. The passphrase is the second frame | `ok kdos-` | | `close ` | Close the mapping `unlock` made | `ok kdos-` | | `format ` | Write a filesystem. **Off unless `format = yes`.** The second frame is the device's kernel name, typed by the person | `ok ` | | `smart ` | The drive's health | `ok \t\t` | | `cifs ` | Mount an SMB share. The password is the second frame | `ok ` | | `krb5 ` | Mount an SMB share with the Kerberos ticket `kinit` left in the caller's credential cache. **No second frame** | `ok ` | | `shares` | The mounted network shares | One row each: index, `//server/share`, mountpoint, tab-separated; then `ok` | | `browse` | Machines that answered an mDNS and a NetBIOS broadcast at the time of the request | One row each: `nameaddress`; then `ok` | | `disconnect ` | Unmount a network share | `ok //server/share` | | `subscribe` | Hold the connection open and write `changed` on every block-device hotplug event | `ok`, then `changed` lines; never closes | | `ping` | — | `ok` | Every verb answers root, `seat` and `wheel`: mounting a stick is the desktop user's job whether or not they administer the machine. Every failure answers `err `, for example `err unmount it first` or `err no such device`. ### The command-line client ```sh kdos-mount list kdos-mount mount kdos-mount unmount kdos-mount smart kdos-mount write kdos-mount shares kdos-mount browse kdos-mount krb5 kdos-mount ping kdos-mount subscribe ``` For example: ```sh $ kdos-mount list 0 sdb1 KDOS vfat 28.7G - 1 sdb2 backup ext4 120.0G /media/kdos/backup ok $ kdos-mount mount 0 ok /media/kdos/KDOS ``` The client prints the daemon's reply unchanged, flushing after every read so that `subscribe` can be piped into another program. | Exit status | Means | |---|---| | 0 | The daemon answered, **including when the answer was `err …`**. A script must check standard output for a leading `err` to tell a failed mount | | 2 | No `kdos-mountd` to ask (`kdos-mount: no kdos-mountd on ()`), or bad usage | The index is re-rendered as a number before it is sent, through `atoi`, so an argument that is not a number becomes row 0: `kdos-mount mount sdb1` acts on row 0 rather than being refused. `kdos-mount write ` writes an image (see [Writing an image](#writing-an-image)): it opens the image itself, as you, and prints the daemon's progress lines as they arrive. The other verbs that carry a secret (`unlock`, `format`, `cifs`), and `eject`, `close` and `disconnect`, are reached from the desktop's surfaces rather than from `kdos-mount`: | Surface | Uses | |---|---| | `kdos-devices` | `list`, `mount`, `unmount` | | `kdos-disks` | `list`, `mount`, `unmount`, `unlock`, `close`, `format` (always as `ext4`), `smart`, `write` | | `kdos-connect` | `cifs`, `krb5`, `shares`, `browse`, `disconnect` | | `kdos-mediad` | `subscribe`, `list`, `mount`, `eject` | ### The request format A request is one line, plus a second frame where a secret is involved. - **Frame one** is a verb and up to five tokens, separated by spaces or tabs, ending in a newline. The line must be shorter than 1,024 bytes (`err too long` otherwise). That ceiling is set by `cifs` alone: a DNS name may be 253 bytes, a share 80, a username 104 and an NT domain 255, so a legal corporate share spells a request of about seven hundred. - **Frame two** is exactly the number of bytes frame one's last token declared, from 1 to 512. A passphrase travels as a frame and not a token because the tokeniser splits on spaces and a passphrase may contain them. A connection that closes before the whole frame arrives is answered `err short frame`. - **A descriptor** rides on frame one for `write` only: the image, attached as `SCM_RIGHTS`. The daemon reads frame one with `recvmsg` so the descriptor is not lost, keeps at most one, and closes one that arrives with any other verb before it looks at the verb. Every token is checked before it means anything, and the token count is fixed per verb: - A row is one to three digits and must be inside the list the daemon has published for this request. - A count is one to four digits and between 1 and 512. A bad row or count on a two-frame verb answers `err bad request`. - A trailing token nobody asked for makes the request unknown (`err unknown command`) rather than ignored. A dispatcher that read an index and discarded the rest would accept `mount 0 rm -rf /` as a well-formed mount. - A line with eight or more tokens is refused as `err too many arguments`. The device list is rescanned on every request rather than cached, so a stick pulled out between two requests is never still offered. ### Which devices are offered The daemon walks `/sys/block`, ignoring `loop`, `ram`, `zram` and `dm-` devices, and considers each partition of a disk, and the whole disk when none of its partitions qualifies (a stick formatted without a partition table is the usual case). A device appears in `list` only if every one of these holds: | Rule | Why | |---|---| | Its disk is removable, or is on USB | An internal disk is the administrator's. An external drive in a USB enclosure reports itself as non-removable, so the bus is checked too | | It carries a filesystem the daemon recognises | See the list below | | It is not named in `/etc/fstab`, by device path or by `LABEL=` | An entry there is a decision somebody already made | | It is not the medium this system booted from | Offering to unmount the live medium is offering to end the session | A device that is already mounted is listed, with its mountpoint in the last column. The boot medium is a device mounted at `/`, `/mnt/iso` or `/boot`, and in a live session (root on an overlay) any ISO 9660 medium. The live ISO does not appear in the running system's `/proc/mounts` at all, because the initramfs moved the root out from under those mounts, so this broad rule is the only reliable one; the cost is that a second data CD cannot be mounted while running live. The label and filesystem type are read directly from the superblock rather than through a detection library. The daemon recognises, in this order: | On disk | Reported as | |---|---| | LUKS (checked first, because a LUKS header written over an old filesystem still carries that filesystem's superblock) | `crypto_LUKS` | | ext2, ext3, ext4 | `ext4` | | FAT12/16/32 | `vfat` | | NTFS | `ntfs3` | | exFAT | `exfat` | | ISO 9660 | `iso9660` | | btrfs | `btrfs` | **Kernel support is checked at mount time.** Before calling `mount(2)`, the daemon checks the type against `/proc/filesystems` and answers `err this kernel cannot mount ` when the driver is missing, instead of failing halfway. **Mount options.** `nosuid` and `nodev` always; `noexec` unless `exec = yes` is set in `/etc/kdos/mountd.conf`. A setuid-root binary on somebody else's stick is a local root hole, so executing from removable media is something you opt into. FAT, exFAT and NTFS have no ownership of their own, so they are mounted with `uid=` and `gid=` set to the caller and `fmask=0117,dmask=0007`; on a native filesystem the mountpoint itself is given to the caller. **The mountpoint** is `/media//