Raspberry Pi as a File Server: Samba NAS Build & Debug Guide

Setting up a Raspberry Pi as a file server yields a low-power, always-on NAS capable of saturating a Gigabit Ethernet link (110 MB/s real-world) if you bypass common USB and filesystem bottlenecks. This guide targets the Raspberry Pi 5 (8GB RAM) running Raspberry Pi OS Bookworm (64-bit). We will configure a Samba (SMB3) share optimized for mixed Windows/macOS environments, handle USB Attached SCSI (UAS) quirks, and implement robust error handling for drive mounting.

Hardware Spec Sheet & Parts List

The most common failure point in a Pi-based NAS is inadequate power delivery to the USB storage controller, leading to silent filesystem corruption. The official 27W USB-C PD power supply is mandatory for the Pi 5 when driving external SSDs.

Interface, Pin Mapping & Power Delivery

While a Pi doesn't have traditional 'wiring' like a microcontroller, mapping the physical interfaces and GPIO pins used by the enclosure and storage is critical for debugging hardware-level faults.

Network & Filesystem Tuning

Before installing Samba, we must optimize the underlying filesystem and network stack. Flash-based SSDs degrade quickly if the OS constantly updates file access timestamps. Furthermore, the default Linux TCP window scaling can leave Gigabit transfers stuttering on high-latency local networks.

When formatting your drive, use ext4 with the noatime and discard flags. The noatime flag prevents the kernel from writing to the disk every time a file is merely read, drastically reducing I/O wait times and extending the SSD's lifespan. The discard flag enables continuous TRIM, which is essential for maintaining write speeds on USB-attached flash storage.

For network tuning, edit /etc/sysctl.conf and append the following to increase the TCP receive buffer and enable BBR congestion control, which significantly stabilizes Samba throughput over WiFi-to-Ethernet bridged connections:

net.core.rmem_max = 2500000
net.ipv4.tcp_congestion_control = bbr

Samba Configuration & Error Handling

The following bash script automates the installation of Samba, formats the attached USB drive to ext4, configures fstab for persistent mounting, and writes an optimized smb.conf. It includes strict error handling via set -euo pipefail and a trap to prevent partial configurations if the drive format fails.

Target Board: Raspberry Pi 5 (8GB) | OS: Bookworm 64-bit

#!/bin/bash
# Samba NAS Setup Script for Raspberry Pi 5
set -euo pipefail

DRIVE='/dev/sda1'
MOUNT_POINT='/mnt/nas_data'
SHARE_NAME='PiNAS'
SMB_USER='pi'

cleanup() {
  echo "[ERROR] Setup failed at line $1. Check drive connection and permissions."
  systemctl stop smbd nmbd 2>/dev/null || true
}
trap 'cleanup $LINENO' ERR

echo "Updating packages and installing Samba..."
sudo apt-get update && sudo apt-get install -y samba samba-common-bin exfat-fuse

echo "Formatting $DRIVE to ext4 with noatime..."
sudo umount $DRIVE 2>/dev/null || true
sudo mkfs.ext4 -F -L 'NAS_DATA' $DRIVE

sudo mkdir -p $MOUNT_POINT
UUID=$(sudo blkid -s UUID -o value $DRIVE)
echo "UUID=$UUID $MOUNT_POINT ext4 defaults,noatime,discard,nofail 0 2" | sudo tee -a /etc/fstab
sudo mount -a

echo "Configuring Samba..."
sudo cp /etc/samba/smb.conf /etc/samba/smb.conf.bak
cat <