# 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

```bash
$ 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

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

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

### Tier 3: Docker federation relay

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

Exposes port 8001 (federation API only).

### Kubernetes

```bash
$ 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:

```bash
$ 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

```bash
# 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
```