NAME
    Net::TCPwrappers - Perl interface to tcp_wrappers.

SYNOPSIS
      use Net::TCPwrappers qw(RQ_DAEMON RQ_FILE request_init fromhost hosts_access);
      ...
      my $progname = 'yadd';
      while (accept(CLIENT, SERVER)) {
        my $req = request_init(RQ_DAEMON, $progname, RQ_FILE, fileno(CLIENT));
        fromhost($req);
        if (!hosts_access($req)) {
          # unauthorized access.
          ...
        }
        else {
          # service connecting client.
          ...
        }
      }

ABSTRACT
    Net::TCPwrappers offers perl programmers a convenient interface to the
    libwrap.a library from tcp_wrappers, Wietse Venema's popular TCP/IP
    daemon wrapper package. Use it in your perl code to monitor and filter
    access to TCP-based network services on unix hosts.

DESCRIPTION
    Net::TCPwrappers mimics the libwrap.a library fairly closely - the names
    of the functions and constants are identical, and calling arguments have
    been altered only slightly to be more perl-like.

  FUNCTIONS
    This module defines all the public functions available in the libwrap.a
    library: "request_init", "request_set", "hosts_access", and "hosts_ctl".
    None are exported by default; you must either add the package name when
    calling them (eg, "Net::TCPwrappers::request_init(...)") or import them
    explicitly (eg, "use Net::TCPwrappers qw(request_init ...);").

    request_init($key1, $value1, $key2, $value2, ...)
        Creates a new request structure and initializes it using the
        supplied key / value pairs. The keys are used to specify the
        interpretation of the value argument (eg, daemon name, file
        descriptor, host name, etc) and should be one of the constants
        described below. As many key / value pairs (for the same request, of
        course) can be specified as desired.

        Returns an integer representing a pointer to the newly created
        request structure. In the unlikely event of failure, the function
        returns undef. This may arise because memory can not be allocated
        for the request structure or because the key / value pairs are not
        of the correct types. [If the later, make sure you're using the
        proper constants as described below.]

        Note: the pointer to the request structure is blessed into the class
        Request_infoPtr and will be automatically destroyed when the program
        exits.

    request_set($request, $key1, $value1, $key2, $value2, ...)
        Copies an existing request structure (represented by the pointer
        $request) into a new one and updates it using the supplied key /
        value pairs, which are described above.

        Returns an integer representing a pointer to the updated request
        structure. In the unlikely event of failure, the function returns
        undef. This may arise because memory can not be allocated for the
        request structure or because the key / value pairs are not of the
        correct types. [If the later, make sure you're using the proper
        constants as described below.]

        Note: the pointer to the request structure is blessed into the class
        Request_infoPtr and will be automatically destroyed when the program
        exits.

    fromhost($request))
        Updates an existing request structure (pointed to by $request) with
        the port and address information obtained from the client and server
        endpoints.

        Note: this should be used after "request_init" or "request_set" if
        either is called with "RQ_FILE".

    hosts_access($request)
        Determines whether to allow access based on information in the
        request structure pointed to by $request along with the host access
        tables (see hosts_access).

        Returns 0 if access should be denied.

    hosts_ctl($daemon, $client_name, $client_addr [, $client_user])
        Determines whether to allow access based on the supplied daemon
        name, host name, host IP address, and optionally username of the
        client host making the request.

        Returns 0 if access should be denied.

        Note: this is implemented in libwrap.a as a wrapper around the
        "request_init" and "hosts_access" functions.

  CONSTANTS
    The keys used in the functions "request_init" and "request_set" and
    their meanings are:

    RQ_CLIENT_ADDR
        A string representing the client's IP address.

    RQ_CLIENT_NAME
        A string representing the client's hostname.

    RQ_CLIENT_SIN
        A pointer to the client's "sockaddr_in" structure, representing its
        host address and port.

    RQ_DAEMON
        A string representing the daemon's name as it appears in the access
        control tables.

        Note: a key / value pair with "RQ_DAEMON" must be supplied via
        either "request_init" or "request_set" if calling "hosts_access".

    RQ_FILE
        An integer representing the file descriptor associated with the
        request.

        Note: "fromhost" should be called after "request_init" or
        "request_set" if using this key.

    RQ_SERVER_ADDR
        A string representing the server's IP address.

    RQ_SERVER_NAME
        A string representing the server's hostname.

    RQ_SERVER_SIN
        A pointer to the server's "sockaddr_in" structure, representing its
        host address and port.

    RQ_USER
        A string representing the name of the user making the request from
        the client host.

    None of these are exported by default.

RATIONALE
    At first blush, this module might seem like overkill. "Why not just
    write the necessary code myself and include that in my programs?" you're
    probably thinking. Sure, any competent programmer can easily do that.
    Moreover, perl, with its regular expressions, affords extremely flexible
    matching of host names / addresses.

    Yet by rolling your own you would likely miss out on the following:

    *   A common facility for controlling host access. As distributed,
        tcp_wrappers works not only with daemons started via inetd but also
        with a wide variety of C programs that support it (eg, sendmail,
        OpenSSH, Nessus, etc). With Net::TCPwrappers, this support is now
        available to perl programs.

    *   Access controls are stored apart from programs and are re-read each
        time a check is done. This makes it trivial to adjust access
        controls, whether by hand as your needs evolve or automatically, as
        in the case of an intrusion detection system.

INSTALLATION
    Installation of Net::TCPWrappers requires a working installation of
    Wietse Venema's TCP/IP daemon wrapper package, tcp_wrappers, including
    the libwrap.a library. The latest version currently is 7.6, released in
    March 1997; earlier versions may also work as it appears the library
    interface has been rather stable.

    If you need a copy, visit <ftp://ftp.porcupine.org/pub/security/> for
    the source code or check with your favourite software respository for
    pre-compiled binaries (eg, RPMs for Linux, Packages for Sun, etc).

  BUILDING
    To build and test the module, type the following:

      perl Build.PL
      ./Build
      ./Build test

    Check the troubleshooting section if you encounter any problems or any
    of the tests fail.

    To install it, type:

      ./Build install

    Note: you probably need to do this as root to have it installed
    system-wide.

    At this point, you may wish to look at the sample programs in the
    examples directory to give you some ideas about how to use this module.

  TROUBLESHOOTING
    Build.PL will look for libwrap.{so,a} and tcpd.h in the following
    prefixes:

      /usr
      /usr/local
      /opt
      /opt/local
      /opt/libwrap
      /opt/tcpwrappers

    If your copy of TCP wrappers is not in one of these directories, pass
    the prefix (not including the 'include' and 'lib' directories) to
    Build.PL:

      perl Build.PL /opt/tcpd-7.6

    Build.PL normally prompts for confirmation when it has found a suitable
    library and include file. To suppress this behaviour and use the first
    match found, pass "--noprompt" to Build.PL on the command line:

      perl Build.PL --noprompt

    If one or more of the tests fail, run them in verbose mode (eg, "./Build
    test verbose=1"). This may give you an idea of which specific tests fail
    and why.

    Another option involves modifying the file TCPwrappers.xs. Edit the file
    and change the line near the top that reads:

      #if 0

    to:

      #if 1

    and recompile. This will turn on tracing of the XSUBs, which provide the
    glue between libwrap.a and Perl. Because this is a compiled-in change,
    it should be used only in extreme situations to send debug information
    to the author. To disable tracing, re-edit the file and recompile /
    reinstall.

TODO
    The current maintainer of this module wrote another Perl wrapper for
    libwrap called Authen::Libwrap. It didn't cover the API as
    comprehensively, and very little feedback was ever received on it. The
    original author of Net::TCPWrappers offered his source code for possible
    integration, but it turned out to be easier to integrate what little
    unique functional was in Authen::Libwrap into Net::TCPWrappers.

    The tests for Authen::Libwrap are part of the test suite for
    Net::TCPWrappers, but many of them are expected to fail at present. The
    goal is to get those tests to pass, at which point Authen::Libwrap can
    be deprecated in favour of this module.

    Other specific tasks:

    * develop an OO interface

BUGS
    None currently reported. If you find one, first read the troubleshooting
    section and then check for a newer version of Net::TCPwrappers on CPAN.
    If problems still persist, submit a bug report via the bug tracker at
    http://rt.cpan.org/.

    If you like this module, please rate it on it's CPAN page:

    http://cpanratings.perl.org/rate/?distribution=Net-TCPwrappers

    In your bug report, please include as much information as possible,
    including:

    *   Your platform and OS version (eg, "uname -a"). If using Linux, also
        include your glibc version (eg, "ls -al /lib/libc*").

    *   The ANSI C/C++ compiler name and version (eg, "gcc -v").

    *   Perl's configuration, obtained by running "perl -V".

    *   The version of tcp_wrappers installed on your system and how it got
        there (ie, from an RPM, compiled yourself, etc).

    *   Results from running "./Build test verbose=1" after building this
        module.

DIAGNOSTICS
    The routines in libwrap.a report problems via the syslog daemon.

SEE ALSO
    hosts_access, libwrap.a documentation.

AUTHOR
    George A. Theall, <theall@tifaware.com>

    Currently maintained by James FitzGibbon, <jfitz@CPAN.org>.

COPYRIGHT AND LICENSE
    Copyright (c) 2002, George A. Theall. All Rights Reserved.

    Copyright (c) 2004, James FitzGibbon. All Rights Reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

