BLACKLISTD(8)

🖤 BLACKLISTD(8) — the blacklistd girlies' guide

okay so real talk, this is the BLACKLISTD(8) page from the System Manager's Manual and it's basically the bouncer at the club of your network. let's get into it bestie ✨

---

🌸 NAME 🌸

blacklistd — block and release ports on demand to avoid DoS abuse 💅

---

✨ SYNOPSIS ✨

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

---

💖 DESCRIPTION 💖

okay so blacklistd is a daemon, kinda like syslogd(8)'s cooler cousin. it listens on sockets at the paths listed in the sockpathsfile, waiting for notifications from other daemons about connection attempts that either slayed or flopped. 🫶

if no such file is specified, then it only listens to the socket path given by sockpath, or — if that's also not specified — to /var/run/blocklistd.sock. no cap.

every notification carries an (action, port, protocol, address, owner) tuple that IDs the remote connection plus the action. that tuple gets checked against the entries in the configfile, using the syntax from blacklistd.conf(5). if an entry matches, a state entry is born for that tuple — and each entry comes with a number-of-tries limit and a duration. it's giving ✨consequences✨.

if configfile is a directory, or a directory exists with the same name as configfile with ".d" appended to it, every file in that directory gets read as a config file. and if configfile exists as a file, it gets processed before the contents of the configfile.d directory — assuming that one exists too.

here's the tea on how blacklistd does config entry matching: the client side passes the file descriptor tied to the connection it wants blacklisted, plus the socket credentials.

that file descriptor gets used to pull info (address and port) about the remote side with getpeername(2), and about the local side with getsockname(2).

by examining the port of the local side, blacklistd can tell whether the client program "owns" the port. by examining the optional address portion on the local side, it can match interfaces. and by examining the remote address, it can match specific allow or deny rules. 🎯

finally, blacklistd can peek at the socket credentials to match the user in the config file.

lowkey important: while this works great for TCP sockets, it cannot be relied on for unbound UDP sockets. it's also less meaningful when it comes to connections using non-privileged ports. on the other hand, if a request comes in that has a local endpoint indicating a UDP privileged port, we can presume the client was privileged enough to acquire that port. iykyk.

once an entry matches, blacklistd can do a bunch of different actions. if the action is “add” and the number-of-tries limit is reached, 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 blacklistd). the script could print a numerical id to stdout as a handle for the rule, so it can be used later to remove that connection — but that's not required, because all the info needed to remove the rule is kept anyway. 💅

if the action is “rem”, then the same control script gets invoked as:

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

where id is the number returned from the “add” action.

blacklistd keeps a whole lil database of known connections in dbfile. on startup it reads entries from that file and updates its internal state. 🌈

blacklistd checks the list of active entries every timeout seconds (default 15) and removes entries and block rules using the control program as needed.

the following options are available:

---

🎀 OPTIONS 🎀

• -C controlprog — use controlprog to communicate with the packet filter instead of the default, which is /usr/libexec/blacklistd-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 removal of 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. the default when -c isn't given is /etc/blacklistd.conf.
• -D dbfile — the Berkeley DB file where blacklistd stores its state. defaults to /var/db/blocklistd.db.
• -d — normally blacklistd disassociates itself from the terminal, unless the -d flag is specified, in which case it stays in the foreground. main character energy, honestly.
• -f — truncate the state database and flush all the rules named rulename are deleted by invoking the control script as:

control flush <rulename>

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

---

⭐ SIGNAL HANDLING ⭐

blacklistd deals with the following signals:

• HUP — receipt of this signal causes blacklistd to re-read the configuration file.
• INT, TERM & QUIT — these signals tell blacklistd to exit in an orderly fashion. say bye nicely bestie 👋
• USR1 — this signal tells blacklistd to increase the internal debugging level by 1.
• USR2 — this signal tells blacklistd to decrease the internal debugging level by 1.

---

🧚 FILES 🧚

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

---

👑 SEE ALSO 👑

blacklistd.conf(5), blacklistctl(8), ipf(8), ipfw(8), pfctl(8), syslogd(8)

---

💀 NOTES 💀

the blacklistd daemon has been renamed to blocklistd(8). periodt. ✨

---

🌸 HISTORY 🌸

blacklistd first appeared in NetBSD 7. FreeBSD support for blacklistd was implemented in FreeBSD 11.

---

💜 AUTHORS 💜

Christos Zoulas

---

okay that's the whole page 🫶 this one's from Debian, dated February 25, 2025 — and honestly? iconic of them. go block some ports responsibly, bestie 💖🎀