Sentry — the friendly user guide

1 · What Sentry is (in plain words)

Imagine your website or server is a shop. Anyone on the internet can walk up to the door. Most are ordinary customers — but a few are troublemakers who try to break in, flood the doorway so real customers can't get in, or trick their way past the till. Sentry is the guard at the door. It looks at everyone who arrives, lets the good ones through to your shop, and stops the bad ones before they get inside.

It does this using five kinds of protection at once (we'll meet them in section 8), and it keeps a tidy logbook of everything it did so you can see it later.

2 · The two pieces: Hub & Agents

Sentry comes in two parts that work together:

3 · What you need before you start

• A computer or small server to run the Hub on (it can be a cheap virtual machine).
• One or more servers/websites you want to protect — each will get an Agent.
• A web browser. That's genuinely it — everything is done through the screens shown in this guide.

4 · Step 1 · Turn on the Hub

The Hub runs as a ready-made package (using a tool called Docker, which just means "run this app in a tidy box"). On the machine that will be your office, open a terminal and run:

cd deploy/hub
export SENTRY_ADMIN_USER=admin
export SENTRY_ADMIN_PASSWORD='choose-a-strong-password'
export SENTRY_HUB_ADMIN_TOKEN=$(openssl rand -hex 24)   # a long random robot-key
export SENTRY_ENROLL_TOKEN=$(openssl rand -hex 24)      # a password guards use to join
docker compose up -d --build

Then open http://YOUR-HUB-ADDRESS:9090/ in your browser.

5 · Step 2 · Sign in for the first time

1. Type the username and password you chose in Step 1.
2. Click Sign in.
3. You'll land on the Overview screen. It will say you have 0 agents — that's expected, we add one next.

6 · Step 3 · Add your first Agent

Now we put a guard on a server. On the Overview screen, click the blue + Add Agent button. A window opens offering the Agent in several formats — pick the one that matches the server you're protecting:

Each option comes pre-filled with your Hub's address and the join password, so you truly just run it. For a Docker Linux host it looks like this:

cd deploy/agent
SENTRY_HUB_URL=http://YOUR-HUB:9090 SENTRY_ENROLL_TOKEN=your-join-password \
  docker compose up -d --build

7 · Reading the Overview screen

The Overview is your home base. From the top down:

• Summary cards — big numbers: how many guards are online, how many bad requests were blocked, and so on.
• The Agents list — one row per server. A row shows a green/grey dot (online/offline), the five protection labels (lit = on), and quick counters. Click a row to open that server's own workspace.
• A 🔎 search box above the list — type a name or address to find one server fast when you have many. Long lists are split into pages with Prev / Next buttons so nothing ever runs off the screen.

Click any server row to see its detail: its live list of currently-banned addresses, a running feed of recent actions, and switches to flip each protection on or off for that one server.

8 · The 5 protections (“pillars”) explained

Each guard can run up to five kinds of protection. You can turn each one on or off per server. Here's what they are, in everyday terms:

9 · Step 4 · Send your website through Sentry

For the guard to protect a website, visitors must reach the guard first, then the guard passes them to your real website. You tell Sentry where your real website lives on the Proxy tab (labelled “Proxy — domains & routing”).

1. Click + Add domain.
2. Under Host, type the public name of your site, e.g. shop.example.com.
3. Under Upstream (backend), type where your real site actually runs, e.g. http://127.0.0.1:8000.
4. Click Save proxy config.

The last thing is to point the website's public address at the guard. In your domain's DNS settings, make an A record for the site point to the guard's public IP address (not your old server's):

Type   Name   Value              TTL
A      shop   203.0.113.10       300      ← the guard's public IP
A      @      203.0.113.10       300

10 · Step 5 · Rules for one specific website

Sometimes one website needs an extra rule the others don't. On the Proxy tab, each site has a Domain Rules button (the pencil ✎). Click it to add rules that apply only to that site — on top of the shared rules.

11 · The WAF — your website bodyguard

The WAF Rules tab lists the patterns that get a request blocked. Sentry ships with sensible ones already switched on (blocking common hacking patterns like SQL-injection, cross-site-scripting, path-traversal, and known scanners). You can add your own, turn any off, and there's a 🔎 search box to find a rule by name or pattern when the list is long.

12 · Firewall & auto-block thresholds

The Firewall tab is the ban list every other pillar feeds into. Two things live here:

• A whitelist — addresses that must never be banned (your office, your own monitoring). Add these first so you can't accidentally lock yourself out.
• Thresholds — the tripwires that decide when a bad address is auto-banned (for example: “after 5 attacks in 60 seconds, ban them for an hour”).

13 · Log Jails (fail2ban) — banning by log lines

On the Log Jails tab each jail says which log file to watch, what a “failure” line looks like, how many failures are allowed, and how long the ban lasts. The 🧪 test button lets you paste a real log line and confirm the jail would catch it, and the ✨ suggest button can write the matching pattern for you (if the AI helper is on).

To let someone back in (you banned a colleague's office, a customer's VPN, yourself): open that host's Firewall tab and remove the address from its ban list, or on the machine itself run sudo sentry unblock 203.0.113.5. There is no automatic release by design — releasing is a decision a person makes.

14 · Streams — protecting email & other services

The WAF understands websites. But email, databases, and game servers don't speak “web” — they speak raw connections. The Streams tab protects those. You tell it “listen on this port and pass it to that server,” and it carries the same protection: banned addresses are dropped before they ever reach the service, and you can limit how fast any one address may connect.

15 · DNS — the three jobs it can do

Remember DNS is the internet's phone book. Sentry's DNS pillar can do up to three jobs, and you choose which:

16 · Authoritative DNS & the Zone editor

Inside a zone you manage its records (the individual entries), its security keys, and who's allowed to copy it. Because a zone can have dozens or hundreds of records, the record list has a 🔎 search box, a type filter (show only A records, only MX records, etc.), and page buttons — so it's always easy to find one entry.

1. On the DNS Zones tab click + Add zone and type your domain under Origin, e.g. example.com.
2. Add records with + Add record — pick a Type (A, MX, TXT…), a Name, and the value.
3. Need standard email records? Click ✉ Add email protection and Sentry drafts SPF, DMARC and MX for you.
4. Tick “Serve zones authoritatively” at the top when you're ready for the guard to start answering.

“Where are my existing zones? The editor is empty.”

This is the most common surprise, and it is not a bug. There are two separate lists on the DNS Zones tab, and they answer different questions:

The transferred-in list also flags serial drift: if one edge holds an older serial than another, its serial is highlighted. You cannot see that by looking at either server on its own.

Choosing which servers answer for a zone

A zone authored at the global level is, by default, handed to every agent. Inside the zone editor, “Which agents answer for this zone” lets you narrow that: pick hosts from the list (each shown as name (ip address)) and only those are given the zone. Leave “Every agent” ticked for the normal case. Targeting only decides who receives the zone — an agent still answers for it only once “Serve zones authoritatively” is on for that agent.

17 · What is TSIG — and why turn it on?

When you run more than one DNS server (a main one and backups), the backups copy the phone book from the main one. Without protection, an impostor could pretend to be your main server and feed your backups fake entries — sending your visitors to the wrong place. TSIG stamps every copy with a secret key, so a backup only accepts a copy that carries the right stamp.

Why you should enable it:

• It stops attackers from poisoning your backups with forged records.
• It makes sure only your servers can pull a full copy of your zone (which would otherwise reveal your whole network layout).
• It's the standard, expected way to run multiple DNS servers safely — auditors and hosting partners will ask for it.

In the zone editor, click Generate TSIG key, then share that key with your backup servers. Sentry keeps a copy so it can stamp the transfers.

18 · What is DNSSEC — and why turn it on?

Normal DNS answers can be forged in transit — an attacker between a visitor and your server could hand back a fake address and send your customers to a copycat site to steal passwords. DNSSEC prevents this: every answer is signed, and browsers/resolvers reject any answer whose signature doesn't check out.

Why you should enable it:

• It protects your visitors from being silently redirected to fraudulent look-alike sites.
• It's increasingly required — for some industries, government domains, and to unlock other security features (like verified email).
• Sentry makes it genuinely easy (below), so the usual excuse — “it's too fiddly” — is gone.

1. In the zone editor, scroll to DNSSEC and click Generate signing key.
2. Tick Enable DNSSEC signing and Save.
3. Copy the DS record Sentry shows you and paste it into your domain registrar's control panel (there's a built-in DS submission + verify guide button that walks you through it).

19 · Secondaries & zone transfer (AXFR)

On the DNS Zones tab you list the IP addresses of your trusted secondaries — the only servers allowed to pull a copy. On a single-server (agent) view, these are your client's own backup DNS servers. You can also choose whether a zone is allowed to be copied at all.

19b · DNS encryption — DoT & DoH

There are two separate directions, and they are easy to confuse:

1. Open the DNS Filter tab (Global Defaults for the whole fleet, or one server's workspace).
2. Under DNS encryption, set a DoT listen address — 0.0.0.0:853 is the standard port.
3. For DoH set a DoH listen address. Use 0.0.0.0:443 unless the WAF already owns 443 on that host — then pick another port, e.g. 0.0.0.0:8443, and publish the URL as https://host:8443/dns-query.
4. Paste the certificate chain and private key (PEM). Use a certificate whose name matches what clients will type.
5. Fill in Server hostname clients use so DoH requests are matched to the right name. Leave it blank to accept any.
6. Save. Each agent rebinds its DNS listeners within about 15 seconds.

20 · The fleet-wide Global Blocklist

Found one really bad address you want banned everywhere at once? The Global Blocklist tab bans an address (or a whole range) across every server in one click. Remove it and the ban lifts everywhere on the next check-in. The list has a 🔎 search box and page controls so it stays manageable even with thousands of entries.

20b · Threat Intel — who is attacking you, and what they are after

Why the “Hosts” number is the important column. An address that one machine banned might be a scanner, a mistake, or a noisy neighbour. An address that three machines banned separately, without talking to each other, is really attacking you. That agreement is the strongest signal you have, so the list is sorted with the most-agreed-upon at the top and the counter tells you how many hosts agree.

Promote to global. Next to a corroborated address is a Promote to global button. That copies it into the Global Blocklist, so every agent — including hosts that have never seen this attacker — drops it from then on. One host's bad night becomes the whole fleet's protection. Promotions are permanent by default, because an address several machines independently banned has earned it.

The second table, What is being targeted, turns it around and asks which of your hosts is taking fire:

• Bans — how many addresses this host is currently holding.
• Permanent — how many of those are held until someone releases them.
• Only here — addresses no other host of yours has seen. This is the one to watch: a high number means somebody is aiming at that specific machine rather than sweeping the whole internet.
• Domains served — the sites and services that live on that host, so you can see what is actually being attacked, not just which box is noisy.

21 · Users & what each role can do

On the Users tab (admins only) you add colleagues and choose how much each can do. There's a 🔎 search box to find a person quickly.

22 · Your profile & two-factor sign-in

The Profile tab is about your own account. The most important thing here is turning on two-factor sign-in.

• TOTP — the 6-digit codes from an app like Google Authenticator or Aegis. Click Enroll TOTP, scan the QR code, type a code to confirm. Done.
• Passkeys — an even easier method using your phone's or laptop's fingerprint/face. No codes to type. Register one or more devices.
• Active sessions — see everywhere you're signed in and sign out any device remotely.

23 · Settings — passkeys, SSO, AI helper

The Settings tab (admins) holds three optional features:

• WebAuthn / Passkeys — the address settings that let passkeys work; set them to match your console's public web address.
• Single-Sign-On (OIDC/SSO) — let your team log in with your existing company account (e.g. Authentik, Google, Microsoft) instead of a separate password.
• AI helper (LLM assist) — optional and off by default. When on, it can suggest rules and summarise activity in plain English. Everything in Sentry works perfectly without it.

24 · Where the logs go (Wazuh / Splunk)

Every action Sentry takes is written, in a tidy machine-readable form, to a log file on each server:

/var/log/sentry/events.jsonl

This is designed to be picked up by security log systems like Wazuh or a Splunk forwarder, so Sentry's activity shows up alongside the rest of your security monitoring. You can also read it directly, or use the built-in Audit tab in the console for a friendly, clickable history of configuration changes and logins.

25 · Finding things: search & page controls

Everywhere Sentry shows a list — servers, users, banned addresses, DNS records, rules, the audit history — you'll find the same two friendly helpers:

• A 🔎 search box to filter the list by typing part of what you're looking for.
• Page buttons (« ‹ Prev · Next › ») at the bottom, so a list of thousands never overwhelms the screen — it shows a comfortable page at a time and tells you where you are (“1–10 of 240”).

The DNS record list adds a type filter too, so you can show, say, only the MX (mail) records in one click.

26 · Mini-glossary of every word

Sentry — centrally-managed firewall + WAF + filtering & authoritative DNS, with a hub/agent design.
← Back to the console · Tap any picture to enlarge and zoom · Technical reference: docs/USER_GUIDE.md in the repository.