.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTTP::Server::Simple::CGI::PreFork 3pm"
.TH HTTP::Server::Simple::CGI::PreFork 3pm "2017-01-27" "perl v5.24.1" "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"
HTTP::Server::Simple::CGI::PreFork \- Turn HSS into a preforking webserver and enable SSL
.SH "SYNOPSIS"
.IX Header "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 \s-1SSL\s0 thingy everyone is using these days?
.PP
Fear not, the (brilliant) HTTP::Server::Simple::CGI is easy to extend and this (only modestly well-designed)
module does it for you.
.PP
HTTP::Server::Simple::CGI::PreFork should be fully IPv6 compliant.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a plugin module for the \*(L"Commands\*(R" module and handles
PostgreSQL admin commands scheduled from the WebGUI.
.SH "Configuration"
.IX Header "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.
.PP
We use two Net::Server classes, depending on if we are preforking or single
threaded:
.PP
Net::Server::Single for singlethreaded
.PP
Net::Server::PreFork for multithreaded
.PP
In addition to the HTTP::Server::Simple configuration,
there are only two additional options (in the hash to) the
\&\fIrun()\fR method: usessl and prefork.
.SS "prefork"
.IX Subsection "prefork"
Basic usage:
.PP
\&\f(CW$myserver\fR\->run(prefork => 1):
.PP
Per default, prefork is turned off (e.g. server runs singlethreaded). This
is very useful for debugging and backward compatibility.
.PP
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 \fIrun()\fR. 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.
.PP
Optionally, you can also add all the different options of Net::Server::Prefork like \*(L"max_servers\*(R" on
the call to \fIrun()\fR to optimize your configuration.
.SS "usessl"
.IX Subsection "usessl"
Caution: \s-1SSL\s0 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!
.PP
Set this option to 1 if you want to use \s-1SSL \s0(default is off). For \s-1SSL\s0 to actually work, need
to add some extra options (required for the underlying Net::Server classes, something like this
usually does the trick:
.PP
\&\f(CW$webserver\fR\->run(usessl => 1,
                proto => 'ssleay',
                \*(L"\-\-SSL_key_file\*(R"=> 'mysite.key',
                \*(L"\-\-SSL_cert_file\*(R"=>'mysite.crt',
                );
.SS "run"
.IX Subsection "run"
Internal functions that overrides the HTTP::Server::Simple::CGI run function. Just as explained above.
.SS "handle_continue_header"
.IX Subsection "handle_continue_header"
Overrideable function that allows one to custom-handle the \*(L"100 Continue\*(R" status codes. This function
is called if the client sends a a \*(L"Expect: 100\-continue\*(R" header. It defaults to sending a \*(L"100 Continue\*(R"
status line and proceed with the rest of the request.
.PP
If you want to override this, for example to check upload size or permissions, subclass this function. You
will receive the headers as a hash as the only input (nothing much else has been parsed from the client as of
this moment in time).
.PP
It is your job to send/print the appropriate status line header, either \*(L"100 Continue\*(R" or the appropriate error code.
Return true if you want HSS::Prefork to continue data transfer and finish setting up the \s-1CGI\s0 environment for the request
or false to abort.
.PP
\&\s-1BEWARE:\s0 Since only the headers have been parsed at this point of time, you don't have the full \s-1CGI\s0 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 \s-1IP,\s0 whatever) on,
just as you would when the client wouldn't have send the Expect-Header
.SH "IPv6"
.IX Header "IPv6"
This module overrides also the pure IPv4 handling of HTTP::Server::Simple::CGI and turns
it into an IPv4/IPv6 multimode server.
.PP
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.
.PP
Net::Server version 0.99 and lower only supports IPv4.
.SH "Possible incompatibilities with your computer"
.IX Header "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 \s-1RFC6540,\s0 titled
\&\*(L"IPv6 Support Required for All IP-Capable Nodes\*(R". If you don't have an IPv6 address, that's \s-1OK \s0(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.
.PP
Doing it this way simplifies many future tasks. Anyway, if your system is old enough to be incapable of
handling IPv6... according to \s-1RFC6540\s0 you are not connected to what is nowadays defined as \*(L"the internet\*(R".
.SH "QUICK-HACK-WARNING"
.IX Header "QUICK-HACK-WARNING"
This module \*(L"patches\*(R" 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!
.SH "AUTHOR"
.IX Header "AUTHOR"
Rene Schickbauer, <cavac@cpan.org>
.PP
This module borrows heavily from the follfowing modules:
.PP
HTTP::Server::Simple by Jesse Vincent
.PP
Net::Server by Paul T. Seamons
.PP
\&\s-1HTTPS\s0 bugfix for version 6 by Luigi Iotti
.SH "LICENSE"
.IX Header "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.
.SH "THANKS"
.IX Header "THANKS"
Special thanks to Jesse Vincent for giving me quick feedback when i needed it.
.PP
Also thanks to the countless PerlMonks helping me out when i'm stuck. This module
is dedicated to you!