Qwerty Samba UI

Qwerty Samba UI is a local-first controller and lightweight agent for centrally viewing simple Samba/SMB servers on a LAN.

Structure

• backend/ FastAPI controller with SQLite.
• frontend/ React + Vite admin UI.
• agent/ Python standard-library agent prototype.
• scripts/ controller and agent install helpers.
• packaging/systemd/ service unit templates.
• docs/ design and safety notes.

See docs/apt-packaging.md for building and publishing qwerty-samba-ui and qwerty-samba-agent Debian packages.

Controller Defaults

• Host: 0.0.0.0
• Port: 8443
• Config: /etc/qwerty-samba-ui/
• Data: /var/lib/qwerty-samba-ui/
• Database: /var/lib/qwerty-samba-ui/qwerty-samba-ui.db
• HTTPS: enabled, self-signed cert generated outside the repo

Agent Defaults

• Config: /etc/qwerty-samba-agent/agent.env
• State: /var/lib/qwerty-samba-agent/
• Poll interval: 30 seconds
• Samba config: /etc/samba/smb.conf

Local Development

Backend:

cd backend
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
QSU_CONFIG_DIR=/tmp/qwerty-samba-ui \
QSU_DATA_DIR=/tmp/qwerty-samba-ui \
QSU_DATABASE_PATH=/tmp/qwerty-samba-ui/qwerty-samba-ui.db \
QSU_HTTPS_ENABLED=false \
QSU_RELOAD=true \
QSU_FRONTEND_DIST_PATH=$(pwd)/../frontend/dist \
QSU_JWT_SECRET=dev-secret \
QSU_ADMIN_USERNAME=admin \
QSU_ADMIN_PASSWORD=admin \
python run.py

Frontend dev server:

cd frontend
npm install
VITE_API_BASE=http://localhost:8443 npm run dev

Production-style local frontend serving:

cd frontend
npm install
npm run build
cd ../backend
. .venv/bin/activate
QSU_CONFIG_DIR=/tmp/qwerty-samba-ui \
QSU_DATA_DIR=/tmp/qwerty-samba-ui \
QSU_DATABASE_PATH=/tmp/qwerty-samba-ui/qwerty-samba-ui.db \
QSU_HTTPS_ENABLED=false \
QSU_FRONTEND_DIST_PATH=$(pwd)/../frontend/dist \
QSU_JWT_SECRET=dev-secret \
QSU_ADMIN_USERNAME=admin \
QSU_ADMIN_PASSWORD=admin \
python run.py

Agent one-shot registration against local dev backend:

cd agent
QSA_CONTROLLER_URL=http://localhost:8443 \
QSA_STATE_PATH=/tmp/qwerty-samba-agent \
QSA_VERIFY_TLS=false \
python3 -m qwerty_samba_agent.main register

After approving the pending node in the UI, run registration again so the agent can claim and store its permanent token:

QSA_CONTROLLER_URL=http://localhost:8443 \
QSA_STATE_PATH=/tmp/qwerty-samba-agent \
QSA_VERIFY_TLS=false \
python3 -m qwerty_samba_agent.main register

Then send a heartbeat:

QSA_CONTROLLER_URL=http://localhost:8443 \
QSA_STATE_PATH=/tmp/qwerty-samba-agent \
python3 -m qwerty_samba_agent.main heartbeat

Debian Controller Install

For apt-based deployment, build/publish the packages and install qwerty-samba-ui. See docs/apt-packaging.md.

From a repository checkout on the Debian 13 controller, the development installer is also available:

sudo scripts/install-controller.sh
sudo systemctl start qwerty-samba-ui

The installer creates /etc/qwerty-samba-ui/controller.env with mode 0600. The first browser visit creates the initial local administrator account.

Agent Install

On a Samba host:

sudo scripts/install-agent.sh https://CONTROLLER_IP:8443
sudo systemctl start qwerty-samba-agent

The agent config lives in /etc/qwerty-samba-agent/agent.env. The agent performs outbound registration and heartbeat only.

Samba Node Actions

Approved Debian/Ubuntu Samba agents can run limited write actions from the node detail page:

• create a Samba user, optionally creating the matching local Unix account first
• create a new share by appending a validated share block to smb.conf

The controller queues tasks; agents pick them up on their normal outbound poll. No inbound port is opened on the Samba node.

Share creation follows the safe config workflow: write a candidate config, validate it with testparm, back up the existing smb.conf, replace only after validation succeeds, then reload Samba. The first write-capable release does not edit or delete existing shares.

Samba user passwords are sent to the approved agent over the existing HTTPS agent channel and are redacted from stored task payloads after completion. Treat the controller database as sensitive.

TrueNAS Monitoring

TrueNAS is monitored remotely through its JSON-RPC 2.0 WebSocket API. Do not install the Debian SMB agent on TrueNAS.

1. In the TrueNAS UI, create an API key from the user/settings API key screen.
2. Copy the key immediately; TrueNAS only shows it once.
3. In Qwerty Samba UI, use Add Server and fill in the TrueNAS form.
4. Use this endpoint format:

wss://TRUENAS-IP/api/current

Use verify_tls=false for self-signed lab certificates. Use verify_tls=true for a trusted certificate.

The connector is read-only monitoring initially. It collects system info, pools, SMB shares, users, alerts, services, and interfaces. API keys are stored centrally in the controller database for now; encryption is a TODO before broader production rollout. API keys are never returned to the frontend after save and should not be logged.

Standalone connection test from a checkout:

backend/.venv/bin/pip install -r backend/requirements.txt
scripts/test-truenas-connection.py wss://TRUENAS-IP/api/current --no-verify-tls

Add --snapshot to collect the normalized monitoring payload.

Remote Repository Credentials

Do not put tokens in the repository. When cloning or pushing is needed, create a root-owned env file outside the repo:

sudo install -d -m 0700 /etc/qwerty-samba-ui
sudo sh -c 'umask 077; cat > /etc/qwerty-samba-ui/repo.env <<EOF
QSU_REPO_TOKEN=replace-with-token
EOF'

Then load it only for the git operation:

set -a
. /etc/qwerty-samba-ui/repo.env
set +a
git clone "https://oauth2:${QSU_REPO_TOKEN}@repo.calhta.com/calum/qwerty-samba.git"

Safety Status

This skeleton does not implement destructive Samba editing. Configuration inventory is read-only. See docs/config-safety.md for the required future write workflow.