Command-line tools for maintainers of the Bentoo Gentoo overlay: keep its ebuilds current with upstream, validate every bump before it ships, publish notices, and protect the machine with btrfs snapshots.
| Command | What for |
|---|---|
bentoo overlay |
The overlay's git workflow (status, add, commit with a generated message, push, pull), compare against ::gentoo, prune what ::gentoo already ships identically, manifest, rename |
bentoo overlay autoupdate |
Read each package's upstream version (--check), prove the bump in a staged tree (--check --llm), then publish what was proven (--apply); packages.toml says where each version is read |
bentoo overlay validate |
Check that an ebuild still matches the source it points at, on a ladder of depths from build options to a full install |
bentoo distfile fetch |
Download a distfile Portage cannot fetch by itself (behind a registration form or a POST) into DISTDIR |
bentoo notice |
Write a notice once, as a GLEP 42 news item in the overlay and an entry in the website's feed |
bentoo snapshot |
Declarative btrfs snapshots: btrbk and snapper, cloud copies with restic or rclone, systemd timers, rollback |
bentoo-tray |
A desktop notifier that announces the notices that concern the packages you have installed, and warns when disk space, memory, CPU or the network degrade |
Add the Bentoo overlay, then install the packages:
eselect repository add bentoo git https://github.com/obentoo/bentoo.git
emerge --sync bentoo
emerge --ask app-portage/bentoolkit # bentoo
emerge --ask app-portage/bentoo-tray # optional: the desktop notifierOr build from source. Go comes from the toolchain line in go.mod, which
go downloads on first use:
git clone https://github.com/obentoo/bentoolkit.git
cd bentoolkit
make build # build/bentoo and build/bentoo-tray
sudo make install # into /usr/local, with the tray's desktop entry and user unitBuilds are reproducible: -trimpath, and a build date taken from
SOURCE_DATE_EPOCH or the last commit.
make install-config # or copy config.example.yaml to ~/.config/bentoo/config.yaml
$EDITOR ~/.config/bentoo/config.yaml # set overlay.path to your checkout
bentoo overlay status # what changed in the overlay
bentoo overlay autoupdate --check # which packages have a newer upstream
bentoo overlay autoupdate --check --llm # prove each one in a staged tree
bentoo overlay autoupdate --apply all # publish what the check provedbentoo --help lists every command, and bentoo <command> --help explains one.
Secrets (API tokens) never go in the config file; see
Configuration.
Besides notices, bentoo-tray watches the machine it runs on and raises a
desktop notification when something degrades that would break or stall an
emerge. A reading must stay bad for the monitor's sustain window before it
notifies, so a short spike stays silent. Every monitor is on by default.
| Monitor | Watches | Warning | Critical | Default sustain |
|---|---|---|---|---|
| disk | /, PORTAGE_TMPDIR and DISTDIR, as portageq envvar PORTAGE_TMPDIR and portageq distdir report them at startup |
under 10% free AND under 20 GiB free | under 2% free OR under 2 GiB free | 1 min |
| memory | MemAvailable in /proc/meminfo, and /proc/pressure/memory |
under 10% of RAM available | under 5% available with no swap or under 10% of swap free, or full avg60 memory pressure at 10 or more |
2 min |
| cpu | some avg60 in /proc/pressure/cpu |
80 or more | never | 5 min |
| network | NetworkManager's connectivity on the system bus | "Network down" after 30 s offline (60 s when the tray starts offline); "Network back" after 10 s online | never | - |
| emerge | /var/log/emerge.log, read from where it was when the tray started |
a build that started and did not complete before an unsuccessful exit, naming the package and its build.log when it still exists |
never | - |
| units | failed systemd units of the system manager and of your session's manager, through D-Bus | a unit entering failed, and every unit already failed when the tray starts |
never | - |
| readonly | /proc/self/mountinfo, every block-device filesystem (/dev/...; not tmpfs, squashfs, overlay, network, FUSE or ISO) |
never | a filesystem seen read-write that is now read-only (the kernel's reaction to an I/O error) | - |
| smart | udisks2's SMART verdict for every drive, on the system bus | never | an ATA drive reporting itself failing, or an NVMe drive with a critical warning (spare, temperature, degraded, read-only...) | - |
| updates | emerge --pretend --update --deep --newuse --quiet @world, run by the update check |
never (a low-urgency notice naming the count and the first packages; "@world does not resolve" when emerge exits non-zero) | never | - |
| glsa | glsa-check --list affected --nocolor (app-portage/gentoolkit), run by the update check before @world |
a GLSA that applies to an installed package, naming its id, title and atoms | never | - |
| sync | every repository in repos.conf with a sync-uri: the newest of metadata/timestamp.chk and .git/FETCH_HEAD |
not synced for more than sync.max_age (7 days), naming the repository and the whole days |
never | - |
How an alert behaves:
- Free disk space is the space an unprivileged user can write (root's reserved blocks do not count). Paths on the same filesystem are announced once, under the first path. On btrfs the kernel's free figure is an estimate.
- CPU pressure is ignored while an
emergeruns: a build is expected to saturate the CPU. Disk and memory are still watched during a build. - One notification per problem. A later notification for the same problem
replaces the earlier one instead of stacking. A warning is sent once; a
critical alert is sent at once (also when a warning gets worse) and
repeated every
reminder(1 h) while it lasts. Falling back from critical to warning sends nothing. - Recovery is quiet. A disk, memory or CPU alert clears only when the
reading stays 20% past its threshold for the sustain window (CPU: below
clear_psi, 70); its notification is then withdrawn. "Network back" is sent only after a "Network down" was shown, and replaces it. - Pause (tray menu) silences warnings, the updates notice and network notifications, never critical alerts. A warning or notice raised during a pause is not sent when it ends; its tooltip line stays.
- The icon asks for attention, and turns to its critical variant for a
critical alert, while any alert is active; the tooltip lists one line per
alert (GNOME's AppIndicator extension shows no tooltip). Alerts never enter
the notices menu, the unread count or
state.json, and "Mark all as read" leaves them alone. Clicking an alert's notification opens nothing. - Nothing is kept across restarts: after a restart a problem still present is announced again once its sustain window has passed.
- Errors notify at once (emerge, units, readonly, smart have no sustain window). A failed emerge clears when a later emerge ends successfully or the failed package completes; Ctrl+C and dependency failures, which you already saw in the terminal, never notify. Failed units share one notification, replaced by each new failure and withdrawn when the last unit recovers. A read-only filesystem clears when it is read-write again or unmounted; a failing drive when its SMART verdict is healthy again or it is removed.
- Pending updates are a notice, not an alert: a low-urgency notification and a tooltip line, no attention icon, never repeated. It is replaced only when the set of packages changes and withdrawn when nothing is left. A GLSA or a stale repository is a warning; all GLSAs share one notification, withdrawn when the last one clears.
- The update check runs after every sync (
/var/lib/portage/repo_revisionschanged), 5 minutes after start, and after each successfulemerge(needs the emerge monitor). Never during anemerge: it waits until none runs. - It costs about 50 s of CPU for
@world, at niceness 19 with the idle I/O class, in its own process group.@worldis killed after 10 min andglsa-checkafter 2 min (one WARN, state kept); Quit kills a running check.
Configure them under tray.monitors in ~/.config/bentoo/config.yaml;
config.example.yaml lists the same keys with their
defaults. Keys under tray.monitors:
| Key | Default | Meaning |
|---|---|---|
sample_interval |
30s |
time between two readings; minimum 10s |
reminder |
1h |
how often a critical alert repeats; minimum 15m |
disk.enabled |
true |
watch free disk space |
disk.paths |
[] |
the paths to watch; empty means /, PORTAGE_TMPDIR and DISTDIR. A configured list replaces the defaults |
disk.warn_percent |
10 |
warning under this percentage free AND under disk.warn_free |
disk.warn_free |
20GiB |
see disk.warn_percent |
disk.crit_percent |
2 |
critical under this percentage free OR under disk.crit_free |
disk.crit_free |
2GiB |
see disk.crit_percent |
disk.sustain |
1m |
how long a disk reading must last |
memory.enabled |
true |
watch memory |
memory.warn_percent |
10 |
warning under this percentage of RAM available |
memory.crit_percent |
5 |
critical under this percentage available, with swap absent or under memory.crit_swap_percent free |
memory.crit_swap_percent |
10 |
see memory.crit_percent |
memory.psi_full_crit |
10.0 |
critical when memory pressure full avg60 reaches this |
memory.sustain |
2m |
how long a memory reading must last |
cpu.enabled |
true |
watch CPU pressure |
cpu.warn_psi |
80.0 |
warning when CPU pressure some avg60 reaches this |
cpu.clear_psi |
70.0 |
the alert clears below this; it must be below cpu.warn_psi. With cpu.warn_psi at 70 or less the default is cpu.warn_psi x 70/80 |
cpu.sustain |
5m |
how long a CPU reading must last |
network.enabled |
true |
watch connectivity |
network.down_after |
30s |
offline this long sends "Network down" |
network.down_after_startup |
60s |
the same, when the tray starts offline |
network.back_after |
10s |
online this long, after a "Network down", sends "Network back" |
emerge.enabled |
true |
announce failed emerge builds (block tray.monitors.emerge) |
emerge.log |
/var/log/emerge.log |
the emerge log to follow; an absolute path |
units.enabled |
true |
announce failed systemd units (block tray.monitors.units) |
units.system |
true |
watch the system manager |
units.user |
true |
watch your session's manager (systemd --user) |
readonly.enabled |
true |
announce read-only remounts (block tray.monitors.readonly) |
smart.enabled |
true |
announce failing drives through udisks2 (block tray.monitors.smart) |
updates.enabled |
true |
announce pending @world updates (block tray.monitors.updates) |
glsa.enabled |
true |
announce applicable GLSAs (block tray.monitors.glsa) |
sync.enabled |
true |
announce repositories not synced recently (block tray.monitors.sync) |
sync.max_age |
168h |
a repository not synced for longer than this is stale; minimum 24h |
Percentages are 0-100, sizes whole KiB, MiB, GiB or TiB, durations
like 30s, 2m or 1h (0 is accepted, a negative value is not). A bad or
out-of-range value logs a WARN naming the key and uses its default; an unknown
key logs a WARN and the tray still starts. For example, to watch /home too
and turn the CPU monitor off:
tray:
monitors:
disk:
paths: [/, /var/tmp, /var/cache/distfiles, /home]
cpu:
enabled: falseLimits worth knowing:
/homeis not watched by default: KDE Plasma (freespacenotifier) and GNOME (gsd-housekeeping) already warn about it. Add it todisk.pathsif you want it here too.- With
/procmountedhidepid=2(check withfindmnt -no OPTIONS /proc), the tray sees only your own processes.emergeruns as root, so it cannot see a build, and the CPU monitor is no longer silent during one. Disablecpu.enabledon such a host if that is noisy. - No NetworkManager, no network monitor: the tray logs one INFO line at startup and sends no network notification.
- No pressure stall information (a kernel without PSI, so no
/proc/pressure/cpu): the CPU monitor turns itself off with one INFO line; the memory monitor uses/proc/meminfoalone. - The emerge log is read through the
portagegroup (it isportage:portage 0660): outside that group the tray logs one WARN and keeps retrying. emerge.log carries no process id, so with two emerge runs at once, or after an emerge killed without its closing line, a failure may name the other run's package until that package completes. - ATA SMART needs
sys-fs/udisks[smart]andsys-libs/libblockdev[smart]: without them udisks2 reports SMART as unsupported and no ATA failure is announced. NVMe health needs udisks2 2.10 or later. Without udisks2 the monitor turns itself off with one INFO line. - No systemd (or no
systemd --user): that manager is not watched, with one INFO line at startup. - No
glsa-check(app-portage/gentoolkit): the GLSA monitor turns off with one INFO line; noemerge, the updates monitor with one WARN. - A repository with neither
metadata/timestamp.chknor.git/FETCH_HEADis skipped with one INFO line.repos.confis read once, at startup. - The shared GLSA notification names the last GLSA raised, even after that one clears while another still applies.
- Not covered: inode exhaustion, the write state of network, FUSE or image filesystems, drive attribute details and self-tests, OpenRC services, which process uses the memory, temperature, battery, network quality.
- Configuration: the config file, the secrets file and logging
- Overlay commands: from status to prune, with a typical workflow
- Autoupdate:
packages.toml, the record model and the LLM providers - Distfiles: gated distfiles, and where updates download them
- Notices: one notice as a news item and a site entry
- Snapshots: btrbk, snapper, cloud copies and rollback
- Desktop notifications: installing and configuring
bentoo-tray - Runtime behaviour: exit codes, live output, concurrency and timeouts
- Shell safety guards: the confirmation code before destructive commands
- Development: the checks, the local CI gate and the project layout
- Architecture: how the code is put together, and why
See CONTRIBUTING.md. In short: make check while you work
(make test for the tests alone), then ./scripts/ci-vm-gate.sh, which runs
the whole CI (tests, linters, CodeQL, scanners) on a clean checkout in a local
VM.
Report security problems privately, as SECURITY.md describes.
MIT. See LICENSE.