97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# Fileshare Web — Planning
|
|
|
|
A lightweight web GUI to manage file shares on a single home server — like a
|
|
minimal NAS control panel for a Proxmox LXC/VM. Manages **SMB shares**,
|
|
**NFS exports**, and **quotas** by editing the host config files and reloading
|
|
the daemons.
|
|
|
|
**Design principle: keep it small.** Single box, home/LAN use only, no database,
|
|
no auth framework, dependency-light. If a feature needs heavy machinery, it's
|
|
out of scope.
|
|
|
|
---
|
|
|
|
## Deployment decision
|
|
|
|
Run **directly on the LXC/VM as a `systemd` service** (Flask behind `gunicorn`).
|
|
**Not** Docker.
|
|
|
|
Reason: this app's whole job is to manipulate *host* services (`smbd`, `nfsd`,
|
|
`/etc/exports`, `exportfs`, `setquota`). Containerizing it means bind-mounting
|
|
host config, running privileged, and fighting the kernel NFS server — all the
|
|
downsides of running on the host with none of the isolation benefit. Docker is
|
|
kept only as an optional dev/test sandbox.
|
|
|
|
**Network:** LAN-only. Never expose to the internet. Reach it via local network
|
|
or Tailscale. Auth is a safety net, not an internet-facing defense.
|
|
|
|
**Backups:** Out of scope. Handled at the Proxmox layer (Proxmox Backup Server
|
|
on a second client). This app does not implement backup.
|
|
|
|
---
|
|
|
|
## Current state (baseline)
|
|
|
|
- `app.py` — Flask API: list/create SMB & NFS shares, set quotas.
|
|
- `index.html` — Bootstrap UI with SMB / NFS / Quotas tabs.
|
|
- `docker-compose.yml` — test sandbox.
|
|
|
|
### Known issues to fix
|
|
- `parse_smb()` is called (`app.py:13`) but never defined → `/api/shares` 500s.
|
|
- `subprocess.run(cmd, shell=True)` with f-string input (`app.py:82`) → command
|
|
injection as root.
|
|
- `add_smb_share` writes raw user input into `smb.conf` → config injection via
|
|
newlines.
|
|
- No authentication on any route.
|
|
- Config is append-only (`open(..., 'a')`) → no working delete/edit; UI Delete
|
|
buttons are wired to nothing.
|
|
- No input validation on names or paths (path traversal, share of `/`).
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
### Phase 1 — Correctness & safety (must-have)
|
|
- [ ] Implement `parse_smb()` so `/api/shares` works.
|
|
- [ ] Remove all `shell=True`; use argument-list `subprocess` calls.
|
|
- [ ] Validate input:
|
|
- share/user names: `^[A-Za-z0-9_-]+$`
|
|
- paths must resolve under `/srv`
|
|
- reject anything else with a clear error.
|
|
- [ ] Simple login: HTTP Basic Auth, single user + password from env var,
|
|
protecting all routes.
|
|
- [ ] `systemd` unit + `gunicorn`, plus README run instructions.
|
|
|
|
### Phase 2 — Dashboard & health (the main goal)
|
|
A landing page that shows the state of the server at a glance:
|
|
- [ ] **Daemon status** — is `smbd` running? is `nfsd` running? (green/red).
|
|
- [ ] **Disk usage** — free / used / total for `/srv` (and per-disk if simple).
|
|
- [ ] **All shares in one view** — every SMB share and NFS export, their paths,
|
|
and who can access them.
|
|
- [ ] **Per-share data used** — size on disk of each share's path (`du`).
|
|
- [ ] **Quota usage** — for each user with a quota: used vs limit, with a
|
|
progress bar (e.g. "12 GB / 50 GB").
|
|
- [ ] Auto-refresh or a manual refresh button.
|
|
|
|
### Phase 3 — Full management (complete the CRUD)
|
|
- [ ] Working **delete** for SMB & NFS (parse config into blocks, rewrite the
|
|
whole file — not append-only).
|
|
- [ ] **Edit** existing shares.
|
|
- [ ] Enable/disable a share without deleting it.
|
|
|
|
### Phase 4 — Nice-to-have
|
|
- [ ] **WebDAV** support. Preferred approach: don't build it in Flask — have the
|
|
app drop an Apache/nginx WebDAV config snippet, same pattern as SMB/NFS,
|
|
so it reuses the existing architecture.
|
|
- [ ] Simple in-browser file browser for `/srv`.
|
|
- [ ] Toast notifications instead of `alert()`.
|
|
|
|
---
|
|
|
|
## Out of scope (intentionally)
|
|
- Backups (Proxmox Backup Server handles this).
|
|
- Multi-user accounts / roles (single admin login is enough).
|
|
- Database (config files are the source of truth).
|
|
- Internet exposure / TLS termination (LAN + Tailscale only).
|
|
- Clustering / multi-host management.
|