1.\" $NetBSD: blocklistd.8,v 1.8 2025/02/25 22:13:34 christos Exp $ 2.\" 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 25, 2025 31.Dt BLOCKLISTD 8 32.Os 33.Sh NAME 34.Nm blocklistd 35.Nd block and release ports on demand to avoid DoS abuse 36.Sh SYNOPSIS 37.Nm 38.Op Fl dfrv 39.Op Fl C Ar controlprog 40.Op Fl c Ar configfile 41.Op Fl D Ar dbfile 42.Op Fl P Ar sockpathsfile 43.Op Fl R Ar rulename 44.Op Fl s Ar sockpath 45.Op Fl t Ar timeout 46.Sh DESCRIPTION 47.Nm 48is a daemon similar to 49.Xr syslogd 8 50that listens to sockets at paths specified in the 51.Ar sockpathsfile 52for notifications from other daemons about successful or failed connection 53attempts. 54If no such file is specified, then it only listens to the socket path 55specified by 56.Ar sockpath 57or if that is not specified to 58.Pa /var/run/blocklistd.sock . 59Each notification contains an (action, port, protocol, address, owner) tuple 60that identifies the remote connection and the action. 61This tuple is consulted against entries from the 62.Ar configfile , 63with the syntax specified in 64.Xr blocklistd.conf 5 . 65If an entry is matched, a state entry is created for that tuple. 66Each entry contains a number of tries limit and a duration. 67.Pp 68If 69.Ar configfile 70is a directory, or a directory exists with the same name as 71.Ar configfile 72with 73.Qq .d 74appended to it, each file in the directory will be read as configuration file. 75If 76.Ar configfile 77exists as a file it will be processed before the contents of the 78.Ar configfile Ns .d 79directory if that also exists. 80.Pp 81The way 82.Nm 83does configuration entry matching is by having the client side pass the 84file descriptor associated with the connection the client wants to blocklist 85as well as passing socket credentials. 86.Pp 87The file descriptor is used to retrieve information (address and port) 88about the remote side with 89.Xr getpeername 2 90and the local side with 91.Xr getsockname 2 . 92.Pp 93By examining the port of the local side, 94.Nm 95can determine if the client program 96.Dq owns 97the port. 98By examining the optional address portion on the local side, it can match 99interfaces. 100By examining the remote address, it can match specific allow or deny rules. 101.Pp 102Finally 103.Nm 104can examine the socket credentials to match the user in the configuration file. 105.Pp 106While this works well for TCP sockets, it cannot be relied on for unbound 107UDP sockets. 108It is also less meaningful when it comes to connections using non-privileged 109ports. 110On the other hand, if we receive a request that has a local endpoint indicating 111a UDP privileged port, we can presume that the client was privileged to be 112able to acquire that port. 113.Pp 114Once an entry is matched 115.Nm 116can perform various actions. 117If the action is 118.Dq add 119and the number of tries limit is reached, then a 120control script 121.Ar controlprog 122is invoked with arguments: 123.Bd -literal -offset indent 124control add <rulename> <proto> <address> <mask> <port> 125.Ed 126.Pp 127and should invoke a packet filter command to block the connection 128specified by the arguments. 129The 130.Ar rulename 131argument can be set from the command line (default 132.Dv blocklistd ) . 133The script could print a numerical id to stdout as a handle for 134the rule that can be used later to remove that connection, but 135that is not required as all information to remove the rule is 136kept. 137.Pp 138If the action is 139.Dq rem 140Then the same control script is invoked as: 141.Bd -literal -offset indent 142control rem <rulename> <proto> <address> <mask> <port> <id> 143.Ed 144.Pp 145where 146.Ar id 147is the number returned from the 148.Dq add 149action. 150.Pp 151.Nm 152maintains a database of known connections in 153.Ar dbfile . 154On startup it reads entries from that file, and updates its internal state. 155.Pp 156.Nm 157checks the list of active entries every 158.Ar timeout 159seconds (default 160.Dv 15 ) 161and removes entries and block rules using the control program as necessary. 162.Pp 163The following options are available: 164.Bl -tag -width indent 165.It Fl C Ar controlprog 166Use 167.Ar controlprog 168to communicate with the packet filter, instead of the default, which is 169.Pa /usr/libexec/blocklistd-helper . 170The following arguments are passed to the control program: 171.Bl -tag -width protocol 172.It action 173The action to perform: 174.Dv add , 175.Dv rem , 176or 177.Dv flush ; 178to add, remove or flush a firewall rule. 179.It name 180The rule name. 181.It protocol 182The optional protocol name (can be empty): 183.Dv tcp , 184.Dv tcp6 , 185.Dv udp , 186.Dv udp6 . 187.It address 188The IPv4 or IPv6 numeric address to be blocked or released. 189.It mask 190The numeric mask to be applied to the blocked or released address 191.It port 192The optional numeric port to be blocked (can be empty). 193.It id 194For packet filters that support removal of rules by rule identifier, the 195identifier of the rule to be removed. 196The add command is expected to return the rule identifier string to stdout. 197.El 198.It Fl c Ar configuration 199The name of the configuration file to read. 200The default when 201.Fl c 202is not given is 203.Pa /etc/blocklistd.conf . 204.It Fl D Ar dbfile 205The Berkeley DB file where 206.Nm 207stores its state. 208It defaults to 209.Pa /var/db/blocklistd.db . 210.It Fl d 211Normally, 212.Nm 213disassociates itself from the terminal unless the 214.Fl d 215flag is specified, in which case it stays in the foreground. 216.It Fl f 217Truncate the state database and flush all the rules named 218.Ar rulename 219are deleted by invoking the control script as: 220.Bd -literal -offset indent 221control flush <rulename> 222.Ed 223.It Fl P Ar sockpathsfile 224A file containing a list of pathnames, one per line that 225.Nm 226will create sockets to listen to. 227This is useful for chrooted environments. 228.It Fl R Ar rulename 229Specify the default rule name for the packet filter rules, usually 230.Dv blocklistd . 231.It Fl r 232Re-read the firewall rules from the internal database, then 233remove and re-add them. 234This helps for packet filters that do not retain state across reboots. 235.It Fl s Ar sockpath 236Add 237.Ar sockpath 238to the list of Unix sockets 239.Nm 240listens to. 241.It Fl t Ar timeout 242The interval in seconds 243.Nm 244polls the state file to update the rules. 245.It Fl v 246Cause 247.Nm 248to print 249diagnostic messages to 250.Dv stdout 251instead of 252.Xr syslogd 8 . 253.El 254.Sh SIGNAL HANDLING 255.Nm 256deals with the following signals: 257.Bl -tag -width "USR2" 258.It Dv HUP 259Receipt of this signal causes 260.Nm 261to re-read the configuration file. 262.It Dv INT , Dv TERM & Dv QUIT 263These signals tell 264.Nm 265to exit in an orderly fashion. 266.It Dv USR1 267This signal tells 268.Nm 269to increase the internal debugging level by 1. 270.It Dv USR2 271This signal tells 272.Nm 273to decrease the internal debugging level by 1. 274.El 275.Sh FILES 276.Bl -tag -width /usr/libexec/blocklistd-helper -compact 277.It Pa /usr/libexec/blocklistd-helper 278Shell script invoked to interface with the packet filter. 279.It Pa /etc/blocklistd.conf 280Configuration file. 281.It Pa /var/db/blocklistd.db 282Database of current connection entries. 283.It Pa /var/run/blocklistd.sock 284Socket to receive connection notifications. 285.El 286.Sh SEE ALSO 287.Xr blocklistd.conf 5 , 288.Xr blocklistctl 8 , 289.Xr ipf 8 , 290.Xr ipfw 8 , 291.Xr pfctl 8 , 292.Xr syslogd 8 293.Sh HISTORY 294.Nm 295first appeared in 296.Nx 7 . 297.Fx 298support for 299.Nm 300was implemented in 301.Fx 11 . 302.Sh AUTHORS 303.An Christos Zoulas 304