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`
```bash
//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`
```bash
//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:
```bash
sudo chown root:root /path/to/credentials
sudo chmod 600 /path/to/credentials
```

## Mount Commands

### Apply New Configuration
```bash
# 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
```bash
mount | grep -E 'media|cals-files'
```

### Test Performance
```bash
# 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
```bash
# 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
```bash
# Backup fstab
sudo cp /etc/fstab /etc/fstab.backup-$(date +%Y%m%d-%H%M%S)
```

### Rollback if Needed
```bash
# 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:

```bash
//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](cifs-mount-resilience-fixes.md)** - Enhanced timeout handling and error recovery
- **[Tdarr Container Fixes](../docker/tdarr-container-fixes.md)** - Unmapped architecture to eliminate CIFS streaming during transcoding
- **[Crash Analysis](../docker/crash-analysis-summary.md)** - 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](ssh-key-management.md) - For secure access to systems
- [Tdarr Troubleshooting](../docker/tdarr-troubleshooting.md) - For Tdarr-specific issues
- [Network Troubleshooting](ssh-troubleshooting.md) - For general network issues
- **[CIFS Resilience Fixes](cifs-mount-resilience-fixes.md)** - Critical stability improvements
- **[Tdarr Container Security](../docker/tdarr-container-fixes.md)** - 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*