ePerl(3pm)

📦
version 2.2.14 · 3 versions
, in ubuntu jammy

🎀 ePerl — like, the whole vibe 🎀

okay so this is the manual page for ePerl, from the User Contributed Perl Documentation (that's the 3pm section bestie, Perl module territory 💅). Real name of the thing? Apache::ePerl. Sit down, grab a strawberry, we're doing this.

✨ NAME ✨

Apache::ePerl — Fast emulated Embedded Perl (ePerl) facility 🦋

✨ SYNOPSIS ✨

so here's the whole setup, in its natural habitat (Apache's httpd.conf):

#   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>

like, that's it. that's the whole vibe check. now let's get into why. 👑

✨ DESCRIPTION ✨

so these packages hand you a handler function for Apache/mod_perl that emulates the stand-alone Server-Side-Scripting-Language ePerl (peep eperl(3) for the full lore) but in a very fast way. it is not a real 100% replacement for nph-eperl tho, 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, and it also does not check for allowed filename extensions (speedup! ⚡). instead it uses further features like object caching, which ePerl does not use. different beast, same soul.

but here's the slay: 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 that works under nph-eperl can also be used under Apache::ePerl. no cap. 🔥

the intent is to use this special variant of ePerl for scripts which are directly under control of the webmaster. in that situation no real security problems exist 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.

⚠️ bestie read this twice: Apache::ePerl is for the webmaster's own scripts only. for regular users, install nph-eperl instead. the risk is literally all on the webmaster's own head.

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. and the reason is 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. no fork, no drama, just vibes. 💫

🌸 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. (yes, same one. don't be messy about it. 🙈)

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%. ninety percent, iconic behavior honestly. 💅

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. 🌈 (yes, everywhere. just saying. that's the trade.)

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 ✨

okay storytime, because this module has lore. 📖✨

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, hi bestie 👋). 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. glow up complete. 💖

✨ SEE ALSO ✨

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/

okay that's the whole page, you ate it, you read it, you understand it. 🫶 this little treasure came to you courtesy of perl v5.34.0, dated 2022-02-06 — so like, vintage in a cute way. go forth and emulate embedded Perl at twice the speed, bestie. 🌸💜⭐

📦 where this page comes from