1# NeferAFK
2
3NeferAFK is an idle daemon for Wayland compositors. It fades the screen, locks the session, turns the outputs off and suspends the machine after configurable idle delays.
4
5It uses standard protocols only: `ext-idle-notify-v1`, `ext-session-lock-v1`, `wlr-output-power-management-v1` and systemd-logind. The lock screen renders with [NeferGUI](https://github.com/bnema/nefergui) (Vulkan, DMA-BUF, explicit sync).
6
7## Behaviour
8
9- Four independent actions: fade, lock, screens off and sleep. Each has its own delay, counted from the last input. Set a delay to `off` to disable the action.
10- Input undoes the fade and turns the screens back on. It never unlocks: only a successful authentication does.
11- When the system is about to sleep (lid, menu, `systemctl suspend`), NeferAFK holds the suspend until the lock is confirmed.
12- If the machine cannot suspend (for example, a sleep inhibitor is active), fade, lock and screens off still run and the sleep action is skipped with a warning.
13- Typed secrets go from the lock screen straight to an isolated authentication process. They never pass through the daemon.
14
15## Requirements
16
17- Linux with systemd-logind.
18- A compositor that advertises `ext_idle_notifier_v1` (v2), `ext_session_lock_manager_v1`, `zwp_linux_dmabuf_v1` (v4), `wp_linux_drm_syncobj_manager_v1`, and `zwlr_output_power_manager_v1` when screens off is enabled.
19- Password mode needs a PAM service file, `/etc/pam.d/neferafk`. The Arch package installs it; otherwise create it with:
20
21  ```
22  auth include login
23  ```
24
25## Install
26
27On Arch Linux, install from the AUR:
28
29```sh
30paru -S neferafk-bin   # latest release, pre-built
31paru -S neferafk-git   # latest main, built from source
32```
33
34Pre-built archives are on the [releases page](https://github.com/bnema/neferafk/releases). To build from a checkout:
35
36```sh
37CGO_ENABLED=0 go build -o bin/neferafk ./cmd/neferafk   # builds bin/neferafk
38make pkg                                               # builds an Arch package of HEAD into dist/
39make install                                           # builds that package and installs it with pacman
40```
41
42The packages install `/etc/pam.d/neferafk` for password mode.
43
44## Usage
45
46```
47neferafk run [--config FILE]   run the daemon
48neferafk lock                  lock now
49neferafk status                print the daemon state
50neferafk validate-config FILE  check a configuration file
51neferafk version               print the version
52```
53
54Start `neferafk run` from your compositor's startup. The daemon writes its log to `$XDG_STATE_HOME/neferafk/logs/daemon.log` (default `~/.local/state/neferafk/logs/daemon.log`).
55
56## Configuration
57
58The file is `$XDG_CONFIG_HOME/neferafk/config` (default `~/.config/neferafk/config`); `examples/config` is a commented starting point. It uses flat `key = value` lines, and `#` starts a comment. Changes are applied live. Two cases need a daemon restart: enabling screens off, and enabling lock or sleep when both were off at startup.
59
60```
61fade.after = 6m
62fade.duration = 2s
63lock.after = 5m
64screens.off-after = 7m
65sleep.after = 20m
66auth.mode = password
67```
68
69| Key | Values | Default |
70|---|---|---|
71| `fade.after` | duration or `off` | `6m` |
72| `fade.duration` | duration | `2s` |
73| `lock.after` | duration or `off` | `5m` |
74| `screens.off-after` | duration or `off` | `7m` |
75| `sleep.after` | duration or `off` | `20m` |
76| `auth.mode` | `password` or `pin` | `password` |
77| `auth.pin-source` | `env` or `pass` | none |
78| `auth.pin-env` | environment variable name (with `env`) | none |
79| `auth.pin-entry` | `pass` entry (with `pass`) | none |
80
81Durations use Go syntax (`30s`, `5m`, `1h`), up to 24h. The order of the actions comes from their delays: for example, `lock.after = 20s` with `screens.off-after = 50s` turns the screens off 30 seconds after the lock.
82
83PIN mode compares a 6 to 32 digit PIN read from the daemon's environment or from `pass show ENTRY`. If the PIN source is unavailable or invalid, the lock asks for the password through PAM.
84
85With the defaults, the lock comes first and the fade then darkens the lock screen before the screens go off. Set `fade.after` below `lock.after` to fade before locking.
86
87## Development
88
89```sh
90make check        # build, vet, tests, handwritten-double check, staticcheck
91make race         # race tests (CGO_ENABLED=1)
92make mocks-check  # Mockery v3 mocks are up to date
93```
94
95## License
96
97[GNU GPL v3](LICENSE).