NAME
HTTP::Server::Simple::CGI::PreFork - Turn HSS into a preforking webserver and enable SSL
SYNOPSIS
Are you using HTTP::Server::Simple::CGI (or are you planning to)? But you want to handle multiple connections at once and even try out this SSL thingy everyone is using these days?
Fear not, the (brilliant) HTTP::Server::Simple::CGI is easy to extend and this (only modestly well-designed) module does it for you.
HTTP::Server::Simple::CGI::PreFork should be fully IPv6 compliant.
DESCRIPTION
This module is a plugin module for the "Commands" module and handles PostgreSQL admin commands scheduled from the WebGUI.
Configuration
Obviously, you want to read the HTTP::Server::Simple documentation for the bulk of configuration options. Since we also overload the base tcp connection class with Net::Server, you might also want to read the documentation for that.
We use two Net::Server classes, depending on if we are preforking or single threaded:
Net::Server::Single for singlethreaded
Net::Server::PreFork for multithreaded
In addition to the HTTP::Server::Simple configuration, there are only two additional options (in the hash to) the run() method: usessl and prefork.
prefork
Basic usage:
$myserver->run(prefork => 1):
Per default, prefork is turned off (e.g. server runs singlethreaded). This is very usefull for debugging and backward compatibility.
Beware when forking: Keep in mind how database and filehandles behave. Normally, you should set up everything before the run method (cache files, load confiugurations,...), then close all handles and run(). Then, depending on your site setup, either open a database connection for every request and close it again, or (and this is the better performing option) open a database handle at every request you don't have an open handle yet - since we are forking, every thread get's its own unique handle while not constantly opening and closing the handles.
Optionally, you can also add all the different options of Net::Server::Prefork like "max_servers" on the call to run() to optimize your configuration.
usessl
Caution: SSL support is experimental at best. I got this to work with a lot of warnings, sometimes it might not work at all. If you use this, please send patches!
Set this option to 1 if you want to use SSL (default is off). For SSL to actually work, need to add some extra options (required for the underlying Net::Server classes, something like this usually does the trick:
$webserver->run(usessl => 1, proto => 'ssleay', "--SSL_key_file"=> 'mysite.key', "--SSL_cert_file"=>'mysite.crt', );
run
Internal functions that overrides the HTTP::Server::Simple::CGI run function. Just as explained above.
handle_continue_header
Overrideable function that allows to to custom-handle the "100 Continue" status codes. This function is called if the client sends a a "Expect: 100-continue" header. It defaults to sending a "100 Continue" status line and proceed with the rest of the request.
If you want to override this, for example to check upload size or permissions, subclass this function. You will recieve the headers as a hash as the only input (nothing much else has been parsed from the client as of this moment in time).
It is your job to send/print the appropriate status line header, either "100 Continue" or the appropriate error code. Return true if you want HSS::Prefork to continue data transfer and finish setting up the CGI environment for the request or false to abort.
BEWARE: Since only the headers have been parsed at this point of time, you don't have the full CGI kaboodle at your disposal. The way HSS:Prefork overrides the base modules, the internal setup phase is not complete and you should only use the headers provided to make a basic decision if you want to continue and make a full check later (permissions, client IP, whatever) on, just as you would when the client wouldn't have send the Expect-Header
IPv6
This module overrides also the pure IPv4 handling of HTTP::Server::Simple::CGI and turns it into an IPv4/IPv6 multimode server.
Only caveat here is, that you need the Net::Server modules in version 2.0 or higher. If you still use Net::Server 0.99.6.*, you should install HTTP::Server::Simple::CGI::PreFork 1.2 from BackPan.
Net::Server version 0.99 and lower only supports IPv4.
Possible incompatibilities with your computer
Older versions of HSSC::Prefork did not automatically require the IPv6 modules on installation. This behaviour has changed, starting at version 2.0. This is in accordance with with RFC6540, titled "IPv6 Support Required for All IP-Capable Nodes". If you don't have an IPv6 address, thats OK (or more precisely *your* problem). But the software now assumes that your system is technicaly capable of handling IPv6 connections, even if you don't have an IPv6 uplink at the moment.
Doing it this way simplifies many future tasks. Anyway, if your system is old enough to be incapable of handling IPv6... according to RFC6540 you are not connected to what is nowadays defined as "the internet".
QUICK-HACK-WARNING
This module "patches" HTTP::Server::Simple by overloading one of the functions. Updating HTTP::Server::Simple *might* break something. While this is not very likely, make sure to test updates before updating a production system!
AUTHOR
Rene Schickbauer, <cavac@cpan.org>
This module borrows heavily from the follfowing modules:
HTTP::Server::Simple by Jesse Vincent
Net::Server by Paul T. Seamons
HTTPS bugfix for version 6 by Luigi Iotti
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
THANKS
Special thanks to Jesse Vincent for giving me quick feedback when i needed it.
Also thanks to the countless PerlMonks helping me out when i'm stuck. This module is dedicated to you!