Ident(3pm)

📦
version 1.31 · 6 versions
, in ubuntu stonking

👑 NAME 👑

Net::Ident — the module that looks up the username on the remote end of a TCP/IP connection 💅

This is the Ident(3pm) page, filed under User Contributed Perl Documentation. Yep, Perl manual, section 3pm. Iykyk 🎀

✨ SYNOPSIS ✨

okay so here is literally every single way you're allowed to summon this thing, bestie 🫶

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 'ident_lookup';

$username = ident_lookup(SOCKET, $timeout);

use Net::Ident 'lookupFromInAddr';

$username = lookupFromInAddr($localsockaddr, $remotesockaddr, $timeout);

use Net::Ident ':fh';

$username = SOCKET->ident_lookup($timeout);

use Net::Ident ':apache';

# my Apache $r;
$c = $r->connection;
$username = $c->ident_lookup($timeout);

🌈 OVERVIEW 🌈

Net::Ident is a module that looks up the username on the remote side of a TCP/IP connection, using the ident protocol (also called auth/tap, iconic name honestly) described in RFC1413, which supersedes RFC931. ✨

But here's the tea, bestie: for this to work, the remote site has to be running a daemon — often called identd — to actually hand over the requested info. So no cap, it is not always available for all TCP/IP connections. 😭

💖 DESCRIPTION 💖

You've got two whole vibes to pick from:

  • the simple interface, which does one ident lookup at a time, or
  • the asynchronous interface, which lets you perform (possibly) many simultaneous lookups, or just keep serving other things while the lookup is proceeding. main character multitasking energy 👑

🔍 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 how you call them, these routines behave exactly the same. Periodt.

Net::Ident::lookup (SOCKET [, $timeout])

Net::Ident::lookup is an exportable function. But listen — because the name lookup is so generic, the recommendation is that you import the alias function Net::Ident::ident_lookup instead. Both of these functions go out through @EXPORT_OK, so you have to explicitly ask for it if you want ident_lookup to be callable from your program. 🙈

For the socket, you can pass either a string — which doesn't have to be qualified with a package name — or use 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, i.e. something that's either connect()ed or accept()ed.

The optional $timeout parameter specifies a timeout in seconds. If you don't specify a timeout, or you pass a value of undef, there will be no timeout — apart from any default system timeouts like TCP connection timeouts, obviously. 💀

Net::Ident::lookupFromInAddr ($localaddr, $remoteaddr [, $timeout])

Net::Ident::lookupFromInAddr is an exportable function (via @EXPORT_OK).

The arguments are the local and remote address of a connection, in packed "sockaddr" format — the kind of thing that getsockname returns. The optional timeout value specifies a timeout in seconds; see also the description of the timeout value in the Net::Ident::lookup section above. 🦋

bestie, heads up: the given localaddr must have the IP address of a local interface of the machine you're calling this on, otherwise an error will occur. 👀

Use this function whenever you have a local and remote socket address but no direct access to the socket itself. For example, because you're parsing the output of netstat and extracting socket addresses, or because you're writing a mod_perl script under apache (in that case, also peep the Apache::Connection method below 💜).

ident_lookup SOCKET [$timeout]

When you import the "magic" tag ':fh' using use Net::Ident ':fh';, the Net::Ident module extends the FileHandle class with one extra method call: ident_lookup.

It assumes that the object it's operating on (a FileHandle) is a connected TCP/IP socket, i.e. something that's either connect()ed or accept()ed. The optional parameter specifies the timeout in seconds, just like the timeout parameter of the function calls above. ✨

Some people do not like the way "proper" object design gets broken by letting one module add methods to another class. Which is why, starting from version 1.20, you have to explicitly ask for this behaviour to happen. 😌

Personally? 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 :), that's an acceptable solution. But you might think otherwise, and honestly, valid. 🫶

ident_lookup Apache::Connection [$timeout]

When you import the "magic" tag ':apache' using use Net::Ident ':apache';, the Net::Ident module extends the Apache::Connection class with one extra method call: ident_lookup. This method takes one optional parameter: a timeout value in seconds.

It's a similar convenience function to the FileHandle::ident_lookup method, to be used with mod_perl scripts under Apache. 🌸

What these functions return depends on the context:

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

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 RFC1413 for more information. 👑

array context

In array context, these functions return: ($username, $opsys, $error).

  • The $username is the remote username or ID, as returned in scalar context, or undef on error.
  • The $opsys is the remote operating system as reported by the remote ident daemon, or undef on a network error, or "ERROR" when the remote ident daemon reported an error. This could also contain the character set of the returned username. See RFC1413.
  • The $error is the error message, either the error reported by the remote ident daemon (in which case $opsys is "ERROR"), or the internal message from the Net::Ident module, which includes the system errno $! whenever possible. A likely candidate is "Connection refused" when the remote site isn't running an ident daemon, or "Connection timed out" when the remote site isn't answering our connection request. 💀
fr fr: when $username has a value, $error is always undef, and vice versa. That's the deal.

🌸 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. Most of this code will look super familiar if you just read perlipc. 💅

Exercise this server by telnetting to it, preferably from a machine that has a suitable ident daemon installed. ✨

#!/usr/bin/perl -w

use Net::Ident ':fh';
# 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, "\n" }

my $port = shift || 2345;
my $proto = getprotobyname('tcp');
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\@$name, it's now ",
       scalar localtime, "\n";
}

🦋 Asynchronous Interface

The asynchronous interface is meant for those who know the ins and outs of the select() call — the 4-argument version of select(), but I didn't need to say that, did I? 😏

This interface is completely object oriented. The following methods are available:

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 Net::Ident::lookup subroutine.

This method returns immediately — the supplied $timeout is only stored in the object and used in future methods. ✨

If you want to implement your own timeout, that's totally fine. Simply throw away the object when you don't want it anymore. 🗑️

The constructor will always succeed. When it detects an error, though, it returns an object that "has already failed" internally. In that case, all methods will return "undef" — except for the "geterror" method, which will return the error message. 🙈

The timeout is not implemented using alarm(). In fact you can use alarm() completely independent of this library — they do not interfere. 🧚

newFromInAddr $localaddr, $remoteaddr, $timeout

Alternative constructor, that takes two packed sockaddr structures. Otherwise it behaves identical to the "new" constructor above. 🦋

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 $obj itself — or undef on error.

  • ready $obj [$blocking] — this object method tells you whether the data we got back from the remote daemon is complete yet, as a plain old true or false 💖. On error it hands you undef. It reads whatever data is sitting on the connection. If $blocking is true, it just sits there and waits until all the data arrives — and heads up, when blocking is true it will never return false, only true or undef, bestie. If $blocking is not true, it doesn't block at all (unless… see right below 👀).

If you haven't called query $obj yet, this method will call it for you 🫶 — which means it can block no matter what $blocking says, depending on whether the connection to the ident is writable.

Obviously the whole point is that you call this routine whenever you see the connection to the ident daemon is readable, and then act appropriately when it comes back true. Periodt.

Lowkey important: once ready returns true, there are no longer any checks on timeout (because the networking part of the lookup is done anyway, slay). So ready $obj can totally return true way after the timeout expired, as long as it returned true at least once before the timeout expired. And yes, this is to be construed as a feature ✨. Iconic behaviour honestly.
  • username $obj — this object method parses the return from the remote ident daemon, and blocks until the query is complete if it needs to (it effectively calls ready $obj 1 for you if you didn't already do it yourself, no cap). Returns the parsed username on success 🎀, or undef on error. In an array context, the return values are the same as described for the Net::Ident::lookup subroutine.
  • getfh $obj — this object method hands you the internal FileHandle used for the connection to the remote ident daemon. Absolutely invaluable if you want it to dance in your select() ring 💃. Returns undef when an error has occurred.
  • geterror $obj — this object method returns the error message in case there was an error. undef when there was no error. Simple as that 💅.

An asynchronous example implementing the above server in a multi-threaded way via select, is left as an exercise for the interested reader 🙈 (iykyk).

🫣 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. Like, all of it. The whole vibe is at your own risk, bestie 💀.

👑 AUTHOR

Jan-Pieter Cornet, <johnpc@xs4all.nl>

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.

🌈 REVISION HISTORY

V1.20

August 2, 1999. Finally implemented the long-asked-for lookupFromInAddr method 🔥. Other changes:

  • 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).
  • Allow adding an ident_lookup method to the Apache::Connection class, as a convenience for mod_perl script writers.
  • Rewritten tests, included test for the Apache::Connection method by actually launching apache and performing ident lookups from within mod_perl 🧚.
  • 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.

V1.11

Jan 15th, 1997. Several bugfixes, and some slight interface changes:

  • constructor now called "new" instead of "initconnect", constructor now always succeeds, if something has gone wrong in the constructor, all methods return undef (like "getfh"), except for "geterror", which returns the error message.
  • The recommended exported function is now "ident_lookup" instead of "lookup".
  • Fixed a bug: now chooses O_NDELAY or O_NONBLOCK from %Config, instead of hardcoding O_NDELAY (argh) 😭.
  • 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.
  • Miscellaneous pod fixes.
  • Test script now actually tests multiple different things ✨.

V1.10

Jan 11th, 1997. Complete rewrite for perl5. Requires perl5.002 or up.

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

[this release wasn't called Net::Ident, of course, it was called rfc931.pl]

V1.01

Around November 1994. Removed a spurious perl5 -w complaint. First public release. Has been tested against perl 5.000 and perl 4.036.

V1.00

Dunno, somewhere 1994. First neat collection of dusty routines put in a package 🦋.

🌸 SEE ALSO

Socket RFC1413, RFC931

okay that's a wrap bestie, we ate and left no crumbs 💅✨ this lil page came from perl v5.40.1, dated 2026-04-05, and it's the Ident(3pm) manual page — go forth and ident responsibly 🫶💖

📦 where this page comes from