1.\" $NetBSD: blacklistd.8,v 1.23 2020/04/21 13:57:12 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 April 21, 2020 31.Dt BLACKLISTD 8 32.Os 33.Sh NAME 34.Nm blacklistd 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 sockspath 57or if that is not specified to 58.Pa /var/run/blacklistd.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 in 62.Ar configfile 63with syntax specified in 64.Xr blacklistd.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 68The way 69.Nm 70does configuration entry matching is by having the client side pass the 71file descriptor associated with the connection the client wants to blacklist 72as well as passing socket credentials. 73.Pp 74The file descriptor is used to retrieve information (address and port) 75about the remote side with 76.Xr getpeername 2 77and the local side with 78.Xr getsockname 2 . 79.Pp 80By examining the port of the local side, 81.Nm 82can determine if the client program 83.Dq owns 84the port. 85By examining the optional address portion on the local side, it can match 86interfaces. 87By examining the remote address, it can match specific allow or deny rules. 88.Pp 89Finally 90.Nm 91can examine the socket credentials to match the user in the configuration file. 92.Pp 93While this works well for TCP sockets, it cannot be relied on for unbound 94UDP sockets. 95It is also less meaningful when it comes to connections using non-privileged 96ports. 97On the other hand, if we receive a request that has a local endpoint indicating 98a UDP privileged port, we can presume that the client was privileged to be 99able to acquire that port. 100.Pp 101Once an entry is matched 102.Nm 103can perform various actions. 104If the action is 105.Dq add 106and the number of tries limit is reached, then a 107control script 108.Ar controlprog 109is invoked with arguments: 110.Bd -literal -offset indent 111control add <rulename> <proto> <address> <mask> <port> 112.Ed 113.Pp 114and should invoke a packet filter command to block the connection 115specified by the arguments. 116The 117.Ar rulename 118argument can be set from the command line (default 119.Dv blacklistd ) . 120The script could print a numerical id to stdout as a handle for 121the rule that can be used later to remove that connection, but 122that is not required as all information to remove the rule is 123kept. 124.Pp 125If the action is 126.Dq rem 127Then the same control script is invoked as: 128.Bd -literal -offset indent 129control rem <rulename> <proto> <address> <mask> <port> <id> 130.Ed 131.Pp 132where 133.Ar id 134is the number returned from the 135.Dq add 136action. 137.Pp 138.Nm 139maintains a database of known connections in 140.Ar dbfile . 141On startup it reads entries from that file, and updates its internal state. 142.Pp 143.Nm 144checks the list of active entries every 145.Ar timeout 146seconds (default 147.Dv 15 ) 148and removes entries and block rules using the control program as necessary. 149.Pp 150The following options are available: 151.Bl -tag -width indent 152.It Fl C Ar controlprog 153Use 154.Ar controlprog 155to communicate with the packet filter, usually 156.Pa /usr/libexec/blacklistd-helper . 157The following arguments are passed to the control program: 158.Bl -tag -width protocol 159.It action 160The action to perform: 161.Dv add , 162.Dv rem , 163or 164.Dv flush 165to add, remove or flush a firewall rule. 166.It name 167The rule name. 168.It protocol 169The optional protocol name (can be empty): 170.Dv tcp , 171.Dv tcp6 , 172.Dv udp , 173.Dv udp6 . 174.It address 175The IPv4 or IPv6 numeric address to be blocked or released. 176.It mask 177The numeric mask to be applied to the blocked or released address 178.It port 179The optional numeric port to be blocked (can be empty). 180.It id 181For packet filters that support removal of rules by rule identifier, the 182identifier of the rule to be removed. 183The add command is expected to return the rule identifier string to stdout. 184.El 185.It Fl c Ar configuration 186The name of the configuration file to read, usually 187.Pa /etc/blacklistd.conf . 188.It Fl D Ar dbfile 189The Berkeley DB file where 190.Nm 191stores its state, usually 192.Pa /var/db/blacklistd.db . 193.It Fl d 194Normally, 195.Nm 196disassociates itself from the terminal unless the 197.Fl d 198flag is specified, in which case it stays in the foreground. 199.It Fl f 200Truncate the state database and flush all the rules named 201.Ar rulename 202are deleted by invoking the control script as: 203.Bd -literal -offset indent 204control flush <rulename> 205.Ed 206.It Fl P Ar sockspathsfile 207A file containing a list of pathnames, one per line that 208.Nm 209will create sockets to listen to. 210This is useful for chrooted environments. 211.It Fl R Ar rulename 212Specify the default rule name for the packet filter rules, usually 213.Dv blacklistd . 214.It Fl r 215Re-read the firewall rules from the internal database, then 216remove and re-add them. 217This helps for packet filters that do not retain state across reboots. 218.It Fl s Ar sockpath 219Add 220.Ar sockpath 221to the list of Unix sockets 222.Nm 223listens to. 224.It Fl t Ar timeout 225The interval in seconds 226.Nm 227polls the state file to update the rules. 228.It Fl v 229Cause 230.Nm 231to print 232diagnostic messages to 233.Dv stdout 234instead of 235.Xr syslogd 8 . 236.El 237.Sh SIGNAL HANDLING 238.Nm 239deals with the following signals: 240.Bl -tag -width "USR2" 241.It Dv HUP 242Receipt of this signal causes 243.Nm 244to re-read the configuration file. 245.It Dv INT , Dv TERM & Dv QUIT 246These signals tell 247.Nm 248to exit in an orderly fashion. 249.It Dv USR1 250This signal tells 251.Nm 252to increase the internal debugging level by 1. 253.It Dv USR2 254This signal tells 255.Nm 256to decrease the internal debugging level by 1. 257.El 258.Sh FILES 259.Bl -tag -width /usr/libexec/blacklistd-helper -compact 260.It Pa /usr/libexec/blacklistd-helper 261Shell script invoked to interface with the packet filter. 262.It Pa /etc/blacklistd.conf 263Configuration file. 264.It Pa /var/db/blacklistd.db 265Database of current connection entries. 266.It Pa /var/run/blacklistd.sock 267Socket to receive connection notifications. 268.El 269.Sh SEE ALSO 270.Xr blacklistd.conf 5 , 271.Xr blacklistctl 8 , 272.Xr pfctl 8 , 273.Xr syslogd 8 274.Sh HISTORY 275.Nm 276first appeared in 277.Nx 7 . 278.Fx 279support for 280.Nm 281was implemented in 282.Fx 11 . 283.Sh AUTHORS 284.An Christos Zoulas 285