contrib/blacklist/bin/blacklistd.8

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