.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Authen::Libwrap 3"
.TH Authen::Libwrap 3 "2016-08-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::Libwrap \- access to Wietse Venema's TCP Wrappers library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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", "\en";
\&
\&  # we don\*(Aqt know the remote username
\&  $rc = hosts_ctl(
\&    "programname",
\&        "hostname.domain.com",
\&        "10.1.1.1"),
\&  );
\&  print "Access is ", $rc ? "granted" : "refused", "\en";
\&
\&  # use a socket instead
\&  my $client = $listener\->accept();
\&  $rc = hosts_ctl( "programname" $socket );
\&  print "Access is ", $rc ? "granted" : "refused", "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Authen::Libwrap module allows you to access the \fIhosts_ctl()\fR function from
the popular \s-1TCP\s0 Wrappers security package.  This allows validation of
network access from perl programs against the system-wide \fIhosts.allow\fR
file.
.PP
If any of the parameters to \fIhosts_ctl()\fR are not known (i.e. username due to
lack of an identd server), the constant \s-1STRING_UNKNOWN\s0 may be passed to
the function.
.SH "FUNCTIONS"
.IX Header "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 \fIhosts.allow\fR and an
undef value indicates the opposite.
.ie n .SS "hosts_ctl($daemon, $hostname, $ip_addr, [ $user ] )"
.el .SS "hosts_ctl($daemon, \f(CW$hostname\fP, \f(CW$ip_addr\fP, [ \f(CW$user\fP ] )"
.IX Subsection "hosts_ctl($daemon, $hostname, $ip_addr, [ $user ] )"
Takes three mandatory and one optional argument. \f(CW$daemon\fR is the service
for which access is being requested (like 'ftpd' or 'sendmail').
\&\f(CW$hostname\fR is the name of the host requesting access. \f(CW$ip_addr\fR is the
\&\s-1IP\s0 address of the host in dotted-quad notation. \f(CW$user\fR is the name of the
user requesting access. If unknown, \f(CW$user\fR can be omitted; \s-1STRING_UNKNOWN\s0
will be passed in it's place.
.ie n .SS "hosts_ctl($daemon, $socket, [ $user ] )"
.el .SS "hosts_ctl($daemon, \f(CW$socket\fP, [ \f(CW$user\fP ] )"
.IX Subsection "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 \s-1IP\s0 address will
be determined using this socket. If the hostname or \s-1IP\s0 address cannot be
determined from the socket, \s-1STRING_UNKNOWN\s0 will be passed in their place.
.SH "DEBUGGING"
.IX Header "DEBUGGING"
If you want to see the arguments that will be passed to the C function
\&\fIhosts_ctl()\fR, set \f(CW$Authen::Libwrap::DEBUG\fR to a true value.
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing unless you ask for it.
.PP
hosts_ctl optionally
.PP
\&\s-1STRING_UNKNOWN\s0 optionally
.SH "EXPORT_TAGS"
.IX Header "EXPORT_TAGS"
.IP "\(bu" 4
\&\fBfunctions\fR
.Sp
.Vb 1
\& hosts_ctl
.Ve
.IP "\(bu" 4
\&\fBconstants\fR
.Sp
.Vb 1
\& STRING_UNKNOWN
.Ve
.IP "\(bu" 4
\&\fBall\fR
.Sp
everything the module has to offer.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
.Vb 1
\& STRING_UNKNOWN
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 4
\&\fBtwist\fR in \fIhosts.allow\fR
.Sp
Calls to \fIhosts_ctl()\fR which match a line in \fIhosts.allow\fR that uses the
\&\*(L"twist\*(R" option will terminate the running perl program.  This is not a bug
in Authen::Libwrap per se \*(-- libwrap uses \fIexec\fR\|(3) to replace the running
process with the specified program, so there's nothing to return to.
.Sp
Some operating systems ship with a default catch-all rule in \fIhosts.allow\fR
that uses the twist option.  You may have to modify this configuration to
use Authen::Libwrap effectively.
.IP "\(bu" 4
Test suite is not comprehensive
.Sp
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.
.SH "TODO"
.IX Header "TODO"
In early 2003 I was contacted by another Perl developer who had developed an
\&\s-1XS\s0 interface to libwrap that covered more of the \s-1API\s0 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 \s-1CPAN,\s0 so I suggested that he
upload it himself. I unfortunately lost the email thread to a disk crash.
.PP
As of December 2003 I don't see any other modules professing to support
libwrap om \s-1CPAN.\s0 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:
.IP "\(bu" 4
provide support for hosts_access and request_* functions
.IP "\(bu" 4
develop an \s-1OO\s0 interface
.SH "SEE ALSO"
.IX Header "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.
.PP
\&\fIhosts_access\fR\|(3), \fIhosts_access\fR\|(5), \fIhosts_options\fR\|(5)
.PP
Wietse's tools and papers page:
<ftp://ftp.porcupine.org/pub/security/index.html>.
.SH "AUTHOR"
.IX Header "AUTHOR"
James FitzGibbon, <jfitz@CPAN.org>