Enrol the first server
Enrolment is how a server joins the fleet — and how it gets its rules and their updates from then on, without anyone copying files. The agent stays the same program: it still reads, decides and bans locally; only its configuration now comes from the controller.
On the controller: a join token
In the console, the Join a server panel mints a join token; at the terminal:
sudo -u shieldlist shieldlist-controller token # one use, valid a day
The token carries the controller's certificate fingerprint: the agent that presents it pins the controller from then on.
On the server: the agent
Same repository, other package:
curl -fsSL https://repo.lrob.net/apt/shieldlist/shieldlist.gpg -o /usr/share/keyrings/shieldlist.gpg
echo "deb [signed-by=/usr/share/keyrings/shieldlist.gpg] https://repo.lrob.net/apt/shieldlist stable main" > /etc/apt/sources.list.d/shieldlist.list
apt update && apt install shieldlist-agent
stablecarries the releases. There is also adevsuite with our development builds: ahead of the releases, and expected to break.
Tell it where the controller is, then enrol:
mode: enrolled
controller: https://console.example.net:17453
shieldlist-agent -t && systemctl restart shieldlist-agent
shield enrol <join-token>
Within seconds the machine appears under Servers in the console, with the configuration revision it holds. shield status on the server shows controller_sync.
It starts in detect-only
A fresh agent records what every rule would have done and touches nothing. Leave it a day, read the console — the hits, the would-be bans, the addresses — and only then arm it: the server's switch in the console, or state: on in its declaration. Nothing is armed in silence.
What stays on the server
agent.yaml, its secrets, its local exemptions and hooks. Switching back is mode: local and a restart: the local files were never touched. Everything about the conversation — what is pushed, what is sent back, what happens when the controller is unreachable — is in Agent → Enrolment.