NAME

Server - simple TCP/IP server (forking and non-forking)

SYNOPSIS

my $server_cb = sub  {
                       my ($s) = shift ;
                       print STDOUT "Echo server: type bye to quit, exit ",
                                    "to kill the server.\n\n" ;
                       while (defined ($tmp = <STDIN>)) {
                           return if ($tmp =~ /^bye/i);
                           $s->quit() if ($tmp =~ /^exit/i);
                           print STDOUT "You said:>$tmp\n";
                     }                            
my ($foo) = new Server;
$foo->port(9000);
$foo->callback($server_cb);
$foo->mode("forking");
print "Starting server\n";
$foo->run();

DESCRIPTION

Server provides a (very) simple server daemon for TCP/IP processes. It is intended to free the programmer from having to think too hard about networking issues so that they can concentrate on doing something useful.

The Server object accepts the following methods, which configure various aspects of the new server:

port

The port to listen on.

hostname

The local address to bind to. If no address is specified, listens for any connection on the designated port.

listen

Queue size for listen.

proto

Protocol we're listening to (defaults to tcp)

timeout

Timeout value (see IO::Socket::INET)

allowed

list of IP addresses or hostnames that are explicitly allowed to connect to the server. If empty, the default policy is to allow connections from anyone not in the 'forbidden' list.

NOTE: IP addresses or hostnames may be specified as perl regular expressions; for example 154\.153\.4\..* matches any IP address beginning with '154.153.4.'; .*antipope\.org matches any hostname in the antipope.org domain.

forbidden

list of IP addresses or hostnames that are refused permission to connect to the server. If empty, the default policy is to refuse connections from anyone not in the 'allowed' list (unless the allowed list is empty, in which case anyone may connect).

callback

Coderef to a subroutine which handles incoming connections (called with one parameter -- a Server object which can be used to shut down the session).

mode

Can be one of forking, select, client, threaded, or inetd. (threaded and inetd are not yet implemented and doesn't do anything!) If forking mode is selected, the server handles requests by forking a child process to service them. If select mode is selected, the server uses the IO::Select class to implement a simple non-forking server. (NB: This is not recommended for slow or resource-intensive servers, but may be useful for servers that provide access to some kind of shared resource for other processes, where the resource may be held in memory).

The client mode is special; it indicates that rather than sitting around waiting for an incoming connection, the server is itself a TCP/IP client. In client mode, hostname is the remote host to connect to and port is the remote port to open. The callback routine is used, as elsewhere, but it should be written as for a client -- i.e. it should issue a request or command, then read. An additional method exists for client mode: trigger. trigger expects a coderef as a parameter. This coderef is executed before the client-mode server spawns a child; if it returns a non-zero value the child is forked and opens a client connection to the target host, otherwise the server exits. The trigger method may be used to sleep for a random interval then return 1 (so that repeated clients are spawned at random intervals), or fork several children (on a one- time-only basis) then work as above (so that several clients poke at the target server on a random basis). The default trigger method returns 1 immediately the first time it is called, then returns 0 -- this means that the client makes a single connection to the target host, invokes the callback routine, then exits. (See the test examples which come with this module for examples of how to use client mode.)

Note that client mode relies on the fork() system call.

The threaded mode indicates that multithreading will be used to service requests; code to support this doesn't exist yet (and requires Perl 5.005 or higher and a native threads library to run, so it's not 100% portable). The inetd mode indicates that the server will run as a daemon from inetd, rather than standalone; it implies that the run() method will install(!) the server on the host system's inetd configuration and re-start inetd. (This doesn't exist yet, either, and is only suitable for stable, high-throughput systems in heavy production use.)

By default, forking mode is selected.

Of these, the callback method is most important; it specifies a reference to a subroutine which effectively does whatever the server does.

A callback subroutine is a normal Perl subroutine. It is invoked with STDIN and STDOUT attached to an IO::Socket::INET object, so that reads from STDIN get information from the client, and writes to STDOUT send information to the client. Note that both STDIN and STDOUT are unbuffered. In addition, a Server object is passed as an argument (but the callback is free to ignore it).

Your server reads and writes data via the socket as if it is the standard input and standard output filehandles; for example:

while (defined ($tmp = <STDIN>)) {  # read a line from the socket

print STDOUT "You said: $tmp\n";    # print something to the socket

(See IO::Handle and IO::Socket for more information on this.)

If you're not familiar with sockets, don't get too fresh and try to close or seek on STDIN or STDOUT; just treat them like a file.

The server object is not strictly necessary in the callback, but comes in handy: you can shut down the server completely by calling the quit() method.

When writing a callback subroutine, remember to define some condition under which you return!

Here's a slightly more complex server example:

 # minimal http server (HTTP/0.9):
 # this is a REALLY minimal HTTP server. It only understands GET
 # requests, does no header parsing whatsoever, and doesn't understand
 # relative addresses! Nor does it understand CGI scripts. And it ain't
 # suitable as a replacement for Apache (at least, not any time soon :).
 # The base directory for the server and the default
 # file name are defined in B<url_to_file()>, which maps URLs to
 # absolute pathnames. The server code itself is defined in the
 # closure B<$http>, which shows how simple it is to write a server
 # using this module.

 sub url_to_file($) {
   # for a given URL, turn it into an absolute pathname
   my ($u) = shift ;  # incoming URL fragment from GET request
   my ($f) = "";      # file pathname to return
   my ($htbase) = "/usr/local/etc/httpd/docs/";
   my ($htdefault) = "index.html";
   chop $u;
   if ($u eq "/") {
       $f = $htbase . $htdefault;
       return $f;
   } else {
       if ($u =~ m|^/.+|) {
           $f = $htbase;  chop $f;
           $f .= $u;
       } elsif ($u =~ m|[^/]+|) {
           $f = $htbase . $u;
       }
       if ($u =~ m|.+/$|) {
           $f .= $htdefault;
       }
       if ($f =~ /\.\./) {
           my (@path) = split("/", $f);
           my ($buff, $acc) = "";
           shift @path;
           while ($buff = shift @path) {
               my ($tmp) = shift @path;
               if ($tmp ne '..') {
                   unshift @path, $tmp;
                   $acc .= "/$buff";
               }
           }
           $f = $acc;
       }
   }
   return $f;
 }

 my ($http) = sub {
    my ($fh) = shift ;
    while (defined ($tmp = <STDIN>)) {
        chomp $tmp;
        if ($tmp =~ /^GET\s+(.*)$/i) {
            $getfile = $1;
	    $getfile = url_to_file($getfile);
            print STDERR "Sending $getfile\n";
            my ($in) = new IO::File();
            if ($in->open("<$getfile") ) {
                $in->autoflush(1);
                print STDOUT "Content-type: text/html\n\n";
                while (defined ($line = <$in>)) {
                    print STDOUT $line;
                }
            } else {
                print STDOUT "404: File not found\n\n";
            }
        }
        return 0;
    }
 };                           

 # main program starts here

 my (%config) =  ("port"     => 9000, 
                  "callback" => $http, 
		  "hostname" => "public.antipope.org");

 my ($allowed) = ['.*antipope\.org', 
 		 '.*localhost.*'];

 my ($forbidden) = [ '194\.205\.10\.2'];

 my ($foo) = new Server(%config); # create new http server bound to port 
                                  # 9000 of public.antipope.org
 $foo->allowed($allowed);         # who is allowed to connect to us
 $foo->forbidden($forbidden);     # who is refused access
 print "Starting http server on port 9000\n";
 $foo->run();                     
 exit 0;

Additional methods

NetServer::Generic provides a couple of extra methods.

peer()

The peer() method returns a reference to a two-element list containing the hostname and IP address of the host at the other end of the socket. If called before a connection has been received, its value will be undefined. (Don't try to assign values via peer unless you want to confuse the allowed/forbidden checking code!)

quit()

The quit() method attempts to shut down a server. If running as a forking service, it does so by sending a kill -15 to the parent process. If running as a select-based service it returns from run().

Types of server

A full discussion of internet servers is well beyond the scope of this man page. Beginners may want to start with a source like "Beginning Linux Programming" (which provides a simple, lucid discussion); more advanced readers may find Stevens' "Advanced Programming in the UNIX environment" useful.

In general, on non-threaded systems, a forking server is slightly less efficient than a select-based server (and uses up lots of PIDs). On the other hand, a select-based server is not a good solution to high workloads or time-consuming processes such as providing an NNTP news feed to an online newsreader.

A major issue with the select-based server code in this release is that the IO::Select based server cannot know that a socket is ready until some data is received over it. (It calls can_read() to detect sockets waiting to be read from.) Thus, it is not suitable for writing servers like which emit status information without first reading a request.

SEE ALSO

IO::Handle, IO::Socket, LWP, perlfunc, "I/O Operators" in perlop

HISTORY

Version 0.1

Based on the simple forking server in Chapter 10 of "Advanced Perl Programming" by Sriram Srinivasan, with a modular wrapper to make it easy to use and configure, and a rudimentary access control system.

Version 0.2

Added the peer() method to provide peer information.

Bugfix to ok_to_serve from Marius Kjeldahl marius@ace.funcom.com.

Added select-based server code, mode method to switch between forking and selection server modes.

Updated test code (should do something now!)

Added example: fortune server and client code.

Supports NetServer::SMTP (and, internally, NetServer::vTID).

cpanm NetServer::Generic

perl -MCPAN -e shell
install NetServer::Generic