Repository navigation
sacdfs 0.6.1
Security: this release is affected by GHSA-phfg-58h9-f2pp (High), GHSA-wfjg-pqhm-4mm2 (High) and GHSA-825f-7xrc-fqf7 (Medium). They are fixed in 0.6.4; use the latest release. Upgrade as the install guide describes.
Tested on main against 0.6.0; the results are in docs/test-plan.md ("Results: 0.6.1 gate").
The pace change for WAV copies over SMB (#271, #323) was taken out before the release because it
could stall a player beside four starting copies (#338); 0.6.1 keeps 0.6.0's pace rules.
Changed
- SMB directory leases stay off: why they can't be fresh (part of #325). Docs and a comment in the
container's entry point only; no code or default changed, so this needs no soak. Samba (4.24.7) breaks a
directory lease only for a change made through Samba, never for a kernel change notification, and a FUSE
file system can't raise one for an entry it adds; so neither FUSE invalidations from sacdfs nor
kernel change notify = yeskeep a leased listing fresh. Measured on 0.6.0: with leases on, a new image
didn't show within 155 s on the Linux kernel client (also withkernel change notify = yes, and also on
a plain folder shared by the same Samba) nor on Windows 11 listing every second; with leases off it showed
in 0.4 to 1.7 s on Linux and 5.1 s on Windows.docs/deployment.mdnow says that turning leases on for
Windows makes Windows miss new images too, and that a Linux kernel client mounted withnohandlecache
stays fresh with leases on (1.6 s). - Windows thumbnail pass: where the extra folder opens come from (part of #312). Docs only. On
Windows 11 in a VM, the pass over 196 files sends 2,104 to 2,166 requests on 0.6.0 against 508 to 514
on 0.5.0 and 921 to 941 on 0.4.1; the 800 extra areOPENDIRandRELEASEDIRpairs. They come from
the container'ssmb3 directory leases = no(#205), not from theopendirchange: with leases on,
0.6.0 counts 496. On a 5,040-file tree the pass took about 1.5 times as long (121 to 126 s against 80 to
86 s).docs/deployment.mdsays so, and thatSMB_EXTRA_GLOBAL=smb3 directory leases = yesturns the
leases back on for a Windows-only share, at the cost the container's default avoids for the Linux kernel
client. No code or default changed. - DST areas read faster on one thread: scarletbook is built in one codegen unit (#270). Release
builds now compile scarletbook withcodegen-units = 1. Its DST decoder then runs in as many cycles
as in the library's own builds, about 4 % fewer than before. Six-channel DST on one thread went from
1.11-1.15× to 0.99× of the library on a NAS-class CPU, which meets the 1.1× target.
Audio bytes are unchanged. A clean release build takes about 10 s longer. Details are in
docs/performance.md, "One codegen unit for scarletbook". - sacdfs exits after a grace period on SIGTERM even while clients hold files open (#276). This
changes the lifecycle next to the read path, not the reads, and the next release needs a soak.
The mount is still detached at once; sacdfs now serves the files still open for--stop-grace
seconds (default 10, container:SACDFS_STOP_GRACE,0for the old wait-for-ever) and then
saves its state and exits with status 0. Clients with a file still open get I/O errors. It exits
only when its mount is gone from the mount table, so a stop never leavesTransport endpoint is not connected; if the detach fails it logs an error and keeps serving. The stop timeouts stay
above the grace: the container'sstop_grace_periodand the Unraid--stop-timeoutgo from
20 s to 30 s,TimeoutStopSecandsacdfs-ctlstay at 30 s (sacdfs-ctlwaitsgrace + 15s
for a larger--stop-grace). Tests: an integration test with a held-open file, and
deploy/ci-held-stop-test.shin the container share test (files held open over SMB and NFS and
inside the container). - Install guides rewritten to be simpler (part of #310).
docs/install/README.mdis now a chooser
with three questions; the Docker and Podman, Linux binary and Linux client guides follow one shape
(what you need, numbered steps, check it worked, three common problems, Details), with the test
history moved to Details. The NAS and player guides follow in later pull requests. - Player install guides rewritten (part of #310). Roon, Plex, Jellyfin, Navidrome, Lyrion and MPD now follow the common guide shape (what you need, numbered steps, check, three problems, Details), start from the Docker/Podman and Linux client guides, and were run on 0.6.0 for Jellyfin, Navidrome, Lyrion and MPD. Lyrion no longer needs the root settings with the SMB mount, and MPD needs no cover renaming.
- NAS install guides rewritten (part of #310). Each vendor guide (Synology, QNAP, ASUSTOR, TerraMaster, UGREEN, ReadyNAS) is one page with one path, the 0.6.0 release archive and the vendor's own start-at-boot method, followed as written on 0.6.0 in the NAS VMs; TrueNAS SCALE, Unraid and OpenMediaVault keep their facts in the same layout, marked untested on 0.6.0.
nas-binary.mdis the short generic guide; test history, options and the longer troubleshooting moved to each page's Details. Found while checking: TOS has no/usr/local/bin, so the unit steps make it.
Fixed
- Mount tests: a failing stop test no longer hangs the run (#335). Tests only. The two tests
that stop a daemon (SIGSTOP) now hold it in a guard that, when the test fails, resumes it
(SIGCONT), stops and reaps it, and prints its debug log: a failed assertion no longer leaves
a stopped daemon that blocks the rest of the run. The cause of those failures under load was
the #305 race through tests outside the lock:bad_arguments_fail_cleanly,
start_up_messages_name_the_fixanda_source_or_cache_under_the_mount_point_is_refused
need no FUSE but spawn sacdfs, so they did not take the shared lock, and a child they forked
could inherit a stop test's file on the mount it was about to stop. The child then blocked in
exec, the mount stayed busy, and the stop test failed to unmount it. They now hold the lock
shared (common::spawns_children!). - Mount tests no longer hang under load (#305). A child forked by one test holds a copy of the
open files of the other tests' threads until it execs, and closing a file on a FUSE mount waits
for its daemon. While a test held a daemon stopped (SIGSTOP), such a child, and the test that
spawned it, blocked inexec. The two tests that stop a daemon now run exclusive: every FUSE
test holds a shared lock for its whole run (common::skip_without_fuse!), and they hold it
exclusive (skip_without_fuse!(exclusive)). The folder-times test also waits for each folder to
move, not only the root, which failed one run in four under load. - Real-disc tests: a truncated image fails (#294). Before the tests run, each image is checked
against its own TOC (every area's TOC copies and audio must lie inside the file); a copy cut
short fails the run with "truncated: ...". A test on truncated copies of a corpus image runs in
CI. A corrupt image of the right size is still not caught. - Soak: designed art-churn errors no longer fail the verdict (#279).
ESTALEon acover-N.jpg
the churner replaced or removed, andENOENTorESTALEon an area'scover.jpgin the
art-churn album after a cover removal, are counted as replaced sidecars. Every other errno, and
these on any other path, still fail the soak;scripts/test_soak.pypins both. - macOS: precomposed (NFC) lookups of accented names (part of #308). Docs only. Names are
served precomposed and macOS lists them decomposed; the macOS SMB client answers a precomposed
lookup itself, without asking the server, once it has cached the folder's listing. All 111 names
with a differing NFC and NFD spelling failed that way, not 111 of 357 at random. The setting
dir_cache_off=yesinnsmb.conffixed it on macOS 27.2 in a VM.docs/deployment.md(macOS)
says so. No code or Samba setting changed. Checked on macOS in a VM, not on Apple hardware.
Documentation
- What a player's import costs over SMB, and the settings that change it (part of #266).
Through a Linux kernel SMB mount, Navidrome's scan made sacdfs serve 3.5 times the bytes, and
use 5 times the CPU, of a direct mount. The cause is the client reading ahead around each
file's header and tags.cache=noneon the client mount, oroplocks = noon the share,
brings it down to the direct mount's cost;smb2 max read = 262144halves it. Copies and
playback were measured with each. The defaults are unchanged
(performance, Navidrome guide).
Downloads
Linux binaries, glibc 2.17 or later (RHEL 7 era and later), needing FUSE and, as a user other than root, FUSE 3's fusermount3 (package fuse3) or FUSE 2's fusermount; root needs neither:
sacdfs-0.6.1-x86_64-linux.tar.gz: generic x86-64, for any x86_64 CPU.sacdfs-0.6.1-x86_64-v3-linux.tar.gz: x86-64-v3 (AVX2, most Intel and AMD CPUs since about 2015): about 20 % less CPU for WAV files. It stops with an illegal-instruction error on older CPUs.sacdfs-0.6.1-aarch64-linux.tar.gz: aarch64 (64-bit ARM).
Container image for a NAS (SMB and NFS): ghcr.io/aclater/sacdfs:0.6.1 (generic CPU; amd64 and arm64).
Verify a download: sha256sum -c <asset>.sha256 and gh attestation verify <asset> -R aclater/sacdfs; the image: gh attestation verify oci://ghcr.io/aclater/sacdfs:0.6.1 -R aclater/sacdfs. See the README, "Install".
Built from 03c2026.