fieldwitness/docs/training/admin-reference.md

Administrator Quick Reference

Audience: IT staff and technical leads responsible for deploying and maintaining SooSeF instances.

---

Deployment Tiers

Tier	Form Factor	Use Case	Key Feature
1 -- Field Device	Bootable Debian Live USB	Reporter in the field	Amnesic, LUKS encrypted, pull USB = zero trace
2 -- Org Server	Docker on mini PC or VPS	Newsroom / NGO office	Persistent, web UI + federation API
3 -- Federation Relay	Docker on VPS	Friendly jurisdiction	Attestation sync only, zero knowledge of keys

---

Quick Deploy

Tier 1: Build USB image

$ sudo apt install live-build
$ cd deploy/live-usb
$ sudo ./build.sh
$ sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress

Tier 2: Docker org server

$ cd deploy/docker
$ docker compose up server -d

Exposes port 5000 (web UI) and port 8000 (federation API).

Tier 3: Docker federation relay

$ cd deploy/docker
$ docker compose up relay -d

Exposes port 8001 (federation API only).

Kubernetes

$ docker build -t soosef-server --target server -f deploy/docker/Dockerfile .
$ docker build -t soosef-relay --target relay -f deploy/docker/Dockerfile .
$ kubectl apply -f deploy/kubernetes/namespace.yaml
$ kubectl apply -f deploy/kubernetes/server-deployment.yaml
$ kubectl apply -f deploy/kubernetes/relay-deployment.yaml

Single-replica only. SooSeF uses SQLite -- do not scale horizontally.

---

Threat Level Presets

Copy the appropriate preset to configure SooSeF for the operational environment:

$ cp deploy/config-presets/<level>-threat.json ~/.soosef/config.json

Level	Session	Killswitch	Dead Man	Cover Name
low-threat	30 min	Off	Off	None
medium-threat	15 min	On	48h / 4h grace	"Office Document Manager"
high-threat	5 min	On	12h / 1h grace	"Local Inventory Tracker"
critical-threat	3 min	On	6h / 1h grace	"System Statistics"

---

Essential CLI Commands

System

Command	Description
soosef init	Create directory structure, generate keys, write default config
soosef serve --host 0.0.0.0	Start web UI (LAN-accessible)
soosef status	Pre-flight check: keys, chain, deadman, backup, geofence
soosef status --json	Machine-readable status output

Keys

Command	Description
soosef keys show	Display current key info and fingerprints
soosef keys export -o backup.enc	Export encrypted key bundle
soosef keys import -b backup.enc	Import key bundle from backup
soosef keys rotate-identity	Rotate Ed25519 identity (records in chain)
soosef keys rotate-channel	Rotate AES-256-GCM channel key
soosef keys trust --import pubkey.pem	Trust a collaborator's public key

Fieldkit

Command	Description
soosef fieldkit status	Show fieldkit state (deadman, geofence, USB, tamper)
soosef fieldkit checkin	Reset dead man's switch timer
soosef fieldkit check-deadman	Check if deadman timer expired (for cron)
soosef fieldkit purge --confirm CONFIRM-PURGE	Activate killswitch
soosef fieldkit geofence set --lat X --lon Y --radius M	Set GPS boundary
soosef fieldkit usb snapshot	Record USB whitelist baseline
soosef fieldkit tamper baseline	Record file integrity baseline

Chain and Evidence

Command	Description
soosef chain status	Show chain head, length, integrity
soosef chain verify	Verify full chain (hashes + signatures)
soosef chain log --count 20	Show recent chain entries
soosef chain export -o bundle.zip	Export attestation bundle
soosef chain disclose -i 5,12,47 -o disclosure.json	Selective disclosure
soosef chain anchor	Manual anchor (prints hash for external witness)
soosef chain anchor --tsa https://freetsa.org/tsr	RFC 3161 automated anchor

---

User Management

The web UI admin panel at /admin provides:

• Create user accounts
• Delete user accounts
• Reset passwords (temporary password issued)
• View active sessions

User credentials are stored in SQLite at ~/.soosef/auth/soosef.db.

---

Backup Checklist

What	How often	Command
Key bundle	After every rotation, weekly minimum	soosef keys export -o backup.enc
Cold archive	Weekly or before travel	soosef archive export --include-keys -o archive.zip
Docker volume	Before updates	docker compose stop server && docker run --rm -v server-data:/data -v /backup:/backup busybox tar czf /backup/soosef-$(date +%Y%m%d).tar.gz -C /data .

Store backups on separate physical media. Keep one copy offsite.

---

Federation Setup

1. Exchange public keys between organizations (verify fingerprints out-of-band)
2. Import collaborator keys: soosef keys trust --import /path/to/pubkey.pem
3. Register peers via web UI at /federation or via CLI
4. Gossip starts automatically; monitor at /federation

For airgapped federation: soosef chain export to USB, carry to partner, import there.

---

Source Drop Box

1. Navigate to /dropbox/admin (admin login required)
2. Create a token with label, expiry, and file limit
3. Share the generated URL with the source over a secure channel
4. Monitor submissions at /dropbox/admin
5. Revoke tokens when no longer needed

---

Hardening Checklist

• Disable or encrypt swap (swapoff -a or dm-crypt random-key swap)
• Disable core dumps (echo "* hard core 0" >> /etc/security/limits.conf)
• Configure firewall (UFW: allow 5000, 8000; deny all other incoming)
• Disable unnecessary services (bluetooth, avahi-daemon)
• Apply a threat level preset appropriate for the environment
• Set cover_name in config if operating under cover
• Set SOOSEF_DATA_DIR to an inconspicuous path if needed
• Enable HTTPS (default) or place behind a reverse proxy with TLS
• Create systemd service for bare metal (see docs/deployment.md Section 7)
• Set up regular backups (key bundle + cold archive)
• Arm dead man's switch if appropriate for threat level
• Take initial USB whitelist snapshot
• Record tamper baseline

---

Troubleshooting Quick Fixes

Symptom	Check
Web UI unreachable from LAN	host must be 0.0.0.0, not 127.0.0.1. Check firewall.
Docker container exits	docker compose logs server -- check for port conflict or volume permissions
Dead man fires unexpectedly	Service crashed and exceeded interval+grace. Ensure Restart=on-failure.
Permission errors on ~/.soosef/	Run SooSeF as the same user who ran soosef init
Drop box tokens expire immediately	System clock wrong. Run date -u and fix if needed.
Chain anchor TSA fails	Requires network. Use manual anchor on airgapped devices.
Account locked out	Wait for lockout to expire, or restart the server.
SSL cert shows wrong name	Delete ~/.soosef/certs/cert.pem, set cover_name, restart.

---

Health Checks

# Web UI
$ curl -k https://127.0.0.1:5000/health

# Federation API (Tier 2)
$ curl http://localhost:8000/health

# Relay (Tier 3)
$ curl http://localhost:8001/health

# Full system status
$ soosef status --json