BLOCKLISTD(8)

✨ blocklistd(8) ✨

okay bestie so you're looking at the manual page for blocklistd, from the System Manager's Manual — it's a daemon that blocks and releases ports on demand so nobody can DoS-abuse your box 💅

---

🎀 NAME 🎀

blocklistd — block and release ports on demand to avoid DoS abuse

---

🌸 SYNOPSIS 🌸

blocklistd [-dfrv] [-C controlprog] [-c configfile] [-D dbfile]
           [-P sockpathsfile] [-R rulename] [-s sockpath] [-t timeout]

---

💖 DESCRIPTION 💖

So blocklistd is a daemon, kinda like syslogd(8)'s cousin 👯 — it listens on sockets at the paths listed in the sockpathsfile, waiting for notifications from other daemons about connection attempts that either succeeded or failed. If you don't give it such a file, then it only listens to the socket path you gave in sockpath — and if that isn't specified either, it goes to /var/run/blocklistd.sock. Defaults, amirite 🫶

Every notification carries an (action, port, protocol, address, owner) tuple that identifies the remote connection plus the action. That tuple gets checked against entries from the configfile, using the syntax in blocklistd.conf(5). If something matches, a state entry is created for that tuple. Each entry has a number-of-tries limit and a duration. periodt ✨

If configfile is a directory, or a directory exists with the same name as configfile but with ".d" appended to it, then every file in that directory gets read as a configuration file. And if configfile exists as a file, it's processed before the contents of the configfile.d directory — assuming that directory also exists. stacking order matters, bestie 😌

Here's how blocklistd does its config-entry matching: the client side passes the file descriptor associated with the connection it wants blocklisted, plus it passes socket credentials.

That file descriptor is used to get info — address and port — about the remote side with getpeername(2), and about the local side with getsockname(2). detective work 🔍

By looking at the local side's port, blocklistd can figure out whether the client program "owns" that port. By looking at the optional address portion on the local side, it can match interfaces. By looking at the remote address, it can match specific allow or deny rules. and finally, it can peek at the socket credentials to match the user in the configuration file. the full vibe check 🔥

⚠️ ngl this all works great for TCP sockets, but you cannot rely on it for unbound UDP sockets. It's also less meaningful for connections using non-privileged ports. On the flip side: if a request comes in whose local endpoint indicates a UDP privileged port, we can presume the client was privileged enough to acquire that port in the first place. slay for them 💀

Once an entry matches, blocklistd can do a bunch of different things. If the action is "add" and the tries limit is reached, then a control script controlprog gets invoked with these arguments:

control add <rulename> <proto> <address> <mask> <port>

...and it should invoke a packet filter command to block the connection specified by those arguments. The rulename argument can be set from the command line (default is blocklistd). The script could print a numerical id to stdout as a handle for the rule, which you can use later to remove that connection — but that's not required, because all the info needed to remove the rule is kept anyway. generous of it 🎀

If the action is "rem", then that same control script gets invoked like this:

control rem <rulename> <proto> <address> <mask> <port> <id>

where id is the number that came back from the "add" action.

blocklistd keeps a database of known connections in dbfile. On startup it reads entries from that file and updates its internal state. memory queen 👑

Every timeout seconds (default 15), blocklistd checks the list of active entries and removes entries and block rules using the control program, as necessary.

The following options are available:

---

🦋 OPTIONS 🦋

• -C controlprog — use controlprog to talk to the packet filter instead of the default, which is /usr/libexec/blocklistd-helper. The following arguments get passed to the control program:
  • action — the action to perform: add, rem, or flush; to add, remove or flush a firewall rule.
  • name — the rule name.
  • protocol — the optional protocol name (can be empty): tcp, tcp6, udp, udp6.
  • address — the IPv4 or IPv6 numeric address to be blocked or released.
  • mask — the numeric mask to be applied to the blocked or released address
  • port — the optional numeric port to be blocked (can be empty).
  • id — for packet filters that support removing rules by rule identifier, the identifier of the rule to be removed. The add command is expected to return the rule identifier string to stdout.
• -c configuration — the name of the configuration file to read. When -c isn't given, the default is /etc/blocklistd.conf.
• -D dbfile — the Berkeley DB file where blocklistd stores its state. Defaults to /var/db/blocklistd.db.
• -d — normally blocklistd disassociates itself from the terminal, but with the -d flag it stays in the foreground instead. hi bestie, still here 💅
• -f — truncate the state database, and flush all the rules named rulename by invoking the control script like this:

control flush <rulename>

• -P sockpathsfile — a file containing a list of pathnames, one per line, that blocklistd will create sockets to listen to. super useful for chrooted environments 🧚
• -R rulename — specify the default rule name for the packet filter rules — usually blocklistd.
• -r — re-read the firewall rules from the internal database, then remove them and re-add them. this is the fix for packet filters that don't retain their state across reboots 🔁
• -s sockpath — add sockpath to the list of Unix sockets blocklistd listens to.
• -t timeout — the interval in seconds that blocklistd polls the state file to update the rules.
• -v — make blocklistd print diagnostic messages to stdout instead of to syslogd(8).

---

🌈 SIGNAL HANDLING 🌈

blocklistd deals with the following signals:

• HUP — receiving this signal makes blocklistd re-read the configuration file.
• INT, TERM & QUIT — these signals tell blocklistd to exit in an orderly fashion. bye bestie, no mess 😭
• USR1 — this signal tells blocklistd to increase the internal debugging level by 1.
• USR2 — this signal tells blocklistd to decrease the internal debugging level by 1.

---

🍓 FILES 🍓

• /usr/libexec/blocklistd-helper — shell script invoked to interface with the packet filter.
• /etc/blocklistd.conf — configuration file.
• /var/db/blocklistd.db — database of current connection entries.
• /var/run/blocklistd.sock — socket to receive connection notifications.

---

⭐ SEE ALSO ⭐

blocklistd.conf(5), blocklistctl(8), ipf(8), ipfw(8), pfctl(8), syslogd(8)

---

👑 HISTORY 👑

blocklistd first appeared in NetBSD 7. FreeBSD support for blocklistd was implemented in FreeBSD 11. glow-up pipeline fr fr ✨

---

💜 AUTHORS 💜

Christos Zoulas

---

Debian — February 25, 2025 🫶 that's the source and date, bestie, go forth and block those ports 💅✨