.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ePerl 3pm"
.TH ePerl 3pm 2024-03-07 "perl v5.38.2" "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
Apache::ePerl \- Fast emulated Embedded Perl (ePerl) facility
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\& # Apache\*(Aqs httpd.conf file
\& # mandatory: activation of Apache::ePerl
\& PerlModule Apache::ePerl
\&
\&
\& Options +ExecCGI
\& SetHandler perl\-script
\& PerlHandler Apache::ePerl
\&
\&
\& # optional: configuration of Apache::ePerl
\&
\& $Apache::ePerl::Config\->{\*(AqBeginDelimiter\*(Aq} = \*(Aq\*(Aq;
\& $Apache::ePerl::Config\->{\*(AqEndDelimiter\*(Aq} = \*(Aq!>\*(Aq;
\& $Apache::ePerl::Config\->{\*(AqCaseDelimiters\*(Aq} = 0;
\& $Apache::ePerl::Config\->{\*(AqConvertEntities\*(Aq} = 1;
\&
\& # optional: activation of Apache::Status for Apache::ePerl
\&
\& Options +ExecCGI
\& SetHandler perl\-script
\& PerlHandler Apache::Status
\&
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
These packages provides a handler function for Apache/mod_perl which can be
used to emulate the stand-alone Server-Side-Scripting-Language \fIePerl\fR (see
\&\fBeperl\fR\|(3) for more details) in a very fast way. This is not a real 100%
replacement for \fInph-eperl\fR because of reduced functionality under some
special cases, principal runtime restrictions and speedup decisions. For
instance this variant does not (and cannot) provide the SetUID feature of
ePerl nor does it check for allowed filename extensions (speedup!), etc.
Instead it uses further features like object caching which ePerl does not use.
.PP
But the accepted bristled source file format is exactly the same as with the
regular ePerl facility, because Apache::ePerl uses the Parse::ePerl package
which provides the original ePerl parser and translator. So, any valid ePerl
which works under \fInph-eperl\fR can also be used under Apache::ePerl.
.PP
The intent is to use this special variant of ePerl for scripts which are
directly under control of the webmaster. In this situation no real security
problems exists for him, because all risk is at his own hands. For the average
user you should \fBnot\fR use Apache::ePerl. Instead additionally install the
regular stand-alone ePerl facility (\fInph-eperl\fR) for those users.
.PP
So, the advantage of Apache::ePerl against the regular \fInph-eperl\fR is better
performance and nothing else. Actually scripts executed under Apache::ePerl
are at least twice as fast as under \fInph-eperl\fR. The reason its not that
ePerl itself is faster. The reason is the runtime in-core environment of
Apache/mod_perl which does not have any forking overhead.
.SS "Installation and Configuration"
.IX Subsection "Installation and Configuration"
First you have to install Apache::ePerl so that Apache/mod_perl can find it.
This is usually done via configuring the ePerl distribution via the same Perl
interpreter as was used when building Apache/mod_perl.
.PP
Second, you have to add the following config snippet to Apache's \fIhttpd.conf\fR
file:
.PP
.Vb 8
\& PerlModule Apache::ePerl
\&
\&
\& Options +ExecCGI
\& SetHandler perl\-script
\& PerlHandler Apache::ePerl
\&
\&
.Ve
.PP
This forces all files under the directory /root/of/webmaster/area/ with
extension .iphtml to be processed by the Apache::ePerl::handler function which
emulates the runtime behavior of the stand-alone "eperl" program (when run as
a SSSL) up to 90%.
.PP
If you're not paranoid about security (for instance driving a stand-alone
webserver without user accounts) you can also just use
.PP
.Vb 5
\& PerlModule Apache::ePerl
\&
\& SetHandler perl\-script
\& PerlHandler Apache::ePerl
\&
.Ve
.PP
which enables .iphtml files everywhere.
.PP
Third, when you want to change the defaults of the ePerl parser, you also can
add something like this to the end of the snippet above.
.PP
.Vb 6
\&
\& $Apache::ePerl::Config\->{\*(AqBeginDelimiter\*(Aq} = \*(Aq\*(Aq;
\& $Apache::ePerl::Config\->{\*(AqEndDelimiter\*(Aq} = \*(Aq!>\*(Aq;
\& $Apache::ePerl::Config\->{\*(AqCaseDelimiters\*(Aq} = 0;
\& $Apache::ePerl::Config\->{\*(AqConvertEntities\*(Aq} = 1;
\&
.Ve
.PP
Fourth, you can additionally enable the mod_perl runtime status which then
automatically enables an Apache::ePerl status handler:
.PP
.Vb 5
\&
\& Options +ExecCGI
\& SetHandler perl\-script
\& PerlHandler Apache::Status
\&
.Ve
.PP
This enables the URL \f(CW\*(C`/perl\-status\*(C'\fR in general and the URL
\&\f(CW\*(C`/perl\-status?ePerl\*(C'\fR in special. Use it to see how much scripts where run and
how much are still cached.
.SH AUTHOR
.IX Header "AUTHOR"
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve
.SH HISTORY
.IX Header "HISTORY"
Apache::ePerl was first implemented by Mark Imbriaco
in December 1996 as a plain Perl module after he has seen the original ePerl
from Ralf S. Engelschall. It implemented the ePerl idea, but was not
compatible to the original ePerl. In May 1997 Hanno Mueller
has taken over the maintenance from Mark I. and
enhanced Apache::ePerl by adding caching for P\-Code, adding the missing
\&\f(CW\*(C`chdir\*(C'\fR stuff, etc.
.PP
Nearly at the same time Ralf S. Engelschall was unhappy of the old
Apache::ePerl from Mark I. and already started to write this version (the one
you are current reading its POD). He has rewritten the complete module from
scratch, but incorporated the P\-Code caching idea and the Apache::Status usage
from Hanno M.'s version. The big difference between this one and Mark I.'s or
Hanno M.'s versions are that this version makes use of the new Parse::ePerl
module which itself incorporates the original ePerl parser. So this version
is more compliant to the original ePerl facility.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBParse::ePerl\fR\|(3)
.PP
Web-References:
.PP
.Vb 4
\& Perl: perl(1), http://www.perl.com/
\& ePerl: eperl(1), http://www.engelschall.com/sw/eperl/
\& mod_perl: mod_perl(1), http://perl.apache.org/
\& Apache: httpd(7), http://www.apache.org/
.Ve