fieldwitness/docs/training/admin-reference.md

Administrator Quick Reference

Audience: IT staff and technical leads responsible for deploying and maintaining FieldWitness 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 fieldwitness-server --target server -f deploy/docker/Dockerfile .
$ docker build -t fieldwitness-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. FieldWitness uses SQLite -- do not scale horizontally.

---

Threat Level Presets

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

$ cp deploy/config-presets/<level>-threat.json ~/.fwmetadata/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
fieldwitness init	Create directory structure, generate keys, write default config
fieldwitness serve --host 0.0.0.0	Start web UI (LAN-accessible)
fieldwitness status	Pre-flight check: keys, chain, deadman, backup, geofence
fieldwitness status --json	Machine-readable status output

Keys

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

Fieldkit

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

Chain and Evidence

Command	Description
fieldwitness chain status	Show chain head, length, integrity
fieldwitness chain verify	Verify full chain (hashes + signatures)
fieldwitness chain log --count 20	Show recent chain entries
fieldwitness chain export -o bundle.zip	Export attestation bundle
fieldwitness chain disclose -i 5,12,47 -o disclosure.json	Selective disclosure
fieldwitness chain anchor	Manual anchor (prints hash for external witness)
fieldwitness 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 ~/.fwmetadata/auth/fieldwitness.db.

---

Backup Checklist

What	How often	Command
Key bundle	After every rotation, weekly minimum	fieldwitness keys export -o backup.enc
Cold archive	Weekly or before travel	fieldwitness 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/fieldwitness-$(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: fieldwitness 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: fieldwitness 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 FIELDWITNESS_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 ~/.fwmetadata/	Run FieldWitness as the same user who ran fieldwitness 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 ~/.fwmetadata/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
$ fieldwitness status --json