diff options
Diffstat (limited to 'en_US.ISO8859-1/books')
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/firewalls/chapter.xml | 323 |
1 files changed, 323 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml index e1d7b26bbd..0a55823d28 100644 --- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml @@ -3788,4 +3788,327 @@ LOG_ERR - packets which have been logged and which can be considered short due t message.</para> </sect2> </sect1> + + <sect1 xml:id="firewalls-blacklistd"> + <title>Blacklistd</title> + + <para>Blacklistd is a daemon listening to sockets to receive + notifications from other daemons about connection attempts + that failed or were successful. It is most widely used in + blocking too many connection attempts on open ports. A + prime example is <application>SSH</application> running on + the internet getting a lot of requests from bots or scripts + trying to guess passwords and gain access. Using + <application>blacklistd</application>, the daemon can notify + the firewall to create a filter rule to block excessive + connection attempts from a single source after a number of + tries. Blacklistd was first developed on + NetBSD and appeared there in version 7. &os; 11 + imported blacklistd from NetBSD.</para> + + <para>This chapter describes how to set up blacklistd, + configure it, and provides examples on how to use it. + Readers should be familiar with basic firewall concepts like + rules. For details, refer to the firewall chapter. PF is + used in the examples, but other firewalls available on + &os; should be able to work with blacklistd, too.</para> + + <sect2> + <title>Enabling Blacklistd</title> + + <para>The main configuration for blacklistd is stored in + &man.blacklistd.conf.5;. Various command line options are + also available to change blacklistd's run-time behavior. + Persistent configuration across reboots should be stored + in <filename>/etc/blacklistd.conf</filename>. To enable + the daemon during system boot, add a + <literal>blacklistd_enable</literal> line to + <filename>/etc/rc.conf</filename> like this:</para> + + <screen>&prompt.root; <userinput>sysrc blacklistd_enable=yes</userinput></screen> + + <para>To start the service manually, run this command:</para> + + <screen>&prompt.root; <userinput>service blacklistd start</userinput></screen> + </sect2> + + <sect2> + <title>Creating a Blacklistd Ruleset</title> + + <para>Rules for blacklistd are configured in + &man.blacklistd.conf.5; with one entry per line. Each + rule contains a tuple separated by spaces or tabs. Rules + either belong to a <literal>local</literal> or a + <literal>remote</literal>, which applies to the machine + where blacklistd is running or an outside source, + respectively.</para> + + <sect3> + <title>Local Rules</title> + + <para>An example blacklistd.conf entry for a local rule + looks like this:</para> + + <programlisting>[local] +ssh stream * * * 3 24h</programlisting> + + <para>All rules that follow the <literal>[local]</literal> + section are treated as local rules (which is the + default), applying to the local machine. When a + <literal>[remote]</literal> section is encountered, all + rules that follow it are handled as remote machine + rules.</para> + + <para>Seven fields define a rule separated by either tabs + or spaces. The first four fields identify the traffic + that should be blacklisted. The three fields that + follow define backlistd's behavior. Wildcards are + denoted as asterisks (<literal>*</literal>), matching + anything in this field. The first field defines the + location. In local rules, these are the network ports. + The syntax for the location field is as follows:</para> + + <programlisting>[<replaceable>address</replaceable>|<replaceable>interface</replaceable>][/<replaceable>mask</replaceable>][:<replaceable>port</replaceable>]</programlisting> + + <para>Adressses can be specified as IPv4 in numeric format + or IPv6 in square brackets. An interface name like + <literal><replaceable>em0</replaceable></literal> can also + be used.</para> + + <para>The socket type is defined by the second field. TCP + sockets are of type <literal>stream</literal>, whereas UDP + is denoted as <literal>dgram</literal>. The example above + uses TCP, since SSH is using that protocol.</para> + + <para>A protocol can be used in the third field of a + blacklistd rule. The following protocols can be used: + <literal>tcp</literal>, <literal>udp</literal>, + <literal>tcp6</literal>, <literal>udp6</literal>, or + numeric. A wildcard, like in the example, is typically + used to match all protocols unless there is a reason to + distinguish traffic by a certain protocol.</para> + + <para>In the fourth field, the effective user or owner of + the daemon process that is reporting the event is defined. + The username or <acronym>UID</acronym> can be used here, + as well as a wildcard (see example rule above).</para> + + <para>The packet filter rule name is declared by the fifth + field, which starts the behavior part of the rule. By + default, blacklistd puts all blocks under a pf anchor + called <literal>blacklistd</literal> in + <filename>pf.conf</filename> like this:</para> + + <programlisting>anchor "blacklistd/*" in on $ext_if +block in +pass out</programlisting> + + <para>For separate blacklists, an anchor name can be used in + this field. In other cases, the wildcard will suffice. + When a name starts with a hyphen (<literal>-</literal>) it + means that an anchor with the default rule name prepended + should be used. A modified example from the above using + the hyphen would look like this:</para> + + <programlisting>ssh stream * * -ssh 3 24h</programlisting> + + <para>With such a rule, any new blacklist rules are added to + an anchor called <literal>blacklistd-ssh</literal>.</para> + + <para>To block whole subnets for a single rule violation, a + <literal>/</literal> in the rule name can be used. This + causes the remaining portion of the name to be interpreted + as the mask to be applied to the address specified in + the rule. For example, this rule would block every + address adjoining <literal>/24</literal>.</para> + + <programlisting>22 stream tcp * */24 3 24h</programlisting> + + <note> + <para>It is important to specify the proper + protocol here. IPv4 and IPv6 treat /24 differently, + that is the reason why <literal>*</literal> cannot be + used in the third field for this rule.</para> + </note> + + <para>This rule defines that if any one host in that network + is misbehaving, everything else on that network will be + blocked, too.</para> + + <para>The sixth field, called <literal>nfail</literal>, sets + the number of login failures required to blacklist the + remote IP in question. When a wildcard is used at this + position, it means that blocks will never happen. In the + example rule above, a limit of three is defined meaning + that after three attempts to log into + <application>SSH</application> on one connection, the IP + is blocked.</para> + + <para>The last field in a blacklistd rule definition + specifies how long a host is blacklisted. The default + unit is seconds, but suffixes like <literal>m</literal>, + <literal>h</literal>, and <literal>d</literal> can also be + specified for minutes, hours, and days, + respectively.</para> + + <para>The example rule in its entirety means that after + three times authenticating to + <application>SSH</application> will result in a new PF + block rule for that host. Rule matches are performed by + first checking local rules one after another, from most + specific to least specific. When a match occurs, the + <literal>remote</literal> rules are applied and the name, + <literal>nfail</literal>, and disable fields are changed + by the <literal>remote</literal> rule that matched.</para> + </sect3> + + <sect3> + <title>Remote Rules</title> + + <para>Remote rules are used to specify how blacklistd + changes its behavior depending on the remote host + currently being evaluated. Each field in a remote rule + is the same as in a local rule. The only difference is + in the way blacklistd is using them. To explain it, + this example rule is used:</para> + + <programlisting>[remote] +203.0.113.128/25 * * * =/25 = 48h</programlisting> + + <para>The address field can be an IP address (either v4 or + v6), a port or both. This allows setting special rules + for a specific remote address range like in this example. + The fields for type, protocol and owner are identically + interpreted as in the local rule.</para> + + <para>The name fields is different though: the equal sign + (<literal>=</literal>) in a remote rule tells blacklistd + to use the value from the matching local rule. It means + that the firewall rule entry is taken and the + <systemitem class="netmask">/25</systemitem> prefix (a + netmask of <systemitem + class="netmask">255.255.255.128</systemitem>) is added. + When a connection from that address range is blacklisted, + the entire subnet is affected. A PF anchor name can also + be used here, in which case blacklistd will add rules for + this address block to the anchor of that name. The + default table is used when a wildcard is specified.</para> + + <para>A custom number of failures in the + <literal>nfail</literal> column can be defined for an + address. This is useful for exceptions to a specific + rule, to maybe allow someone a less strict application + of rules or a bit more leniency in login tries. + Blocking is disabled when an asterisk is used in this + sixth field.</para> + + <para>Remote rules allow a stricter enforcement of limits + on attempts to log in compared to attempts coming from a + local network like an office.</para> + </sect3> + </sect2> + + <sect2> + <title>Blacklistd Client Configuration</title> + + <para>There are a few software packages in &os; that can + utilize blacklistd's functionality. The two most + prominent ones are &man.ftpd.8; and &man.sshd.8; to block + excessive connection attempts. To activate blacklistd in + the SSH daemon, add the following line to + <filename>/etc/ssh/sshd_config</filename>:</para> + + <programlisting>UseBlacklist yes</programlisting> + + <para>Restart sshd afterwards to make these changes take + effect.</para> + + <para>Blacklisting for &man.ftpd.8; is enabled using + <literal>-B</literal>, either in + <filename>/etc/inetd.conf</filename> or as a + flag in <filename>/etc/rc.conf</filename> like + this:</para> + + <programlisting>ftpd_flags="-B"</programlisting> + + <para>That is all that is needed to make these programs + talk to blacklistd.</para> + </sect2> + + <sect2> + <title>Blacklistd Management</title> + + <para>Blacklistd provides the user with a management utility + called &man.blacklistctl.8;. It displays blocked + addresses and networks that are blacklisted by the rules + defined in &man.blacklistd.conf.5;. To see the + list of currently blocked hosts, use + <command>dump</command> combined with <option>-b</option> + like this.</para> + + <screen>&prompt.root; <userinput>blacklistctl dump -b</userinput> + address/ma:port id nfail last access +213.0.123.128/25:22 OK 6/3 2019/06/08 14:30:19</screen> + + <para>This example shows that there were 6 out of three + permitted attempts on port 22 coming from the address + range <systemitem + class="netmask">213.0.123.128/25</systemitem>. There + are more attempts listed than are allowed because SSH + allows a client to try multiple logins on a single TCP + connection. A connection that is currently going on is + not stopped by blacklistd. The last connection attempt is + listed in the <literal>last access</literal> column of the + output.</para> + + <para>To see the remaining time that this host will be on + the blacklist, add <option>-r</option> to the previous + command.</para> + + <screen>&prompt.root; <userinput>blacklistctl dump -br</userinput> + address/ma:port id nfail remaining time +213.0.123.128/25:22 OK 6/3 36s</screen> + + <para>In this example, there are 36s seconds left until this + host will not be blocked any more.</para> + </sect2> + + <sect2> + <title>Removing Hosts from the Block List</title> + + <para>Sometimes it is necessary to remove a host from the + block list before the remaining time expires. + Unfortunately, there is no functionality in blacklistd to + do that. However, it is possible to remove the address + from the PF table using pfctl. For each blocked port, + there is a child anchor inside the blacklistd anchor + defined in <filename>/etc/pf.conf</filename>. For + example, if there is a child anchor for blocking port 22 + it is called <literal>blacklistd/22</literal>. There is a + table inside that child anchor that contains the blocked + addresses. This table is called port followed by the port + number. In this example, it would be called + <literal>port22</literal>. With that information at hand, + it is now possible to use &man.pfctl.8; to display all + addresses listed like this:</para> + + <screen>&prompt.root; <userinput>pfctl -a <replaceable>blacklistd/22</replaceable> -t <replaceable>port22</replaceable> -T show</userinput> +... +213.0.123.128/25 +...</screen> + + <para>After identifying the address to be unblocked from the + list, the following command removes it from the list:</para> + + <screen>&prompt.root; <userinput>pfctl -a <replaceable>blacklistd/22</replaceable> -T delete <replaceable>213.0.123.128/25</replaceable></userinput></screen> + + <para>The address is now removed from PF, but will still + show up in the blacklistctl list, since it does not know + about any changes made in PF. The entry in blacklistd's + database will eventually expire and be removed from its + output eventually. The entry will be added again if the + host is matching one of the block rules in blacklistd + again.</para> + </sect2> + </sect1> </chapter> |