synguard: how to actually set up the BPF-LSM gate
The enforcement section said the gate exists and what it cannot do, but not
how to turn it on. Adds the operator path, in the order someone has to do it.
- Confirm the kernel offers it: 'bpf' must appear in
/sys/kernel/security/lsm (stock Arch has it), and it is LAST in that list
on purpose — additive only.
- Nothing ships armed: 55 rules, zero deny or quarantine verdicts. As
installed synguard detects and alerts, it does not kill.
- Which rules can lower, as a table. There is no fnmatch in a BPF program,
so a pattern is an exact string or a prefix and synguard refuses anything
else rather than approximating. Plus the ordering constraint that will
bite first: first-match-wins means a deny rule only lowers when synguard
can PROVE no earlier rule matches the same input, and the stock base rules
open with allows at priority 1.
- The exec gotcha: 'comm' is the process CALLING execve, not the binary
being run, because the kernel has not installed the new name at that hook.
- Arming is a separate decision from loading — the drop-in for
--bpf-enforce, and what a loaded-but-unarmed rule looks like.
- The five distinct bpf-lsm log lines, so each outcome is greppable.
- The way out: synapse.bpf_enforce=0 on the kernel command line, plus the
30s warmup and the fail-open-on-crash behaviour that make a bad rule
survivable.
- Points at /etc/synguard/rules.d/40-enforce.rules.example for the
long-form version, which ships on the system and parses as nothing until
it is copied to .rules.
Every flag, hook name, kernel parameter and log string checked against the
source; the rule count and the zero-deny claim recounted rather than copied.
Document the installer rebuild, synguard enforcement, and kitty
The wiki stopped at 2026-07-28 and the whole synguard-to-now range was
undocumented. Installation.md still described a single ext4-and-GRUB
installer that no longer exists.
Installation — install modes now include ADVANCED (partition it yourself,
then name the partitions), plus the filesystem table, the bootloader table
and what each implies for the ESP, snapshots, swap and zram. Marked with
what is actually published: 0.2.4 has ERASE/ALONGSIDE only, everything else
is on main and needs a self-built ISO.
synguard — the enforcement model had no page anywhere. Adds the two paths
(post-hoc SIGKILL vs the in-kernel BPF-LSM gate) and why they are not
equivalent, the mode/flag split, the four things the gate cannot do, the
two cases where a DENY stands down, how to read the stats line, and how to
test a deny rule without killing your own session.
synsh — kitty is the default terminal; foot is kept as the CPU-rendered
rescue. Includes the dynamic_background_opacity trap, which cannot be fixed
after the fact. Terminal references updated across Commands, synui,
Window-Effects and Gaming.
Development Notes — five new entries, all from silent failures: systemd
dependency lists are additive-only so a drop-in cannot remove one;
socket-activated services resurrect a daemon you stopped, over the network;
an indented heredoc terminator swallows code while bash -n passes; a prompt
after a long step answers itself from typeahead; grep -q in a pipeline under
pipefail makes "must be absent" checks pass vacuously.
Make Troubleshooting a user's page; move the engineering history out
Troubleshooting had become a development changelog — bugs *we* hit, told as
history, with commit hashes and the internal test rigs used to find them. That
is not what someone reaches for when their machine is misbehaving, and a lot of
it described one particular machine rather than the system.
Troubleshooting is now symptom-first and about the reader's computer: no sound
from event sounds, an installed cursor theme that won't appear, a giant pointer
in one app, the bar gone, a widget eating clicks, games on the wrong monitor,
black screen after suspend, being locked out with no VT, pacman 404s, a module
that won't load after a kernel upgrade, the AI not answering, Secure Boot
enrollment, a LUKS header you didn't back up. Each entry says what to run.
The engineering material moves to a new Development-Notes page, which keeps the
generalisable rules — a commit is not an install, dkms status is not a health
check, /etc units shadow /usr/lib ones, signal dispositions survive exec,
tightening a check must handle the values already sitting on the wrong side —
without the narrative or the machine it happened on.
Also removed personal and machine-specific detail from the pages added in
ae733c0: a named USB volume knob, downloaded archive names, which apps had which
shadow, screen widths, monitor names, and the private-desktop state that
prompted the sound-theme fix. The rules they illustrate all still stand on their
own, stated generally. The one home path in Building-and-Packaging is now $HOME.
Fixed two dead anchors that predate this batch (synui#game-mode and
synui#task-manager pointed at bold text, not headings) and verified every
internal link and cross-page anchor resolves.
wiki: initial operator's manual
Ten pages: installation, keybindings, architecture, per-component pages
(synapd, synui, synguard+kmod, synsh), Secure Boot, building/packaging,
cutting an ISO release, and a troubleshooting catalogue.
The wiki deliberately carries what the README cannot: the failure modes.
Nearly every hard bug in this project has been SILENT — a build that exits 0
on stale code, a dkms module that reports installed while being unloadable, a
security rule that reports clean because it was reading garbage. Those are
written down here with the generalisable lesson attached.