Repository navigation
sacdfs 0.6.0
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 as release candidate 0.6.0-rc.1 (2026-11-10). The final version carries only the version
change on top of the rc.1 code. The results are in docs/clients.md and docs/test-plan.md.
Added
-
Soak: the memory steps explained, and judged without them (part of #247). The steps of 3 to
9 MiB in a soak's resident size are the kernel swapping pages out and in on a busy host: four
parallel runs fell by the same amounts at the same samples while the malloc heap did not change.
scripts/soak.pynow recordsVmSwap(swap_kb) and judges resident plus swapped memory,
and has--smapsand--malloc-info-everyto trace a step to its mapping. -
The release archives also ship
sacdfs-ctl,sacdfs.serviceandsacdfs.conf.example
(part of #289), next to the binary, so a NAS install doesn't need a second download. -
Safe start and stop for the release binary on a NAS (#289).
deploy/systemd/sacdfs.service
is a unit for/usr/local/bin/sacdfs(settings in/etc/default/sacdfs, loads FUSE, waits up to
30 s for the unmount, clears a leftover mount);deploy/sacdfs-ctldoesstart,stop,status
andrestartwith BusyBoxshwhere there is no systemd. Stopping is SIGTERM, and SIGKILL only
after the wait. The NAS steps warn againstkill -9, which leaves a dead mount, and the
TerraMaster guide uses the shipped unit. CI runsshellcheckon the script and
systemd-analyze verifyon the unit. The NAS steps now say how to start it at boot with the
vendor's own tools: an ASUSTORinit.dscript, a QNAPautorun.shand a Synology Task Scheduler
task, checked in VMs. The QNAPautorun.shstarted sacdfs by itself
after a restart of the QuTScloud VM, on a hand-made volume. -
Unraid and TrueNAS app-store entries, prepared (part of #284).
deploy/unraid/sacdfs.xmlis a
Community Applications template (device, capabilities and AppArmor setting in Extra Parameters,
not privileged; ports 10445 and 12049; read-only images and index cache paths; SMB and NFS
settings), loadable today from Unraid's user templates.deploy/truenas/sacdfs/is a TrueNAS
apps-catalog app definition (form, template, test values) that renders with the catalog's tooling.
Both were started with rootful Podman and served the SMB share; neither was run on Unraid or
TrueNAS, and neither is submitted to a store. Seedocs/install/store-apps.md.
The store icon is now an original drawing (deploy/icon.svg,deploy/icon.png), and
ca_profile.xml(the Community Applications repository profile) is in the repository root.
The catalog app passes the TrueNAS apps repository's own render, metadata, port and validate
checks (part of #284). -
One Compose file for every NAS container manager (#283).
deploy/nas-compose.yamlruns the
published image with ports 10445 and 12049 (a NAS's own SMB and NFS usually hold 445 and 2049),
the health check and a commented setting list. The one line to edit is the path of your images.
The Synology, QNAP, UGREEN, TerraMaster, Unraid, OpenMediaVault and ASUSTOR guides point to it
instead of repeating Compose blocks, and each says where it was actually run: Docker Compose on
Podman, Docker 25 with Compose 2.24 on ASUSTOR ADM in a VM, and Docker 29 with Compose 5.1 from
the App Center on TerraMaster TOS in a VM, and Docker 27 with Compose 5.1 from Container Station
on QuTScloud in a VM (on a hand-made volume: QuTScloud wouldn't make a pool); the other vendors'
container managers are untested. -
Plain start-up messages for NAS users (#282). Before scanning or mounting, sacdfs checks
what the mount needs and says in one line what is missing and what to type: FUSE not loaded
(modprobe fuse, instead ofcannot mount on X: No such file or directory), the folder to
mount on missing (mkdir -p X), no mount helper for a user other than root, no right to mount
in a container (--cap-add SYS_ADMIN). A mount refused by AppArmor or SELinux, and
--allow-otherwithoutuser_allow_other, are explained the same way. The container's entry
point checks/dev/fuse,CAP_SYS_ADMIN, ports 445 and 2049 already taken, and the/srvbind
for players on the same host before it starts. -
The RF64 test is read by other programs, and the file-handle tests also run on arm64 (#220).
wav::rf64_fileused to be ignored and asserted only the file's size. It now runs in every test
job: it writes the 4.6 GB sparse file and hasscripts/check_rf64.py(Python, shares no code with
sacdfs) check the chunk layout and sizes, andffprobewhen installed check the channels, rate,
duration and tags. A newfile handles (arm64)job in the NFS workflow runs theopen_by_handle_at
tests as root on a native arm64 runner, where the normal arm64 job skips them. Tests and CI only; no
change to the program.
Changed
- Listings over SMB cost sacdfs a quarter fewer requests (#205). The kernel now keeps the
listing of every folder until it changes, including areas that are re-read for their art, which
it listed again at every open before. The container's Samba no longer asks sacdfs for the
filesystem's size at each folder (vfs_default:VFS_OPEN_HOW_RESOLVE_NO_XDEV = noon the share),
and no longer offers directory leases (smb3 directory leases = no), with which the Linux kernel
client did not show a new image while it kept listing that folder. Through the container and the
Linux kernel client, a repeatedls -lRof 2,484 entries costs 2,010 requests instead of 2,776,
and a library rescan 1,582 instead of 2,345. Names, sizes, times and bytes are unchanged. See
docs/deployment.md ("What a listing costs over SMB"), with the settings for your own Samba. - Root's mount lets other users read it (#282). Run as root, sacdfs now mounts with
allow_otherby default, so Samba guests, NFS clients and apps can read the mount instead of
getting "Permission denied".--no-allow-other(-o no_allow_other) keeps it to root. Users
other than root are unchanged. The mount is read-only; the decision and its trade-off are in
docs/design.md. - Unmount hints name a command that exists (#282):
umountas root (DSM, ADM and QuTScloud
have nofusermount3), elsefusermount3 -uorfusermount -u, whichever is installed.
Fixed
- Two
sacdfs-ctl startat once started two sacdfs (#289). ASUSTOR ADM runs its start script
twice at boot; both starts passed the "already running" check and stacked two mounts, one of
whichstopnever reached. A lock now serialisesstartandstop. - A background mount that failed printed its error twice (#282).
- The container could take 10 s to stop (#283). A stop within a few seconds of the start (a
restart right afterup, say) sometimes waited 10 s for the servers to release the mount,
becausefuser -mlisted every process on the container's filesystem once the mount was gone.
Podman's default stop timeout then killed the container ("resorting to SIGKILL"). The entry point
now waits only while the mount exists: 0 of 75 stops took over a second, against 14 of 75 before (Podman on Fedora and Docker on ADM).
Documentation
-
A player beside whole-file scans, checked on a NAS's own CPU (#230). The 0.5.0 image as an app on
a NAS's E-cores, client on another host over SMB and NFS: a 6-channel WAV player held real time with
one or four whole-file scanners on 2 and 4 cores (0.4.1: 0.35 to 0.65× real time), and players that
buffer 8 to 64 MiB ahead weren't hurt by counting as scanners while they settle. One run in 7 with
four scanners on 2 cores fell to 0.88× while the NAS was busy. Tables indocs/deployment.mdand
docs/performance.md. -
#185 (MusicBrainz lookup) is complete except fingerprinting. Fallback naming,
tags fetchand
--musicbrainzare shipped; the AcoustID fingerprint lookup, which needs an API key and a
Chromaprint dependency decision, moved to #296 (Later). The user guide and design notes say so. -
macOS and SMB restarts (part of #204): the install guides now say, where a user updates, that a
macOS client must mount the SMB share again after an upgrade or restart, while Linux and Windows
clients carry on.docs/deployment.mdrecords that the SMB server identity follows the container's
host name, how to keep it across a recreate (hostname: sacdfsornetbios name, checked with a
raw SMB2 negotiate and the gvfs client), and why that is not the default. macOS was not re-tested. -
NAS install guides for people new to SSH and Linux: a new
docs/install/nas-binary.mdruns the
release binary on a NAS one command at a time, each with what you should see, and a table of the
messages met when something goes wrong and what to do. It keeps sacdfs on the data volume, adds
--allow-other(without it, SMB guests and other users got "Permission denied"), and usescp,
notinstall, which on TerraMaster TOS is a different program. The Synology, QNAP, ASUSTOR,
TerraMaster and UGREEN guides were rewritten around it and run again as written with the 0.5.0
release, in VMs, not on the vendors' hardware. ASUSTOR gains a tested Compose file (other ports, the
health check written in); TerraMaster a systemd service that mounted again after a restart, and a
warning that its NFS service empties/etc/exports. Why Synology's Container Manager and QNAP's
Container Station couldn't be tested is recorded.docs/install/binary.mdcreates~/.local/bin
before installing into it.
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.0-x86_64-linux.tar.gz: generic x86-64, for any x86_64 CPU.sacdfs-0.6.0-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.0-aarch64-linux.tar.gz: aarch64 (64-bit ARM).
Container image for a NAS (SMB and NFS): ghcr.io/aclater/sacdfs:0.6.0 (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.0 -R aclater/sacdfs. See the README, "Install".
Built from f2f587e.