Skip to content

Operational Witness Setup

This is the optional monitored mode. For the simpler setup without host services, use system clock witnessing instead.

Use this mode for ordinary NTP-backed observations without a numeric UTC-accuracy promise. The bundled timesyncd adapter reports synchronization status only. The existing bounded mode and version 1 receipts are unchanged. Witnessing remains disabled by default; do not enable it until the policy is approved and the monitor has been checked on the actual host.

Install the host monitor

On Beelink, from the updated Spurline checkout, install the standalone Python file and systemd units. Only Python 3 and the existing systemd tools are needed; the host does not need Poetry or the relay's dependencies.

sudo install -d -m 0755 /usr/local/libexec
sudo install -m 0644 src/spurline/clock_monitor.py /usr/local/libexec/spurline-clock-monitor.py
sudo install -m 0644 deploy/spurline-clock-monitor.service /etc/systemd/system/
sudo install -m 0644 deploy/spurline-clock-monitor.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now spurline-clock-monitor.timer
sudo systemctl start spurline-clock-monitor.service
cat /run/spurline-clock/health.json

Check for synchronized: true, mode: "operational", uncertainty_ms: null, and reason: "ok". The file should refresh while the timer is active. The service runs with a dynamic unprivileged user and atomically replaces a public, readable status file. No keys are involved. Review failures with:

systemctl status spurline-clock-monitor.timer
journalctl -u spurline-clock-monitor.service --since '10 minutes ago'

The adapter reads NTPSynchronized and requires timesyncd to be active. It also uses /run/systemd/timesync/synchronized, which systemd touches on successful synchronization, to reject samples older than two hours. It does not use /var/lib/systemd/timesync/clock, which can also be refreshed without an NTP exchange. See systemd-timesyncd documentation and the machine-readable timedatectl interface. The two-hour limit accommodates the reported 34-minute polling interval; it is not a calculated uncertainty bound. No NTP configuration changes are required.

If the host does not expose the expected synchronization file or read-only D-Bus properties, the adapter reports unhealthy. Do not substitute a static healthy JSON file. Check the adapter on the actual Linux host before enabling issuance.

Mount the status directory and select the mode

Add these settings to the deployment .env, retaining all existing settings:

COMPOSE_FILE=compose.yaml:deploy/compose.clock.yaml
SPURLINE_WITNESS_ENABLED=false
SPURLINE_WITNESS_CLOCK_MODE=operational
SPURLINE_WITNESS_CLOCK_FILE=/run/spurline-clock/health.json
SPURLINE_WITNESS_MAX_DELAY_SECONDS=60

If COMPOSE_FILE already lists custom files, append deploy/compose.clock.yaml instead of replacing that list. The overlay mounts /run/spurline-clock read-only and refuses to create an absent host directory. The mount is a directory so atomic file replacements remain visible. Do not expose the host D-Bus socket to the relay container. Docker must run on the same host whose clock is monitored.

Recreate the container with the overlay in effect and inspect the mounted file:

docker compose config --quiet
docker compose up -d --build --force-recreate spurline
docker compose exec -T spurline cat /run/spurline-clock/health.json

This does not enable witnessing. If the runtime directory is removed and recreated while the container is running, recreate the container to refresh the bind mount. The supplied service preserves the directory between timer runs.

Approve the operational policy

Review Operational Witness Policy Version 1. It is ready for adoption only if the operator accepts its commitments. Copy its exact bytes to the mounted data directory; for example, when that directory is /mnt/bitcoin/spurline:

sudo install -m 0644 docs/policies/operational-witness-v1.md /mnt/bitcoin/spurline/witness-policy.txt
docker compose exec -T spurline spurline service show > commissioning-state.json
docker compose exec -T spurline spurline service witness request \
  --policy /data/witness-policy.txt --valid-for 2592000 \
  --kind 1415 --kind 1416 > witness-request.json

Adjust the host destination to your actual SPURLINE_DATA_DIR. The signed policy must contain the exact line Spurline-Clock-Profile: operational-v1. This explicit permission marker prevents enabling operational mode under an unrelated policy; the relay also rejects bounded mode under this marker and operational issuance configured with a delay greater than the policy's 60-second limit. The rest of the policy still requires human review. Changing bytes after signing changes the digest and requires new approval. Do not promise bounded accuracy elsewhere in the policy.

Copy the JSON files and exact policy to the trusted operator workstation. Use the operator signing command, then import and publish the signed authorization on the relay host:

docker compose exec -T spurline spurline service witness authorize < witness-authorization.json
docker compose exec -T spurline spurline service witness verify
docker compose exec -T spurline spurline service publish --relay ws://127.0.0.1:8080
docker compose exec -T spurline spurline service witness publish --relay ws://127.0.0.1:8080

These commands assume no prior witness grant, as in the current deployment. For an already authorized instance, use the existing renewal process; the offline signer currently supports initial grants only. Do not erase lifecycle history to switch policies. The commissioning already completed need not be repeated.

Enable and test

After checking the monitor and authorization, set SPURLINE_WITNESS_ENABLED=true and recreate the container. /info should report clock_mode: "operational" and receipt_version: 2; configuration alone is not proof of current clock health. Submit a fresh signed kind 1415 or 1416 test event and query kind 1418 receipts by its e tag. Verify the resulting receipt's signature, exact subject binding, policy reference, and the version 2 time fields.

Old receipts are never rewritten. Pending jobs retain their acquisition profile; a mode change makes incompatible pending jobs unavailable, not silently upgraded or downgraded. The same signed subject's existing job is not replaced on resubmission. There is no database schema migration for this mode.

To stop issuance, use the existing local service witness suspend command or set witnessing disabled and recreate the container. To investigate a clock-step alarm, first suspend issuance, correct and check host synchronization, restart the relay, and only then resume. Restart clears the process-local alarm; it is not itself evidence that the clock is trustworthy.