qiurui
/
freebsd-doc
mirror of https://git.FreeBSD.org/doc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

handbook/firewalls: Adapt blacklistd to blocklistd 

Follow upstream rename from blacklistd to blocklistd, and adapt the
documentation accordingly.

ftpd(8) has been changed to ftp/freebsd-ftpd, as it is no longer
included in base.

Reviewed by:	ziaee
Pull Request:	https://github.com/freebsd/freebsd-doc/pull/569
This commit is contained in:
Jose Luis Duran 2025-11-22 17:05:55 +00:00
parent 1a3cbee28a
commit d8631346f9
No known key found for this signature in database
GPG Key ID: 5415E244477475CC
1 changed files with 55 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
documentation/content/en/books/handbook/firewalls/_index.adoc
View File

@ -4,7 +4,7 @@ part: IV. Network Communication
prev: books/handbook/network-servers prev: books/handbook/network-servers
next: books/handbook/advanced-networking next: books/handbook/advanced-networking
description: "FreeBSD has three firewalls built into the base system: PF, IPFW, and IPFILTER. This chapter covers how to define packet filtering rules, the differences between the firewalls built into FreeBSD and how to use them" description: "FreeBSD has three firewalls built into the base system: PF, IPFW, and IPFILTER. This chapter covers how to define packet filtering rules, the differences between the firewalls built into FreeBSD and how to use them"
tags: ["firewall", "pf", "ipfw", "ipfilter", "blacklistd", "filtering"] tags: ["firewall", "pf", "ipfw", "ipfilter", "blocklistd", "filtering"]
showBookMenu: true showBookMenu: true
weight: 38 weight: 38
params: params:
@ -2451,48 +2451,48 @@ Refer to man:ipf[5] for a list of letters and their flags.
If the packet is an ICMP packet, there will be two fields at the end: the first always being "icmp" and the next being the ICMP message and sub-message type, separated by a slash. If the packet is an ICMP packet, there will be two fields at the end: the first always being "icmp" and the next being the ICMP message and sub-message type, separated by a slash.
For example: `icmp 3/3` for a port unreachable message. For example: `icmp 3/3` for a port unreachable message.
[[firewalls-blacklistd]] [[firewalls-blocklistd]]
== Blacklistd == Blocklistd
Blacklistd is a daemon listening to sockets awaiting to receive notifications from other daemons about connection attempts that failed or were successful. Blocklistd is a daemon listening to sockets awaiting 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. It is most widely used in blocking too many connection attempts on open ports.
A prime example is SSH running on the internet getting a lot of requests from bots or scripts trying to guess passwords and gain access. A prime example is SSH running on the internet getting a lot of requests from bots or scripts trying to guess passwords and gain access.
Using blacklistd, 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. Using blocklistd, 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. Blocklistd was first developed on NetBSD and appeared there in version 7, it was originally called blacklistd.
FreeBSD 11 imported blacklistd from NetBSD. FreeBSD 11 imported blocklistd from NetBSD.
This chapter describes how to set up blacklistd, configure it, and provides examples on how to use it. This chapter describes how to set up blocklistd, configure it, and provides examples on how to use it.
Readers should be familiar with basic firewall concepts like rules. Readers should be familiar with basic firewall concepts like rules.
For details, refer to the firewall chapter. For details, refer to the firewall chapter.
PF is used in the examples, but other firewalls available on FreeBSD should be able to work with blacklistd, too. PF is used in the examples, but other firewalls available on FreeBSD should be able to work with blocklistd, too.
=== Enabling Blacklistd === Enabling Blocklistd
The main configuration for blacklistd is stored in man:blacklistd.conf[5]. The main configuration for blocklistd is stored in man:blocklistd.conf[5].
Various command line options are also available to change blacklistd's run-time behavior. Various command line options are also available to change blocklistd's run-time behavior.
Persistent configuration across reboots should be stored in [.filename]#/etc/blacklistd.conf#. Persistent configuration across reboots should be stored in [.filename]#/etc/blocklistd.conf#.
To enable the daemon during system boot, add a `blacklistd_enable` line to [.filename]#/etc/rc.conf# like this: To enable the daemon during system boot, add a `blocklistd_enable` line to [.filename]#/etc/rc.conf# like this:
[source,shell] [source,shell]
.... ....
# sysrc blacklistd_enable=yes # sysrc blocklistd_enable=yes
.... ....
To start the service manually, run this command: To start the service manually, run this command:
[source,shell] [source,shell]
.... ....
# service blacklistd start # service blocklistd start
.... ....
=== Creating a Blacklistd Ruleset === Creating a Blocklistd Ruleset
Rules for blacklistd are configured in man:blacklistd.conf[5] with one entry per line. Rules for blocklistd are configured in man:blocklistd.conf[5] with one entry per line.
Each rule contains a tuple separated by spaces or tabs. Each rule contains a tuple separated by spaces or tabs.
Rules either belong to a `local` or a `remote`, which applies to the machine where blacklistd is running or an outside source, respectively. Rules either belong to a `local` or a `remote`, which applies to the machine where blocklistd is running or an outside source, respectively.
==== Local Rules ==== Local Rules
An example blacklistd.conf entry for a local rule looks like this: An example blocklistd.conf entry for a local rule looks like this:
[.programlisting] [.programlisting]
.... ....
@ -2505,7 +2505,7 @@ When a `[remote]` section is encountered, all rules that follow it are handled a
Seven fields separated by either tabs or spaces define a rule. Seven fields separated by either tabs or spaces define a rule.
The first four fields identify the traffic that should be blocklisted. The first four fields identify the traffic that should be blocklisted.
The three fields that follow define backlistd's behavior. The three fields that follow define blocklistd's behavior.
Wildcards are denoted as asterisks (`*`), matching anything in this field. Wildcards are denoted as asterisks (`*`), matching anything in this field.
The first field defines the location. The first field defines the location.
In local rules, these are the network ports. In local rules, these are the network ports.
@ -2523,7 +2523,7 @@ The socket type is defined by the second field.
TCP sockets are of type `stream`, whereas UDP is denoted as `dgram`. TCP sockets are of type `stream`, whereas UDP is denoted as `dgram`.
The example above uses TCP, since SSH is using that protocol. The example above uses TCP, since SSH is using that protocol.
A protocol can be used in the third field of a blacklistd rule. A protocol can be used in the third field of a blocklistd rule.
The following protocols can be used: `tcp`, `udp`, `tcp6`, `udp6`, or numeric. The following protocols can be used: `tcp`, `udp`, `tcp6`, `udp6`, 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. 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.
@ -2531,11 +2531,11 @@ In the fourth field, the effective user or owner of the daemon process that is r
The username or UID can be used here, as well as a wildcard (see example rule above). The username or UID can be used here, as well as a wildcard (see example rule above).
The packet filter rule name is declared by the fifth field, which starts the behavior part of the rule. 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 `blacklistd` in [.filename]#pf.conf# like this: By default, blocklistd puts all blocks under a pf anchor called `blocklistd` in [.filename]#pf.conf# like this:
[.programlisting] [.programlisting]
.... ....
anchor "blacklistd/*" in on $ext_if anchor "blocklistd/*" in on $ext_if
block in block in
pass out pass out
.... ....
@ -2550,7 +2550,7 @@ A modified example from the above using the hyphen would look like this:
ssh stream * * -ssh 3 24h ssh stream * * -ssh 3 24h
.... ....
With such a rule, any new blocklist rules are added to an anchor called `blacklistd-ssh`. With such a rule, any new blocklist rules are added to an anchor called `blocklistd-ssh`.
To block whole subnets for a single rule violation, a `/` in the rule name can be used. To block whole subnets for a single rule violation, a `/` 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. This causes the remaining portion of the name to be interpreted as the mask to be applied to the address specified in the rule.
@ -2573,18 +2573,18 @@ The sixth field, called `nfail`, sets the number of login failures required to b
When a wildcard is used at this position, it means that blocks will never happen. 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 SSH on one connection, the IP is blocked. In the example rule above, a limit of three is defined meaning that after three attempts to log into SSH on one connection, the IP is blocked.
The last field in a blacklistd rule definition specifies how long a host is blocklisted. The last field in a blocklistd rule definition specifies how long a host is blocklisted.
The default unit is seconds, but suffixes like `m`, `h`, and `d` can also be specified for minutes, hours, and days, respectively. The default unit is seconds, but suffixes like `m`, `h`, and `d` can also be specified for minutes, hours, and days, respectively.
The example rule in its entirety means that after three times authenticating to SSH will result in a new PF block rule for that host. The example rule in its entirety means that after three times authenticating to SSH 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. Rule matches are performed by first checking local rules one after another, from most specific to least specific.
When a match occurs, the `remote` rules are applied and the name, `nfail`, and disable fields are changed by the `remote` rule that matched. When a match occurs, the `remote` rules are applied and the `name`, `nfail`, and `duration` fields are changed by the `remote` rule that matched.
==== Remote Rules ==== Remote Rules
Remote rules are used to specify how blacklistd changes its behavior depending on the remote host currently being evaluated. Remote rules are used to specify how blocklistd 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. 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. The only difference is in the way blocklistd is using them.
To explain it, this example rule is used: To explain it, this example rule is used:
[.programlisting] [.programlisting]
@ -2597,10 +2597,10 @@ 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. This allows setting special rules for a specific remote address range like in this example.
The fields for socket type, protocol and owner are identically interpreted as in the local rule. The fields for socket type, protocol and owner are identically interpreted as in the local rule.
The name fields is different though: the equal sign (`=`) in a remote rule tells blacklistd to use the value from the matching local rule. The name fields is different though: the equal sign (`=`) in a remote rule tells blocklistd to use the value from the matching local rule.
It means that the firewall rule entry is taken and the `/25` prefix (a netmask of `255.255.255.128`) is added. It means that the firewall rule entry is taken and the `/25` prefix (a netmask of `255.255.255.128`) is added.
When a connection from that address range is blocklisted, the entire subnet is affected. When a connection from that address range is blocklisted, 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. A PF anchor name can also be used here, in which case blocklistd will add rules for this address block to the anchor of that name.
The default table is used when a wildcard is specified. The default table is used when a wildcard is specified.
A custom number of failures in the `nfail` column can be defined for an address. A custom number of failures in the `nfail` column can be defined for an address.
@ -2609,53 +2609,53 @@ Blocking is disabled when an asterisk is used in this sixth field.
Remote rules allow a stricter enforcement of limits on attempts to log in compared to attempts coming from a local network like an office. Remote rules allow a stricter enforcement of limits on attempts to log in compared to attempts coming from a local network like an office.
=== Blacklistd Client Configuration === Blocklistd Client Configuration
There are a few software packages in FreeBSD that can utilize blacklistd's functionality. There are a few software packages in FreeBSD that can utilize blocklistd's functionality.
The two most prominent ones are man:ftpd[8] and man:sshd[8] to block excessive connection attempts. The two most prominent ones are package:freebsd-ftpd[] 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#: To activate blocklistd in the SSH daemon, add the following line to [.filename]#/etc/ssh/sshd_config#:
[.programlisting] [.programlisting]
.... ....
UseBlacklist yes UseBlocklist yes
.... ....
Restart sshd afterwards to make these changes take effect. Restart sshd afterwards to make these changes take effect.
Blacklisting for man:ftpd[8] is enabled using `-B`, either in [.filename]#/etc/inetd.conf# or as a flag in [.filename]#/etc/rc.conf# like this: Blocklisting for package:freebsd-ftpd[] is enabled using `-B`, either in [.filename]#/etc/inetd.conf# or as a flag in [.filename]#/etc/rc.conf# like this:
[.programlisting] [.programlisting]
.... ....
ftpd_flags="-B" ftpd_flags="-B"
.... ....
That is all that is needed to make these programs talk to blacklistd. That is all that is needed to make these programs talk to blocklistd.
=== Blacklistd Management === Blocklistd Management
Blacklistd provides the user with a management utility called man:blacklistctl[8]. Blocklistd provides the user with a management utility called man:blocklistctl[8].
It displays blocked addresses and networks that are blocklisted by the rules defined in man:blacklistd.conf[5]. It displays blocked addresses and networks that are blocklisted by the rules defined in man:blocklistd.conf[5].
To see the list of currently blocked hosts, use `dump` combined with `-b` like this. To see the list of currently blocked hosts, use `dump` combined with `-b` like this.
[source,shell] [source,shell]
.... ....
# blacklistctl dump -b # blocklistctl dump -b
address/ma:port id nfail last access rulename address/ma:port id nfail last access
213.0.123.128/25:22 OK 6/3 2019/06/08 14:30:19 blocklistd 213.0.123.128/25:22 OK 6/3 2019/06/08 14:30:19
.... ....
This example shows that there were 6 out of three permitted attempts on port 22 coming from the address range `213.0.123.128/25`. This example shows that there were 6 out of three permitted attempts on port 22 coming from the address range `213.0.123.128/25`.
There are more attempts listed than are allowed because SSH allows a client to try multiple logins on a single TCP connection. 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. A connection that is currently going on is not stopped by blocklistd.
The last connection attempt is listed in the `last access` column of the output. The last connection attempt is listed in the `last access` column of the output.
To see the remaining time that this host will be on the blocklist, add `-r` to the previous command. To see the remaining time that this host will be on the blocklist, add `-r` to the previous command.
[source,shell] [source,shell]
.... ....
# blacklistctl dump -br # blocklistctl dump -br
address/ma:port id nfail remaining time rulename address/ma:port id nfail remaining time
213.0.123.128/25:22 OK 6/3 36s blocklistd 213.0.123.128/25:22 OK 6/3 36s
.... ....
In this example, there are 36s seconds left until this host will not be blocked any more. In this example, there are 36s seconds left until this host will not be blocked any more.
@ -2663,10 +2663,10 @@ In this example, there are 36s seconds left until this host will not be blocked
=== Removing Hosts from the Block List === Removing Hosts from the Block List
Sometimes it is necessary to remove a host from the block list before the remaining time expires. 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. Unfortunately, there is no functionality in blocklistd to do that.
However, it is possible to remove the address from the PF table using pfctl. 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#. For each blocked port, there is a child anchor inside the blocklistd anchor defined in [.filename]#/etc/pf.conf#.
For example, if there is a child anchor for blocking port 22 it is called `blacklistd/22`. For example, if there is a child anchor for blocking port 22 it is called `blocklistd/22`.
There is a table inside that child anchor that contains the blocked addresses. There is a table inside that child anchor that contains the blocked addresses.
This table is called port followed by the port number. This table is called port followed by the port number.
In this example, it would be called `port22`. In this example, it would be called `port22`.
@ -2674,7 +2674,7 @@ With that information at hand, it is now possible to use man:pfctl[8] to display
[source,shell] [source,shell]
.... ....
# pfctl -a blacklistd/22 -t port22 -T show # pfctl -a blocklistd/22 -t port22 -T show
... ...
213.0.123.128/25 213.0.123.128/25
... ...
@ -2684,9 +2684,9 @@ After identifying the address to be unblocked from the list, the following comma
[source,shell] [source,shell]
.... ....
# pfctl -a blacklistd/22 -t port22 -T delete 213.0.123.128/25 # pfctl -a blocklistd/22 -t port22 -T delete 213.0.123.128/25
.... ....
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 address is now removed from PF, but will still show up in the blocklistctl 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. The entry in blocklistd's database will eventually expire and be removed from its output.
The entry will be added again if the host is matching one of the block rules in blacklistd again. The entry will be added again if the host is matching one of the block rules in blocklistd again.