NAME

       Apache::ePerl - Fast emulated Embedded Perl (ePerl) facility

SYNOPSIS

          #   Apache's httpd.conf file
          #   mandatory: activation of Apache::ePerl
          PerlModule Apache::ePerl
          <Directory /root/of/webmaster/area>
              <Files *.iphtml>
                  Options     +ExecCGI
                  SetHandler  perl-script
                  PerlHandler Apache::ePerl
              </Files>
          </Directory>
          #   optional: configuration of Apache::ePerl
          <Perl>
          $Apache::ePerl::Config->{'BeginDelimiter'}  = '<?';
          $Apache::ePerl::Config->{'EndDelimiter'}    = '!>';
          $Apache::ePerl::Config->{'CaseDelimiters'}  = 0;
          $Apache::ePerl::Config->{'ConvertEntities'} = 1;
          </Perl>
          #   optional: activation of Apache::Status for Apache::ePerl
          <Location /perl-status>
              Options     +ExecCGI
              SetHandler  perl-script
              PerlHandler Apache::Status
          </Location>

DESCRIPTION

       These packages provides a handler function for Apache/mod_perl which can be used to
       emulate the stand-alone Server-Side-Scripting-Language ePerl (see eperl(3) for more
       details) in a very fast way. This is not a real 100% replacement for nph-eperl 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.

       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 nph-eperl can also be
       used under Apache::ePerl.

       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 not use
       Apache::ePerl. Instead additionally install the regular stand-alone ePerl facility (nph-
       eperl) for those users.

       So, the advantage of Apache::ePerl against the regular nph-eperl is better performance and
       nothing else. Actually scripts executed under Apache::ePerl are at least twice as fast as
       under nph-eperl. 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.

   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.

       Second, you have to add the following config snippet to Apache's httpd.conf file:

          PerlModule Apache::ePerl
          <Directory /root/of/webmaster/area>
              <Files *.iphtml>
                  Options     +ExecCGI
                  SetHandler  perl-script
                  PerlHandler Apache::ePerl
              </Files>
          </Directory>

       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%.

       If you're not paranoid about security (for instance driving a stand-alone webserver
       without user accounts) you can also just use

          PerlModule Apache::ePerl
          <Files *.iphtml>
              SetHandler  perl-script
              PerlHandler Apache::ePerl
          </Files>

       which enables .iphtml files everywhere.

       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.

          <Perl>
          $Apache::ePerl::Config->{'BeginDelimiter'}  = '<?';
          $Apache::ePerl::Config->{'EndDelimiter'}    = '!>';
          $Apache::ePerl::Config->{'CaseDelimiters'}  = 0;
          $Apache::ePerl::Config->{'ConvertEntities'} = 1;
          </Perl>

       Fourth, you can additionally enable the mod_perl runtime status which then automatically
       enables an Apache::ePerl status handler:

          <Location /perl-status>
              Options     +ExecCGI
              SetHandler  perl-script
              PerlHandler Apache::Status
          </Location>

       This enables the URL "/perl-status" in general and the URL "/perl-status?ePerl" in
       special. Use it to see how much scripts where run and how much are still cached.

AUTHOR

        Ralf S. Engelschall
        rse@engelschall.com
        www.engelschall.com

HISTORY

       Apache::ePerl was first implemented by Mark Imbriaco <mark@itribe.net> 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 <hmueller@kabel.de> has taken over the maintenance from Mark I. and enhanced
       Apache::ePerl by adding caching for P-Code, adding the missing "chdir" stuff, etc.

       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.

SEE ALSO

       Parse::ePerl(3)

       Web-References:

         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/