Shieldlist

Install the controller

The controller is one static binary with a SQLite store; it runs on any Linux with systemd. Pick a machine that the servers can reach on port 17453 — usually not one you protect, though it can share a machine with an agent.

Install the package

On Debian and its derivatives:

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-controller

stable carries the releases. There is also a dev suite with our development builds: ahead of the releases, and expected to break.

The package creates the shieldlist system user, writes a starter tree under /etc/shieldlist/controller, installs the unit and starts the service. For other systems, or by hand, see Installing.

Put the console behind TLS

The API and the console listen on 127.0.0.1:17454 and expect a reverse proxy with a certificate in front; the agents' port, 0.0.0.0:17453, needs nothing — the controller signs its own certificate and the agents pin it.

With nginx and Let's Encrypt on the same machine:

server {
    server_name console.example.net;
    location / {
        proxy_pass http://127.0.0.1:17454;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then certbot --nginx -d console.example.net --redirect.

Create the first account

sudo -u shieldlist shieldlist-controller account -name you    # asks for a password twice

Open https://console.example.net, sign in. The console is empty: no server yet. It tells you what to do next — a join token, and a command to run on the first machine. That is the next page.

Details — listeners, retention, geolocation, updates, who may lift a ban: Controller → Configuration.