Skip to content

sacdfs 0.6.1

Choose a tag to compare

@github-actions github-actions released this 11 Nov 09:12
· 432 commits to main since this release
03c2026

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 = yes keep 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 with kernel 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.md now says that turning leases on for
    Windows makes Windows miss new images too, and that a Linux kernel client mounted with nohandlecache
    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 are OPENDIR and RELEASEDIR pairs. They come from
    the container's smb3 directory leases = no (#205), not from the opendir change: 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.md says so, and that SMB_EXTRA_GLOBAL=smb3 directory leases = yes turns 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 with codegen-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, 0 for 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 leaves Transport endpoint is not connected; if the detach fails it logs an error and keeps serving. The stop timeouts stay
    above the grace: the container's stop_grace_period and the Unraid --stop-timeout go from
    20 s to 30 s, TimeoutStopSec and sacdfs-ctl stay at 30 s (sacdfs-ctl waits grace + 15 s
    for a larger --stop-grace). Tests: an integration test with a held-open file, and
    deploy/ci-held-stop-test.sh in 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.md is 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.md is 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_fix and a_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 in exec. 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). ESTALE on a cover-N.jpg
    the churner replaced or removed, and ENOENT or ESTALE on an area's cover.jpg in 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.py pins 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=yes in nsmb.conf fixed 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=none on the client mount, or oplocks = no on the share,
    brings it down to the direct mount's cost; smb2 max read = 262144 halves 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.