git: aa05c93cb793 - main - blacklistd: Update documentation changes

The branch main has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=aa05c93cb793f65cb3bed1548e514f9943c6472e

commit aa05c93cb793f65cb3bed1548e514f9943c6472e
Author:     Jose Luis Duran <jlduran@gmail.com>
AuthorDate: 2022-10-12 13:23:39 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2022-10-12 13:27:08 +0000

    blacklistd: Update documentation changes
    
    Cherry-pick upstream documentation changes.
    
    Obtained from:   https://github.com/zoulasc/blocklist
    Differential Revision:  https://reviews.freebsd.org/D36086
---
 contrib/blacklist/bin/blacklistd.8      | 52 ++++++++++++++++++++++++++++-----
 contrib/blacklist/bin/blacklistd.conf.5 |  6 ++--
 contrib/blacklist/lib/libblacklist.3    | 18 +++++++++---
 3 files changed, 61 insertions(+), 15 deletions(-)

diff --git a/contrib/blacklist/bin/blacklistd.8 b/contrib/blacklist/bin/blacklistd.8
index ec7f8b429d9d..82e1f15f61c9 100644
--- a/contrib/blacklist/bin/blacklistd.8
+++ b/contrib/blacklist/bin/blacklistd.8
@@ -1,4 +1,4 @@
-.\" $NetBSD: blacklistd.8,v 1.18 2016/07/30 06:09:29 dholland Exp $
+.\" $NetBSD: blacklistd.8,v 1.23 2020/04/21 13:57:12 christos Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 5, 2018
+.Dd April 21, 2020
 .Dt BLACKLISTD 8
 .Os
 .Sh NAME
@@ -65,6 +65,42 @@ with syntax specified in
 If an entry is matched, a state entry is created for that tuple.
 Each entry contains a number of tries limit and a duration.
 .Pp
+The way
+.Nm
+does configuration entry matching is by having the client side pass the
+file descriptor associated with the connection the client wants to blacklist
+as well as passing socket credentials.
+.Pp
+The file descriptor is used to retrieve information (address and port)
+about the remote side with
+.Xr getpeername 2
+and the local side with
+.Xr getsockname 2 .
+.Pp
+By examining the port of the local side,
+.Nm
+can determine if the client program
+.Dq owns
+the port.
+By examining the optional address portion on the local side, it can match
+interfaces.
+By examining the remote address, it can match specific allow or deny rules.
+.Pp
+Finally
+.Nm
+can examine the socket credentials to match the user in the configuration file.
+.Pp
+While this works well for TCP sockets, it cannot be relied on for unbound
+UDP sockets.
+It is also less meaningful when it comes to connections using non-privileged
+ports.
+On the other hand, if we receive a request that has a local endpoint indicating
+a UDP privileged port, we can presume that the client was privileged to be
+able to acquire that port.
+.Pp
+Once an entry is matched
+.Nm
+can perform various actions.
 If the action is
 .Dq add
 and the number of tries limit is reached, then a
@@ -87,10 +123,10 @@ that is not required as all information to remove the rule is
 kept.
 .Pp
 If the action is
-.Dq remove
+.Dq rem
 Then the same control script is invoked as:
 .Bd -literal -offset indent
-control remove <rulename> <proto> <address> <mask> <port> <id>
+control rem <rulename> <proto> <address> <mask> <port> <id>
 .Ed
 .Pp
 where
@@ -202,19 +238,19 @@ instead of
 .Nm
 deals with the following signals:
 .Bl -tag -width "USR2"
-.It HUP
+.It Dv HUP
 Receipt of this signal causes
 .Nm
 to re-read the configuration file.
-.It INT, TERM & QUIT
+.It Dv INT , Dv TERM & Dv QUIT
 These signals tell
 .Nm
 to exit in an orderly fashion.
-.It USR1
+.It Dv USR1
 This signal tells
 .Nm
 to increase the internal debugging level by 1.
-.It USR2
+.It Dv USR2
 This signal tells
 .Nm
 to decrease the internal debugging level by 1.
diff --git a/contrib/blacklist/bin/blacklistd.conf.5 b/contrib/blacklist/bin/blacklistd.conf.5
index c0e1a2b87380..3a7ecd9be171 100644
--- a/contrib/blacklist/bin/blacklistd.conf.5
+++ b/contrib/blacklist/bin/blacklistd.conf.5
@@ -1,4 +1,4 @@
-.\" $NetBSD: blacklistd.conf.5,v 1.7 2017/06/07 13:50:57 wiz Exp $
+.\" $NetBSD: blacklistd.conf.5,v 1.9 2019/11/06 20:33:30 para Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 5, 2017
+.Dd May 18, 2020
 .Dt BLACKLISTD.CONF 5
 .Os
 .Sh NAME
@@ -192,7 +192,7 @@ rule that matched.
 .Pp
 The
 .Va remote
-rules can be used for whitelisting specific addresses, changing the mask
+rules can be used for allowing specific addresses, changing the mask
 size, the rule that the packet filter uses, the number of failed attempts,
 or the block duration.
 .Sh FILES
diff --git a/contrib/blacklist/lib/libblacklist.3 b/contrib/blacklist/lib/libblacklist.3
index aaf809469e6a..146915c8dc31 100644
--- a/contrib/blacklist/lib/libblacklist.3
+++ b/contrib/blacklist/lib/libblacklist.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: libblacklist.3,v 1.8 2017/10/22 10:31:57 abhinav Exp $
+.\" $NetBSD: libblacklist.3,v 1.10 2020/03/30 15:47:15 christos Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 5, 2017
+.Dd March 30, 2020
 .Dt LIBBLACKLIST 3
 .Os
 .Sh NAME
@@ -96,11 +96,13 @@ There was an unsuccessful authentication attempt.
 A user successfully authenticated.
 .It Va BLACKLIST_ABUSIVE_BEHAVIOR
 The sending daemon has detected abusive behavior
-from the remote system.  The remote address should
+from the remote system.
+The remote address should
 be blocked as soon as possible.
 .It Va BLACKLIST_BAD_USER
 The sending daemon has determined the username
-presented for authentication is invalid.  The
+presented for authentication is invalid.
+The
 .Xr blacklistd 8
 daemon compares the username to a configured list of forbidden
 usernames and
@@ -122,6 +124,14 @@ functions can be used with unconnected sockets, where
 .Xr getpeername 2
 will not work, the server will pass the peer name in the message.
 .Pp
+In all cases the file descriptor passed in the
+.Fa fd
+argument must be pointing to a valid socket so that
+.Xr blacklistd 8
+can establish ownership of the local endpoint
+using
+.Xr getsockname 2 .
+.Pp
 By default,
 .Xr syslogd 8
 is used for message logging.