I went down the "install via gem" road, so it wasn't too painful to being with. When I reached the phase of actually installing passenger to apache, I discovered that the configuration tool is a bit confused by Solaris, especially the apache APU component.

Here's the problem:

* GNU C++ compiler... found at /opt/csw/gcc4/bin/g++
* Ruby development headers... found
* OpenSSL support for Ruby... found
* RubyGems... found
* Rake... found at /opt/csw/bin/rake
* rack... found
* Apache 2... found at /opt/csw/apache/bin/httpd
* Apache 2 development headers... found at /opt/csw/apache/bin/apxs
* Apache Portable Runtime (APR) development headers... not found
* Apache Portable Runtime Utility (APU) development headers... not found


No big deal - we'll just pass it some options, right? Wrong. The CLI only accepts arguments for apxs2 and apr, but not apu.

Running with --apr-config-path /opt/csw/apache2/bin gets us slightly further:


* GNU C++ compiler... found at /opt/csw/gcc4/bin/g++
* Ruby development headers... found
* OpenSSL support for Ruby... found
* RubyGems... found
* Rake... found at /opt/csw/bin/rake
* rack... found
* Apache 2... found at /opt/csw/apache/bin/httpd
* Apache 2 development headers... found at /opt/csw/apache/bin/apxs
* Apache Portable Runtime (APR) development headers... found at /opt/csw/apache2/bin/
* Apache Portable Runtime Utility (APU) development headers... not found


Finally the APU. This is a bit tricky to track down.

This was my process:

passenger-install-apache2-module secretly runs this file:

/opt/csw/lib/ruby/gems/1.8/gems/passenger-2.2.9/bin/passenger-install-apache2-module

Right away we see the following lines:

37 require 'phusion_passenger/dependencies'
52 Dependencies::Apache2,
53 Dependencies::Apache2_DevHeaders

So we follow them:

lib/phusion_passenger/dependencies.rb reveals that it secrely calls PlatformInfo to look for the APU:

304 if PlatformInfo.apu_config.nil?

So we jump into lib/phusion_passenger/platform_info.rb and discover (with some casual grepping):

284 if env_defined?('APU_CONFIG')
285 return ENV['APU_CONFIG']

This means that if we do the following, we can convince the installer that we do, in fact, have the necessary files:

setenv APU_CONFIG /opt/csw/apache2/bin/apu-1-config
passenger-install-apache2-module --apr-config-path /opt/csw/apache2/bin/

Hopefully this will make your life easier.

I'm using Ubuntu Server 10.04 for my server and rather then authentication against a real IdP, I'm using the public TestShib Two service as an IdP and configuring the SP myself.

Here's how I did it:

0) Register with OpenIdP and get a machine ready for testing.

1) Install the necessary packages:
apache mpm-prefork
php5
libapache2-mod-shib2
mysql (for drupal)!
...and all their friends.

2) Get drupal and install that properly. There are plenty of tutorials out there on how to do this.

3) Configure your apache server so that it looks something like this:



ServerAdmin webmaster@localhost
ServerName x-128-101-79-21.pop.umn.edu
UseCanonicalName On

AuthType Shibboleth
ShibRequireSession On
require shibboleth


...and a whole bunch more as needed. You can actually base it off the default-ssl site (...like I did.)

4. Somewhere in your shibboleth2.xml (probably in /etc/shibboleth), you have something that looks like this:









This is the really important part. It's telling you exactly which paths on the server are going to be secured by

1) Each vhost should have its own interpretter pool with its own paths.
2) vhosts do not need to use custom directives during startup.
3) Custom liraries in each vhost should not be shared with the others.
4) Users should be able to execute mod_perl scripts only from docs/bin.

Here's a snip from my apache2ctl status: "Server Version: Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0"

Let's get started!

I have three vhosts {a, b, c} each listening on ports 5050, 8080, and 9090 respectively.

Here's my initial /etc/apache2/sites-available/vhosts.conf file:

<VirtualHost *:5050>

    DocumentRoot /var/www/a

    #PerlPostConfigHandler MyApache2::Test->post_config

</VirtualHost>


<VirtualHost *:8080>

    DocumentRoot /var/www/b

    #PerlPostConfigHandler MyApache2::Test->post_config

</VirtualHost>

<VirtualHost *:9090>

    DocumentRoot /var/www/c

    #PerlPostConfigHandler MyApache2::Test->post_config

</VirtualHost>

ServerName localhost

PerlSwitches -I/var/myperl/dep_lib

PerlPostConfigHandler MyApache2::Test->post_config

/var/myperl/dep_lib/MyApache2::Test.pm looks like this:

package MyApache2::Test;

use Apache2::ServerRec;

use Apache2::Const -compile => OK

use strict;

use warnings;


sub post_config {

  my ($self, $conf_pool, $log_pool, $temp_pool, $s) = @_;

  warn "HELLO " . $s->port . "\n";

}

1;

When we start the server, this is the output we get:

root@larx:~# tail -fn 0 /var/log/apache2/error.log
HELLO 0
HELLO 0
[Tue Mar 09 19:09:00 2010] [notice] Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0 configured -- resuming normal operations
[Tue Mar 09 19:09:00 2010] [info] Server built: Nov 13 2009 21:59:28
[Tue Mar 09 19:09:00 2010] [debug] prefork.c(1032): AcceptMutex: sysvsem (default: sysvsem)

This shows that the global configuration (*:0) is saying hello when it calls the PostConfigHandler. After the first call to PerlPostConfigHandler, Apache restarts itself to test its graceful restart ability. [1]

Now what happens when we try to implement a PostConfigHandler in a VirtualHost? According to the documentation, since PerlPostConfigHandler is valid in the SRV scope, we should be able to do this:

/etc/apache2/httpd.conf:

ServerName localhost

PerlSwitches -I/var/myperl/dep_lib

#PerlPostConfigHandler MyApache2::Test->post_config

/etc/apache2/site-available/vhosts.conf:

<VirtualHost *:5050>

        DocumentRoot /var/www/a

        PerlSwitches -I/var/myperl/dep_lib

        PerlPostConfigHandler MyApache2::Test->post_config

</VirtualHost>


<VirtualHost *:8080>

        DocumentRoot /var/www/b

</VirtualHost>

<VirtualHost *:9090>

        DocumentRoot /var/www/c

</VirtualHost>

root@larx:~# tail -fn 0 /var/log/apache2/error.log
[Tue Mar 09 19:19:23 2010] [notice] Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0 configured -- resuming normal operations
[Tue Mar 09 19:19:23 2010] [info] Server built: Nov 13 2009 21:59:28
[Tue Mar 09 19:19:23 2010] [debug] prefork.c(1032): AcceptMutex: sysvsem (default: sysvsem)

Notice that the PerlPostConfigHandler hasn't said anything. This is actually by design, contrary to what the documentation might say. In reality, PerlPostConfigHandler is only valid in the server-wide configuration context, NOT in vhosts. There are two ways to get around this.

1) Patch your mod_perl installation using a patch (possibly outdated) available on the mod-perl mailing lists here [2].
2) Use startup.pl files in a per-host configuration scheme.

Since I have less than no desire to go hacking around inside the monster, I've opted for choice 2.

To achieve this, we need to provide each vhost with a way to load some file at server startup. In /var/www/(a|b|c) we place a file called startup.pl that looks remarkably like this: (just make sure to s/a/(b|c) when and where appropriate)

/var/www/a/startup.pl:

#!/usr/bin/perl


use lib qw( /var/www/a/lib /var/www/a/lib/dep_lib );

use Data::Dumper;

use warnings;

use strict;

warn "Dumping the A startup.pl:\n";

print STDERR Dumper(\@INC);

warn "Finished processing A startup!\n";

1;

Notice that "1;". That's pretty important since the script is effectively being require()'d by mod_perl and therefore must return true.

Next we need to configure the vhost:

/etc/apache2/sites-available/vhosts.conf:

<VirtualHost *:5050>

        DocumentRoot /var/www/a

        PerlPostConfigRequire /var/www/a/startup.pl

</VirtualHost>


<VirtualHost *:8080>

        DocumentRoot /var/www/b

</VirtualHost>

<VirtualHost *:9090>

        DocumentRoot /var/www/c

</VirtualHost>

root@larx:~# tail -fn 0 /var/log/apache2/error.log
[Thu Mar 11 16:54:12 2010] [info] removed PID file /var/run/apache2.pid (pid=4057)
[Thu Mar 11 16:54:12 2010] [notice] caught SIGTERM, shutting down
Dumping the A startup.pl:
$VAR1 = [
'/var/www/a/lib',
'/var/www/a/lib/dep_lib',
'/var/myperl/dep_lib',
'/etc/perl',
'/usr/local/lib/perl/5.10.0',
'/usr/local/share/perl/5.10.0',
'/usr/lib/perl5',
'/usr/share/perl5',
'/usr/lib/perl/5.10',
'/usr/share/perl/5.10',
'/usr/local/lib/site_perl',
'.',
'/etc/apache2'
];
Finished processing A startup!
Dumping the A startup.pl:
$VAR1 = [
'/var/www/a/lib',
'/var/www/a/lib/dep_lib',
'/var/myperl/dep_lib',
'/etc/perl',
'/usr/local/lib/perl/5.10.0',
'/usr/local/share/perl/5.10.0',
'/usr/lib/perl5',
'/usr/share/perl5',
'/usr/lib/perl/5.10',
'/usr/share/perl/5.10',
'/usr/local/lib/site_perl',
'.',
'/etc/apache2'
];
Finished processing A startup!
[Thu Mar 11 16:54:15 2010] [notice] Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0 configured -- resuming normal operations
[Thu Mar 11 16:54:15 2010] [info] Server built: Mar 9 2010 21:04:15
[Thu Mar 11 16:54:15 2010] [debug] prefork.c(1032): AcceptMutex: sysvsem (default: sysvsem)

Notice that we see the Dumper being called twice. This is, again, because immediately after starting up for the first time Apache starts once, and then restarts to test its graceful restart ability. [1]

Really interesting side note: when you reload (aka "graceful restart," "-k graceful," SIGUSR1) the apache server will start new children with the new configuration settings. On the other hand, restarting (aka "restart now, "-k restart", SIGHUP) stops all children, reloads the parent, and then loads all children with the new configuration. This means that when you send "reload" you get one startup pass from modperl instead of two (since the server is already running it doesn't test it's ability to restart) whereas with restart, the server (for all intents and purposes) stops and starts again meaning that you see the output from modperl twice. [3]

Now that we know what's going on with the modperl startup, let's finish our setup. The remaining adjustments are fairly straightforward:

/etc/apache2/httpd.conf:

ServerName localhost

PerlSwitches -I/var/myperl/dep_lib

#This option allows us to say things like print "Content-Type: text/plain\n\n"

PerlOptions +ParseHeaders

#We still might want to do something server-wide

PerlPostConfigHandler MyApache2::Test->post_config

/etc/apache2/sites-available/vhosts.conf:

#I've actually ignored one of the criteria I set earlier (because I can, and partially to show a point):

#vhost a allows scripts to run under modperl from docs/bin even though the documentroot is under ExecCGI.

#The PerlOptions +Parent gives vhost a it's own perl interpreter pool complete with its own @INC.

<VirtualHost *:5050>

        DocumentRoot /var/www/a/docs

        Options ExecCGI +Includes FollowSymLinks +MultiViews Indexes

        DirectoryIndex index.html


        PerlPostConfigRequire /var/www/a/startup.pl

        PerlOptions +Parent

        <Directory /var/www/a>

                AllowOverride All

        </Directory>

        <Directory /var/www/a/docs/bin>

                SetHandler perl-script

                PerlResponseHandler ModPerl::Registry

        </Directory>

</VirtualHost>

#vhost b is configred identically to vhost a.

<VirtualHost *:8080>

        DocumentRoot /var/www/b/docs

        Options ExecCGI +Includes FollowSymLinks +MultiViews Indexes

        DirectoryIndex index.html

        PerlPostConfigRequire /var/www/b/startup.pl

        PerlOptions +Parent

        <Directory /var/www/b>

                AllowOverride All

        </Directory>

        <Directory /var/www/b/docs/bin>

                SetHandler perl-script

                PerlResponseHandler ModPerl::Registry

        </Directory>

</VirtualHost>

#vhost c is a little different.  This vhost allows scripts to be run under modperl from anywhere it its document root.

<VirtualHost *:9090>

        DocumentRoot /var/www/c/docs

        Options ExecCGI +Includes FollowSymLinks +MultiViews Indexes

        DirectoryIndex index.html

        PerlPostConfigRequire /var/www/c/startup.pl

        PerlOptions +Parent

    SetHandler perl-script

        PerlResponseHandler ModPerl::Registry

        <Directory /var/www/c>

                AllowOverride All

        </Directory>

</VirtualHost>

There are two things that should be explained:

PerlOptions +Parent
...creates a separate interpreter pool for each of the vhosts. These pools do not inherit any settings from other pools.

SetHandler perl-script
...tells Apache to parse all files in that Directory (also valid for Locations) as perl-scripts. ("SetHandler modperl" also works just as well here). More on this in a week or two.

PerlResponseHandler ModPerl::Registry
...tells modperl that everytime it needs to process something, use ModPerl::Registry to generate the response by compiling/parsing/executing your code when it needs to.

Finally, to prove that this actually works (in addition to having the error log), here's a script that you can actually run under modperl in each of the vhosts. Notice the lack of a #! line and a 1;. They're not necessary [in this particular instance]!

test.pl:

use Data::Dumper;


print "Content-type: text/plain\n\n";

for(sort keys %ENV) {

        print "$_ => $ENV{$_}\n";

}

print Dumper(\@INC);

Finally, my directory structure looks like this:

root@larx:/var/www# tree
.
|-- a
| |-- docs
| | |-- bin
| | | `-- test.pl
| | `-- index.html
| |-- lib
| | `-- dep_lib
| `-- startup.pl
|-- b
| |-- docs
| | |-- bin
| | | `-- test.pl
| | `-- lib
| | `-- dep_lib
| |-- lib
| | `-- dep_lib
| `-- startup.pl
`-- c
|-- docs
| |-- bin
| | `-- test.pl
| |-- lib
| | `-- dep_lib
| `-- test.pl
|-- lib
| `-- dep_lib
`-- startup.pl

19 directories, 8 files

Try visiting http://localhost:8080/bin/test.pl and http://localhost:9090/test.pl . Now you have mod_perl working with isolated vhosts!

Join me next week as I delve further into mod_perl. Possible topics include authentication and authorization, ModPerl::Registry and/or ModPerl::PerlRun, custom environment variables, and further per-vhost configuration options.

References:

[1] http://perl.apache.org/docs/2.0/user/handlers/server.html#Server_Life_Cycle

[2] http://www.gossamer-threads.com/lists/modperl/modperl/60796#60796

[3] http://httpd.apache.org/docs/2.2/en/stopping.html#graceful

I usually use CGI::Application::Plugin::TT and CGI::Application::Plugin::AutoRunmode in my applications.

Suppose your application has two screens: statistics and administration.

In the administration screen a user can add or remove other users.
In the statistics screen a user can generate reports based on a type and some parameters.

Each of these screens corresponds to a run mode. Here's the general logic behind the runmodes:

Enter the mode and create useful objects (esp. $self = shift;)
Test to see if the form has been submitted.
If it has, process the associated information and return something useful.
If it hasn't, return the information to display.
Return

Both methods use POST for form submission, but can be accessed by GET URL parameters by default.

When your clients visit the website http://example.com/cgi-bin/myapp?rm=stats they get sent to the statistics page and visiting http://example.com/cgi-bin/myapp?rm=admin they get sent to the administration page.

Here's the problem: When the user clicks on the "submit" button on either page, the runmode parameter (rm=stats) becomes part of the CGI environment variable QUERY_STRING (which, by definition, contains URL parameters).

Suppose your instance script (cgi-bin/myapp) looks like this:

my $app = MyApp::Admin->new();

$app->run();

It may not appear obvious, but without any fancy processing, passing rm?=stats will cause the value of rm to be the runmode. Read more about that here: http://search.cpan.org/~markstos/CGI-Application-4.31/lib/CGI/Application.pm .

Anyway, if you try that with a POST request, it will blow up in your face (I suggest using use CGI::Carp qw(fatalsToBrowser) to have it explode cleanly).

Before you jump into a runmode, any runmode, CGI::Application calls cgiapp_prerun(). If here you can check to figure out if you have a runmode set or not!

With a GET request, $q->param('rm') will give you the rm parameter that you expect to be your runmode. With a POST submission, however, you'll notice that you have form data there instead and your rm is now in the CGI environment variable. You can get at these with $q->url_param().

sub cgiapp_prerun {

        my $self = shift;

        my $q = $self->query();

        my $v = undef;

        $v = $q->param('rm');

        if(!defined($v)) {

                my $arm = $q->url_param('rm');

                $self->prerun_mode($arm);

        }

}

• Try to get the parameter rm from the CGI parameters ($v = $q->param('rm')). When this fails $v will be undefined.
• If $v is undefined then get the rm parameter from the URL encoded parameters list and pass it to prerun_mode() which will set the runmode.
• Fall off the end of control and your runmode will either be the rm passed via GET, or the one you set from url_params().

It's just that easy!

Checkout these sites for more information:

http://search.cpan.org/~markstos/CGI-Application-4.31/lib/CGI/Application.pm
http://search.cpan.org/dist/CGI.pm/lib/CGI.pm#MIXING_POST_AND_URL_PARAMETERS