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.13

With 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

  1. On the leader, print a join string. It works once, for 10 minutes by default (--minutes up 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
  2. Start the new instance with it, as SLOWSHIELD_JOIN='ssj1:…' (or SLOWSHIELD_JOIN_FILE). Nothing else needs configuring: the follower takes the leader's policy.
  3. 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. With SLOWSHIELD_JOIN_CONFIRM=auto the 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

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