Shield wall
A shield wall is several SlowShield instances working as one: a leader and its followers. The leader holds the policy and shows the traffic of every instance. Followers take the leader's policy and blocks, report their statistics and events to it, and fetch package files through its cache, so the wall downloads each file from the registries once. A follower that can't reach its leader keeps working on its own.
When to use one
Run one instance per office, region or CI cluster, close to the machines that use it. Without a shield wall each instance has its own policy and its own dashboard. With one, you set the delay, the exceptions and the blocks once on the leader, and you see every instance's installs and security events in one place.
1. Make one instance the leader
Start the instance that should lead with SLOWSHIELD_SHIELDWALL_ROLE=leader. It needs a
public_url its followers can reach over HTTPS.
docker run -d --name slowshield -p 127.0.0.1:8080:8080 -v slowshield:/data \
-e SLOWSHIELD_PUBLIC_URL=https://slowshield.example.com \
-e SLOWSHIELD_SHIELDWALL_ROLE=leader \
-e SLOWSHIELD_INSTANCE_NAME=hq -e SLOWSHIELD_INSTANCE_LOCATION=Zurich \
ghcr.io/squirro/slowshield:0.0.13With Compose, set the same variables in deploy/docker/.env, and SLOWSHIELD_HOSTNAMES to the
public URL's host so Caddy serves that name; with Helm, set
shieldwall.role: leader. The leader keeps its identity in /data/shieldwall/identity.key:
back it up, because losing it means pairing every follower again.
2. Add a follower
- On the leader, print a join string. It works once, for 10 minutes by default (
--minutesup to 60):docker exec slowshield slowshield wall invite --name sg-1 --location Singapore # Compose, from deploy/docker: docker compose exec slowshield slowshield wall invite --name sg-1 --location Singapore - Start the new instance with it, as
SLOWSHIELD_JOIN='ssj1:…'(orSLOWSHIELD_JOIN_FILE). Nothing else needs configuring: the follower takes the leader's policy. - Confirm the leader. Open the new instance's Shield wall page (
/ui/shieldwall). It shows the leader's name and fingerprint; click Join if the fingerprint matches the one the invite printed. WithSLOWSHIELD_JOIN_CONFIRM=autothe follower joins without the click.
The follower must trust the leader's certificate. A leader with a publicly trusted certificate (ACME)
needs nothing. The shipped Compose and Helm setups default to Caddy's private CA, so a follower of such a leader needs
that CA certificate: LEADER_CA_SECRET_FILE with Compose, shieldwall.leaderCaSecret with Helm
(or shieldwall.leaderPubliclyTrusted: true for a public certificate). The leader's Helm NOTES show how to
read the CA.
On Kubernetes
Create the join string as a Secret right before installing, and install the chart with
shieldwall.joinSecret and shieldwall.confirm: auto. The chart README has a full walkthrough
and example values, including a leader that is only reachable on a tailnet:
deploy/helm/slowshield.
With configuration management
Ansible, cloud-init or a GitOps tool can pair followers without anyone clicking: run
slowshield wall invite --quiet on the leader, pass the string as SLOWSHIELD_JOIN with
SLOWSHIELD_JOIN_CONFIRM=auto, and check with slowshield wall status. A follower that has
joined ignores a join string, so the automation can leave it set; an invalid join string stops the instance at
startup, so never use a placeholder. Details:
docs/operations.md.
3. What followers take from the leader
- Policy and blocks. Stricter settings apply at once; looser ones after an hour, and a follower's
delay never goes below one day (
SLOWSHIELD_SHIELDWALL_MIN_DELAY_DAYS). A follower's own stricter settings and its own exceptions stay in force, so leave the policy settings out of a follower's config. - Package files through the leader's cache when it is up, checked by the follower as always
(
SLOWSHIELD_SHIELDWALL_VIA_LEADER). Indexes and publish times still come from the registries. - Evidence: takedowns, tamper flags and the first fingerprint of each file. A follower that saw different bytes for a file than the leader refuses it.
4. Watch the whole wall
The leader's Overview and Security pages cover every instance and narrow to one instance, a location or a label. Its Shield wall page lists the instances and what each served in the last 24 hours: installs, packages, data, and how much came from its own cache, through the leader, or from the registries.
One name on a tailnet
On Tailscale, every instance of the wall can serve one Tailscale Service, so clients use one URL and reach an instance that is up, the nearest one with regional routing or MagicRoute. How to set it up on hosts and on Kubernetes: docs/tailscale.md.
Remove or leave
slowshield wall remove <name> on the leader removes a follower; it keeps running on its own. An
instance keeps its role across restarts; only SLOWSHIELD_SHIELDWALL_ROLE=standalone takes it out of the
shield wall. How it works in detail:
docs/design/shieldwall.md.
For agents: this page as Markdown · llms.txt · the SlowShield skill