Net::Server(3pm) User Contributed Perl Documentation Net::Server(3pm)
NAME
Net::Server - Extensible, general Perl server engine
SYNOPSIS
#!/usr/bin/perl -w -T
package MyPackage;
use Net::Server;
@ISA = qw(Net::Server);
sub process_request {
#...code...
}
MyPackage->run(port => 160);
exit;
FEATURES
* Single Server Mode
* Inetd Server Mode
* Preforking Simple Mode (PreForkSimple)
* Preforking Managed Mode (PreFork)
* Forking Mode
* Multiplexing Mode using a single process
* Multi port accepts on Single, Preforking, and Forking modes
* Simultaneous accept/recv on tcp, udp, and unix sockets
* Safe signal handling in Fork/PreFork avoids perl signal trouble
* User customizable hooks
* Chroot ability after bind
* Change of user and group after bind
* Basic allow/deny access control
* Customized logging (choose Syslog, log_file, or STDERR)
* HUP able server (clean restarts via sig HUP)
* Dequeue ability in all Fork and PreFork modes.
* Taint clean
* Written in Perl
* Protection against buffer overflow
* Clean process flow
* Extensibility
DESCRIPTION
"Net::Server" is an extensible, generic Perl server engine.
"Net::Server" combines the good properties from "Net::Daemon" (0.34),
"NetServer::Generic" (1.03), and "Net::FTPServer" (1.0), and also from
various concepts in the Apache Webserver.
"Net::Server" attempts to be a generic server as in "Net::Daemon" and
"NetServer::Generic". It includes with it the ability to run as an
inetd process ("Net::Server::INET"), a single connection server
("Net::Server" or "Net::Server::Single"), a forking server
("Net::Server::Fork"), a preforking server which maintains a constant
number of preforked children ("Net::Server::PreForkSimple"), or as a
managed preforking server which maintains the number of children based
on server load ("Net::Server::PreFork"). In all but the inetd type,
the server provides the ability to connect to one or to multiple server
ports.
"Net::Server" uses ideologies of "Net::FTPServer" in order to provide
extensibility. The additional server types are made possible via "per-
sonalities" or sub classes of the "Net::Server". By moving the multi-
ple types of servers out of the main "Net::Server" class, the
"Net::Server" concept is easily extended to other types (in the near
future, we would like to add a "Thread" personality).
"Net::Server" borrows several concepts from the Apache Webserver.
"Net::Server" uses "hooks" to allow custom servers such as SMTP, HTTP,
POP3, etc. to be layered over the base "Net::Server" class. In addi-
tion the "Net::Server::PreFork" class borrows concepts of
min_start_servers, max_servers, and min_waiting servers.
"Net::Server::PreFork" also uses the concept of an flock serialized
accept when accepting on multiple ports (PreFork can choose between
flock, IPC::Semaphore, and pipe to control serialization).
PERSONALITIES
"Net::Server" is built around a common class (Net::Server) and is
extended using sub classes, or "personalities". Each personality
inherits, overrides, or enhances the base methods of the base class.
Included with the Net::Server package are several basic personalities,
each of which has their own use.
Fork
Found in the module Net/Server/Fork.pm (see Net::Server::Fork).
This server binds to one or more ports and then waits for a connec-
tion. When a client request is received, the parent forks a child,
which then handles the client and exits. This is good for moder-
ately hit services.
INET
Found in the module Net/Server/INET.pm (see Net::Server::INET).
This server is designed to be used with inetd. The "pre_bind",
"bind", "accept", and "post_accept" are all overridden as these
services are taken care of by the INET daemon.
MultiType
Found in the module Net/Server/MultiType.pm (see Net::Server::Mul-
tiType). This server has no server functionality of its own. It
is designed for servers which need a simple way to easily switch
between different personalities. Multiple "server_type" parameters
may be given and Net::Server::MultiType will cycle through until it
finds a class that it can use.
Multiplex
Found in the module Net/Server/Multiplex.pm (see Net::Server::Mul-
tiplex). This server binds to one or more ports. It uses IO::Mul-
tiplex to multiplex between waiting for new connections and waiting
for input on currently established connections. This personality
is designed to run as one process without forking. The "pro-
cess_request" method is never used but the "mux_input" callback is
used instead (see also IO::Multiplex). See examples/samplechat.pl
for an example using most of the features of Net::Server::Multi-
plex.
PreForkSimple
Found in the module Net/Server/PreFork.pm (see Net::Server::Pre-
Fork). This server binds to one or more ports and then forks
"max_servers" child process. The server will make sure that at any
given time there are always "max_servers" available to receive a
client request. Each of these children will process up to
"max_requests" client connections. This type is good for a heavily
hit site that can dedicate max_server processes no matter what the
load. It should scale well for most applications. Multi port
accept is accomplished using either flock, IPC::Semaphore, or pipe
to serialize the children. Serialization may also be switched on
for single port in order to get around an OS that does not allow
multiple children to accept at the same time. For a further dis-
cussion of serialization see Net::Server::PreFork.
PreFork
Found in the module Net/Server/PreFork.pm (see Net::Server::Pre-
Fork). This server binds to one or more ports and then forks
"min_servers" child process. The server will make sure that at any
given time there are at least "min_spare_servers" but not more than
"max_spare_servers" available to receive a client request, up to
"max_servers". Each of these children will process up to
"max_requests" client connections. This type is good for a heavily
hit site, and should scale well for most applications. Multi port
accept is accomplished using either flock, IPC::Semaphore, or pipe
to serialize the children. Serialization may also be switched on
for single port in order to get around an OS that does not allow
multiple children to accept at the same time. For a further dis-
cussion of serialization see Net::Server::PreFork.
Single
All methods fall back to Net::Server. This personality is provided
only as parallelism for Net::Server::MultiType.
"Net::Server" was partially written to make it easy to add new person-
alities. Using separate modules built upon an open architecture allows
for easy addition of new features, a separate development process, and
reduced code bloat in the core module.
SOCKET ACCESS
Once started, the Net::Server will take care of binding to port and
waiting for connections. Once a connection is received, the
Net::Server will accept on the socket and will store the result (the
client connection) in $self->{server}->{client}. This property is a
Socket blessed into the the IO::Socket classes. UDP servers are
slightly different in that they will perform a recv instead of an
accept.
To make programming easier, during the post_accept phase, STDIN and
STDOUT are opened to the client connection. This allows for programs
to be written using <STDIN> and print "out\n" to print to the client
connection. UDP will require using a ->send call.
SAMPLE CODE
The following is a very simple server. The main functionality occurs
in the process_request method call as shown below. Notice the use of
timeouts to prevent Denial of Service while reading. (Other examples
of using "Net::Server" can, or will, be included with this distribu-
tion).
#!/usr/bin/perl -w -T
#--------------- file test.pl ---------------
package MyPackage;
use strict;
use vars qw(@ISA);
use Net::Server::PreFork; # any personality will do
@ISA = qw(Net::Server::PreFork);
MyPackage->run();
exit;
### over-ridden subs below
sub process_request {
my $self = shift;
eval {
local $SIG{ALRM} = sub { die "Timed Out!\n" };
my $timeout = 30; # give the user 30 seconds to type a line
my $previous_alarm = alarm($timeout);
while( <STDIN> ){
s/\r?\n$//;
print "You said \"$_\"\r\n";
alarm($timeout);
}
alarm($previous_alarm);
};
if( $@=~/timed out/i ){
print STDOUT "Timed Out.\r\n";
return;
}
}
1;
#--------------- file test.pl ---------------
Playing this file from the command line will invoke a Net::Server using
the PreFork personality. When building a server layer over the
Net::Server, it is important to use features such as timeouts to pre-
vent Denial of Service attacks.
ARGUMENTS
There are five possible ways to pass arguments to Net::Server. They
are passing on command line, using a conf file, passing parameters to
run, returning values in the default_values method, or using a pre-
built object to call the run method (such as that returned by the new
method).
Arguments consist of key value pairs. On the commandline these pairs
follow the POSIX fashion of "--key value" or "--key=value", and also
"key=value". In the conf file the parameter passing can best be shown
by the following regular expression:
($key,$val)=~/^(\w+)\s+(\S+?)\s+$/. Passing arguments to the run
method is done as follows: "Net::Server-"run(key1 => 'val1')>. Passing
arguments via a prebuilt object can best be shown in the following
code:
#!/usr/bin/perl -w -T
#--------------- file test2.pl ---------------
package MyPackage;
use strict;
use vars (@ISA);
use Net::Server;
@ISA = qw(Net::Server);
my $server = MyPackage->new({
key1 => 'val1',
});
$server->run();
#--------------- file test.pl ---------------
All five methods for passing arguments may be used at the same time.
Once an argument has been set, it is not over written if another method
passes the same argument. "Net::Server" will look for arguments in the
following order:
1) Arguments contained in the prebuilt object.
2) Arguments passed on command line.
3) Arguments passed to the run method.
4) Arguments passed via a conf file.
5) Arguments set in default_values method.
6) Arguments set in the configure_hook.
Each of these levels will override parameters of the same name speci-
fied in subsequent levels. For example, specifying --setsid=0 on the
command line will override a value of "setsid 1" in the conf file.
Note that the configure_hook method doesn't return values to set, but
is there to allow for setting up configured values before the configure
method is called.
Key/value pairs used by the server are removed by the configuration
process so that server layers on top of "Net::Server" can pass and read
their own parameters. Currently, Getopt::Long is not used. The follow-
ing arguments are available in the default "Net::Server" or
"Net::Server::Single" modules. (Other personalities may use additional
parameters and may optionally not use parameters from the base class.)
Key Value Default
conf_file "filename" undef
log_level 0-4 2
log_file (filename|Sys::Syslog) undef
## syslog parameters
syslog_logsock (unix|inet) unix
syslog_ident "identity" "net_server"
syslog_logopt (cons|ndelay|nowait|pid) pid
syslog_facility \w+ daemon
port \d+ 20203
host "host" "*"
proto (tcp|udp|unix) "tcp"
listen \d+ SOMAXCONN
reverse_lookups 1 undef
allow /regex/ none
deny /regex/ none
cidr_allow CIDR none
cidr_deny CIDR none
## daemonization parameters
pid_file "filename" undef
chroot "directory" undef
user (uid|username) "nobody"
group (gid|group) "nobody"
background 1 undef
setsid 1 undef
no_close_by_child (1|undef) undef
## See Net::Server::Proto::(TCP|UDP|UNIX|etc)
## for more sample parameters.
conf_file
Filename from which to read additional key value pair arguments for
starting the server. Default is undef.
log_level
Ranges from 0 to 4 in level. Specifies what level of error will be
logged. "O" means logging is off. "4" means very verbose. These
levels should be able to correlate to syslog levels. Default is 2.
These levels correlate to syslog levels as defined by the following
key/value pairs: 0=>'err', 1=>'warning', 2=>'notice', 3=>'info',
4=>'debug'.
log_file
Name of log file to be written to. If no name is given and hook is
not overridden, log goes to STDERR. Default is undef. If the
magic name "Sys::Syslog" is used, all logging will take place via
the Sys::Syslog module. If syslog is used the parameters "sys-
log_logsock", "syslog_ident", and "syslog_logopt",and "sys-
log_facility" may also be defined. If a "log_file" is given or if
"setsid" is set, STDIN and STDOUT will automatically be opened to
/dev/null and STDERR will be opened to STDOUT. This will prevent
any output from ending up at the terminal.
pid_file
Filename to store pid of parent process. Generally applies only to
forking servers. Default is none (undef).
syslog_logsock
Only available if "log_file" is equal to "Sys::Syslog". May be
either "unix" of "inet". Default is "unix". See Sys::Syslog.
syslog_ident
Only available if "log_file" is equal to "Sys::Syslog". Id to
prepend on syslog entries. Default is "net_server". See Sys::Sys-
log.
syslog_logopt
Only available if "log_file" is equal to "Sys::Syslog". May be
either zero or more of "pid","cons","ndelay","nowait". Default is
"pid". See Sys::Syslog.
syslog_facility
Only available if "log_file" is equal to "Sys::Syslog". See
Sys::Syslog and syslog. Default is "daemon".
port
See Net::Server::Proto. Local port/socket on which to bind. If
low port, process must start as root. If multiple ports are given,
all will be bound at server startup. May be of the form
"host:port/proto", "host:port", "port/proto", or "port", where host
represents a hostname residing on the local box, where port repre-
sents either the number of the port (eg. "80") or the service des-
ignation (eg. "http"), and where proto represents the protocol to
be used. See Net::Server::Proto. If you are working with unix
sockets, you may also specify "socket_file|unix" or
"socket_file|type|unix" where type is SOCK_DGRAM or SOCK_STREAM.
If the protocol is not specified, proto will default to the "proto"
specified in the arguments. If "proto" is not specified there it
will default to "tcp". If host is not specified, host will default
to "host" specified in the arguments. If "host" is not specified
there it will default to "*". Default port is 20203. Configura-
tion passed to new or run may be either a scalar containing a sin-
gle port number or an arrayref of ports.
host
Local host or addr upon which to bind port. If a value of '*' is
given, the server will bind that port on all available addresses on
the box. See Net::Server::Proto. See IO::Socket. Configuration
passed to new or run may be either a scalar containing a single
host or an arrayref of hosts - if the hosts array is shorter than
the ports array, the last host entry will be used to augment the
hosts arrary to the size of the ports array.
proto
See Net::Server::Proto. Protocol to use when binding ports. See
IO::Socket. As of release 0.70, Net::Server supports tcp, udp, and
unix. Other types will need to be added later (or custom modules
extending the Net::Server::Proto class may be used). Configuration
passed to new or run may be either a scalar containing a single
proto or an arrayref of protos - if the protos array is shorter
than the ports array, the last proto entry will be used to augment
the protos arrary to the size of the ports array.
listen
See L<IO::Socket>. Not used with udp protocol (or UNIX SOCK_DGRAM).
reverse_lookups
Specify whether to lookup the hostname of the connected IP. Infor-
mation is cached in server object under "peerhost" property.
Default is to not use reverse_lookups (undef).
allow/deny
May be specified multiple times. Contains regex to compare to
incoming peeraddr or peerhost (if reverse_lookups has been
enabled). If allow or deny options are given, the incoming client
must match an allow and not match a deny or the client connection
will be closed. Defaults to empty array refs.
cidr_allow/cidr_deny
May be specified multiple times. Contains a CIDR block to compare
to incoming peeraddr. If cidr_allow or cidr_deny options are
given, the incoming client must match a cidr_allow and not match a
cidr_deny or the client connection will be closed. Defaults to
empty array refs.
chroot
Directory to chroot to after bind process has taken place and the
server is still running as root. Defaults to undef.
user
Userid or username to become after the bind process has occured.
Defaults to "nobody." If you would like the server to run as root,
you will have to specify "user" equal to "root".
group
Groupid or groupname to become after the bind process has occured.
Defaults to "nobody." If you would like the server to run as root,
you will have to specify "group" equal to "root".
background
Specifies whether or not the server should fork after the bind
method to release itself from the command line. Defaults to undef.
Process will also background if "setsid" is set.
setsid
Specifies whether or not the server should fork after the bind
method to release itself from the command line and then run the
"POSIX::setsid()" command to truly daemonize. Defaults to undef.
If a "log_file" is given or if "setsid" is set, STDIN and STDOUT
will automatically be opened to /dev/null and STDERR will be opened
to STDOUT. This will prevent any output from ending up at the ter-
minal.
no_close_by_child
Boolean. Specifies whether or not a forked child process has per-
mission or not to shutdown the entire server process. If set to 1,
the child may NOT signal the parent to shutdown all children.
Default is undef (not set).
no_client_stdout
Boolean. Default undef (not set). Specifies that STDIN and STDOUT
should not be opened on the client handle once a connection has
been accepted. By default the Net::Server will open STDIN and STD-
OUT on the client socket making it easier for many types of scripts
to read directly from and write directly to the socket using normal
print and read methods. Disabling this is useful on clients that
may be opening their own connections to STDIN and STDOUT.
This option has no affect on STDIN and STDOUT which has a magic
client property that is tied to the already open STDIN and STDOUT.
leave_children_open_on_hup
Boolean. Default undef (not set). If set, the parent will not
attempt to close child processes if the parent receives a SIG HUP.
The parent will rebind the the open port and begin tracking a fresh
set of children.
Children of a Fork server will exit after their current request.
Children of a Prefork type server will finish the current request
and then exit.
Note - the newly restarted parent will start up a fresh set of
servers on fork servers. The new parent will attempt to keep track
of the children from the former parent but custom communication
channels (open pipes from the child to the old parent) will no
longer be available to the old child processes. New child pro-
cesses will still connect properly to the new parent.
PROPERTIES
All of the "ARGUMENTS" listed above become properties of the server
object under the same name. These properties, as well as other inter-
nal properties, are available during hooks and other method calls.
The structure of a Net::Server object is shown below:
$self = bless( {
'server' => {
'key1' => 'val1',
# more key/vals
}
}, 'Net::Server' );
This structure was chosen so that all server related properties are
grouped under a single key of the object hashref. This is so that
other objects could layer on top of the Net::Server object class and
still have a fairly clean namespace in the hashref.
You may get and set properties in two ways. The suggested way is to
access properties directly via
my $val = $self->{server}->{key1};
Accessing the properties directly will speed the server process. A
second way has been provided for object oriented types who believe in
methods. The second way consists of the following methods:
my $val = $self->get_property( 'key1' );
my $self->set_property( key1 => 'val1' );
Properties are allowed to be changed at any time with caution (please
do not undef the sock property or you will close the client connec-
tion).
CONFIGURATION FILE
"Net::Server" allows for the use of a configuration file to read in
server parameters. The format of this conf file is simple key value
pairs. Comments and white space are ignored.
#-------------- file test.conf --------------
### user and group to become
user somebody
group everybody
### logging ?
log_file /var/log/server.log
log_level 3
pid_file /tmp/server.pid
### optional syslog directive
### used in place of log_file above
#log_file Sys::Syslog
#syslog_logsock unix
#syslog_ident myserver
#syslog_logopt pid|cons
### access control
allow .+\.(net|com)
allow domain\.com
deny a.+
cidr_allow 127.0.0.0/8
cidr_allow 192.0.2.0/24
cidr_deny 192.0.2.4/30
### background the process?
background 1
### ports to bind (this should bind
### 127.0.0.1:20205 and localhost:20204)
### See Net::Server::Proto
host 127.0.0.1
port localhost:20204
port 20205
### reverse lookups ?
# reverse_lookups on
#-------------- file test.conf --------------
PROCESS FLOW
The process flow is written in an open, easy to override, easy to hook,
fashion. The basic flow is shown below. This is the flow of the
"$self->run" method.
$self->configure_hook;
$self->configure(@_);
$self->post_configure;
$self->post_configure_hook;
$self->pre_bind;
$self->bind;
$self->post_bind_hook;
$self->post_bind;
$self->pre_loop_hook;
$self->loop;
### routines inside a standard $self->loop
# $self->accept;
# $self->run_client_connection;
# $self->done;
$self->pre_server_close_hook;
$self->server_close;
The server then exits.
During the client processing phase ("$self->run_client_connection"),
the following represents the program flow:
$self->post_accept;
$self->get_client_info;
$self->post_accept_hook;
if( $self->allow_deny
&& $self->allow_deny_hook ){
$self->process_request;
}else{
$self->request_denied_hook;
}
$self->post_process_request_hook;
$self->post_process_request;
The process then loops and waits for the next connection. For a more
in depth discussion, please read the code.
During the server shutdown phase ("$self->server_close"), the following
represents the program flow:
$self->close_children; # if any
$self->post_child_cleanup_hook;
if( Restarting server ){
$self->restart_close_hook();
$self->hup_server;
}
$self->shutdown_sockets;
exit;
MAIN SERVER METHODS
"$self->run"
This method incorporates the main process flow. This flow is
listed above.
The method run may be called in any of the following ways.
MyPackage->run(port => 20201);
MyPackage->new({port => 20201})->run;
my $obj = bless {server=>{port => 20201}}, 'MyPackage';
$obj->run;
The ->run method should typically be the last method called in a
server start script (the server will exit at the end of the ->run
method).
"$self->configure"
This method attempts to read configurations from the commandline,
from the run method call, or from a specified conf_file. All of
the configured parameters are then stored in the {"server"} prop-
erty of the Server object.
"$self->post_configure"
The post_configure hook begins the startup of the server. During
this method running server instances are checked for, pid_files are
created, log_files are created, Sys::Syslog is initialized (as
needed), process backgrounding occurs and the server closes STDIN
and STDOUT (as needed).
"$self->pre_bind"
This method is used to initialize all of the socket objects used by
the server.
"$self->bind"
This method actually binds to the inialized sockets (or rebinds if
the server has been HUPed).
"$self->post_bind"
During this method priveleges are dropped. The INT, TERM, and QUIT
signals are set to run server_close. Sig PIPE is set to IGNORE.
Sig CHLD is set to sig_chld. And sig HUP is set to call sig_hup.
Under the Fork, PreFork, and PreFork simple personalities, these
signals are registered using Net::Server::SIG to allow for safe
signal handling.
"$self->loop"
During this phase, the server accepts incoming connections. The
behavior of how the accepting occurs and if a child process handles
the connection is controlled by what type of Net::Server personal-
ity the server is using.
Net::Server and Net::Server single accept only one connection at a
time.
Net::Server::INET runs one connection and then exits (for use by
inetd or xinetd daemons).
Net::Server::MultiPlex allows for one process to simultaneously
handle multiple connections (but requires rewriting the pro-
cess_request code to operate in a more "packet-like" manner).
Net::Server::Fork forks off a new child process for each incoming
connection.
Net::Server::PreForkSimple starts up a fixed number of processes
that all accept on incoming connections.
Net::Server::PreFork starts up a base number of child processes
which all accept on incoming connections. The server throttles the
number of processes running depending upon the number of requests
coming in (similar to concept to how Apache controls its child pro-
cesses in a PreFork server).
Read the documentation for each of the types for more information.
"$self->server_close"
This method is called once the server has been signaled to end, or
signaled for the server to restart (via HUP), or the loop method
has been exited.
This method takes care of cleaning up any remaining child pro-
cesses, setting appropriate flags on sockets (for HUPing), closing
up logging, and then closing open sockets.
MAIN CLIENT CONNECTION METHODS
"$self->run_client_connection"
This method is run after the server has accepted and received a
client connection. The full process flow is listed above under
PROCESS FLOWS. This method takes care of handling each client con-
nection.
"$self->post_accept"
This method opens STDIN and STDOUT to the client socket. This
allows any of the methods during the run_client_connection phase to
print directly to and read directly from the client socket.
"$self->get_client_info"
This method looks up information about the client connection such
as ip address, socket type, and hostname (as needed).
"$self->allow_deny"
This method uses the rules defined in the allow and deny configura-
tion parameters to determine if the ip address should be accepted.
"$self->process_request"
This method is intended to handle all of the client communication.
At this point STDIN and STDOUT are opened to the client, the ip
address has been verified. The server can then interact with the
client connection according to whatever API or protocol the server
is implementing. Note that the stub implementation uses STDIN and
STDOUT and will not work if the no_client_stdout flag is set.
This is the main method to override.
The default method implements a simple echo server that will repeat
whatever is sent. It will quit the child if "quit" is sent, and
will exit the server if "exit" is sent.
"$self->post_process_request"
This method is used to clean up the client connection and to handle
any parent/child accounting for the forking servers.
HOOKS
"Net::Server" provides a number of "hooks" allowing for servers layered
on top of "Net::Server" to respond at different levels of execution
without having to "SUPER" class the main built-in methods. The place-
ment of the hooks can be seen in the PROCESS FLOW section.
"$self->configure_hook()"
This hook takes place immediately after the "->run()" method is
called. This hook allows for setting up the object before any
built in configuration takes place. This allows for custom config-
urability.
"$self->post_configure_hook()"
This hook occurs just after the reading of configuration parameters
and initiation of logging and pid_file creation. It also occurs
before the "->pre_bind()" and "->bind()" methods are called. This
hook allows for verifying configuration parameters.
"$self->post_bind_hook()"
This hook occurs just after the bind process and just before any
chrooting, change of user, or change of group occurs. At this
point the process will still be running as the user who started the
server.
"$self->pre_loop_hook()"
This hook occurs after chroot, change of user, and change of group
has occured. It allows for preparation before looping begins.
"$self->can_read_hook()"
This hook occurs after a socket becomes readible on an
accept_multi_port request (accept_multi_port is used if there are
multiple bound ports to accept on, or if the "multi_port" configu-
ration parameter is set to true). This hook is intended to allow
for processing of arbitrary handles added to the IO::Select used
for the accept_multi_port. These handles could be added during the
post_bind_hook. No internal support is added for processing these
handles or adding them to the IO::Socket. Care must be used in how
much occurs during the can_read_hook as a long response time will
result in the server being susceptible to DOS attacks. A return
value of true indicates that the Server should not pass the readi-
ble handle on to the post_accept and process_request phases.
It is generally suggested that other avenues be pursued for sending
messages via sockets not created by the Net::Server.
"$self->post_accept_hook()"
This hook occurs after a client has connected to the server. At
this point STDIN and STDOUT are mapped to the client socket. This
hook occurs before the processing of the request.
"$self->allow_deny_hook()"
This hook allows for the checking of ip and host information beyond
the "$self->allow_deny()" routine. If this hook returns 1, the
client request will be processed, otherwise, the request will be
denied processing.
"$self->request_denied_hook()"
This hook occurs if either the "$self->allow_deny()" or
"$self->allow_deny_hook()" have taken place.
"$self->post_process_request_hook()"
This hook occurs after the processing of the request, but before
the client connection has been closed.
"$self->pre_server_close_hook()"
This hook occurs before the server begins shutting down.
"$self->write_to_log_hook"
This hook handles writing to log files. The default hook is to
write to STDERR, or to the filename contained in the parameter
"log_file". The arguments passed are a log level of 0 to 4 (4
being very verbose), and a log line. If log_file is equal to
"Sys::Syslog", then logging will go to Sys::Syslog and will bypass
the write_to_log_hook.
"$self->fatal_hook"
This hook occurs when the server has encountered an unrecoverable
error. Arguments passed are the error message, the package, file,
and line number. The hook may close the server, but it is sug-
gested that it simply return and use the built in shut down fea-
tures.
"$self->post_child_cleanup_hook"
This hook occurs in the parent server process after all children
have been shut down and just before the server either restarts or
exits. It is intended for additional cleanup of information. At
this point pid_files and lockfiles still exist.
"$self->restart_open_hook"
This hook occurs if a server has been HUPed (restarted via the HUP
signal. It occurs just before reopening to the filenos of the
sockets that were already opened.
"$self->restart_close_hook"
This hook occurs if a server has been HUPed (restarted via the HUP
signal. It occurs just before restarting the server via exec.
OTHER METHODS
"$self->default_values"
Allow for returning configuration values that will be used if no
other value could be found.
Should return a hashref.
sub default_values {
return {
port => 20201,
};
}
"$self->new"
As of Net::Server 0.91 there is finally a new method. This method
takes a class name and an argument hashref as parameters. The
argument hashref becomes the "server" property of the object.
package MyPackage;
use base qw(Net::Server);
my $obj = MyPackage->new({port => 20201});
# same as
my $obj = bless {server => {port => 20201}}, 'MyPackage';
"$self->log"
Parameters are a log_level and a message.
If log_level is set to 'Sys::Syslog', the parameters may alter-
nately be a log_level, a format string, and format string parame-
ters. (The second parameter is assumed to be a format string if
additional arguments are passed along). Passing arbitrary format
strings to Sys::Syslog will allow the server to be vulnerable to
exploit. The server maintainer should make sure that any string
treated as a format string is controlled.
# assuming log_file = 'Sys::Syslog'
$self->log(1, "My Message with %s in it");
# sends "%s", "My Message with %s in it" to syslog
$self->log(1, "My Message with %s in it", "Foo");
# sends "My Message with %s in it", "Foo" to syslog
If log_file is set to a file (other than Sys::Syslog), the message
will be appended to the log file by calling the write_to_log_hook.
"$self->shutdown_sockets"
This method will close any remaining open sockets. This is called
at the end of the server_close method.
RESTARTING
Each of the server personalities (except for INET), support restarting
via a HUP signal (see "kill -l"). When a HUP is received, the server
will close children (if any), make sure that sockets are left open, and
re-exec using the same commandline parameters that initially started
the server. (Note: for this reason it is important that @ARGV is not
modified until "->run" is called).
The Net::Server will attempt to find out the commandline used for
starting the program. The attempt is made before any configuration
files or other arguments are processed. The outcome of this attempt is
stored using the method "->commandline". The stored commandline may
also be retrieved using the same method name. The stored contents will
undoubtedly contain Tainted items that will cause the server to die
during a restart when using the -T flag (Taint mode). As it is impos-
sible to arbitrarily decide what is taint safe and what is not, the
individual program must clean up the tainted items before doing a
restart.
sub configure_hook{
my $self = shift;
### see the contents
my $ref = $self->commandline;
use Data::Dumper;
print Dumper $ref;
### arbitrary untainting - VERY dangerous
my @untainted = map {/(.+)/;$1} @$ref;
$self->commandline(\@untainted)
}
FILES
The following files are installed as part of this
distribution.
Net/Server.pm
Net/Server/Fork.pm
Net/Server/INET.pm
Net/Server/MultiType.pm
Net/Server/PreForkSimple.pm
Net/Server/PreFork.pm
Net/Server/Single.pm
Net/Server/Daemonize.pm
Net/Server/SIG.pm
Net/Server/Proto.pm
Net/Server/Proto/*.pm
INSTALL
Download and extract tarball before running these commands in its base
directory:
perl Makefile.PL
make
make test
make install
AUTHOR
Paul T. Seamons <paul at seamons.com>
THANKS
Thanks to Rob Brown (bbb at cpan.org) for help with miscellaneous con-
cepts such as tracking down the serialized select via flock ala Apache
and the reference to IO::Select making multiport servers possible. And
for researching into allowing sockets to remain open upon exec (making
HUP possible). Rob Brown is also the maintainer for Net::Server.
Thanks to Jonathan J. Miner <miner at doit.wisc.edu> for patching a
blatant problem in the reverse lookups.
Thanks to Bennett Todd <bet at rahul.net> for pointing out a problem in
Solaris 2.5.1 which does not allow multiple children to accept on the
same port at the same time. Also for showing some sample code from
Viktor Duchovni which now represents the semaphore option of the seri-
alize argument in the PreFork server.
Thanks to traveler and merlyn from http://perlmonks.org for pointing me
in the right direction for determining the protocol used on a socket
connection.
Thanks to Jeremy Howard <j+daemonize at howard.fm> for numerous sugges-
tions and for work on Net::Server::Daemonize.
Thanks to Vadim <vadim at hardison.net> for patches to implement par-
ent/child communication on PreFork.pm.
Thanks to Carl Lewis for suggesting "-" in user names.
Thanks to Slaven Rezic for suggesing Reuse => 1 in Proto::UDP.
Thanks to Tim Watt for adding udp_broadcast to Proto::UDP.
Thanks to Christopher A Bongaarts for pointing out problems with the
Proto::SSL implementation that currently locks around the socket accept
and the SSL negotiation. See Net::Server::Proto::SSL.
Thanks to Alessandro Zummo for pointing out various bugs including some
in configuration, commandline args, and cidr_allow.
Thanks to various other people for bug fixes over the years. These and
future thank-you's are available in the Changes file as well as CVS
comments.
Thanks to Ben Cohen and tye (on Permonks) for finding and diagnosing
more correct behavior for dealing with re-opening STDIN and STDOUT on
the client handles.
Thanks to Mark Martinec for trouble shooting other problems with STDIN
and STDOUT (he proposed having a flag that is now the no_client_stdout
flag).
Thanks to David (DSCHWEI) on cpan for asking for the nofatal option
with syslog.
Thanks to Andreas Kippnick and Peter Beckman for suggesting leaving
open child connections open during a HUP (this is now available via the
leave_children_open_on_hup flag).
Thanks to LUPE on cpan for helping patch HUP with taint on.
Thanks to Michael Virnstein for fixing a bug in the check_for_dead sec-
tion of PreFork server.
SEE ALSO
Please see also Net::Server::Fork, Net::Server::INET, Net::Server::Pre-
ForkSimple, Net::Server::PreFork, Net::Server::MultiType,
Net::Server::Single
AUTHOR
Paul Seamons <paul AT seamons.com>
http://seamons.com/
Rob Brown <bbb AT cpan.org>
LICENSE
This package may be distributed under the terms of either the
GNU General Public License
or the
Perl Artistic License
All rights reserved.
perl v5.8.8 2005-06-20 Net::Server(3pm)
Linux-Distributionen
Huschi als Linux-Admin