101 lines
3.1 KiB
Markdown
101 lines
3.1 KiB
Markdown
ID: DOC_000010 | Version: 0.2.1 | Status: Draft
|
|
By: Codex (GPT-5)
|
|
|
|
# Usage
|
|
|
|
## Authentifizierung
|
|
- PAM-Login: `POST /login` mit Benutzername/Passwort. Liefert JWT und setzt Session-Cookie.
|
|
- OIDC-Login: `GET /login/oidc/start` startet Flow, Callback setzt Session-Cookie.
|
|
- Alle geschuetzten Endpunkte akzeptieren `Authorization: Bearer $TOKEN` oder Session-Cookie.
|
|
|
|
### Beispiel: Login und Token nutzen
|
|
```bash
|
|
token=$(curl -s -X POST -H "Content-Type: application/json" \
|
|
-d '{"username":"root","password":"example-password"}' \
|
|
http://localhost/login | jq -r .token)
|
|
|
|
curl -s -H "Authorization: Bearer $token" http://localhost/me
|
|
```
|
|
Hinweis: `jq` ist optional; ohne jq das Token manuell aus der JSON-Antwort lesen.
|
|
Login ist nur fuer erlaubte Nutzer moeglich (siehe `SKD_AUTH_ALLOWED_USERS` und `SKD_AUTH_ALLOWED_GROUPS`).
|
|
|
|
## Web-UI
|
|
- Aufruf: `http://localhost/`
|
|
- Login per PAM oder OIDC (wenn konfiguriert).
|
|
- Aktionen: Benutzer sperren/entsperren, Update-Status, Update-Check, Apply/Rollback.
|
|
|
|
## Automatisierung (Power-User)
|
|
Die API kann in Skripten oder Zeitplaenen genutzt werden, z.B. fuer regelmaessige Sperrungen.
|
|
|
|
Beispiel (cron, taeglich 21:00 sperren):
|
|
```bash
|
|
0 21 * * * curl -s -X POST -H "Authorization: Bearer $TOKEN" http://localhost/users/child1/disable
|
|
```
|
|
Hinweis: Token sicher speichern (z.B. Root-Only Datei) und regelmaessig rotieren.
|
|
|
|
## API-Endpunkte (Auszug)
|
|
### Health und Identitaet
|
|
- `GET /health` (ohne Auth)
|
|
- `GET /me`
|
|
|
|
### Benutzerverwaltung
|
|
- `GET /users`
|
|
- `POST /users/{username}/disable` mit JSON `{countdown?, sound?, message?}`
|
|
- `POST /users/{username}/enable`
|
|
|
|
Beispiel (disable):
|
|
```bash
|
|
curl -X POST -H "Authorization: Bearer $token" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"countdown":90,"sound":true,"message":"Bitte speichern"}' \
|
|
http://localhost/users/child1/disable
|
|
```
|
|
|
|
### Update-API (lokal)
|
|
Alle Update-Endpunkte erfordern Admin-Auth.
|
|
- `GET /update/status`
|
|
- `GET /update/service-status` (zeigt URL und Erreichbarkeit des Update-Services)
|
|
- `POST /update/enroll` (optional Body: `{ "enroll_token": "..." }`)
|
|
- `POST /update/check`
|
|
- `POST /update/apply` (optional Body: `{ "version": "x.y.z" }`)
|
|
- `POST /update/rollback`
|
|
- `GET /update/logs?limit=200`
|
|
|
|
Beispiel (Enrollment):
|
|
```bash
|
|
ENROLL_TOKEN="example-enroll-token"
|
|
curl -X POST -H "Authorization: Bearer $token" \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"enroll_token\":\"${ENROLL_TOKEN}\"}" \
|
|
http://localhost/update/enroll
|
|
```
|
|
|
|
Beispiel (Update-Check):
|
|
```bash
|
|
curl -X POST -H "Authorization: Bearer $token" http://localhost/update/check
|
|
```
|
|
Hinweis: Ohne gespeichertes Update-Token liefert der Check einen Fehler.
|
|
|
|
## Healthcheck per Makefile
|
|
```bash
|
|
make healthcheck TOKEN="$token"
|
|
```
|
|
|
|
## Weitere Dokumente
|
|
- Konfiguration: `docs/CONFIGURATION.md`
|
|
- Deployment: `docs/DEPLOYMENT.md`
|
|
- Troubleshooting: `docs/TROUBLESHOOTING.md`
|
|
|
|
## CLI-Fallback (sk.sh)
|
|
Das Legacy-Script arbeitet direkt auf dem Host und benoetigt Root-Rechte.
|
|
|
|
Aufruf:
|
|
```bash
|
|
sudo ./sk.sh USERNAME disable|enable [countdown] [sound] [countdown_time_in_seconds]
|
|
```
|
|
|
|
Beispiel:
|
|
```bash
|
|
sudo ./sk.sh demo_user disable countdown sound 90
|
|
```
|