MicroNAS/README.md

MicroNAS

Lightweight web GUI to manage SMB shares, NFS exports, and users on a single home server (Proxmox LXC/VM). Runs directly on the host as a systemd service.

Proxmox LXC setup

Use a privileged Debian/Ubuntu container — required for the NFS server kernel module and quotas.

On the Proxmox host, load the NFS kernel module before starting the container:

modprobe nfsd
echo nfsd >> /etc/modules

Install

Run everything below inside the LXC container as root.

1. System dependencies

apt update
apt install -y git samba nfs-kernel-server apache2 apache2-utils python3 python3-venv

Enable Apache WebDAV modules:

a2enmod dav dav_fs auth_basic authn_file
systemctl restart apache2

2. Clone the repo

git clone https://gitea.honeyy.duckdns.org/Honey/MicroNAS.git /opt/micronas

3. Python environment

python3 -m venv /opt/micronas/venv
/opt/micronas/venv/bin/pip install flask gunicorn

4. Config directory

mkdir -p /etc/micronas
chmod 750 /etc/micronas
chown root:www-data /etc/micronas

Credentials are set on first login via the /setup page in the browser. No manual env file editing needed.

5. systemd service

cp /opt/micronas/micronas.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now micronas

Open http://<lxc-ip>:5000 in your browser.

---

Updates

cd /opt/micronas
git pull
systemctl restart micronas

Network

The service binds to 0.0.0.0:5000 — accessible from any LAN device at http://<lxc-ip>:5000.

For HTTPS, put nginx in front as a reverse proxy.

LAN or Tailscale only — never expose to the internet.

Dev / test

# Quick local run (no gunicorn needed, must have flask installed):
MICRONAS_USER=admin MICRONAS_PASS_HASH="$(python3 -c "
import hashlib, os
s=os.urandom(16).hex()
h=hashlib.pbkdf2_hmac('sha256',b'secret',s.encode(),260000).hex()
print(f'{s}\${h}')
")" flask --app app.py run --debug --host=0.0.0.0

Or use plaintext for dev only (still supported): MICRONAS_USER=admin MICRONAS_PASS=secret flask --app app.py run --debug

Note: SMB/NFS/user management calls require root and the relevant daemons — run on the actual LXC for full testing.

Auth

All routes require a login session. On first run you are redirected to /setup to create the admin account. Credentials are stored hashed (PBKDF2-HMAC-SHA256, 260 000 iterations) in /etc/micronas/micronas.env. The WebDAV htpasswd file lives at /etc/micronas/webdav.passwd (group-readable by www-data, not world-readable).

Changing the admin password — click the ⚙ Settings button in the top-right corner. Enter your current password to confirm, then set a new username and/or password. You will be logged out automatically and redirected to login.

---

User management

Users created in MicroNAS are standard Linux system accounts (useradd -M -s /usr/sbin/nologin). Their password is set in both the Linux shadow file (via smbpasswd) and the WebDAV htpasswd file automatically.

Delete — removes the Linux account, SMB entry, and WebDAV htpasswd entry.

Password change — updates SMB and WebDAV passwords in sync. Changing a user's password also re-registers them in WebDAV if they were created before WebDAV was installed.

---

Share settings reference

SMB share settings

Valid Users — who is allowed to connect to the share. Checked by Samba before the OS even looks at folder permissions. Separate multiple entries with a space or comma. Prefix with @ for a whole group.

alice bob          → only alice and bob can connect
@family            → everyone in the 'family' group
alice @family      → alice plus everyone in family

Folder Permissions (Owner / Group / Mode) — the actual Linux filesystem permissions on the shared folder. Applied by chown/chmod on the server. Valid Users controls the door; folder permissions control what's inside.

Mode	Meaning
770	Owner and group have full read/write. Everyone else: nothing.
750	Owner: read/write. Group: read-only. Others: nothing.
755	Owner: read/write. Group + others: read-only.

Force Group — every file written through this share gets assigned to this group, regardless of who the connecting user is. Solves the mixed-ownership problem on shared folders: Alice writes a file, it belongs to group family, Bob (also in family) can edit it.

Typical shared folder recipe:

1. Create group family in the Users tab, add all users to it
2. Share: Valid Users → @family, Force Group → family
3. Folder: Group → family, Mode → 770

Force User — more extreme version: all writes appear as one specific user. Useful when a service (Plex, Jellyfin, etc.) needs to own everything in a media folder.

Guest OK — allows connecting without any username or password. Anyone on the network can access the share. Good for a public read-only share (combine with a 755 folder mode so guests can read but not write). For a writable guest share, set mode 777 — but only do this on a fully trusted LAN.

Read only — clients can read files but not write, rename, or delete anything. Overrides writable setting.

Recycle Bin — when enabled, files deleted through the share go to a .recycle folder inside the share instead of being permanently gone. Clients (Windows Explorer, Nautilus) can browse and restore from there. Files stay until you manually delete them — there is no automatic expiry. To clean files older than 30 days add a cron job:

find /srv/yourshare/.recycle -mtime +30 -delete

---

WebDAV share settings

WebDAV is served by Apache on port 80. Shares are accessible at http://<nas-ip>/dav/<name>. Auth is HTTP Basic (username + password), managed via an htpasswd file that MicroNAS keeps in sync with the Users tab automatically.

Allowed Users — space-separated list of usernames who can access this share. Leave empty to allow all users in the htpasswd file (anyone with a MicroNAS account). Groups (@groupname) are not supported for WebDAV — list individual usernames.

alice bob       → only alice and bob
                → (empty) anyone with a valid MicroNAS password

Password sync — when you create a user or change a password in the Users tab, MicroNAS automatically updates the WebDAV htpasswd file. Users created before WebDAV was installed need their password changed once to register.

Folder Permissions — same as SMB: owner, group, and mode on the actual folder on disk. WebDAV clients write files as the Apache process user (www-data by default), so the folder needs to be writable by www-data or you need to set force group equivalent at the OS level. Simplest setup:

chown www-data:www-data /srv/yourfolder
chmod 775 /srv/yourfolder

Or give your group write access and add www-data to that group:

usermod -aG family www-data
# Then set folder: group=family, mode=775

No toggle/disable — WebDAV shares can only be created or deleted, not temporarily disabled. To block access temporarily, remove the users or delete and recreate the share.

---

NFS export settings

NFS has no username/password concept — access is controlled by IP/hostname only (the Clients field). Once connected, the client's UID/GID is passed to the server and Linux file permissions apply normally.

Clients — who can mount the export. Use an IP, subnet, or * for everyone.

*                   → anyone
192.168.1.0/24      → one subnet
192.168.1.10        → one specific host
192.168.1.0/24 10.0.0.0/8   → two networks (space-separated)

Read only — mount is read-only for the client, regardless of folder permissions.

no_root_squash — by default, NFS maps root on the client (uid 0) to the anonymous nobody user on the server (root squashing). This prevents a compromised client from owning all server files as root. no_root_squash disables that mapping — root on the client stays root on the server. Useful when you manage both machines and need to run chown/chmod on mounted shares.

all_squash — maps every client user to the anonymous nobody user (or a custom anonuid). Nobody can impersonate their UID from the client. Simple for single-user setups where you just want consistent ownership on the server side.

---

Mounting shares on a Linux client

Replace <nas-ip> with your LXC's IP address throughout.

SMB (Samba)

# Install client tools
apt install cifs-utils

# One-time mount
mount -t cifs //<nas-ip>/sharename /mnt/nas -o username=youruser,password=yourpass

# Permanent — add to /etc/fstab:
//<nas-ip>/sharename  /mnt/nas  cifs  username=youruser,password=yourpass,_netdev  0  0

For better security, store credentials in a file instead of putting them in fstab:

# Create /etc/nas-credentials (root-only):
cat > /etc/nas-credentials <<EOF
username=youruser
password=yourpass
EOF
chmod 600 /etc/nas-credentials

# Then in /etc/fstab:
//<nas-ip>/sharename  /mnt/nas  cifs  credentials=/etc/nas-credentials,_netdev  0  0

NFS

# Install client tools
apt install nfs-common

# One-time mount
mount -t nfs <nas-ip>:/srv/data /mnt/nas

# Permanent — add to /etc/fstab:
<nas-ip>:/srv/data  /mnt/nas  nfs  defaults,_netdev  0  0

_netdev tells the system to wait for the network before mounting — important for both SMB and NFS so the mount doesn't fail on boot.

Multiple networks (e.g. LAN + Tailscale): enter both subnets space-separated in the Clients field when creating the export, e.g. 192.168.1.0/24 100.64.0.0/10. Both get the same ro/rw setting.

WebDAV

WebDAV shares are served by Apache at http://<nas-ip>/dav/<sharename> (port 80).

# Mount WebDAV on Linux (davfs2)
apt install davfs2
mount -t davfs http://<nas-ip>/dav/photos /mnt/webdav -o username=alice

# Permanent — /etc/fstab:
http://<nas-ip>/dav/photos  /mnt/webdav  davfs  username=alice,_netdev  0  0
# Store password in /etc/davfs2/secrets:
http://<nas-ip>/dav/photos alice yourpassword

On Windows: open File Explorer → "Map network drive" → \\<nas-ip>\DavWWWRoot\dav\photos (WebDAV via WebClient service), or use http://<nas-ip>/dav/photos directly in the address bar.

On Mac: Finder → Go → Connect to Server → http://<nas-ip>/dav/photos.

User passwords are synced automatically — when you set a password in the Users tab it is also written to the WebDAV htpasswd file. Existing users created before WebDAV was set up need their password changed once to register.

Useful commands

# List available NFS exports from the server
showmount -e <nas-ip>

# Unmount
umount /mnt/nas

# Mount all fstab entries (after editing fstab)
mount -a