NFS Mount Migration: DSMedia Share — Implementation Plan¶
History. Done on 2026-03-16 (#82), then reverted on 2026-03-29 (#102, 2026-03-28-revert-to-virtiofs.md). The Podman VM no longer mounts NFS; it reads the host's mount through VirtioFS.
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Replace SMB mount with NFS for the DSMedia share to eliminate VirtioFS/SMB .smbdelete lock conflicts.
Architecture: Swap the mount command in mount-nas-media.sh from mount_smbfs to mount -t nfs. Remove credential embedding (NFS uses host-based auth). Add NAS_VOLUME config variable for the Synology export path. Same mountpoint, same LaunchAgent, same downstream consumers.
Tech Stack: macOS NFS client, Synology NFS server, bash, LaunchAgents
Prerequisite (Manual — Already Done)¶
Synology DSM: Enable NFS, create export rule for DSMedia:
- Hostname/IP:
192.168.20.0/22, Privilege: Read/Write, Squash: Map all to admin, Security: sys, Async: enabled
Task 1: Verify NFS Mount Works Manually¶
Before changing any code, confirm the Synology NFS export is accessible.
Step 1: Test NFS mount to a temp path¶
sudo mkdir -p /tmp/nfs-test
sudo mount -t nfs -o resvport,rw,soft romano.local:/volume1/DSMedia /tmp/nfs-test
Expected: Mount succeeds without error.
Step 2: Verify contents match SMB mount¶
Expected: Same directory listing as the current SMB mount (Movies, TV Shows, Torrents, etc.)
Step 3: Test file creation and deletion¶
Expected: Both succeed without error or .smbdelete remnants.
Step 4: Clean up test mount¶
Step 5: STOP if any step above failed. Debug NFS export config on Synology before proceeding.
Task 2: Add NAS_VOLUME to Config Template¶
Files:
- Modify:
config/config.conf.template:22-24
Step 1: Add NAS_VOLUME variable¶
After NAS_SHARE_NAME="DSMedia" (line 24), add:
Step 2: Commit config change¶
git add config/config.conf.template
git commit -m "feat(config): add NAS_VOLUME for NFS export path"
Task 3: Rewrite Mount Script Template for NFS¶
Files:
- Modify:
app-setup/templates/mount-nas-media.sh
Step 1: Replace the entire template with the NFS version¶
The new script keeps the same structure (set -euo pipefail, logging, wait_for_network, test_mount, main with numbered steps) but replaces the SMB-specific parts:
#!/usr/bin/env bash
# mount-nas-media.sh - User-specific NFS mount script for NAS media access
# This script is designed to be called by a per-user LaunchAgent
# to provide persistent NFS mounting for individual users.
set -euo pipefail
# Load Homebrew paths from system-wide configuration (LaunchAgent doesn't inherit PATH)
if [[ -f "/etc/paths.d/homebrew" ]]; then
HOMEBREW_PATHS=$(cat /etc/paths.d/homebrew)
export PATH="${HOMEBREW_PATHS}:${PATH}"
fi
# Configuration - these will be set during installation
NAS_HOSTNAME="__NAS_HOSTNAME__"
NAS_SHARE_NAME="__NAS_SHARE_NAME__"
NAS_VOLUME="__NAS_VOLUME__"
PLEX_MEDIA_MOUNT="${HOME}/.local/mnt/__NAS_SHARE_NAME__"
SERVER_NAME="__SERVER_NAME__"
WHOAMI="$(whoami)"
IDG="$(id -gn)"
IDU="$(id -un)"
# Logging configuration
HOSTNAME_LOWER="$(tr '[:upper:]' '[:lower:]' <<<"${SERVER_NAME}")"
LOG_FILE="${HOME}/.local/state/${HOSTNAME_LOWER}-mount.log"
# Ensure directories exist
mkdir -p "${HOME}/.local/state"
mkdir -p "${HOME}/.local/mnt"
# Ensure log file exists with proper permissions
touch "${LOG_FILE}"
chmod 600 "${LOG_FILE}"
truncate -s 0 "${LOG_FILE}" || true
# Logging function
log() {
local timestamp
timestamp=$(date '+%Y-%m-%d %H:%M:%S')
echo "${timestamp} [mount-nas-media] $*" | tee -a "${LOG_FILE}"
}
# Wait for network connectivity
wait_for_network() {
local max_attempts=30
local attempt=1
log "Waiting for network connectivity to ${NAS_HOSTNAME}..."
while [[ ${attempt} -le ${max_attempts} ]]; do
if ping -c 1 -W 5000 "${NAS_HOSTNAME}" >/dev/null 2>&1; then
log "✅ Network connectivity to ${NAS_HOSTNAME} established (attempt ${attempt})"
return 0
fi
log " Attempt ${attempt}/${max_attempts}: No connectivity to ${NAS_HOSTNAME}, waiting 5 seconds..."
sleep 5
((attempt += 1))
done
log "❌ Failed to establish network connectivity to ${NAS_HOSTNAME} after ${max_attempts} attempts"
return 1
}
test_mount() {
if ! mount -t nfs | grep -q "${PLEX_MEDIA_MOUNT}"; then
log "⚠️ NFS mount not visible in system mount table"
return 1
fi
log "✅ Mount verification successful (active NFS mount found)"
return 0
}
# Main execution - idempotent mounting process
main() {
log "Starting idempotent NAS media mount process"
log "Target: ${PLEX_MEDIA_MOUNT}"
log "Running as: ${WHOAMI} (${IDU}:${IDG})"
local nfs_source="${NAS_HOSTNAME}:/${NAS_VOLUME}/${NAS_SHARE_NAME}"
log "Source: ${nfs_source}"
# Wait for network connectivity first
if ! wait_for_network; then
log "❌ Cannot proceed without network connectivity"
exit 1
fi
# Step 0: Check for existing mount; return 0 if true
log "Step 0: Check for existing mount..."
if test_mount; then
return 0
fi
# Step 1: Unmount existing mount (ignore failures)
log "Step 1: Unmounting any existing mount..."
umount "${PLEX_MEDIA_MOUNT}" 2>/dev/null || true
log "✅ Unmount completed (or was not mounted)"
# Step 2: Remove mount point (ignore failures)
log "Step 2: Removing existing mount point..."
rmdir "${PLEX_MEDIA_MOUNT}" 2>/dev/null || true
log "✅ Mount point removal completed (or didn't exist)"
# Step 3: Create mount point with proper ownership and permissions
log "Step 3: Creating mount point with proper permissions..."
mkdir -p "${PLEX_MEDIA_MOUNT}"
chmod 755 "${PLEX_MEDIA_MOUNT}"
log "✅ Mount point created: ${PLEX_MEDIA_MOUNT} (user-owned 755)"
# Step 4: Mount the NFS share
log "Step 4: Mounting NFS share..."
if mount -t nfs -o resvport,rw,soft,bg,intr,rsize=65536,wsize=65536 "${nfs_source}" "${PLEX_MEDIA_MOUNT}"; then
log "✅ NFS mount successful"
else
log "❌ NFS mount failed"
exit 1
fi
# Wait a moment for mount to be fully accessible
sleep 2
# Step 5: Test access for current user
log "Step 5: Testing access..."
if ! test_mount; then
exit 1
fi
# Step 6: Create or replace $HOME symlink to mount dir
ln -fs "${PLEX_MEDIA_MOUNT}/Media/" "${HOME}"
log "✅ NAS media mount process completed successfully"
}
# Execute main function
main "$@"
exit 0
Step 2: Verify shellcheck passes¶
Expected: No errors, warnings, or info.
Step 3: Commit mount script¶
git add app-setup/templates/mount-nas-media.sh
git commit -m "feat(mount): replace SMB with NFS in mount-nas-media template
NFS eliminates VirtioFS/SMB oplock conflict that caused .smbdelete
ghost files when deleting torrents while Podman VM is running."
Task 4: Update plex-setup.sh — Remove Credential Embedding, Add NAS_VOLUME¶
Files:
- Modify:
app-setup/plex-setup.sh:378-549(thesetup_persistent_smb_mountfunction) - Modify:
app-setup/plex-setup.sh:1614-1622(troubleshooting output)
Step 1: Rename function and strip credential logic¶
Rename setup_persistent_smb_mount → setup_persistent_nfs_mount.
Replace the function body. The new version:
- Removes: keychain retrieval (lines 398-424), credential splitting,
__PLEX_NAS_USERNAME__/__PLEX_NAS_PASSWORD__sed substitutions,unset plex_nas_username plex_nas_password - Adds:
__NAS_VOLUME__substitution (fromconfig.conf) - Updates: all log messages from "SMB" → "NFS"
- Keeps: template copy,
__NAS_HOSTNAME__/__NAS_SHARE_NAME__/__SERVER_NAME__substitutions, deploy_user_mount function, LaunchAgent plist creation, immediate mount test
Step 2: Update the function call site (line 1511)
Change setup_persistent_smb_mount → setup_persistent_nfs_mount
Step 3: Update troubleshooting output (lines 1614-1622)
Replace SMB-specific hints with NFS equivalents:
- Manual mount command:
mount -t nfs -o resvport,rw,soft romano.local:/volume1/DSMedia '${PLEX_MEDIA_MOUNT}' - Check mounts:
mount -t nfs - Remove "Too many users" SMB error hint
Step 4: Commit plex-setup¶
git add app-setup/plex-setup.sh
git commit -m "feat(plex-setup): switch mount deployment from SMB to NFS
Removes credential embedding (NFS uses host-based auth).
Adds NAS_VOLUME template substitution for export path."
Task 5: Live Cutover — Stop Services, Switch Mounts, Restart¶
This task is performed manually with human confirmation at each step.
Step 1: Stop Transmission container and Podman VM¶
sudo -H -u operator podman stop transmission-vpn
sudo -H -u operator podman machine stop transmission-vm
Step 2: Unmount existing SMB mounts for both users¶
# Operator
sudo umount /Users/operator/.local/mnt/DSMedia 2>/dev/null || true
# Admin (if mounted)
umount ~/.local/mnt/DSMedia 2>/dev/null || true
Step 3: Deploy and run updated mount script for operator¶
# Copy the updated template and substitute values
cp app-setup/templates/mount-nas-media.sh /tmp/mount-nas-media-configured.sh
sed -i '' \
-e 's|__NAS_HOSTNAME__|romano.local|g' \
-e 's|__NAS_SHARE_NAME__|DSMedia|g' \
-e 's|__NAS_VOLUME__|volume1|g' \
-e 's|__SERVER_NAME__|TILSIT|g' \
/tmp/mount-nas-media-configured.sh
# Deploy to operator
sudo -u operator cp /tmp/mount-nas-media-configured.sh /Users/operator/.local/bin/mount-nas-media.sh
sudo -u operator chmod 700 /Users/operator/.local/bin/mount-nas-media.sh
# Run it
sudo -iu operator /Users/operator/.local/bin/mount-nas-media.sh
Step 4: Verify NFS mount for operator¶
Expected: NFS mount visible, Media directories listed.
Step 5: Deploy and run updated mount script for admin¶
sudo -u admin cp /tmp/mount-nas-media-configured.sh ~/.local/bin/mount-nas-media.sh
chmod 700 ~/.local/bin/mount-nas-media.sh
~/.local/bin/mount-nas-media.sh
Step 6: Verify NFS mount for admin¶
Step 7: Clean up¶
Step 8: Restart Podman VM and Transmission¶
sudo -H -u operator podman machine start transmission-vm
sudo -H -u operator podman start transmission-vpn
Step 9: Verify the original problem is fixed¶
# Create a test file
sudo touch /Users/operator/.local/mnt/DSMedia/Media/Torrents/pending-move/nfs-delete-test
# Delete it while VM is running
sudo rm /Users/operator/.local/mnt/DSMedia/Media/Torrents/pending-move/nfs-delete-test
# Verify no .smbdelete remnant
sudo ls -la /Users/operator/.local/mnt/DSMedia/Media/Torrents/pending-move/
Expected: File deletes cleanly, no .smbdelete* files.
Step 10: Verify Plex still sees its libraries¶
Open Plex web UI (http://localhost:32400/web) and confirm libraries are accessible with no re-scan triggered.
Task 6: Commit the Plan Update¶
git add docs/plans/2026-03-16-nfs-mount-migration.md
git commit -m "docs: update NFS migration plan with implementation details"
Revert Plan¶
If NFS causes issues at any point after cutover:
# 1. Stop services
sudo -H -u operator podman stop transmission-vpn
sudo -H -u operator podman machine stop transmission-vm
# 2. Unmount NFS
sudo umount /Users/operator/.local/mnt/DSMedia 2>/dev/null || true
umount ~/.local/mnt/DSMedia 2>/dev/null || true
# 3. Restore SMB mount script from git
git show HEAD~3:app-setup/templates/mount-nas-media.sh > /tmp/mount-nas-media-smb.sh
# 4. Re-embed credentials and deploy (needs keychain values)
# Substitute __PLEX_NAS_USERNAME__ and __PLEX_NAS_PASSWORD__ manually
# or re-run plex-setup.sh from the pre-NFS commit
# 5. Restart everything
sudo -iu operator /Users/operator/.local/bin/mount-nas-media.sh
sudo -H -u operator podman machine start transmission-vm
sudo -H -u operator podman start transmission-vpn
The SMB service on Synology was never disabled — both protocols coexist. Rollback only requires swapping the mount script back.