NFS Network Storage Guide for YTMDL
Status: EXPERIMENTAL (Architecture implemented; real host-mounted NFS release verification pending)
This guide describes how to reliably mount an NFS export (NFSv4.2 or NFSv3) on the host for YTMDL v0.11.0+.
1. Architecture Overview
[ NAS / NFS Server ]
│ (NFSv4.2 TCP)
▼
[ Linux Host Mount: /srv/music ]
│ (Podman volume bind mount: /srv/music:/music:Z)
▼
[ YTMDL Container: /music ] (UID: 10001, GID: 10001)IMPORTANT
YTMDL never mounts NFS inside the container. All NFS mounts must be performed on the host operating system. The host directory is passed to the container via volume mount (-v /srv/music:/music:Z or compose bind).
2. NFS Server Export Configuration (NAS)
On the NFS server (e.g. Synology, TrueNAS, Linux server), ensure the export is configured with UID/GID mapping for 10001:
Linux /etc/exports Example:
/export/music 192.168.1.0/24(rw,sync,no_subtree_check,all_squash,anonuid=10001,anongid=10001)rw: Read/Write access.sync: Guarantees writes are committed before responding to I/O requests.all_squash,anonuid=10001,anongid=10001: Maps all incoming client requests directly to YTMDL's container UID/GID (10001:10001).
3. Host Prerequisites & Mount Options
Install the NFS client utilities on the host:
sudo apt-get update && sudo apt-get install -y nfs-commonCritical Mount Flag Guidelines:
- Use
hard: If the NFS server temporarily drops, processes wait indefinitely until storage returns. - NEVER use
soft:softcauses the kernel to return silent I/O errors (EIO) on timeout, leading to corrupted files and data loss. - DO NOT use
intr:intris obsolete and completely ignored in Linux kernels 2.6.25+. - Use
_netdev,nofail: Ensures proper systemd network ordering and prevents host boot freezes if the NAS is temporarily offline.
4. Host Mount Configuration (/etc/fstab)
Add the mount entry to /etc/fstab:
192.168.1.100:/export/music /srv/music nfs nfsvers=4.2,hard,timeo=600,retrans=2,rsize=1048576,wsize=1048576,_netdev,nofail 0 0Option Explanations:
nfsvers=4.2: Modern NFS protocol with compound RPCs, server-side copy support, and better security.hard: Safe retry policy that prevents corrupted writes during NAS reboots.timeo=600: 60.0 second timeout before initiating TCP reconnect attempts.retrans=2: Number of retries before issuing a major timeout warning.rsize=1048576,wsize=1048576: 1 MiB transfer buffer size for maximum throughput.
Test the mount:
sudo mkdir -p /srv/music
sudo mount -a
mountpoint /srv/music5. Storage Identity Guard Setup
Initialize the Storage Identity Guard on the mounted NFS share:
# Generate a unique UUID for this storage volume
STORAGE_UUID=$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen)
# Write the marker file to the root of the mounted share
echo "ytmdl-storage:${STORAGE_UUID}" | sudo tee /srv/music/.ytmdl-storage-id > /dev/null
sudo chmod 0644 /srv/music/.ytmdl-storage-id
sudo chown 10001:10001 /srv/music/.ytmdl-storage-id
echo "Configured Storage UUID: ${STORAGE_UUID}"Then set the matching value in .env (Compose passes it to ytmdl-backend). MUSICDL_STORAGE_GUARD_ID accepts the bare UUID or the full ytmdl-storage:<uuid> string:
# .env
MUSICDL_STORAGE_GUARD_ID=<PASTE-YOUR-STORAGE_UUID-HERE>
# Optional but recommended for network storage: pause downloads below 1 GiB free
MUSICDL_LIBRARY_MIN_FREE_BYTES=1073741824After editing .env, recreate the backend so it re-reads the value (ytmdlctl update on an unchanged version, or podman compose -f compose.ghcr.yaml up -d).
6. Systemd Mount Unit (Alternative to fstab)
Create /etc/systemd/system/srv-music.mount:
[Unit]
Description=YTMDL NFS Music Library Mount
After=network-online.target
Wants=network-online.target
[Mount]
What=192.168.1.100:/export/music
Where=/srv/music
Type=nfs
Options=nfsvers=4.2,hard,timeo=600,retrans=2,rsize=1048576,wsize=1048576,_netdev
TimeoutSec=60
[Install]
WantedBy=multi-user.targetEnable and activate:
sudo systemctl daemon-reload
sudo systemctl enable --now srv-music.mount