Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 57_Wolve
|
d8a297a843 | ||
|
57_Wolve
|
b22524091e | ||
 William Gill
|
f54bf88e50 |
@@ -2,15 +2,15 @@
|
||||
|
||||
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.
|
||||
userspace relay daemon. Maintained as one long-lived branch per
|
||||
currently-supported upstream scoutfs version.
|
||||
|
||||
## What the series adds
|
||||
|
||||
Three patches against the scoutfs source tree:
|
||||
Three patches against each supported scoutfs release:
|
||||
|
||||
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
|
||||
a single-reader drain ioctl (`SCOUTFS_IOC_READ_NOTIFY`, nr 26). 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,
|
||||
@@ -25,58 +25,70 @@ Three patches against the scoutfs source tree:
|
||||
clients. Pure-stdlib Go; no external module dependencies. Shipped
|
||||
with a systemd template unit `scoutfs-notifyd@<mountpoint>.service`.
|
||||
|
||||
## Base
|
||||
The 64-byte event record layout is identical on every branch, so
|
||||
consumers and the daemon do not need per-version branching in their own
|
||||
code. The ioctl number is not: it is nr 25 on `v1.28`-`v1.30` and nr 26
|
||||
on `v1.32`, because upstream v1.32 took nr 25 for
|
||||
`SCOUTFS_IOC_INJECT_TOTL_DELTA`.
|
||||
|
||||
Currently rebased against:
|
||||
## Repository layout
|
||||
|
||||
scoutfs v1.30
|
||||
Each supported scoutfs version lives on its own long-lived branch. The
|
||||
patches in each branch are tuned for that specific scoutfs tree; they do
|
||||
NOT apply cross-version without rebasing.
|
||||
|
||||
See [base.txt](./base.txt).
|
||||
| Branch | Targets scoutfs | Tag |
|
||||
|----------------|-----------------|------------------|
|
||||
| `v1.28` | `v1.28` | `v1.28-notify-1` |
|
||||
| `v1.29` | `v1.29` | `v1.29-notify-1` |
|
||||
| `main` / `v1.30` | `v1.30` | `v1.30-notify-1` |
|
||||
| `v1.32` | `v1.32` | `v1.32-notify-1` |
|
||||
|
||||
## Build dependencies added
|
||||
|
||||
On top of the stock scoutfs build requirements, patch 3 adds:
|
||||
|
||||
* `golang >= 1.26` on the build host (fetched from go.dev by the CI; no distro currently packages 1.26).
|
||||
|
||||
|
||||
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.
|
||||
`main` tracks the newest supported scoutfs version. When a new scoutfs
|
||||
release ships, a new branch is created and the patches are rebased onto
|
||||
it; when a scoutfs version ages out of support, its branch stays in the
|
||||
repo for historical builds but is no longer maintained.
|
||||
|
||||
## Applying
|
||||
|
||||
Against a scoutfs git working tree at the matching upstream tag:
|
||||
|
||||
```sh
|
||||
./apply.sh /path/to/scoutfs
|
||||
git clone -b v1.29 https://git.anomalous.dev/alphacentri/scoutfs-notify.git /tmp/notify
|
||||
/tmp/notify/apply.sh /path/to/scoutfs-v1.29-checkout
|
||||
```
|
||||
|
||||
Runs `git am --3way` on each patch. For a tarball instead of a git tree,
|
||||
loop `patch -p1 < patches/*.patch`.
|
||||
The script runs `git am --3way` on each patch in order.
|
||||
|
||||
## 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
|
||||
# In a fresh scoutfs checkout:
|
||||
git checkout v1.31
|
||||
git checkout -b notify-v1.31
|
||||
|
||||
# Apply the previous branch's patches (usually clean; resolve any
|
||||
# conflicts, git am --continue).
|
||||
git am --3way /path/to/scoutfs-notify-v1.30/patches/*.patch
|
||||
git format-patch v1.31..notify-v1.31 -o /tmp/new-patches/
|
||||
|
||||
# Push a new branch + tag in this repo:
|
||||
cd /path/to/scoutfs-notify
|
||||
git checkout -b v1.31 main
|
||||
rm patches/*.patch
|
||||
cp /tmp/new-patches/*.patch patches/
|
||||
echo v1.31 > base.txt
|
||||
git commit -am 'v1.31-notify-1: rebase onto scoutfs v1.31'
|
||||
git push -u origin v1.31
|
||||
git tag v1.31-notify-1 && git push origin v1.31-notify-1
|
||||
# Fast-forward main to the new tip once you're ready to promote it.
|
||||
```
|
||||
|
||||
## Tag history
|
||||
|
||||
v1.30-notify-1 (current — rebased onto scoutfs v1.30, no code changes)
|
||||
v1.29-notify-4 (retired — last v1.29-base release)
|
||||
v1.29-notify-3 (retired — Go 1.21 toolchain)
|
||||
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
|
||||
FSID=$(scoutfs stat /mnt/scoutfs | awk '/fsid/ { print $2 }')
|
||||
socat - UNIX-CONNECT:/run/scoutfs/${FSID}/notify.sock | xxd | head
|
||||
# touch some files in /mnt/scoutfs in another terminal
|
||||
```
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
From 1be639b8a4fdfaac37fc5801a314d080200105cb Mon Sep 17 00:00:00 2001
|
||||
From 50eba28d24c3b98c71d851c8093abc27a1835cce Mon Sep 17 00:00:00 2001
|
||||
From: William Gill <claude@williamgill.net>
|
||||
Date: Wed, 22 Apr 2026 14:38:51 -0500
|
||||
Subject: [PATCH 1/3] notify: core file-access notification infrastructure
|
||||
@@ -84,7 +84,7 @@ index 9088496..94e4f44 100644
|
||||
EXPAND_COUNTER(orphan_scan_attempts) \
|
||||
EXPAND_COUNTER(orphan_scan_cached) \
|
||||
diff --git a/kmod/src/ioctl.c b/kmod/src/ioctl.c
|
||||
index 7a73d4d..9893559 100644
|
||||
index 156538a..4740ff0 100644
|
||||
--- a/kmod/src/ioctl.c
|
||||
+++ b/kmod/src/ioctl.c
|
||||
@@ -47,6 +47,7 @@
|
||||
@@ -95,22 +95,22 @@ index 7a73d4d..9893559 100644
|
||||
#include "scoutfs_trace.h"
|
||||
#include "util.h"
|
||||
|
||||
@@ -1718,6 +1719,8 @@ long scoutfs_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
|
||||
return scoutfs_ioc_mod_quota_rule(file, arg, false);
|
||||
case SCOUTFS_IOC_READ_XATTR_INDEX:
|
||||
return scoutfs_ioc_read_xattr_index(file, arg);
|
||||
@@ -1829,6 +1830,8 @@ long scoutfs_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
|
||||
return scoutfs_ioc_punch_offline(file, arg);
|
||||
case SCOUTFS_IOC_INJECT_TOTL_DELTA:
|
||||
return scoutfs_ioc_inject_totl_delta(file, arg);
|
||||
+ case SCOUTFS_IOC_READ_NOTIFY:
|
||||
+ return scoutfs_ioc_read_notify(file, arg);
|
||||
}
|
||||
|
||||
return -ENOTTY;
|
||||
diff --git a/kmod/src/ioctl.h b/kmod/src/ioctl.h
|
||||
index cefecd4..23fda13 100644
|
||||
index 1bb466c..0ac8d24 100644
|
||||
--- a/kmod/src/ioctl.h
|
||||
+++ b/kmod/src/ioctl.h
|
||||
@@ -848,4 +848,88 @@ struct scoutfs_ioctl_read_xattr_index {
|
||||
#define SCOUTFS_IOC_READ_XATTR_INDEX \
|
||||
_IOR(SCOUTFS_IOCTL_MAGIC, 23, struct scoutfs_ioctl_read_xattr_index)
|
||||
@@ -889,4 +889,88 @@ struct scoutfs_ioctl_inject_totl_delta {
|
||||
#define SCOUTFS_IOC_INJECT_TOTL_DELTA \
|
||||
_IOW(SCOUTFS_IOCTL_MAGIC, 25, struct scoutfs_ioctl_inject_totl_delta)
|
||||
|
||||
+/*
|
||||
+ * File access notification stream (observer-only).
|
||||
@@ -194,7 +194,7 @@ index cefecd4..23fda13 100644
|
||||
+};
|
||||
+
|
||||
+#define SCOUTFS_IOC_READ_NOTIFY \
|
||||
+ _IOWR(SCOUTFS_IOCTL_MAGIC, 25, struct scoutfs_ioctl_read_notify)
|
||||
+ _IOWR(SCOUTFS_IOCTL_MAGIC, 26, struct scoutfs_ioctl_read_notify)
|
||||
+
|
||||
#endif
|
||||
diff --git a/kmod/src/notify.c b/kmod/src/notify.c
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
From e970d4d8c6ab1f13cc7e2e51a830ba2f387b62d3 Mon Sep 17 00:00:00 2001
|
||||
From 482c0be372e2982cd7ca9ad7c0ea3522437886c6 Mon Sep 17 00:00:00 2001
|
||||
From: William Gill <claude@williamgill.net>
|
||||
Date: Wed, 22 Apr 2026 14:40:04 -0500
|
||||
Subject: [PATCH 2/3] notify: file open/read hook sites
|
||||
@@ -37,7 +37,7 @@ Nothing in the data-waiter state machine is touched.
|
||||
2 files changed, 39 insertions(+)
|
||||
|
||||
diff --git a/kmod/src/data.c b/kmod/src/data.c
|
||||
index 7903e8d..6e3b133 100644
|
||||
index b6ca5eb..439ce09 100644
|
||||
--- a/kmod/src/data.c
|
||||
+++ b/kmod/src/data.c
|
||||
@@ -41,6 +41,7 @@
|
||||
@@ -48,7 +48,7 @@ index 7903e8d..6e3b133 100644
|
||||
|
||||
/*
|
||||
* We want to amortize work done after dirtying the shared transaction
|
||||
@@ -2207,6 +2208,32 @@ const struct address_space_operations scoutfs_file_aops = {
|
||||
@@ -2312,6 +2313,32 @@ const struct address_space_operations scoutfs_file_aops = {
|
||||
.write_end = scoutfs_write_end,
|
||||
};
|
||||
|
||||
@@ -81,7 +81,7 @@ index 7903e8d..6e3b133 100644
|
||||
const struct file_operations scoutfs_file_fops = {
|
||||
#ifdef KC_LINUX_HAVE_FOP_AIO_READ
|
||||
.read = do_sync_read,
|
||||
@@ -2219,6 +2246,7 @@ const struct file_operations scoutfs_file_fops = {
|
||||
@@ -2324,6 +2351,7 @@ const struct file_operations scoutfs_file_fops = {
|
||||
.splice_read = generic_file_splice_read,
|
||||
.splice_write = iter_file_splice_write,
|
||||
#endif
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
From a227eecabc78f331fcb8c483e6051021cb44a94b Mon Sep 17 00:00:00 2001
|
||||
From 31ef1c5ff1522a6de4501ff41fed0d72ecb57e8d Mon Sep 17 00:00:00 2001
|
||||
From: William Gill <claude@williamgill.net>
|
||||
Date: Wed, 22 Apr 2026 14:40:34 -0500
|
||||
Subject: [PATCH 3/3] notify: scoutfs-notifyd userspace relay daemon (Go 1.26)
|
||||
@@ -72,10 +72,10 @@ recv() events.
|
||||
utils/Makefile | 28 +-
|
||||
utils/man/scoutfs-notifyd.8 | 120 +++++++
|
||||
utils/notifyd/go.mod | 3 +
|
||||
utils/notifyd/main.go | 434 +++++++++++++++++++++++++
|
||||
utils/notifyd/main.go | 437 +++++++++++++++++++++++++
|
||||
utils/notifyd/scoutfs-notifyd@.service | 40 +++
|
||||
utils/scoutfs-utils.spec.in | 8 +
|
||||
6 files changed, 630 insertions(+), 3 deletions(-)
|
||||
6 files changed, 633 insertions(+), 3 deletions(-)
|
||||
create mode 100644 utils/man/scoutfs-notifyd.8
|
||||
create mode 100644 utils/notifyd/go.mod
|
||||
create mode 100644 utils/notifyd/main.go
|
||||
@@ -274,10 +274,10 @@ index 0000000..d99f395
|
||||
+go 1.26
|
||||
diff --git a/utils/notifyd/main.go b/utils/notifyd/main.go
|
||||
new file mode 100644
|
||||
index 0000000..9478bae
|
||||
index 0000000..41b98ab
|
||||
--- /dev/null
|
||||
+++ b/utils/notifyd/main.go
|
||||
@@ -0,0 +1,434 @@
|
||||
@@ -0,0 +1,437 @@
|
||||
+// Copyright (C) 2026 Versity Software, Inc. All rights reserved.
|
||||
+//
|
||||
+// This program is free software; you can redistribute it and/or
|
||||
@@ -396,8 +396,11 @@ index 0000000..9478bae
|
||||
+var (
|
||||
+ scoutfsIocStatfsMore = iocEncode(iocDirRead,
|
||||
+ scoutfsIoctlMagic, 10, statfsMoreSize)
|
||||
+ // nr must match SCOUTFS_IOC_READ_NOTIFY in kmod/src/ioctl.h. On the
|
||||
+ // v1.32 base this is 26: upstream v1.32 took nr 25 for
|
||||
+ // SCOUTFS_IOC_INJECT_TOTL_DELTA, so the notify ioctl moved to 26.
|
||||
+ scoutfsIocReadNotify = iocEncode(iocDirRead|iocDirWrite,
|
||||
+ scoutfsIoctlMagic, 25, readNotifySize)
|
||||
+ scoutfsIoctlMagic, 26, readNotifySize)
|
||||
+)
|
||||
+
|
||||
+func init() {
|
||||
|
||||
Reference in New Issue
Block a user