1.\" $NetBSD: blacklistd.8,v 1.14 2015/06/04 16:11:48 wiz 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 June 4, 2015 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 a 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/blsock . 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 68If the action is 69.Dq add 70and the number of tries limit is reached, then a 71control script 72.Ar controlprog 73is invoked with arguments: 74.Bd -literal -offset indent 75control add <rulename> <proto> <address> <mask> <port> 76.Ed 77.Pp 78and should invoke a packet filter command to block the connection 79specified by the arguments. 80The 81.Ar rulename 82argument can be set from the command line (default 83.Dv blacklistd ) . 84The script could print a numerical id to stdout as a handle for 85the rule that can be used later to remove that connection, but 86that is not required as all information to remove the rule is 87kept. 88.Pp 89If the action is 90.Dq remove 91Then the same control script is invoked as: 92.Bd -literal -offset indent 93control remove <rulename> <proto> <address> <mask> <port> <id> 94.Ed 95.Pp 96where 97.Ar id 98is the number returned from the 99.Dq add 100action. 101.Pp 102.Nm 103maintains a database of known connections in 104.Ar dbfile . 105On startup it reads entries from that file, and updates its internal state. 106.Pp 107.Nm 108checks the list of active entries every 109.Ar timeout 110seconds (default 111.Dv 15 ) 112and removes entries and block rules using the control program as necessary. 113.Pp 114The following options are available: 115.Bl -tag -width indent 116.It Fl C Ar controlprog 117Use 118.Ar controlprog 119to communicate with the packet filter, usually 120.Pa /libexec/blacklistd-helper . 121The following arguments are passed to the control program: 122.Bl -tag -width protocol 123.It action 124The action to perform: 125.Dv add , 126.Dv rem , 127or 128.Dv flush 129to add, remove or flush a firewall rule. 130.It name 131The rule name. 132.It protocol 133The optional protocol name (can be empty): 134.Dv tcp , 135.Dv tcp6 , 136.Dv udp , 137.Dv udp6 . 138.It address 139The IPv4 or IPv6 numeric address to be blocked or released. 140.It mask 141The numeric mask to be applied to the blocked or released address 142.It port 143The optional numeric port to be blocked (can be empty). 144.It id 145For packet filters that support removal of rules by rule identifier, the 146identifier of the rule to be removed. 147The add command is expected to return the rule identifier string to stdout. 148.El 149.It Fl c Ar configuration 150The name of the configuration file to read, usually 151.Pa /etc/blacklistd.conf . 152.It Fl D Ar dbfile 153The Berkeley DB file where 154.Nm 155stores its state, usually 156.Pa /var/run/blacklistd.db . 157.It Fl d 158Normally, 159.Nm 160disassociates itself from the terminal unless the 161.Fl d 162flag is specified, in which case it stays in the foreground. 163.It Fl f 164Truncate the state database and flush all the rules named 165.Ar rulename 166are deleted by invoking the control script as: 167.Bd -literal -offset indent 168control flush <rulename> 169.Ed 170.It Fl P Ar sockspathsfile 171A file containing a list of pathnames, one per line that 172.Nm 173will create sockets to listen to. 174This is useful for chrooted environments. 175.It Fl R Ar rulename 176Specify the default rule name for the packet filter rules, usually 177.Dv blacklistd . 178.It Fl r 179Re-read the firewall rules from the internal database, then 180remove and re-add them. 181This helps for packet filters that don't retain state across reboots. 182.It Fl s Ar sockpath 183Add 184.Ar sockpath 185to the list of Unix sockets 186.Nm 187listens to. 188.It Fl t Ar timeout 189The interval in seconds 190.Nm 191polls the state file to update the rules. 192.It Fl v 193Cause 194.Nm 195to print 196diagnostic messages to 197.Dv stdout 198instead of 199.Xr syslogd 8 . 200.El 201.Sh FILES 202.Bl -tag -width /libexec/blacklistd-helper -compact 203.It Pa /libexec/blacklistd-helper 204Shell script invoked to interface with the packet filter. 205.It Pa /etc/blacklistd.conf 206Configuration file. 207.It Pa /var/db/blacklistd.db 208Database of current connection entries. 209.It Pa /var/run/blsock 210Socket to receive connection notifications. 211.El 212.Sh SEE ALSO 213.Xr blacklistd.conf 5 , 214.Xr blacklistctl 8 , 215.Xr npfctl 8 , 216.Xr syslogd 8 217.Sh HISTORY 218.Nm 219appeared in 220.Nx 7 . 221.Sh AUTHORS 222.An Christos Zoulas 223