Permits Foswiki to be executed under mod_perl


This is a runtime engine component from Foswiki Standalone architecture.

mod_perl is the Perl API to the Apache web server. It permits hooking applications into Apache, providing good performance and great flexibility.

It has better performance than 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

TIP As of Foswiki 2.0, ModPerlEngineContrib is installed by default.

This block of instructions is only needed on Foswiki 1.x systems.

Install ModPerlEngineContrib either manually (download the package and extract its contents over your foswiki directory) or using configure (under Extensions section, push the Find More Extensions button).

ALERT! Foswiki 1.x installations must be configured before mod_perl is enabled in Apache. Run 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
  2. Configure Foswiki using bin/configure
  3. Re-configure Apache with mod_perl active.

Visit the 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 Apache HTTP Request Library (module apreq). If apreq is not loaded, the following error may be encountered in certain situations, e.g., during login:
apache2: symbol lookup error: /usr/lib/perl5/auto/APR/Request/Apache2/ undefined symbol: apreq_handle_apache2

Confirming mod_perl installation

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

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 Port 2116
SERVER_SOFTWARE Apache/2.2.9 (Debian) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0

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

Foswiki configuration tuning

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

Access the 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 SitePreferences, default taken from SitePreferences.
<IfModule mod_perl.c>
   PerlSwitches -wT    # DO NOT USE THIS with Foswiki 2.0
   # must exist, otherwise Apache will not start.
   PerlRequire "/var/www/foswiki/tools/"
   APREQ2_ReadLimit  104857600

Known Issues

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

  • 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 in your Apache config or bin/.htaccess file.
   <FilesMatch "configure.*">
      SetHandler cgi-script
  • 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 FilesMatch and list all the exceptions.
   <FilesMatch "[script name needing CGI].*">
      SetHandler cgi-script

List of Files

File Description
data/System/ModPerlEngineContrib.txt Documentation
lib/Foswiki/Contrib/ Perl module
lib/Foswiki/Engine/ Perl module
lib/Foswiki/Engine/Apache/ Perl module
lib/Foswiki/Engine/ Perl module
lib/Foswiki/Engine/Apache2/ Perl module
tools/ Perl script


Change History:  
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 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.
Foswikitask:Item13830: Unable to upload utf-8 filenames as attachments.
14 Jun 2015 (1.00) Released with Foswiki 2.0.
Foswikitask:Item13378: Foswikitask:Item13405: Update for UNICODE core
Foswikitask:Item13228: Fix JSON operation with ApacheRequest2
Foswikitask:Item13125: CGI updates
Foswikitask:Item13225: Fix compatibility with Apache 2.4
Foswikitask:Item13052: Documentation improvements for APREQ2_ReadLimit
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
mod_perl2>=2.0Optional, but required if you're using Apache 2.x and plan to enable mod_perl
Apache2::Request>=2.0Optional, but recommended if you're using Apache 2.x and plan to enable mod_perl

Topic revision: r1 - 22 Jan 2018, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback