Skip to content

sacdfs 0.6.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 13:42
· 490 commits to main since this release
f2f587e

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.py now records VmSwap (swap_kb) and judges resident plus swapped memory,
    and has --smaps and --malloc-info-every to trace a step to its mapping.

  • The release archives also ship sacdfs-ctl, sacdfs.service and sacdfs.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-ctl does start, stop, status
    and restart with BusyBox sh where there is no systemd. Stopping is SIGTERM, and SIGKILL only
    after the wait. The NAS steps warn against kill -9, which leaves a dead mount, and the
    TerraMaster guide uses the shipped unit. CI runs shellcheck on the script and
    systemd-analyze verify on the unit. The NAS steps now say how to start it at boot with the
    vendor's own tools: an ASUSTOR init.d script, a QNAP autorun.sh and a Synology Task Scheduler
    task, checked in VMs. The QNAP autorun.sh started 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.xml is 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. See docs/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.yaml runs 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 of cannot 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-other without user_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 /srv bind
    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_file used 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 has scripts/check_rf64.py (Python, shares no code with
    sacdfs) check the chunk layout and sizes, and ffprobe when installed check the channels, rate,
    duration and tags. A new file handles (arm64) job in the NFS workflow runs the open_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 = no on 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 repeated ls -lR of 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_other by 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): umount as root (DSM, ADM and QuTScloud
    have no fusermount3), else fusermount3 -u or fusermount -u, whichever is installed.

Fixed

  • Two sacdfs-ctl start at 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
    which stop never reached. A lock now serialises start and stop.
  • 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 after up, say) sometimes waited 10 s for the servers to release the mount,
    because fuser -m listed 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 in docs/deployment.md and
    docs/performance.md.

  • #185 (MusicBrainz lookup) is complete except fingerprinting. Fallback naming, tags fetch and
    --musicbrainz are 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.md records that the SMB server identity follows the container's
    host name, how to keep it across a recreate (hostname: sacdfs or netbios 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.md runs 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 uses cp,
    not install, 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.md creates ~/.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.