William Gill
25a2182c45
Two changes from v1.29-notify-2: 1. kmod: fix a latent ring-size compile error. The record struct was 56 bytes with an _pad[6] trailer, which meant NOTIFY_RING_BYTES / sizeof(record) = 1170 events per ring — not a power of two, so the BUILD_BUG_ON in notify_setup would have fired. Bumped _pad to 14 bytes so the record is 64 bytes, capacity is 1024, and every record is cache-line aligned. Wire ABI bumped accordingly; no deployed consumers yet. 2. scoutfs-notifyd: rewritten in Go using the standard library only. Three goroutines (reader / accept / broadcaster) with channel communication replace the single-thread epoll + ioctl loop from the C version. Slow-client handling is done by setting an in-the-past write deadline; the broadcaster drops clients whose kernel send buffer is full. Packaging changes: utils/Makefile now invokes "go build" with CGO_ENABLED=0 and GOPROXY=off; utils/scoutfs-utils.spec.in adds BuildRequires: golang >= 1.21.
81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# scoutfs-notify
|
|
|
|
Observer-only file access notifications for [ScoutFS](https://github.com/versity/scoutfs),
|
|
distributed as a rebasable `git format-patch` series plus a small Go
|
|
userspace relay daemon. Layers onto each upstream release with minimal
|
|
maintenance.
|
|
|
|
## What the series adds
|
|
|
|
Three patches against the scoutfs source tree:
|
|
|
|
1. **Kmod core** — a per-mount 64 KiB ring of 64-byte notification records and
|
|
a single-reader drain ioctl (`SCOUTFS_IOC_READ_NOTIFY`, nr 25). Emit is
|
|
non-blocking, drop-on-full; the monotonic `seq` field exposes drops to
|
|
consumers. Three percpu counters (`notify_emitted`,
|
|
`notify_dropped_ring_full`, `notify_reader_attached`). No mount option,
|
|
no sysfs toggle.
|
|
2. **Kmod hooks** — `->open` wrapper and READ emit in
|
|
`scoutfs_file_aio_read` / `scoutfs_file_read_iter`. Every hook is a
|
|
single predicted-false branch when no reader is attached. Nothing in
|
|
the data-waiter state machine is touched.
|
|
3. **scoutfs-notifyd (Go)** — userspace daemon that binds
|
|
`/run/scoutfs/<fsid>/notify.sock` (AF_UNIX SOCK_SEQPACKET, mode 0600,
|
|
root-only), drains the ring, and broadcasts each record to connected
|
|
clients. Pure-stdlib Go; no external module dependencies. Shipped
|
|
with a systemd template unit `scoutfs-notifyd@<mountpoint>.service`.
|
|
|
|
## Base
|
|
|
|
Currently rebased against:
|
|
|
|
scoutfs v1.29
|
|
|
|
See [base.txt](./base.txt).
|
|
|
|
## Build dependencies added
|
|
|
|
On top of the stock scoutfs build requirements, patch 3 adds:
|
|
|
|
* `golang >= 1.21` on the build host (RHEL/EL9: `golang`, EL8: `go-toolset`).
|
|
Debian 12 / Ubuntu 22.04+: `golang-go`.
|
|
|
|
The Go build is offline (`GOPROXY=off`) — no network access required at
|
|
build time. `CGO_ENABLED=0` so the produced binary is a pure-Go static
|
|
ELF.
|
|
|
|
## Applying
|
|
|
|
```sh
|
|
./apply.sh /path/to/scoutfs
|
|
```
|
|
|
|
Runs `git am --3way` on each patch. For a tarball instead of a git tree,
|
|
loop `patch -p1 < patches/*.patch`.
|
|
|
|
## Rebasing onto a new upstream release
|
|
|
|
```sh
|
|
git fetch --tags
|
|
git checkout -B notify v1.30
|
|
git am --3way patches/*.patch
|
|
# resolve any conflicts, git am --continue
|
|
git format-patch v1.30..notify -o patches/
|
|
# update base.txt and commit
|
|
```
|
|
|
|
## Tag history
|
|
|
|
v1.29-notify-3 (current — Go daemon, struct alignment fix)
|
|
v1.29-notify-2 (retired — C daemon; had latent ring-size compile bug)
|
|
v1.29-notify-1 (retired — shipped mount options)
|
|
|
|
## Quick smoke test after installation
|
|
|
|
```sh
|
|
systemctl enable --now scoutfs-notifyd@mnt-scoutfs.service
|
|
FSID=$(stat -f -c %i /mnt/scoutfs) # or use your scoutfs cli
|
|
socat - UNIX-CONNECT:/run/scoutfs/${FSID}/notify.sock | xxd | head
|
|
# touch some files in /mnt/scoutfs in another terminal
|
|
```
|