# lemurs

The login manager as a module (novox/hq ADR 0208, research 026, to-be 42 phase 2, step 3).

- **Claims `node-login-manager`** and serves its verb `sessions`.
- **Package `lemurs`**, from the official repositories. It replaces the user repository's
  `lemurs-git` that both workstations run.
- **Service `lemurs.service`, enabled at boot and running.** It is its own `display-manager.service`
  alias. It declares no restart or reload trigger, so a push starts it only where it is not running
  and never restarts it, because restarting it ends the session it started. (A state is required:
  the host refuses `boot` on a service that leaves its state to the machine.) A change to its configuration applies at its next
  start (a reboot).
- **Gated by `package-manager`, `service-manager` and `seat`.** A machine without a display has
  nothing to log into.

## What it owns

| path | class | what |
|---|---|---|
| `/etc/lemurs/config.toml` | owned (the found file is kept once, ADR 0102) | lemurs 0.4's configuration in its current format: the structure of the shipped file, every option present, as lemurs requires. The source is [`config/config.toml`](config/config.toml), carried whole in the manifest |
| `/etc/lemurs/xsessions/`, `/etc/lemurs/wayland-sessions/` | owned, empty | where the configuration points lemurs for desktop entries, so none is offered |

**Sessions are drop-ins.** The sessions offered are the executable files session modules place in
`/etc/lemurs/wms/` (X) and `/etc/lemurs/wayland/` (Wayland). The file's name is the session's name.
`i3` places `/etc/lemurs/wms/i3`, and `sway` will place its own in `wayland/`. The desktop entries
packages install (`/usr/share/xsessions/i3.desktop`, `i3-with-shmlog.desktop`) are no longer offered.
They start the window manager bare, skipping `~/.xinitrc`, which holds the environment, the
resources and every module's session lines. Today the workstations log in through exactly such an
entry (`i3`). It reaches the session's start only because `~/.xprofile` sources `~/.xinitrc`.

**What the configuration changes** from the shipped file, each marked `mesh:` in it:

- the two desktop-entry directories, as above;
- `switcher_visibility = "F3"`. The session switcher stays hidden as today, and F3 shows it once a
  second session (sway) exists.

Everything else is lemurs's default, which is also what runs today: X on `:1`, tty 2, the cache in
`/var/cache/lemurs`, `remember = true`. The workstations' current file is two releases old. The
running `lemurs-git` ignores its X keys and uses these defaults already, which is why X is on `:1`
although the file says `:0`.

## Tools

| tool | | what |
|---|---|---|
| `node-login-manager.sessions` | r | each session offered: name, X11 or Wayland, script or desktop entry, the file and what it runs, whether lemurs can run it (a script that is not executable is skipped); the default session and account from the cache |
| `lemurs_default_session` | r/a | the preselected session; set it to one that is offered. It writes the cache through `sudo -n`, and shows when lemurs next starts |
| `lemurs_logins` | r | logins from the journal (opened, closed, failed passwords), and which entry lemurs started each session with (its own log) |

None needs the graphical session.

## What it improves

- the official package instead of a `-git` build from the user repository;
- the configuration in the format the binary reads. Today's file is mostly ignored, and the unmerged
  `.pacnew` sits beside it;
- one session per session module, each starting through the session's start, and no bare desktop
  entries;
- a dead entry gone: `/etc/lemurs/wms/i3wm` (`exec startx`) would start a second X server inside
  the one lemurs started.

## What it leaves found

- `/etc/lemurs/xsetup.sh`, the package's;
- `/etc/pam.d/lemurs`, the package's (it unlocks the login keyring through `pam_gnome_keyring`);
- `/var/cache/lemurs`, lemurs's own.

## The one-off migration (ADR 0182)

1. **Replace the package by hand, once per workstation, at a moment you choose:**
   `sudo pacman -S lemurs`, answering yes to removing `lemurs-git` (and `lemurs-git-debug` on the
   laptop). The host cannot do this. `pacman -Q lemurs` answers with `lemurs-git`, which provides
   `lemurs`, so the declared package already reads as installed. A non-interactive install would
   also refuse the conflict. The binary is replaced on disk, and the running login manager keeps
   running the old one until the next boot.
2. **Delete `/etc/lemurs/config.toml.pacnew`.** The module's file is that structure.
3. **Delete `/etc/lemurs/wms/i3wm`** once `i3` is assigned and `/etc/lemurs/wms/i3` exists.
4. **Delete `~/.xprofile`**, or its `. ~/.xinitrc` line (see `xorg`'s README). Until then the X setup
   runs `~/.xinitrc` from `.xprofile` before it reaches the session's entry. That still works, once.

Steps 1, 2 and 3 are harmless in any order. Step 4 waits for `i3`.

## What changes when it is assigned

| | g14 | shanks |
|---|---|---|
| package | nothing until step 1 (`lemurs-git` reads as installed) | the same |
| `/etc/lemurs/config.toml` | the found file kept once, then the module's written | the same |
| `/etc/lemurs/xsessions/`, `wayland-sessions/` | created, empty | the same |
| `lemurs.service` | already enabled: nothing | the same |
| the running login manager and session | **nothing** | **nothing** |
| next boot | the login screen offers `i3wm` until step 3, and `i3` once the `i3` module is assigned. It no longer offers the two desktop entries. The remembered session `i3` matches the `i3` module's entry by name | the same |

**Order matters at one point:** assign `i3` before the next reboot after `lemurs`. Otherwise the
screen offers only `i3wm`, which runs `startx` inside lemurs's own X server and fails. Assigned in
to-be 42's order (`xorg`, `lemurs`, `i3` in one sitting), this cannot happen.

## Blockers

- **The package swap is a person's act** (step 1). The host's package resource cannot replace a
  package that provides the same name.
- **No restart, by design.** A configuration change takes a reboot to show.

## The X server never resets (added 2026-10-04)

lemurs starts the server through `/etc/lemurs/xserver`, which adds `-noreset`. Without it, X resets
whenever its last client disconnects, and a reset empties the resource database. The session's start
merges the X resources before any long-lived client connects. On the first login with these modules,
the server reset twice within four seconds: the X log showed three server generations. xterm fell
back to the bitmap `fixed` font, without the mesh's face and colours. lemurs reads its configuration
when it starts, so the change applies after the next boot.