.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Ident 3pm"
.TH Ident 3pm 2024-03-07 "perl v5.38.2" "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
Net::Ident \- lookup the username on the remote end of a TCP/IP connection
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::Ident;
\& 
\& $username = Net::Ident::lookup(SOCKET, $timeout);
\&
\& $username = Net::Ident::lookupFromInAddr($localsockaddr,
\&                                           $remotesockaddr, $timeout);
\& 
\& $obj = Net::Ident\->new(SOCKET, $timeout);
\& $obj = Net::Ident\->newFromInAddr($localsockaddr, $remotesockaddr,
\&                                        $timeout);
\& $status = $obj\->query;
\& $status = $obj\->ready;
\& $username = $obj\->username;
\& ($username, $opsys, $error) = $obj\->username;
\& $fh = $obj\->getfh;
\& $txt = $obj\->geterror;
\& 
\& use Net::Ident \*(Aqident_lookup\*(Aq;
\& 
\& $username = ident_lookup(SOCKET, $timeout);
\&
\& use Net::Ident \*(AqlookupFromInAddr\*(Aq;
\&
\& $username = lookupFromInAddr($localsockaddr, $remotesockaddr, $timeout);
\&
\& use Net::Ident \*(Aq:fh\*(Aq;
\&
\& $username = SOCKET\->ident_lookup($timeout);
\&
\& use Net::Ident \*(Aq:apache\*(Aq;
\&
\& # my Apache $r;
\& $c = $r\->connection;
\& $username = $c\->ident_lookup($timeout);
.Ve
.SH OVERVIEW
.IX Header "OVERVIEW"
\&\fBNet::Ident\fR is a module that looks up the username on the remote
side of a TCP/IP connection through the ident (auth/tap) protocol
described in RFC1413 (which supersedes RFC931). Note that this
requires the remote site to run a daemon (often called \fBidentd\fR) to
provide the requested information, so it is not always available for
all TCP/IP connections.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
You can either use the simple interface, which does one ident
lookup at a time, or use the asynchronous interface to perform
(possibly) many simultaneous lookups, or simply continue serving other
things while the lookup is proceeding.
.SS "Simple Interface"
.IX Subsection "Simple Interface"
The simple interface comes in four varieties. An object oriented method
call of a FileHandle object, an object oriented method of an Apache::Connection
object, and as one of two different simple subroutine calls. Other than the
calling method, these routines behave exactly the same.
.ie n .IP """Net::Ident::lookup (SOCKET"" ["", $timeout""]"")""" 4
.el .IP "\f(CWNet::Ident::lookup (SOCKET\fR [\f(CW, $timeout\fR]\f(CW)\fR" 4
.IX Item "Net::Ident::lookup (SOCKET [, $timeout])"
\&\fBNet::Ident::lookup\fR is an exportable function. However, due to the
generic name of the \fBlookup\fR function, it is recommended that you
instead import the alias function \fBNet::Ident::ident_lookup\fR. Both
functions are exported through \f(CW@EXPORT_OK\fR, so you'll have to
explicitly ask for it if you want the function \fBident_lookup\fR to be
callable from your program.
.Sp
You can pass the socket using either a string, which doesn't have to be
qualified with a package name, or using the more modern FileHandle calling
styles: as a glob or as a reference to a glob. The Socket has to be a
connected TCP/IP socket, ie. something which is either \fBconnect()\fRed
or \fBaccept()\fRed. The optional timeout parameter specifies a timeout
in seconds. If you do not specify a timeout, or use a value of undef,
there will be no timeout (apart from any default system timeouts like
TCP connection timeouts).
.ie n .IP """Net::Ident::lookupFromInAddr ($localaddr, $remoteaddr"" ["", $timeout""]"")""" 4
.el .IP "\f(CWNet::Ident::lookupFromInAddr ($localaddr, $remoteaddr\fR [\f(CW, $timeout\fR]\f(CW)\fR" 4
.IX Item "Net::Ident::lookupFromInAddr ($localaddr, $remoteaddr [, $timeout])"
\&\fBNet::Ident::lookupFromInAddr\fR is an exportable function (via \f(CW@EXPORT_OK\fR).
The arguments are the local and remote address of a connection, in packed
``sockaddr'' format (the kind of thing that \f(CW\*(C`getsockname\*(C'\fR returns). The
optional timeout value specifies a timeout in seconds, see also the
description of the timeout value in the \f(CW\*(C`Net::Ident::lookup\*(C'\fR section above.
.Sp
The given localaddr \fBmust\fR have the IP address of a local interface of
the machine you're calling this on, otherwise an error will occur.
.Sp
You can use this function whenever you have a local and remote socket address,
but no direct access to the socket itself. For example, because you are
parsing the output of "netstat" and extracting socket address, or because you
are writing a mod_perl script under apache (in that case, also see the
Apache::Connection method below).
.ie n .IP """ident_lookup SOCKET"" [$timeout]" 4
.el .IP "\f(CWident_lookup SOCKET\fR [\f(CW$timeout\fR]" 4
.IX Item "ident_lookup SOCKET [$timeout]"
When you import the ``magic'' tag ':fh' using \f(CW\*(C`use Net::Ident \*(Aq:fh\*(Aq;\*(C'\fR,
the \fBNet::Ident\fR module extends the \fBFileHandle\fR class with one
extra method call, \fBident_lookup\fR. It assumes that the object (a
FileHandle) it is operating on, is a connected TCP/IP socket,
ie. something which is either \fBconnect()\fRed or \fBaccept()\fRed. The optional
parameter specifies the timeout in seconds, just like the timeout parameter
of the function calls above.
.Sp
\ 
.Sp
Adding the \fBident_lookup\fR method to the \fBFileHandle\fR class used to be
automatic in previous version of \fBNet::Ident\fR. During the installation
of this \fBNet::Ident\fR package, the system administrator choose to install
it in a compatible way, meaning that on this machine, the \fBident_lookup\fR
method is automatically added if you use just \f(CW\*(C`use Net::Ident;\*(C'\fR
.Sp
\ 
.Sp
Some people do not like the way that ``proper'' object design is broken
by letting one module add methods to another class. This is why, starting
from version 1.20, you have to explicitly ask for this behaviour to occur.
Personally, I this it's a compromise: if you want an object-oriented
interface, then either you make a derived class, like a
FileHandleThatCanPerformIdentLookups, and make sure all appropriate
internal functions get wrappers that do the necessary re-blessing. Or,
you simply extend the FileHandle class. And since Perl doesn't object to this
(pun intended :), I find this an acceptable solution. But you might think
otherwise.
.ie n .IP """ident_lookup Apache::Connection"" [$timeout]" 4
.el .IP "\f(CWident_lookup Apache::Connection\fR [\f(CW$timeout\fR]" 4
.IX Item "ident_lookup Apache::Connection [$timeout]"
When you import the ``magic'' tag ':apache' using \f(CW\*(C`use Net::Ident \*(Aq:apache\*(Aq;\*(C'\fR,
the \fBNet::Ident\fR module extends the \fBApache::Connection\fR class with one
extra method call, \fBident_lookup\fR. This method takes one optional parameter:
a timeout value in seconds.
.Sp
This is a similar convenience function as the FileHandle::ident_lookup method,
to be used with mod_perl scripts under Apache.
.PP
What these functions return depends on the context:
.IP "scalar context" 4
.IX Item "scalar context"
In scalar context, these functions return the remote username on
success, or undef on error. "Error" is rather broad, it might mean:
some network error occurred, function arguments are invalid, the remote site
is not responding (in time) or is not running an ident daemon, or the
remote site ident daemon says there's no user connected with that
particular connection.
.Sp
More precisely, the functions return whatever the remote daemon
specified as the ID that belongs to that particular connection. This
is often the username, but it doesn't necessarily have to be. Some
sites, out of privacy and/or security measures, return an opaque ID
that is unique for each user, but is not identical to the username.
See \fIRFC1413\fR for more information.
.IP "array context" 4
.IX Item "array context"
In array context, these functions return: \f(CW\*(C`($username, $opsys,
$error)\*(C'\fR.  The \fR\f(CI$username\fR\fI\fR is the remote username or ID, as returned
in the scalar context, or undef on error.
.Sp
The \fR\f(CI$opsys\fR\fI\fR is the remote operating system as reported by the remote
ident daemon, or undef on a network error, or \fB"ERROR"\fR when the
remote ident daemon reported an error. This could also contain the
character set of the returned username. See RFC1413.
.Sp
The \fR\f(CI$error\fR\fI\fR is the error message, either the error reported by the
remote ident daemon (in which case \fI\fR\f(CI$opsys\fR\fI\fR is \fB"ERROR"\fR), or the
internal message from the \fBNet::Ident\fR module, which includes the
system errno \f(CW$!\fR whenever possible. A likely candidate is
\&\fB"Connection refused"\fR when the remote site isn't running an ident
daemon, or \fB"Connection timed out"\fR when the remote site isn't
answering our connection request.
.Sp
When \fR\f(CI$username\fR\fI\fR has a value, \fI\fR\f(CI$error\fR\fI\fR is always undef, and vice versa.
.SS EXAMPLE
.IX Subsection "EXAMPLE"
The following code is a complete example, implementing a server that
waits for a connection on a port, tells you who you are and what time
it is, and closes the connection again. The majority of the code will
look very familiar if you just read perlipc.
.PP
Excersize this server by telnetting to it, preferably from a machine
that has a suitable ident daemon installed.
.PP
.Vb 1
\&    #!/usr/bin/perl \-w
\&
\&    use Net::Ident;
\&    # uncomment the below line if you want lots of debugging info
\&    # $Net::Ident::DEBUG = 2;
\&    use Socket;
\&    use strict;
\&    
\&    sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\en" }
\&    
\&    my $port = shift || 2345;
\&    my $proto = getprotobyname(\*(Aqtcp\*(Aq);
\&    socket(Server, PF_INET, SOCK_STREAM, $proto) or die "socket: $!";
\&    setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1)) or
\&      die "setsockopt: $!";
\&    bind(Server, sockaddr_in($port, INADDR_ANY)) or die "bind: $!";
\&    listen(Server,SOMAXCONN) or die "listen: $!";
\&    
\&    logmsg "server started on port $port";
\&    
\&    my $paddr;
\&    
\&    for ( ; $paddr = accept(Client,Server); close Client) {
\&        my($port,$iaddr) = sockaddr_in($paddr);
\&        my $name = gethostbyaddr($iaddr,AF_INET) || inet_ntoa($iaddr);
\&        logmsg "connection from $name [" . inet_ntoa($iaddr) .
\&          "] at port $port";
\&       
\&        my $username = Client\->ident_lookup(30) || "~unknown";
\&        logmsg "User at $name:$port is $username";
\&        
\&        print Client "Hello there, $username\e@$name, it\*(Aqs now ",
\&           scalar localtime, "\en";
\&    }
.Ve
.SS "Asynchronous Interface"
.IX Subsection "Asynchronous Interface"
The asynchronous interface is meant for those who know the ins and outs
of the \f(CWselect()\fR call (the 4\-argument version of \f(CWselect()\fR, but I
didn't need saying that, did I?). This interface is completely object
oriented. The following methods are available:
.ie n .IP """new Net::Ident SOCKET, $timeout""" 4
.el .IP "\f(CWnew Net::Ident SOCKET, $timeout\fR" 4
.IX Item "new Net::Ident SOCKET, $timeout"
This constructs a new Net::Ident object, and initiates the connection
to the remote ident daemon. The parameters are the same as described
above for the \fBNet::Ident::lookup\fR subroutine. This method returns
immediately, the supplied \fR\f(CI$timeout\fR\fI\fR is only stored in the object and
used in future methods.
.Sp
If you want to implement your own timeout, that's fine. Simply throw
away the object when you don't want it anymore.
.Sp
The constructor will always succeed. When it detects an error,
however, it returns an object that "has already failed" internally. In
this case, all methods will return \f(CW\*(C`undef\*(C'\fR except for the \f(CW\*(C`geterror\*(C'\fR
method, wich will return the error message.
.Sp
The timeout is \fInot\fR implemented using \f(CWalarm()\fR. In fact you can
use \f(CWalarm()\fR completely independent of this library, they do not
interfere.
.ie n .IP """newFromInAddr $localaddr, $remoteaddr, $timeout""" 4
.el .IP "\f(CWnewFromInAddr $localaddr, $remoteaddr, $timeout\fR" 4
.IX Item "newFromInAddr $localaddr, $remoteaddr, $timeout"
Alternative constructor, that takes two packed sockaddr structures. Otherwise
behaves identical to the \f(CW\*(C`new\*(C'\fR constructor above.
.ie n .IP """query $obj""" 4
.el .IP "\f(CWquery $obj\fR" 4
.IX Item "query $obj"
This object method queries the remote rfc931 daemon, and blocks until
the connection to the ident daemon is writable, if necessary (but you
are supposed to make sure it is, of course). Returns true on success
(or rather it returns the \fR\f(CI$obj\fR\fI\fR itself), or undef on error.
.ie n .IP """ready $obj"" [$blocking]" 4
.el .IP "\f(CWready $obj\fR [\f(CW$blocking\fR]" 4
.IX Item "ready $obj [$blocking]"
This object method returns whether the data received from the remote
daemon is complete (true or false). Returns undef on error. Reads any
data from the connection.  If \fR\f(CI$blocking\fR\fI\fR is true, it blocks and
waits until all data is received (it never returns false when blocking
is true, only true or undef). If \fI\fR\f(CI$blocking\fR\fI\fR is not true, it doesn't
block at all (unless... see below).
.Sp
If you didn't call \f(CW\*(C`query $obj\*(C'\fR yet, this method calls it for you,
which means it \fIcan\fR block, regardless of the value of \fR\f(CI$blocking\fR\fI\fR,
depending on whether the connection to the ident is writable.
.Sp
Obviously, you are supposed to call this routine whenever you see that
the connection to the ident daemon is readable, and act appropriately
when this returns true.
.Sp
Note that once \fBready\fR returns true, there are no longer checks on
timeout (because the networking part of the lookup is over anyway).
This means that even \f(CW\*(C`ready $obj\*(C'\fR can return true way after the
timeout has expired, provided it returned true at least once before
the timeout expired. This is to be construed as a feature.
.ie n .IP """username $obj""" 4
.el .IP "\f(CWusername $obj\fR" 4
.IX Item "username $obj"
This object method parses the return from the remote ident daemon, and
blocks until the query is complete, if necessary (it effectively calls
\&\f(CW\*(C`ready $obj 1\*(C'\fR for you if you didn't do it yourself). Returns the
parsed username on success, or undef on error. In an array context,
the return values are the same as described for the
\&\fBNet::Ident::lookup\fR subroutine.
.ie n .IP """getfh $obj""" 4
.el .IP "\f(CWgetfh $obj\fR" 4
.IX Item "getfh $obj"
This object method returns the internal FileHandle used for the
connection to the remote ident daemon. Invaluable if you want it to
dance in your \fBselect()\fR ring. Returns undef when an error has occurred.
.ie n .IP """geterror $obj""" 4
.el .IP "\f(CWgeterror $obj\fR" 4
.IX Item "geterror $obj"
This object method returns the error message in case there was an
error. undef when there was no error.
.PP
An asynchronous example implementing the above server in a multi-threaded
way via select, is left as an excersize for the interested reader.
.SH DISCLAIMER
.IX Header "DISCLAIMER"
I make NO WARRANTY or representation, either express or implied,
with respect to this software, its quality, accuracy, merchantability, or
fitness for a particular purpose.  This software is provided "AS IS",
and you, its user, assume the entire risk as to its quality and accuracy.
.SH AUTHOR
.IX Header "AUTHOR"
Jan-Pieter Cornet, <johnpc@xs4all.nl>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 1995, 1997, 1999 Jan-Pieter Cornet. All rights reserved. You
can distribute and use this program under the same terms as Perl itself.
.SH "REVISION HISTORY"
.IX Header "REVISION HISTORY"
.IP V1.20 4
.IX Item "V1.20"
August 2, 1999. Finally implemented the long-asked-for lookupFromInAddr
method. Other changes:
.RS 4
.IP \(bu 1
No longer imports ident_lookup into package FileHandle by default, unless you
explicitly ask for it (or unless you installed it that way during compile time
for compatibility reasons).
.IP \(bu 1
Allow adding an ident_lookup method to the Apache::Connection class, as a
convenience for mod_perl script writers.
.IP \(bu 1
Rewritten tests, included test for the Apache::Connection method by actually
launching apache and performing ident lookups from within mod_perl.
.IP \(bu 1
Moved selection of FileHandle/IO::Handle class out of the Makefile.PL. 
PAUSE/CPAN didn't really like modules that weren't present in the
distribution, and it didn't allow you to upgrade your perl version
underneath.
.RE
.RS 4
.RE
.IP V1.11 4
.IX Item "V1.11"
Jan 15th, 1997. Several bugfixes, and some slight interface changes:
.RS 4
.IP \(bu 1
constructor now called \f(CW\*(C`new\*(C'\fR instead of \f(CW\*(C`initconnect\*(C'\fR, constructor
now always succeeds, if something has gone wrong in the constructor,
all methods return undef (like \f(CW\*(C`getfh\*(C'\fR), except for \f(CW\*(C`geterror\*(C'\fR, which
returns the error message.
.IP \(bu 1
The recommended exported function is now \f(CW\*(C`ident_lookup\*(C'\fR instead of
\&\f(CW\*(C`lookup\*(C'\fR
.IP \(bu 1
Fixed a bug: now chooses O_NDELAY or O_NONBLOCK from \f(CW%Config\fR, instead
of hardcoding O_NDELAY (argh)
.IP \(bu 1
Adding a method to FileHandle would break in perl5.004, it should get
added in IO::Handle. Added intelligence in Makefile.PL to detect that
and choose the appropriate package.
.IP \(bu 1
Miscellaneous pod fixes.
.IP \(bu 1
Test script now actually tests multiple different things.
.RE
.RS 4
.RE
.IP V1.10 4
.IX Item "V1.10"
Jan 11th, 1997. Complete rewrite for perl5. Requires perl5.002 or up.
.IP V1.02 4
.IX Item "V1.02"
Jan 20th, 1995. Quite a big bugfix: "connection refused" to the ident
port would kill the perl process with a SIGPIPE if the connect didn't
immediately signal it (ie. almost always on remote machines). Also
recognises the perl5 package separator :: now on fully qualified
descriptors. This is still perl4\-compatible, a perl5\- only version
would require a rewrite to make it neater.  Fixed the constants
normally found in .ph files (but you shouldn't use those anyway).
.Sp
[this release wasn't called \fBNet::Ident\fR, of course, it was called
\&\fBrfc931.pl\fR]
.IP V1.01 4
.IX Item "V1.01"
Around November 1994. Removed a spurious \fBperl5 \-w\fR complaint. First
public release.  Has been tested against \fBperl 5.000\fR and \fBperl 4.036\fR.
.IP V1.00 4
.IX Item "V1.00"
Dunno, somewhere 1994. First neat collection of dusty routines put in
a package.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Socket
RFC1413, RFC931