Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

LIBBLOCKLIST(3)            Library Functions Manual            LIBBLOCKLIST(3)

NAME
     blocklist_open, blocklist_open2, blocklist_close, blocklist_r, blocklist,
     blocklist_sa, blocklist_sa_r - Blocklistd notification library

LIBRARY
     library "libblocklist"

SYNOPSIS
     #include <blocklist.h>

     struct blocklist *
     blocklist_open(void);

     struct blocklist *
     blocklist_open2(void (*logger)(int, struct syslog_data *, va_list));

     void
     blocklist_close(struct blocklist *cookie);

     int
     blocklist(int action, int fd, const char *msg);

     int
     blocklist_r(struct blocklist *cookie, int action, int fd,
         const char *msg);

     int
     blocklist_sa(int action, int fd, const struct sockaddr *sa,
         socklen_t salen, const char *msg);

     int
     blocklist_sa_r(struct blocklist *cookie, int action, int fd,
         const struct sockaddr *sa, socklen_t salen, const char *msg);

DESCRIPTION
     These functions can be used by daemons to notify blocklistd(8) about
     successful and failed remote connections so that blocklistd can block or
     release port access to prevent Denial of Service attacks.

     The function blocklist_open() creates the necessary state to communicate
     with blocklistd(8) and returns a pointer to it, or NULL on failure.

     The function blocklist_open2() is similar to blocklist_open() but allows
     a logger to be specified.  If the logger is NULL, then no logging is
     performed.

     The blocklist_close() function frees all memory and resources used.

     The blocklist() function sends a message to blocklistd(8), with an
     integer action argument specifying the type of notification, a file
     descriptor fd specifying the accepted file descriptor connected to the
     client, and an optional message in the msg argument.

     The action parameter can take these values:

     BLOCKLIST_BAD_USER              The sending daemon has determined the
                                     username presented for authentication is
                                     invalid.  This is considered as one
                                     failure count.

     BLOCKLIST_AUTH_FAIL             There was an unsuccessful authentication
                                     attempt.  This is considered as two
                                     failure counts together.

     BLOCKLIST_ABUSIVE_BEHAVIOR      The sending daemon has detected abusive
                                     behavior from the remote system.  This is
                                     considered as a total immediate failure.
                                     The remote address will be blocked as
                                     soon as possible.

     BLOCKLIST_AUTH_OK               A valid user successfully authenticated.
                                     Any entry for the remote address will be
                                     removed as soon as possible.

     The blocklist_r() function is more efficient because it keeps the
     blocklist state around.

     The blocklist_sa() and blocklist_sa_r() functions can be used with
     unconnected sockets, where getpeername(2) will not work, the server will
     pass the peer name in the message.

     In all cases the file descriptor passed in the fd argument must be
     pointing to a valid socket so that blocklistd(8) can establish ownership
     of the local endpoint using getsockname(2).

     By default, syslogd(8) is used for message logging.  The internal
     bl_create() function can be used to create the required internal state
     and specify a custom logging function.

RETURN VALUES
     The function blocklist_open() returns a cookie on success and NULL on
     failure setting errno to an appropriate value.

     The functions blocklist(), blocklist_sa(), and blocklist_sa_r() return 0
     on success and -1 on failure setting errno to an appropriate value.

SEE ALSO
     blocklistd.conf(5), blocklistd(8)

AUTHORS
     Christos Zoulas

NetBSD 11.99                   February 5, 2025                   NetBSD 11.99