Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
BLOCKLISTD(8) System Manager's Manual BLOCKLISTD(8)
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
blocklistd is a daemon similar to syslogd(8) that listens to sockets at
paths specified in the sockpathsfile for notifications from other daemons
about successful or failed connection attempts. If no such file is
specified, then it only listens to the socket path specified by sockspath
or if that is not specified to /var/run/blocklistd.sock. Each
notification contains an (action, port, protocol, address, owner) tuple
that identifies the remote connection and the action. This tuple is
consulted against entries in configfile with syntax specified in
blocklistd.conf(5). If an entry is matched, a state entry is created for
that tuple. Each entry contains a number of tries limit and a duration.
The way blocklistd does configuration entry matching is by having the
client side pass the file descriptor associated with the connection the
client wants to blocklist as well as passing socket credentials.
The file descriptor is used to retrieve information (address and port)
about the remote side with getpeername(2) and the local side with
getsockname(2).
By examining the port of the local side, blocklistd can determine if the
client program "owns" the port. By examining the optional address
portion on the local side, it can match interfaces. By examining the
remote address, it can match specific allow or deny rules.
Finally blocklistd can examine the socket credentials to match the user
in the configuration file.
While this works well for TCP sockets, it cannot be relied on for unbound
UDP sockets. It is also less meaningful when it comes to connections
using non-privileged ports. On the other hand, if we receive a request
that has a local endpoint indicating a UDP privileged port, we can
presume that the client was privileged to be able to acquire that port.
Once an entry is matched blocklistd can perform various actions. If the
action is "add" and the number of tries limit is reached, then a control
script controlprog is invoked with arguments:
control add <rulename> <proto> <address> <mask> <port>
and should invoke a packet filter command to block the connection
specified by the arguments. The rulename argument can be set from the
command line (default blocklistd). The script could print a numerical id
to stdout as a handle for the rule that can be used later to remove that
connection, but that is not required as all information to remove the
rule is kept.
If the action is "rem" Then the same control script is invoked as:
control rem <rulename> <proto> <address> <mask> <port> <id>
where id is the number returned from the "add" action.
blocklistd maintains a database of known connections in dbfile. On
startup it reads entries from that file, and updates its internal state.
blocklistd checks the list of active entries every timeout seconds
(default 15) and removes entries and block rules using the control
program as necessary.
The following options are available:
-C controlprog
Use controlprog to communicate with the packet filter, usually
/libexec/blocklistd-helper. The following arguments are 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, usually
/etc/blocklistd.conf.
-D dbfile
The Berkeley DB file where blocklistd stores its state, usually
/var/db/blocklistd.db.
-d Normally, blocklistd disassociates itself from the terminal
unless the -d flag is specified, in which case it stays in the
foreground.
-f Truncate the state database and flush all the rules named
rulename are deleted by invoking the control script as:
control flush <rulename>
-P sockspathsfile
A file containing a list of pathnames, one per line that
blocklistd 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 blocklistd.
-r Re-read the firewall rules from the internal database, then
remove and re-add them. This helps for packet filters that do
not retain state across reboots.
-s sockpath
Add sockpath to the list of Unix sockets blocklistd listens to.
-t timeout
The interval in seconds blocklistd polls the state file to update
the rules.
-v Cause blocklistd to print diagnostic messages to stdout instead
of syslogd(8).
SIGNAL HANDLING
blocklistd deals with the following signals:
HUP Receipt of this signal causes blocklistd to re-read the
configuration file.
INT, TERM & QUIT
These signals tell blocklistd to exit in an orderly fashion.
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
/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), npfctl(8), syslogd(8)
HISTORY
blocklistd first appeared in NetBSD 7. FreeBSD support for blocklistd
was implemented in FreeBSD 11.
AUTHORS
Christos Zoulas
NetBSD 10.99 April 21, 2020 NetBSD 10.99