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:

```bash
modprobe nfsd
echo nfsd >> /etc/modules
```

## Install

Run everything below **inside the LXC container** as root.

### 1. System dependencies

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

Enable Apache WebDAV modules:

```bash
a2enmod dav dav_fs auth_basic authn_file
systemctl restart apache2
```

### 2. Clone the repo

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

### 3. Python environment

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

### 4. Config directory

```bash
mkdir -p /etc/micronas
chmod 700 /etc/micronas
```

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

### 5. systemd service

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

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

---

## Updates

```bash
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

```bash
# 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.

## Upgrading from an older install (path migration)

If you installed MicroNAS before the `/etc/micronas/` directory was introduced, run this once:

```bash
mkdir -p /etc/micronas
[ -f /etc/micronas.env ] && mv /etc/micronas.env /etc/micronas/micronas.env
[ -f /etc/micronas-webdav.passwd ] && mv /etc/micronas-webdav.passwd /etc/micronas/webdav.passwd
chown root:www-data /etc/micronas/webdav.passwd
chmod 640 /etc/micronas/webdav.passwd
# Patch the Apache config if it still references the old path
sed -i 's|/etc/micronas-webdav.passwd|/etc/micronas/webdav.passwd|' \
    /etc/apache2/conf-available/micronas-webdav.conf
cp /opt/micronas/micronas.service /etc/systemd/system/
systemctl daemon-reload && systemctl restart micronas && systemctl reload apache2
```

---

## 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.

**Rename** — the Rename button in the Users tab renames the Linux account (`usermod -l`). Because SMB and WebDAV store passwords by username, those entries are removed and must be reset after a rename. The UI shows a warning prompt.

**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:

```bash
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:

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

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

```bash
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)

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

```bash
# 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

```bash
# 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).

```bash
# 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

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

# Unmount
umount /mnt/nas

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