AUTHBIND(1)

💖 AUTHBIND(1) 💖

okay bestie, so this is the authbind page from the Debian Linux manual, and honestly? it's giving ✨least privilege✨ and we're obsessed. sit down, grab a strawberry 🍓, and let's get into it.

---

🌸 NAME 🌸

authbind — bind sockets to privileged ports without root. no cap. 👑

---

✨ SYNOPSIS ✨

authbind [options] program [argument ...]

---

🦋 DESCRIPTION 🦋

so here's the vibe: authbind lets a program that doesn't run as root (or like, shouldn't run as root, bestie, please) bind to low-numbered ports in a controlled way. very demure. very mindful. 💅

the thing is, you have to launch the program through authbind. like, you can't just ask nicely. authbind sets up some environment variables for you, including an LD_PRELOAD, and that's what lets the program — and any subprocesses it may run — bind to low-numbered (<512) ports, if your system is configured to allow that. 🔥

---

💜 OPTIONS 💜

• --deep — normally authbind only affects the one program it directly invokes with its special version of bind(2). but if you pass --deep, then every program that program invokes, directly or indirectly, gets affected too — as long as they don't unset the environment variables authbind set up. it's giving generational trauma but make it file descriptors 🫶
• --depth levels — makes authbind affect programs that are levels deep in the calling graph. the default is --depth 1.

---

🔐 ACCESS CONTROL 🔐

okay so who gets to touch the low-numbered ports? that's decided by the permissions and contents of files in a config area: /etc/authbind. let's go step by step, it's a whole journey. 🧚

first up: /etc/authbind/byport/port gets tested. if this file is accessible for execution to the calling user — per access(2) — then binding to that port is authorised. but if the file can be seen to not exist (the existence check returns ENOENT), then we keep going and use further tests to find authorisation. otherwise? binding is not authorised, and the bind call returns with the errno value from the access(2) call, usually EACCES (Permission denied). 💀

secondly: if that test didn't settle it, we test /etc/authbind/byaddr/addr,port (any protocol) — or, failing that, /etc/authbind/byaddr/addr:port (IPv4 only) — in the same manner as above. here addr is as from inet_ntop, and port is the (local) TCP or UDP port number, expressed as an unsigned integer in the minimal non-zero number of digits.

thirdly, IPv6 only: because the textual representation from inet_ntop is complicated to predict, a variant of addr also gets tested — one that doesn't use the double colon abbreviation. so each 16-byte chunk is expressed in the minimal nonzero number of hex digits (i.e. with leading zeroes removed), and the chunks are separated by colons as is conventional. ✨

fourthly: if the question is still unresolved, the file /etc/authbind/byuid/uid is opened and read. if the file doesn't exist, then the binding is not authorised and bind returns EPERM (Operation not permitted, or Not owner). if it does exist, it gets searched for a line of the form:

addrmin[-addrmax],portmin[-portmax]
addr[/length],portmin[-portmax]
addr4/length:portmin,portmax

matching the request. the first form requires that the address lies in the relevant range (inclusive at both ends). the second and third forms require that the initial length bits of addr match those in the proposed bind call. the third form is only available for IPv4, since IPv6 addresses contain colons. addresses in the byuid file can be in any form acceptable to inet_pton. in all cases, the proposed port number must lie in the inclusive range specified. if such a line is found, the binding is authorised. otherwise it is not, and bind will fail with ENOENT (No such file or directory). 😭

if a read error occurs, or the directory /etc/authbind cannot be accessed, then not only will bind fail, but an error message will be printed to stderr. and fyi: unrecognised lines in /etc/authbind/byuid/uid files are silently ignored — same goes for lines whose addr has non-zero bits more than length from the top, or where some min is larger than max.

---

🌈 EXAMPLE 🌈

so, say uid 432 tries to bind to port 80 of address [2620:106:e002:f00f::21]. authbind would call access(2) on, in order:

/etc/authbind/byport/80
/etc/authbind/byaddr/2620:106:e002:f00f::21,80
/etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80

if none of these files exist, authbind will read:

/etc/authbind/byuid/432

and search for a line to permit the relevant access. examples of lines which would do so are:

2620:106:e002:f00f::21,80
::/0,80

ate. no crumbs. 💅

---

🎀 PORTS 512-1023 🎀

bestie, listen to me. authorising binding to ports from 512 to 1023 inclusive is not recommended. some protocols (including some versions of NFS) authorise clients by seeing that they're using a port number in this range. so by authorising a program to be a server for such a port, you are also authorising it to impersonate the whole host for those protocols. not the vibe. 🚫

to make sure this isn't done by accident, if the port number requested is in the range 512-1023, authbind will expect the permission files to have an additional ! at the start of their leafname. little exclamation mark, big responsibility. ⚠️

---

🧚 MECHANISM 🧚

the shared library loaded using LD_PRELOAD overrides the bind(2) system call. so when a program invoked via authbind calls bind to bind a socket to a low-numbered TCP/IP port, and if the program doesn't already have an effective uid of 0, the version of bind supplied by authbind forks and executes a setuid-root helper program. for non-TCP/IP sockets, high-numbered ports, or programs which are already root, authbind just passes the call to the original bind(2) system call, which is found using dlsym(3) with the handle RTLD_NEXT. iconic behaviour, honestly. ✨

---

😭 ERROR HANDLING 😭

usually the normal C error handling mechanisms apply. but specifically: if authbind cannot find the program it has been asked to execute, it will print a message to stderr and exit with code 255. 💀

the helper program usually reports back to the shared library with an exit status containing an errno value which encodes whether the bind was permitted and successful. this will be returned to the calling program in the usual way. 🫶

in the case of apparent configuration or other serious errors, the library and/or the helper program may cause messages to be printed to the program's stderr, as well as returning -1 from bind.

---

💀 BUGS 💀

ngl, there are a few. let's be honest about them:

• authbind currently only supports IPv4 and IPv6 sockets. programs which open other kinds of sockets will not benefit from authbind, but it won't get in their way. 🚶
• the use of LD_PRELOAD makes an authbind installation specific to a particular C library. this version is for GNU/Linux libc6 (glibc2).
• authbind may not operate correctly with multithreaded programs. it is inherently very difficult (if not impossible) to perform the kind of trickery that authbind does while preventing all undesirable interactions between authbind's activities and those of (say) a threading runtime system. 😵
• it is quite possible that authbind and other programs and facilities which use LD_PRELOAD may interfere with each other, causing unpredictable behaviour or even core dumps. authbind is known sometimes not to work correctly with fakeroot, for example (even supposing it could be determined what correctly means in this context). 💥
• authbind is ineffective with setuid programs, because they do not honour LD_PRELOAD references outside the system directories, for security reasons. (in fact, setuid programs should not honour LD_PRELOAD at all.) of course a setuid-root program doesn't need authbind, but it might be useful to apply it to programs which are setuid to another user or setgid. if the author or builder of such a program wishes it to use authbind, they could have it load the libauthbind library explicitly rather than via LD_PRELOAD. 🤔
• some programs may have trouble because authbind spawns a child process under their feet, causing (for example) a fork(2) to happen and SIGCHLD signal to be delivered. unfortunately the Unix API does not make it possible to deal with this problem in a sane way. 🙈
• the access control configuration scheme is somewhat strange. 💅

---

🌸 FILES AND ENVIRONMENT VARIABLES 🌸

• /usr/lib/authbind/libauthbind.so.1.0 — the shared library which authbind causes to be loaded using LD_PRELOAD, and which actually implements the diversion of bind(2) to an external program.
• LD_PRELOAD — the variable used by the dynamic linker when starting dynamically linked programs and deciding which shared libraries to load, and modified by the authbind program to allow it to override the usual meaning of bind(2).
• AUTHBIND_LIB — if set, forces authbind to use its value as the path to the shared library to put in LD_PRELOAD, instead of the compiled-in value. in any case, unless --deep was specified, authbind will set this variable to the name of the library actually added to LD_PRELOAD, so that the library can find and remove the right entry. 🎯
• AUTHBIND_LEVELS — this variable is set by authbind to the number of levels left from the --depth or --deep option, minus one. it is decremented during _init by the library on each program call, and the library will remove itself from the LD_PRELOAD when it reaches zero. the special value y means --deep was specified. 👑

---

🦋 SEE ALSO 🦋

bind(2), authbind-helper(8), dlsym(3), ld.so(8)

---

💖 AUTHOR 💖

authbind and this manpage were written by Ian Jackson. they are Copyright (C)1998,2012 by him and released under the GNU General Public Licence; there is NO WARRANTY. see /usr/doc/authbind/copyright and /usr/doc/copyright/GPL for details.

---

that's the whole page bestie, you're so welcome. this one came from the Debian Project and it's dated 30th August 1998 — a true elder icon, still serving. go forth and bind responsibly 💅✨🎀