LIBBLOCKLIST(3)

✨ NAME ✨

okay so bestie, welcome to LIBBLOCKLIST(3) from the Library Functions Manual 💖 — this page is the Blocklistd notification library, and it's basically the group chat between your daemon and blocklistd(8).

the main characters are:

• blocklist_open
• blocklist_open2
• blocklist_close
• blocklist_r
• blocklist
• blocklist_sa
• blocklist_sa_r

and together they're the Blocklistd notification library — no cap, that's the whole NAME vibe 🫶

🌈 LIBRARY 🌈

the library is “libblocklist” — yes bestie, that's the one 💅

🎀 SYNOPSIS 🎀

here's the exact shape of it, bestie — these signatures are literally the blueprint:

#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 💅

okay so the whole point: these functions can be used by daemons to notify blocklistd(8) about successful and failed remote connections, so blocklistd can block or release port access to prevent Denial of Service attacks. it's giving protective bestie energy 🛡️✨

blocklist_open() creates the necessary state to communicate with blocklistd(8) and returns a pointer to it, or NULL on failure. iconic little setup moment.

blocklist_open2() is similar to blocklist_open() but lets you specify a logger. if the logger is NULL, then no logging is performed — noted, bestie.

blocklist_close() frees all memory and resources used. clean up your room, periodt 🧹💖

blocklist() 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_AUTH_FAIL — there was an unsuccessful authentication attempt. oop, someone fumbled the login 😭
• BLOCKLIST_AUTH_OK — a user successfully authenticated. slay, they got in ✨
• BLOCKLIST_ABUSIVE_BEHAVIOR — the sending daemon has detected abusive behavior from the remote system. the remote address should be blocked as soon as possible. not cute, block them immediately 💀
• BLOCKLIST_BAD_USER — the sending daemon has determined the username presented for authentication is invalid. the blocklistd(8) daemon compares the username to a configured list of forbidden usernames and blocks the address immediately if a forbidden username matches. 🚫

⚠️ important caveat, bestie: “(The BLOCKLIST_BAD_USER support is not currently available.)” — don't count on that one yet, fr fr.

blocklist_r() is more efficient because it keeps the blocklist state around. lowkey the main-character version for repeated calls 👑

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

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). this is non-negotiable, bestie — valid socket or it's not gonna work.

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. custom logging? highkey flexible 🎀

💖 RETURN VALUES 💖

blocklist_open() returns a cookie on success and NULL on failure setting errno to an appropriate value. a little cookie, cute 🍪

the functions blocklist(), blocklist_sa(), and blocklist_sa_r() return 0 on success and -1 on failure setting errno to an appropriate value. zero is slay, minus one is the sad trombone 😭

🦋 SEE ALSO 🦋

• blocklistd.conf(5)
• blocklistd(8)

👑 AUTHORS 👑

Christos Zoulas — big ups, icon 💜

---

mwah 💋 this page comes from Debian, dated February 5, 2025, and it's LIBBLOCKLIST(3) — go be the main character of your daemon's networking, bestie 🫶✨