latchd/docs/configuration.md

# Configuration reference

Latchd uses `/etc/latchd/config.toml` as its service configuration.
The complete example is [`../extra/config.toml`](../extra/config.toml). Copy it to the main file, then change the required values.

## Command-line overrides

These command-line options replace selected values for one run:

| Option | Field changed |
| --- | --- |
| `--tty N` | `tty` |
| `--xsessions PATH` | `x11.sessions_path` |
| `--wlsessions PATH` | `wayland.sessions_path` |
| `--initial-path PATHS` | `initial_path` |

Use these options for a one-time test. Put permanent values in the main file.

## Top-level fields

| Field | Default | Description |
| --- | --- | --- |
| `tty` | `2` | Virtual terminal number. Valid values are `1` through `63`. |
| `main_log_path` | `/var/log/latchd.log` | Main service log. |
| `client_log_path` | `/var/log/latchd.client.log` | Output log for graphical session clients. |
| `pam_service` | `latchd` | Name of the PAM service file in `/etc/pam.d/`. |
| `system_shell` | `/bin/sh` | Shell used by the TTY session and the preflight check. |
| `initial_path` | `/usr/local/sbin:/usr/local/bin:/usr/bin` | Absolute directories used to resolve session programs. |

The path fields in this table must be absolute. `initial_path` must contain only non-empty absolute directories separated by colons.

## `[x11]`

The X server starts only when the selected session has kind `X11`.

| Field | Default | Description |
| --- | --- | --- |
| `display` | `:1` | X display name passed to Xorg and the session. |
| `server_path` | `/usr/bin/X` | X server executable. |
| `xauth_path` | `/usr/bin/xauth` | Program that writes the temporary Xauthority file. |
| `server_timeout_secs` | `60` | Maximum wait for the X server readiness signal. |
| `server_log_path` | `/var/log/latchd.xorg.log` | X server log. |
| `sessions_path` | `/usr/share/xsessions` | Directory with X11 `.desktop` files. |
| `scripts_path` | `/etc/latchd/wms` | Directory with administrator X11 session scripts. |

Set absolute paths for the X server and `xauth`. Latchd passes `display`, `vtN`, and the authority file to Xorg.

## `[wayland]`

| Field | Default | Description |
| --- | --- | --- |
| `sessions_path` | `/usr/share/wayland-sessions` | Directory with Wayland `.desktop` files. |
| `scripts_path` | `/etc/latchd/wayland` | Directory with administrator Wayland session scripts. |

The selected Wayland program starts with these values; latchd does not start a compositor or create a Wayland socket.

## `[environment_switcher]`

| Field | Default | Description |
| --- | --- | --- |
| `include_tty_shell` | `false` | Add the TTY shell when graphical sessions exist. |
| `max_display_length` | `18` | Maximum display width used for session titles. Must be greater than zero. |
| `remember_last_session` | `true` | Remember the last successful session for each account. |
| `last_session_path` | `/var/lib/latchd/last-session.toml` | File for the saved session preference. |

The preference file stores a session kind and title for each account; it holds at most 128 entries, writes a synced temporary file, and renames it into place. The file and its parent directory must belong to the account that runs latchd and must not be writable by group or other users.

Set `remember_last_session = false` to disable reads and writes; latchd ignores the path in that case.

## `[accounts]`

| Field | Default | Description |
| --- | --- | --- |
| `minimum_uid` | `1000` | Lowest UID that account enumeration includes. |
| `excluded_users` | `[]` | Usernames that account enumeration skips. |
| `enumerate` | `true` | Discover accounts through NSS for the account list. |
| `faillock_path` | `/usr/sbin/faillock` | Faillock helper executable. |
| `faillock_config` | `/etc/security/faillock.conf` | File from which Latchd reads the `deny` value. |
| `shadow_path` | `/etc/shadow` | Shadow file used for account status display. |

Account enumeration also requires an absolute login shell and a safe home directory; `/bin/false`, `/usr/sbin/nologin`, and `/sbin/nologin` are excluded.

Latchd reads the shadow file only when it is a root-owned, non-writable regular file. The screen can show these states:

- `Locked` when the password hash starts with `!` or `*`;
- `PasswordExpired` when the last-change day is zero or the maximum age passed;
- `AccountExpired` when the account expiry day passed;
- `AccountInactive` when the inactive period passed;
- `NoLoginShell` when the shell does not permit login;
- `Unknown` when shadow data is not available.

The faillock check only adds status text. The helper runs:

```text
faillock --user USERNAME --legacy-output
```

The query stops after 750 milliseconds. Bad output, a missing helper, or a timeout removes the faillock status from the screen.

## `[visual]`

| Field | Default | Description |
| --- | --- | --- |
| `wallpaper_path` | not set | Optional PNG or JPEG file for the TUI background. |
| `background_enabled` | `true` | Draw the wallpaper and ambient background. |
| `animations` | `true` | Update the ambient cellular animation. |
| `notifications` | `true` | Show short status notices in the TUI. |
| `reduced_motion` | `false` | Start with the ambient animation disabled. |
| `max_wallpaper_bytes` | `8388608` | Maximum wallpaper file size. Valid range is 1 to 67108864 bytes. |

The wallpaper path must be absolute, and the file must be root-owned, regular, and not group-writable or other-writable. Source images are limited to 8192 by 8192 pixels and 16,777,216 pixels total, then scaled for the terminal.

The TUI also caps the animation state at 160 columns by 64 rows. Press `Ctrl-B` to toggle the background. Press `Ctrl-M` to toggle reduced motion.

## `[power_controls]`

Power actions are disabled in preview mode. Each action needs an absolute program path and a function-key label:

```toml
[[power_controls.entries]]
key = "F1"
hint = "Power off"
program = "/usr/bin/systemctl"
args = ["poweroff"]
```

`key` must be `F1` through `F12`, and `hint` must not be empty; `program` starts directly with `args`, without a shell, after the TUI asks for confirmation.

## Desktop entry rules

Only the `[Desktop Entry]` section is read, with these keys:

| Key | Use |
| --- | --- |
| `Name` | Session title. |
| `Type` | Must be `Application` when present. |
| `Hidden` | `true` hides the entry. |
| `NoDisplay` | `true` hides the entry. |
| `TryExec` | Optional executable check. |
| `Exec` | Program and arguments. |
| `DesktopNames` | Values for `XDG_CURRENT_DESKTOP` and `XDG_SESSION_DESKTOP`. |

Plain and quoted arguments are accepted; desktop field codes such as `%u` and `%f`, plus shell syntax, are rejected.

## Validation failures

The parser rejects unknown fields. The validator rejects these common errors:

- a virtual terminal outside `1` through `63`;
- an empty PAM service name;
- an empty path or a relative directory in `initial_path`;
- a relative path in a required absolute-path field;
- a zero session title width;
- a relative last-session path when preferences are enabled;
- a zero or oversized wallpaper limit;
- an empty X display or zero X server timeout;
- an invalid power-action key, label, or program path.

Use `--preview --no-tui` to report these errors without starting the screen.