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(5)).

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.

KNOWN BUGS AND CAVEATS

Currently, I am not aware of any bugs in this module.

DIAGNOSTICS

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

SEE ALSO

hosts_access(5), 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.