claude-home/reference/networking/nas-mount-configuration.md

NAS Mount Configuration - TrueNAS SMB Optimization

Overview

This document contains the optimized SMB mount configurations for TrueNAS (10.10.0.35) across multiple systems in the homelab. These optimizations provide significant performance improvements over default SMB settings.

TrueNAS System Details

• IP Address: 10.10.0.35
• System: TrueNAS Server
• SMB Version: 3.1.1 (optimized from 3.0)
• Available Shares: /media and /cals-files

Performance Results

Before Optimization

• Tdarr Server: 61.8 MB/s
• Local Workstation: 11.1 MB/s

After Optimization

• Tdarr Server: 103 MB/s (67% improvement)
• Local Workstation: 85.4 MB/s (669% improvement)

Optimized Mount Configurations

Tdarr Server (ubuntu-ct - 10.10.0.43)

File: /etc/fstab

//10.10.0.35/media /mnt/truenas-share cifs vers=3.1.1,cache=loose,credentials=/root/.truenascreds,rsize=16777216,wsize=16777216,bsize=4194304,actimeo=30,closetimeo=5,echo_interval=30

Active Mount Options (negotiated):

vers=3.1.1,cache=loose,rsize=8388608,wsize=8388608,bsize=4194304,
actimeo=30,closetimeo=5,echo_interval=30

Local Workstation (nobara-pc)

File: /etc/fstab

//10.10.0.35/media          /mnt/media        cifs    credentials=/home/cal/.samba_credentials,uid=1000,gid=1000,vers=3.1.1,cache=loose,rsize=16777216,wsize=16777216,bsize=4194304,actimeo=30,closetimeo=5,echo_interval=30,noperm   0 0
//10.10.0.35/cals-files     /mnt/cals-files   cifs    credentials=/home/cal/.samba_credentials,uid=1000,gid=1000,vers=3.1.1,cache=loose,rsize=16777216,wsize=16777216,bsize=4194304,actimeo=30,closetimeo=5,echo_interval=30,noperm   0 0

Active Mount Options (negotiated):

vers=3.1.1,cache=loose,rsize=8388608,wsize=8388608,bsize=4194304,
actimeo=30,closetimeo=5,echo_interval=30,noperm

Key Optimization Parameters

Protocol Version

• Setting: vers=3.1.1
• Previous: vers=3.0
• Benefit: Latest SMB protocol with performance improvements and better security

Cache Strategy

• Setting: cache=loose
• Previous: cache=strict
• Benefit: Better read performance, less strict consistency requirements

Buffer Sizes

• Read Size: rsize=16777216 (requested) → rsize=8388608 (negotiated)
• Write Size: wsize=16777216 (requested) → wsize=8388608 (negotiated)
• Block Size: bsize=4194304 (4MB, up from 1MB)
• Previous: rsize=4194304,wsize=4194304,bsize=1048576
• Benefit: Larger buffers reduce network round trips

Connection Timeouts

• Attribute Cache: actimeo=30 (30 seconds, up from 1 second)
• Close Timeout: closetimeo=5 (5 seconds, up from 1 second)
• Echo Interval: echo_interval=30 (30 seconds, down from 60 seconds)
• Benefit: Better connection persistence, fewer reconnections

Credential Files

Tdarr Server

File: /root/.truenascreds

username=plex
password=[password]
domain=

Local Workstation

File: /home/cal/.samba_credentials

username=plex
password=[password]
domain=

Security: Both files should be owned by root with 600 permissions:

sudo chown root:root /path/to/credentials
sudo chmod 600 /path/to/credentials

Mount Commands

Apply New Configuration

# Unmount existing mounts
sudo umount /mnt/media
sudo umount /mnt/cals-files

# Mount with new optimized settings  
sudo mount /mnt/media
sudo mount /mnt/cals-files

Verify Mount Options

mount | grep -E 'media|cals-files'

Test Performance

# Test read performance (100MB test)
time dd if="/mnt/media/path/to/large/file.mkv" bs=1M count=100 of=/dev/null

Troubleshooting

Common Issues

Mount Error: Device or resource busy

• Solution: Unmount existing mount first: sudo umount /mnt/media

Parse Error in fstab

• Check for missing // before IP address
• Ensure no spaces in comma-separated options
• Verify all commas are present between options

Permission Denied

• Verify credential file exists and has correct permissions (600)
• Check username/password in credential file
• Ensure TrueNAS user has access to the share

Slow Performance After Changes

• Verify new mount options are active: mount | grep media
• Test with different file sizes to confirm improvement
• Check network connectivity: ping 10.10.0.35

Performance Testing Commands

# Quick performance test (50MB)
time dd if="/mnt/media/Movies/[movie-file]" bs=1M count=50 of=/dev/null

# Larger performance test (100MB)  
time dd if="/mnt/media/Movies/[movie-file]" bs=1M count=100 of=/dev/null

# Monitor network during transfer
iftop -i eth0

Backup and Rollback

Before Making Changes

# Backup fstab
sudo cp /etc/fstab /etc/fstab.backup-$(date +%Y%m%d-%H%M%S)

Rollback if Needed

# Restore from backup
sudo cp /etc/fstab.backup-YYYYMMDD-HHMMSS /etc/fstab

# Remount
sudo umount /mnt/media
sudo mount /mnt/media

System-Specific Notes

Tdarr Integration

• Unmapped Node Architecture: Node downloads files from Tdarr server at optimized 103 MB/s
• Cache Directory: Uses local NVMe storage for maximum transcoding performance
• No Direct NAS Access: Unmapped nodes don't directly access NAS mounts

Local Workstation Usage

• Media Browsing: 85.4 MB/s for fast local media access
• File Management: Significantly faster file operations
• Backup Operations: Improved speeds for large file transfers

Future Expansion

When adding new systems, use these optimized settings as the baseline:

//10.10.0.35/media /mnt/media cifs credentials=/path/to/creds,uid=1000,gid=1000,vers=3.1.1,cache=loose,rsize=16777216,wsize=16777216,bsize=4194304,actimeo=30,closetimeo=5,echo_interval=30,noperm 0 0

Adjust uid, gid, and credential path as needed for each system.

System Stability Considerations (2025-08-11)

Critical Stability Issue

During intensive transcoding operations with network storage, CIFS mount failures can escalate to kernel-level crashes requiring hard system reboot. This occurs when:

• Large files (10GB+ remux) are streamed over CIFS during transcoding
• Network connectivity issues cause CIFS timeouts and reconnection failures
• Container processes (like tdarr-ffmpeg) experience memory corruption in CIFS operations

Resilience Improvements

For production systems performing intensive file operations over CIFS, see:

• CIFS Mount Resilience Fixes - Enhanced timeout handling and error recovery
• Tdarr Container Fixes - Unmapped architecture to eliminate CIFS streaming during transcoding
• Crash Analysis - Complete incident analysis and prevention strategies

Recommended Configuration Updates

While the optimized settings above provide excellent performance, add these resilience parameters for stability:

• Timeout handling: timeo=15,retrans=3 - Prevent 90-second hangs
• Interruption support: intr - Allow kernel to interrupt hung operations
• Smaller buffers during issues: Consider reducing buffer sizes during network instability

Related Documentation

• SSH Key Management - For secure access to systems
• Tdarr Troubleshooting - For Tdarr-specific issues
• Network Troubleshooting - For general network issues
• CIFS Resilience Fixes - Critical stability improvements
• Tdarr Container Security - Prevent kernel crashes

---

Last updated: August 11, 2025
Performance improvements: Tdarr Server 67% faster, Local Workstation 669% faster
Stability improvements: Added kernel crash prevention measures