ModPerlEngineContrib < System

See New TB Image Gallery

You are here: Iris Wiki>System Web>ModPerlEngineContrib (11 Aug 2023, TimValenzuela) (raw view)Edit Attach
---+!! !ModPerlEngineContrib
%FORMFIELD{"Description"}%

%TOC%

---++ Overview

This is a runtime engine component from [[Foswiki:Development.FoswikiStandAlone][Foswiki Standalone]] architecture.

[[http://en.wikipedia.org/wiki/Mod_perl][mod_perl]] is the
[[http://perl.apache.org/][Perl API]] to the
[[http://httpd.apache.org/][Apache]] web server. It permits hooking applications
into Apache, providing good performance and great flexibility.

It has better performance than
[[http://en.wikipedia.org/wiki/Common_Gateway_Interface][CGI]] because it loads
and compiles apps at Apache initialization and apps are kept in memory as long
as Apache itself, so there is no need to fork+load+compile all the code for
each request.

---++ Installation Instructions


%T% As of Foswiki 2.0, !ModPerlEngineContrib is installed by default. <button class="twistyExpandAll foswikiButton">Show all Foswiki 1.x instructions</button> 

%TWISTY{ start="hide" showlink="Show Foswiki 1.x details"}%
<div class="foswikiHelp">
*This block of instructions is only needed on Foswiki 1.x systems.*

Install [[Foswiki:Extensions/ModPerlEngineContrib][ModPerlEngineContrib]]
either manually (download the package and extract its contents over your
foswiki directory) or using [[%SCRIPTURL{"configure"}%][configure]]
(under =Extensions= section, push the =Find More Extensions= button).

%X% Foswiki 1.x installations *must* be configured before mod_perl is enabled
in Apache. Run [[%SCRIPTURL{"configure"}%][configure]] *before* enabling mod_perl in Apache. 
or else Apache will not start, reporting an error about a missing
=lib/LocalSite.cfg=.  You will need to:
   1 Configure apache with standard CGI
   1 Configure Foswiki using =bin/configure=
   1 Re-configure Apache with =mod_perl= active.
</div>
%ENDTWISTY{}%

Visit the [[Foswiki:Support/ApacheConfigGenerator][apache config generator]]
and fill in the fields according to your environment. Select __mod_perl__ as your
__Runtime Engine__ and choose your apache version. Push the ==Update config file== 
button and you'll get your config file.

In the web server configuration, you will need to load =mod_perl= but it is also recommended to load the
[[http://httpd.apache.org/apreq/][Apache HTTP Request Library]] (module apreq).
If =apreq= is not loaded, the following error may be encountered in certain situations, e.g., during login:
<verbatim>
apache2: symbol lookup error: /usr/lib/perl5/auto/APR/Request/Apache2/Apache2.so: undefined symbol: apreq_handle_apache2
</verbatim>

---+++ Confirming =mod_perl= installation

On Foswiki 2.0 systems. visit System.FoswikiServerInformation.   Look for the
=Engine= entry in the =General execution environment= table.

%TWISTY{start="hide" showlink="Show Foswiki 1.x details"}%
On Foswiki 1.x systems. you may (though not necessarily) be able to confirm that =mod_perl= is installed and enabled by checking
in configure's "Environment Variables" section.  a sample:

| SERVER_SIGNATURE | Apache/2.2.9 (Debian) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0 Server at 127.0.0.1 Port 2116 |
| SERVER_SOFTWARE | Apache/2.2.9 (Debian) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0 |
%ENDTWISTY{}%

Another technique to see which modules are enabled is using =apache2ctl=
<verbatim>
$ apache2ctl -M | grep perl_module
 perl_module (shared)
</verbatim>
If not found, enable mod_perl with 
<verbatim>
$ a2enmod mod_perl
</verbatim>

---+++ Foswiki configuration tuning

Forking new processes under =mod_perl= can be very slow, so some configuration
changes are recommended.

Access the [[%SCRIPTURL{"configure"}%][configure]] script. (On Foswiki 1.x, you will need to click the =Yes, I've read all the documentation=
button to show the expert settings.)
Go to =Store Settings=:
   * =Store Implementation=: If using RCS, adjust to =RcsLite=.  (If using the !PlainFile store, no change is needed.)
   * =Search Algorithm=: use =Foswiki::Store::SearchAlgorithms::PurePerl= or Foswiki:Extensions/NativeSearchContrib

---+++ =mod_perl= configuration tuning

=mod_perl= limits the size of attachments to 64M by default.  Set the
=APREQ2_ReadLimit= to the maximum expected upload to permit larger
attachments.

Note that this should be kept in sync with the Foswiki =ATTACHFILESIZELIMIT=,
set in %USERSWEB%.SitePreferences, default taken from
%SYSTEMWEB%.SitePreferences.
<verbatim>
<IfModule mod_perl.c>
   PerlSwitches -wT    # DO NOT USE THIS with Foswiki 2.0
   # mod_perl_startup.pl must exist, otherwise Apache will not start.
   PerlRequire "/var/www/foswiki/tools/mod_perl_startup.pl"
   APREQ2_ReadLimit  104857600
</IfModule>
</verbatim>

---++ Known Issues

   * You must ==restart== Apache in order for configuration changes take effect.

%TWISTY{start="hide" showlink="Show Foswiki 1.x details"}%
   * The =bin/configure= script is an exception and should be run as a plain 
   CGI script.  The required =SetHandler cgi-script= should already be specified
   in the =<Files configure.*>= in your Apache config or =bin/.htaccess= file.
<verbatim>
   <FilesMatch "configure.*">
      SetHandler cgi-script
      .
      .
   </FilesMatch>
</verbatim>
%ENDTWISTY{}%
   * If you are using some extension that add files to the =bin/= 
   directory, you may face problems as they were not designed to be executed 
   under =mod_perl=.  You should configure them to be run as plain CGI scripts.
   You can replace =Files= directive by
   [[http://httpd.apache.org/docs/2.2/mod/core.html#filesmatch][FilesMatch]] 
   and list all the exceptions.
<verbatim>
   <FilesMatch "[script name needing CGI].*">
      SetHandler cgi-script
      .
      .
   </FilesMatch>
</verbatim>

---++ List of Files

   | *File* | *Description* |
   | ==data/System/ModPerlEngineContrib.txt== | Documentation |
   | ==lib/Foswiki/Contrib/ModPerlEngineContrib/DEPENDENCIES== |  |
   | ==lib/Foswiki/Contrib/ModPerlEngineContrib.pm== | Perl module |
   | ==lib/Foswiki/Engine/Apache.pm== | Perl module |
   | ==lib/Foswiki/Engine/Apache/MP13.pm== | Perl module |
   | ==lib/Foswiki/Engine/Apache2.pm== | Perl module |
   | ==lib/Foswiki/Engine/Apache2/MP20.pm== | Perl module |
   | ==tools/mod_perl_startup.pl== | Perl script |


---++ Dependencies
<table border="1" class="foswikiTable"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">mod_perl2</td><td align="left">&gt;=2.0</td><td align="left">Optional, but required if you're using Apache 2.x and plan to enable mod_perl</td></tr><tr><td align="left">Apache2::Request</td><td align="left">&gt;=2.0</td><td align="left">Optional, but recommended if you're using Apache 2.x and plan to enable mod_perl</td></tr></table>

---++ Change History

%TABLE{columnwidths="7em" tablewidth="100%"}%
|  06 Aug 2023 (1.08) | Foswikitask:Item15151: add warnings and strictness |
|  08 Dec 2017 (1.06) | Foswikitask:Item14544: SCRIPTURL breaks when X-FORWARDED-HOST has multiple values (partial fix). | 
|  30 Apr 2017 (1.05) | Foswikitask:Item14381: Preserver URL Encoding of the Foswiki URI. |
|  26 Nov 2016 (1.04) | Released with Foswiki 2.1.3. Old Apache 1.x modules have been removed from the DEPENDENCIES file. |
|  08 Apr 2016 (1.03) | Foswikitask:Item14022 Change foswiki.org links to https. |
|  16 Jan 2016 (1.02) | Foswikitask:Item13926 Fix backwards compatibility with Foswiki 1.1. |
|  20 Oct 2015 (1.01) | Released with Foswiki 2.0.3.<br />\
                        Foswikitask:Item13830: Unable to upload utf-8 filenames as attachments. |
|  14 Jun 2015 (1.00) | Released with Foswiki 2.0.<br />\
                        Foswikitask:Item13378: Foswikitask:Item13405: Update for UNICODE core<br />\
                        Foswikitask:Item13228: Fix JSON operation with ApacheRequest2<br />\
                        Foswikitask:Item13125: CGI updates<br />\
                        Foswikitask:Item13225: Fix compatibility with Apache 2.4<br />\
                        Foswikitask:Item13052: Documentation improvements for APREQ2_ReadLimit<br />\
                        Foswikitask:Item9139: Improve compatibility. |
|  03 Sep 2009 (0.9.2) | Improved documentation regarding module apreq |
|  12 Apr 2009 (0.9.1) | Improved documentation |
|  12 Jan 2009 (0.9.0) | Initial Release |
PackageForm edit

Author	Foswiki:Main.GilmarSantosJr
Version	1.08
Release	06 Aug 2023
Description	Permits Foswiki to be executed under mod_perl
Repository	https://github.com/foswiki/ModPerlEngineContrib
Copyright	© 2009-2023 Gilmar Santos Jr and Foswiki Contributors
License	GPL (Gnu General Public License)
Home	https://foswiki.org/Extensions/ModPerlEngineContrib
Support	https://foswiki.org/Support/ModPerlEngineContrib
Topic revision: r2 - 11 Aug 2023, TimValenzuela
System
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Iris Wiki? Send feedback