Authen::Libwrap(3pm)

✨ NAME ✨

okay so bestie, meet Authen::Libwrap — your all-access pass to Wietse Venema's TCP Wrappers library 💅

---

🦋 SYNOPSIS 🦋

  use Authen::Libwrap qw( hosts_ctl STRING_UNKNOWN );

  # we know the remote username (using identd)
  $rc = hosts_ctl(
    "programname",
        "hostname.domain.com",
        "10.1.1.1",
        "username"
  );
  print "Access is ", $rc ? "granted" : "refused", "\n";

  # we don't know the remote username
  $rc = hosts_ctl(
    "programname",
        "hostname.domain.com",
        "10.1.1.1"),
  );
  print "Access is ", $rc ? "granted" : "refused", "\n";

  # use a socket instead
  my $client = $listener->accept();
  $rc = hosts_ctl( "programname" $socket );
  print "Access is ", $rc ? "granted" : "refused", "\n";

---

🌸 DESCRIPTION 🌸

So the tea is: Authen::Libwrap lets you reach into the hosts_ctl() function from the wildly popular TCP Wrappers security package. What does that get you? The ability to validate network access from your Perl programs against the system-wide hosts.allow file. It's giving "gatekeeping, but for sockets" 👑

And if any of the parameters to hosts_ctl() aren't known — like, say, the username, because there's no identd server doing its thing — you can just pass the constant STRING_UNKNOWN to the function instead. Crisis averted, fr fr 🫶

---

💖 FUNCTIONS 💖

Authen::Libwrap has literally only one function, but she can be invoked in several ways, because she contains multitudes ✨

In every case: a true return code means the connection is allowed per the rules in hosts.allow, and an undef value means the opposite. No in-between, no maybes. It's giving binary 💀

hosts_ctl($daemon, $hostname, $ip_addr, [ $user ] )

Takes three mandatory arguments and one optional one.

• $daemon — the service you're requesting access to (think 'ftpd' or 'sendmail').
• $hostname — the name of the host requesting access.
• $ip_addr — that host's IP address in dotted-quad notation.
• $user — the name of the user requesting access. If it's unknown, you can just omit $user, and STRING_UNKNOWN will get passed in its place. Slay, no keystrokes wasted 💅

hosts_ctl($daemon, $socket, [ $user ] )

Got a socket instead? Iconic. If you have a socket — be it a glob, a glob reference, or an IO::Socket::INET — you can pass that as the second argument. The hostname and IP address will be determined using this socket 🧚

And if the hostname or IP address can't be determined from the socket? You already know the drill: STRING_UNKNOWN gets passed in their place 💜

---

🔥 DEBUGGING 🔥

Wanna peek behind the curtain and see the exact arguments that are about to get handed to the C function hosts_ctl()? Set $Authen::Libwrap::DEBUG to a true value. That's it. That's the whole ritual. Main character behaviour 🔍✨

---

🎀 EXPORTS 🎀

Nothing unless you ask for it. Consent is key 💅

• hosts_ctl — optionally
• STRING_UNKNOWN — optionally

---

🌈 EXPORT_TAGS 🌈

• functions
  • hosts_ctl
• constants
  • STRING_UNKNOWN
• all — everything the module has to offer. the whole buffet, bestie 🍓

---

⭐ CONSTANTS ⭐

 STRING_UNKNOWN

---

💀 BUGS AND FEATURES 💀

Please report any bugs or feature requests (and a pull request for bonus points) through the issue tracker at https://github.com/drmuey/p5-Authen-Libwrap/issues.

Now for the spicy bits:

• twist in hosts.allow Calls to hosts_ctl() which match a line in hosts.allow that uses the "twist" option will terminate the running perl program. 😭 And no, this is not a bug in Authen::Libwrap per se — libwrap uses exec(3) to replace the running process with the specified program, so there's literally nothing to return to. Not "nothing returned", not "undef returned" — gone. Bye. 👋 Some operating systems ship with a default catch-all rule in hosts.allow that uses the twist option. You may have to modify that configuration to use Authen::Libwrap effectively. Consider this your vibe check.
• Test suite is not comprehensive The test suite isn't very comprehensive because the path to hosts.allow is set when libwrap is built, and I can't tell what the user's rules are. I can make sure the function calls don't die, but I can't really tell if any call to hosts_ctl should give back a true or false value. It's giving "I did my best" 🙈

---

🧚 TODO 🧚

In early 2003 I was contacted by another Perl developer who had developed an XS interface to libwrap that covered more of the API than mine did. Originally he offered it as a patch to my module, but at the time I wasn't in a position to actively maintain anything on CPAN, so I suggested that he upload it himself. I unfortunately lost the email thread to a disk crash. 💀

As of December 2003 I don't see any other modules professing to support libwrap on CPAN. If that person is still out there, please get in contact with me, otherwise I'll plan on implementing some of these TODOs in the new year:

• provide support for hosts_access and request_* functions
• develop an OO interface

---

👑 SEE ALSO 👑

Authen::Tcpdmatch — a Pure Perl module that can parse hosts.allow and hosts.deny if you don't need all the underlying features of libwrap. Lowkey the lighter-weight option if that's your vibe 🦋

hosts_access(3), hosts_access(5), hosts_options(5)

Wietse's tools and papers page: ftp://ftp.porcupine.org/pub/security/index.html

---

💜 AUTHOR 💜

James FitzGibbon, <jfitz@CPAN.org>

---

okay that's the whole page, bestie, you're fully caught up 🫶 this was Authen::Libwrap(3pm) from the User Contributed Perl Documentation, brought to you by perl v5.42.3 and dated 2026-08-19. go forth and gatekeep those connections ✨💖