76 lines
4.1 KiB
Markdown
76 lines
4.1 KiB
Markdown
# Safe Kiddo Daemon
|
|
|
|
Service to lock/unlock local user accounts on kids' laptops with countdown, notifications, optional sound, and shutdown. Provides a REST API plus a small web UI for remote control; retains the original `sk.sh` script as legacy/CLI fallback.
|
|
|
|
## Features
|
|
- Disable/enable accounts, terminate sessions, optionally trigger shutdown.
|
|
- Desktop notifications and optional sound during countdown.
|
|
- Login-protected API with minimal web UI (PAM auth for root users, bearer token for calls).
|
|
- Systemd-managed service, virtualenv-based deploy, remote update script.
|
|
- Dry-run mode to validate flows without touching accounts.
|
|
|
|
## Quick Start (Local/Target Device)
|
|
```bash
|
|
git clone <repo> /opt/sk
|
|
cd /opt/sk
|
|
./scripts/install.sh
|
|
sudo systemctl status skd.service
|
|
```
|
|
Then open `http://localhost:8000/` and set the API token in the UI.
|
|
|
|
## Configuration
|
|
Set in `/etc/skd/env` (see `env.example`):
|
|
- `SKD_AUTH_SECRET`: HMAC secret for bearer tokens (set a strong value).
|
|
- `SKD_TOKEN_TTL_SECONDS`: token lifetime (default 900s).
|
|
- `SKD_AUTH_ALLOWED_USERS`: optional comma list of accounts allowed to log in.
|
|
- `SKD_AUTH_ALLOWED_GROUPS`: groups whose members may log in (default `sudo`).
|
|
- `SKD_ALLOWED_USERS`: optional comma list to limit manageable accounts (must exist on the system).
|
|
- `SKD_DEFAULT_COUNTDOWN`, `SKD_DEFAULT_SOUND`, `SKD_NOTIFY_TIMEOUT`: behavior defaults.
|
|
- `SKD_DRY_RUN=true` to test without real account changes or shutdown.
|
|
- `SKD_SOUND_PLAYER`/`SKD_SOUND_FILE`, `SKD_NOTIFY_SEND_PATH` if defaults differ.
|
|
Notes:
|
|
- `./scripts/install.sh` will create `/etc/skd/env` from `env.example` if missing (edit afterwards) and ensure the `skd` service user/group exist.
|
|
|
|
## Running
|
|
- Service: managed by systemd; `./scripts/install.sh` writes the unit dynamically to `/etc/systemd/system/skd.service` with the current repo path and restarts it.
|
|
- Manual run: `./scripts/run.sh` (uses `.venv`, defaults to `0.0.0.0:8000`).
|
|
- Login: `curl -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost:8000/login`
|
|
- Health: `curl -H "Authorization: Bearer <token>" http://localhost:8000/health`
|
|
|
|
## API (Bearer token via `/login`)
|
|
- `GET /users` → `[{user, logged_in}]` (manageable system users; excludes root)
|
|
- `POST /users/{name}/disable` with JSON `{countdown?, sound?, message?}`
|
|
- `POST /users/{name}/enable`
|
|
- `GET /health`
|
|
|
|
Example:
|
|
```bash
|
|
token=$(curl -s -X POST -H "Content-Type: application/json" -d '{"username":"root","password":"..."}' http://localhost:8000/login | jq -r .token)
|
|
curl -X POST -H "Authorization: Bearer $token" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"countdown":90,"sound":true}' \
|
|
http://localhost:8000/users/child1/disable
|
|
```
|
|
|
|
## Web UI
|
|
Served at `/`. Login mit Root-Account, danach werden verfügbare System-User angezeigt; Aktionen senden Bearer Token automatisch.
|
|
|
|
## Updates
|
|
- Remote update via SSH: `ssh user@kid-laptop 'cd /opt/sk && ./scripts/update.sh'` (fetch/reset to `origin/main`, reinstalls deps, restarts service).
|
|
- Manual: `git pull && source .venv/bin/activate && pip install -r backend/requirements.txt && sudo systemctl restart skd`
|
|
|
|
## Deployment (zip/SSH)
|
|
- Quick copy: create `sk_deploy.zip` (already in repo root) and unzip on target under `/opt/sk`, then refresh venv deps and restart service.
|
|
- Scripted deploy: edit `deploy_hosts.yml` (host/user/port/install_dir/service user/group), then run `./scripts/deploy.sh <host-name>`; accepts JSON configs too. Requires SSH access and `sudo` on target.
|
|
- After deploy on target: `sudo -u skd /opt/sk/.venv/bin/pip install -r /opt/sk/backend/requirements.txt && sudo systemctl restart skd.service`
|
|
|
|
## Security Hardening
|
|
- Restrict access to API/Web UI to LAN/VPN; firewall the port.
|
|
- Set a strong `SKD_AUTH_SECRET`; rotate tokens by changing the secret.
|
|
- Create dedicated `skd` user/group; no login shell.
|
|
- Configure sudoers minimally: allow `skd` to run `usermod -L/-U`, `pkill -KILL -u`, `shutdown now`, and sound/notify binaries if needed (no full passwordless sudo).
|
|
- Consider mTLS or IP allowlisting for added protection.
|
|
|
|
## Legacy Script
|
|
`sk.sh` remains for direct SSH use. Plan to replace its logic with API-backed helpers; keep it as emergency fallback.
|