NAME
    Authen::Libwrap - access 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
    The Authen::Libwrap module allows you to access the hosts_ctl() function
    from the popular TCP Wrappers security package. This allows validation
    of network access from perl programs against the system-wide hosts.allow
    file.

    If any of the parameters to hosts_ctl() are not known (i.e. username due
    to lack of an identd server), the constant STRING_UNKNOWN may be passed
    to the function.

FUNCTIONS
    Authen::Libwrap has only one function, though it can be invoked in
    several ways. In each case, an true return code indicates that the
    connection is allowed per the rules in hosts.allow and an undef value
    indicates the opposite.

  hosts_ctl($daemon, $hostname, $ip_addr, [ $user ] )
    Takes three mandatory and one optional argument. $daemon is the service
    for which access is being requested (like 'ftpd' or 'sendmail').
    $hostname is the name of the host requesting access. $ip_addr is the IP
    address of the host in dotted-quad notation. $user is the name of the
    user requesting access. If unknown, $user can be omitted; STRING_UNKNOWN
    will be passed in it's place.

  hosts_ctl($daemon, $socket, [ $user ] )
    If you have a socket (be it a glob, 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. If the hostname or
    IP address cannot be determined from the socket, STRING_UNKNOWN will be
    passed in their place.

DEBUGGING
    If you want to see the arguments that will be passed to the C function
    hosts_ctl(), set $Authen::Libwrap::DEBUG to a true value.

EXPORTS
    Nothing unless you ask for it.

    hosts_ctl optionally

    STRING_UNKNOWN optionally

EXPORT_TAGS
    * functions
         hosts_ctl

    * constants
         STRING_UNKNOWN

    * all
        everything the module has to offer.

CONSTANTS
     STRING_UNKNOWN

BUGS
    * 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. 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 nothing
        to return to.

        Some operating systems ship with a default catch-all rule in
        hosts.allow that uses the twist option. You may have to modify this
        configuration to use Authen::Libwrap effectively.

    * 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.

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 om 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.

    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>