# 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](https://github.com/squirro/slowshield/blob/main/deploy/helm/slowshield/README.md).

### 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](https://github.com/squirro/slowshield/blob/main/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](https://github.com/squirro/slowshield/blob/main/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](https://github.com/squirro/slowshield/blob/main/docs/design/shieldwall.md).

---

This page as HTML: https://slowshield.org/docs/shieldwall/. All of the guide in one file: https://slowshield.org/llms-full.txt
