libblocklist(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
LIBBLOCKLIST(3)         NetBSD 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 suc-
     cessful 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 per-
     formed.

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

     The blocklist() function sends a message to blocklistd(8), with an inte-
     ger action argument specifying the type of notification, a file descrip-
     tor 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_AUTH_FAIL         There was an unsuccessful authentication
                                 attempt.

     BLOCKLIST_AUTH_OK           A user successfully authenticated.

     BLOCKLIST_ABUSIVE_BEHAVIOR  The sending daemon has detected abusive
                                 behavior from the remote system.  The remote
                                 address should be blocked as soon as possi-
                                 ble.

     BLOCKLIST_BAD_USER          The sending daemon has determined the user-
                                 name presented for authentication is invalid.
                                 The blocklistd(8) daemon compares the user-
                                 name to a configured list of forbidden user-
                                 names and blocks the address immediately if a
                                 forbidden username matches.  (The
                                 BLOCKLIST_BAD_USER support is not currently
                                 available.)

     The blocklist_r() function is more efficient because it keeps the block-
     list state around.

     The blocklist_sa() and blocklist_sa_r() functions can be used with uncon-
     nected 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 point-
     ing 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 10.99                    August 2, 2024                    NetBSD 10.99