nasberrypi

Simple Raspberry Pi NAS management system with guided storage setup, Samba sharing, safe-mode controls, and one-command network storage deployment.

Turn a Raspberry Pi and a USB storage device into a personal network-attached storage server with guided setup, simplified administration, and built-in recovery tools.

---

FEATURES

Storage Management

• Guided storage setup wizard
• Automatic drive detection
• Mount and unmount controls
• NAS-mode and external mount awareness
• Storage validation and storage-only status reporting
• Safe storage handling and recovery

Network Sharing

• Samba-based network file sharing
• Automatic multiple shared-folder configuration
• Cross-platform device compatibility
• Share status monitoring
• Share user management

Safety & Recovery

• Panic Lock emergency shutdown
• Safe Mode protection
• Service validation checks
• Samba repair utilities
• Startup service management

Administration

• Interactive terminal dashboard
• Storage and share status reporting
• Configuration management
• Mount point visibility
• Share user visibility

---

NASBERRY STATES

State	Purpose
Offline	Storage safely unmounted and sharing offline
Mounted	Storage mounted in NAS mode or mounted elsewhere
Shared	Storage mounted in NAS mode and sharing online
Safe Mode	Sharing services disabled until manually started
Panic Lock	Emergency shutdown of active shares

Each state is designed to provide visibility into the current status of your NAS while keeping storage management simple and predictable.

---

SCREENSHOTS

Main Dashboard

sudo nasberry

---

Nasberry Setup

Configure storage devices, mount points, and NAS settings.

sudo nasberry setup

---

Nasberry Diagnostics

Run a complete health check of storage, Samba, permissions, configuration, and system requirements.

sudo nasberry doctor

---

Active File Sharing

Network share running and accessible from other devices.

---

Emergency lock

Immediately stop sharing services and secure storage access.

---

INSTALLATION

git clone https://github.com/WastelandSYS/nasberrypi.git
cd nasberrypi
chmod +x install.sh uninstall.sh
sudo ./install.sh

Launch with:

sudo nasberry

Nasberry currently supports Debian-family systems that provide apt-get, including Raspberry Pi OS, Debian, Ubuntu, and Kali Linux.

---

UNINSTALLATION

cd nasberrypi
sudo ./uninstall.sh

The uninstaller removes the global nasberry shortcut and related application files. It does not remove your cloned repository folder.

Preview an uninstall without changing the system:

sudo ./uninstall.sh --dry-run

Use --purge to also remove Nasberry's configuration and managed Samba settings. Storage data is never deleted. Run sudo ./uninstall.sh --help for all options.

---

QUICK START

1. Connect Storage

Attach a USB SSD, HDD, or flash drive to your Raspberry Pi.

2. Launch NasberryPi

sudo nasberry

3. Run Storage Setup

Use the setup wizard to configure your storage device and mount point.

4. Configure Share Access

Create or configure your Samba share user.

5. Start File Sharing

Enable network sharing through the dashboard.

6. Connect From Another Device

Windows:

\\hostname\Public

macOS/Linux:

smb://hostname/Public

Public remains the default shared folder. Add more managed shares with:

sudo nasberry shares

Android:

Use an SMB-compatible file manager such as:

• CX File Explorer
• Solid Explorer
• X-plore File Manager

Server:

hostname

Port:

445

Sign in using your Nasberry username and password.

iPhone / iPad:

1. Open the Files app
2. Tap the menu button
3. Select Connect to Server
4. Enter:

smb://hostname

5. Sign in using your Nasberry username and password.

---

USAGE

Launch the dashboard:

sudo nasberry

Main management functions:

Option	Description
Setup Storage	Configure NAS storage device
Mount Storage	Mount configured storage in NAS mode
Unmount Storage	Safely unmount storage
Start Share	Enable network file sharing
Stop Share	Disable network file sharing
Manage Shares	Add, remove, enable, disable, or toggle read-only shared folders
Repair Samba	Repair Samba configuration
Safe Mode CLI	Disable automatic sharing services
Panic Lock	Immediate shutdown of sharing services
Status Dashboard	View NAS health and status

Help menu:

nasberry -h

Storage-only status:

sudo nasberry storage

This reports the configured storage device, whether it is present, its filesystem, mount state, active mount point, configured Nasberry mount point, and disk space. Mount state is reported as mounted in NAS mode, mounted elsewhere, or safely unmounted.

If nasberry mount finds the configured drive mounted elsewhere, interactive use shows the current and configured Nasberry mount points and asks before moving the drive into NAS mode. Press Enter or answer n to leave the existing mount untouched.

---

COMPATIBILITY

Designed primarily for Linux systems.

Tested on:

• Raspberry Pi OS
• Kali Linux ARM
• Raspberry Pi 4B
• Raspberry Pi 5
• Raspberry Pi Zero 2w

Supported storage:

• USB SSD
• USB HDD
• USB Flash Drive

Supported clients:

• Windows
• Linux
• macOS
• Android
• iOS

Notes:

• Samba is installed automatically by the installer.
• ext4 is the recommended filesystem for Linux-based NAS deployments.
• Desktop environments may mount a configured drive outside the Nasberry mount point. Nasberry reports this as mounted elsewhere and asks before moving it into NAS mode.
• Setup creates a default Public share and stores managed shared folders in /etc/nasberry/shares.json.
• Nasberry updates only the clearly marked NasberryPi section in /etc/samba/smb.conf. The previous file is backed up before changes, and unrelated Samba configuration is preserved.
• Network share discovery behavior may vary by operating system.

---

RECOVERY

Nasberry validates a candidate Samba configuration before replacing the live configuration and saves the previous configuration as /etc/samba/smb.conf.nasberry.<timestamp>.bak.

To inspect available backups:

sudo ls -1 /etc/samba/smb.conf.nasberry.*.bak

Before restoring a backup, validate it with testparm. Take Nasberry offline first, copy the selected backup to /etc/samba/smb.conf, validate the restored file, and restart Samba:

sudo nasberry offline
sudo testparm -s /etc/samba/smb.conf.nasberry.<timestamp>.bak
sudo cp /etc/samba/smb.conf.nasberry.<timestamp>.bak /etc/samba/smb.conf
sudo testparm -s /etc/samba/smb.conf
sudo systemctl restart smbd

Nasberry's core configuration is stored at /etc/nasberry/config.ini, and managed shared folders are stored at /etc/nasberry/shares.json. Run sudo nasberry doctor for diagnostics, sudo nasberry shares to manage folders, or sudo nasberry repair-samba to recreate and validate the managed Samba section.

---

SECURITY

The Nasberry PIN protects selected actions within Nasberry. It does not replace Linux account security, Samba passwords, SSH security, disk encryption, or physical security.

Nasberry performs privileged storage and Samba administration. Review release notes before upgrading, keep backups of important data, and test storage-related changes with a disposable drive first.

---

WHY NASBERRYPI?

NasberryPi was built to simplify self-hosted network storage.

Instead of manually configuring Samba, mount points, permissions, and services, NasberryPi provides a guided interface that transforms a Raspberry Pi and a storage device into a reliable personal NAS in minutes.

The project focuses on:

• simple deployment
• safe storage handling
• reliable file sharing
• recovery and repair tools
• lightweight terminal administration

---

LICENSE

NasberryPi is released under the GNU General Public License v3.0. See LICENSE for the full license text.

---

AUTHOR

WastelandSYS