Apache-ASP
view release on metacpan or search on metacpan
> make test
> make install
* use nmake for win32
Please note that you must first have the Apache Web Server & mod_perl
installed before using this module in a web server environment. The offline
mode for building static html at ./cgi/asp-perl may be used with just perl.
Modern Linux Distributions
If you have a modern Linux distribution like CentOS or Ubuntu, you will
likely have the easiest path by using the repository tools to automatically
install mod_perl and Apache before installing Apache::ASP via CPAN.
For example for CentOS, this will install mod_perl into your apache httpd,
the latter likely being installed already by default on your server:
bash> sudo yum install mod_perl-devel.x86_64
For Ubuntu this would be done like this:
bash> sudo apt-get install libapache2-mod-perl2
Quick Start
Once you have successfully built the Apache Web Server with mod_perl, copy
the ./site/eg/ directory from the Apache::ASP installation to your Apache
document tree and try it out! You must put "AllowOverride All" in your
httpd.conf <Directory> config section to let the .htaccess file in the
./site/eg installation directory do its work. If you want a starter config
file for Apache::ASP, just look at the .htaccess file in the ./site/eg/
directory.
So, you might add this to your Apache httpd.conf file just to get the
scripts in ./site/eg working, where $DOCUMENT_ROOT represents the
DocumentRoot config for your apache server:
<Directory $DOCUMENT_ROOT/asp/eg >
Options FollowSymLinks
AllowOverride All
</Directory>
To copy the entire site, including the examples, you might do a raw
directory copy as in:
shell> cp -rpd ./site $DOCUMENT_ROOT/asp
So you could then reference the Apache::ASP docs at /asp/ at your site, and
the examples at /asp/eg/ .
This is not a good production configuration, because it is insecure with the
FollowSymLinks, and tells Apache to look for .htaccess which is bad for
performance but it should be handy for getting started with development.
You will know that Apache::ASP is working normally if you can run the
scripts in ./site/eg/ without any errors. Common problems can be found in
the FAQ section.
Build static Apache and mod_perl for Apache 1.3.x
For a quick build of apache, there is a script in the distribution at
./make_httpd/build_httpds.sh that can compile a statically linked Apache
with mod_ssl and mod_perl. Just drop the sources into the make_httpd
directory, configure the environments as appropriate, and execute the script
like this:
make_httpd> ./build_httpds.sh
You might also find helpful a couple items:
Stas's mod_perl guide install section
http://perl.apache.org/guide/install.html
Apache Toolbox
http://www.apachetoolbox.com/
People have been using Apache Toolbox to automate their complex builds of
Apache 1.3.x with great success.
Win32 / Windows Install
If you are on a Win32 platform, like WinNT or Windows 2000, you can download
the win32 binaries linked to from:
http://perl.apache.org/download/binaries.html#Win32
and install the latest perl-win32-bin-*.exe file.
Randy Kobes has graciously provided these, which include compiled versions
perl, mod_perl, apache, mod_ssl, as well as all the modules required by
Apache::ASP and Apache::ASP itself.
After installing this distribution, in Apache2\conf\perl.conf (pulled in via
Apache2\conf\httpd.conf) there's directives that have Apache::ASP handle
files placed under the Apache2\asp\ directory. There should be a sample
Apache::ASP script there, printenv.html, accessed as
http://127.0.0.1/asp/printenv.html which, if working, will print out your
environment variables.
WinME / 98 / 95 flock() workaround
For those on desktop Windows operation systems, Apache::ASP v2.25 and later
needs a special work around for the lack of flock() support on these
systems. Please add this to your Apache httpd.conf to fix this problem after
mod_perl is installed:
<Perl>
*CORE::GLOBAL::flock = sub { 1 };
</Perl>
PerlModule Apache::ASP
Please be sure to add this configuration before Apache::ASP is loaded via
PerlModule, or a PerlRequire statement.
CONFIG
You may use a <Files ...> directive in your httpd.conf Apache configuration
file to make Apache::ASP start ticking. Configure the optional settings if
you want, the defaults are fine to get started. The settings are documented
below. Make sure Global is set to where your web applications global.asa is
if you have one!
PerlModule Apache::ASP
<Files ~ (\.asp)>
SetHandler perl-script
PerlHandler Apache::ASP
PerlSetVar Global .
PerlSetVar StateDir /tmp/asp
</Files>
NOTE: do not use this for the examples in ./site/eg. To get the examples
working, check out the Quick Start section of INSTALL
You may use other Apache configuration tags like <Directory>, <Location>,
and <VirtualHost>, to separately define ASP configurations, but using the
<Files> tag is natural for ASP application building because it lends itself
naturally to mixed media per directory. For building many separate ASP
sites, you might want to use separate .htaccess files, or <Files> tags in
<VirtualHost> sections, the latter being better for performance.
Core
Global
Global is the nerve center of an Apache::ASP application, in which the
global.asa may reside defining the web application's event handlers.
This directory is pushed onto @INC, so you will be able to "use" and
"require" files in this directory, and perl modules developed for this
application may be dropped into this directory, for easy use.
Unless StateDir is configured, this directory must be some writeable
directory by the web server. $Session and $Application object state
files will be stored in this directory. If StateDir is configured, then
Use global.asa's Script_On* Events
Chances are that you will find yourself doing the same thing repeatedly in
each of your web application's scripts. You can use Script_OnStart and
Script_OnEnd to automate these routine tasks. These events are called before
and after each script request.
For example, let's say you have a header & footer you would like to include
in the output of every page, then you might:
# global.asa
sub Script_OnStart {
$Response->Include('header.inc');
}
sub Script_OnEnd {
$Response->Include('footer.inc');
}
Or let's say you want to initialize a global database connection for use in
your scripts:
# global.asa
use Apache::DBI; # automatic persistent database connections
use DBI;
use vars qw($dbh); # declare global $dbh
sub Script_OnStart {
# initialize $dbh
$dbh = DBI->connect(...);
# force you to explicitly commit when you want to save data
$Server->RegisterCleanup(sub { $dbh->rollback; });
}
sub Script_OnEnd {
# not really necessary when using persistent connections, but
# will free this one object reference at least
$dbh = undef;
}
FAQ
The following are some frequently asked questions about Apache::ASP.
Installation
Examples don't work, I see the ASP script in the browser?
This is most likely that Apache is not configured to execute the
Apache::ASP scripts properly. Check the INSTALL QuickStart section for
more info on how to quickly set up Apache to execute your ASP scripts.
Apache Expat vs. XML perl parsing causing segfaults, what do I do?
Make sure to compile apache with expat disabled. The
./make_httpd/build_httpds.sh in the distribution will do this for you,
with the --disable-rule=EXPAT in particular:
cd ../$APACHE
echo "Building apache =============================="
./configure \
--prefix=/usr/local/apache \
--activate-module=src/modules/perl/libperl.a \
--enable-module=ssl \
--enable-module=proxy \
--enable-module=so \
--disable-rule=EXPAT
^^^^^
keywords: segmentation fault, segfault seg fault
Why do variables retain their values between requests?
Unless scoped by my() or local(), perl variables in mod_perl are treated
as globals, and values set may persist from one request to another. This
can be seen in as simple a script as this:
<HTML><BODY>
$counter++;
$Response->Write("<BR>Counter: $counter");
</BODY></HTML>
The value for $counter++ will remain between requests. Generally use of
globals in this way is a BAD IDEA, and you can spare yourself many
headaches if do "use strict" perl programming which forces you to
explicity declare globals like:
use vars qw($counter);
You can make all your Apache::ASP scripts strict by default by setting:
PerlSetVar UseStrict 1
Apache errors on the PerlHandler or PerlModule directives ?
You get an error message like this:
Invalid command 'PerlModule', perhaps mis-spelled or defined by a
module not included in the server configuration.
You do not have mod_perl correctly installed for Apache. The PerlHandler
and PerlModule directives in Apache *.conf files are extensions enabled
by mod_perl and will not work if mod_perl is not correctly installed.
Common user errors are not doing a 'make install' for mod_perl, which
installs the perl side of mod_perl, and not starting the right httpd
after building it. The latter often occurs when you have an old apache
server without mod_perl, and you have built a new one without copying
over to its proper location.
To get mod_perl, go to http://perl.apache.org
Error: no request object (Apache=SCALAR(0x???????):)
Your Apache + mod_perl build is not working properly, and is likely a
RedHat Linux RPM DSO build. Make sure you statically build your Apache +
mod_perl httpd, recompiled fresh from the sources.
I am getting a tie or MLDBM / state error message, what do I do?
Make sure the web server or you have write access to the eg directory,
or to the directory specified as Global in the config you are using.
Default for Global is the directory the script is in (e.g. '.'), but
should be set to some directory not under the www server document root,
for security reasons, on a production site.
Usually a
+@rv = $Response->Include() now works where there are
multiple return values from an include like:
<% return(1,2); %>
$VERSION = 2.21; $DATE="8/5/2001";
+Documented RequestParams config in CONFIG misc section.
+Documented new XSLT caching directives.
+Updated ./site/eg/.htaccess XSLT example config
to use XSLTCache setting.
+New FAQ section on why perl variables are sticky globals,
suggested by Mark Seger.
-push Global directory onto @INC during ASP script execution
Protect contents of original @INC with local. This makes
things compatible with .09 Apache::ASP where we always had
Global in @INC. Fixed needed by Henrik Tougaard
- ; is a valid separator like & for QueryString Parameters
Fixed wanted by Anders
-XSMLSubsMatch doc fix in CONFIG section
+Reduces number of Session groups to 16 from 32, so
session manager for small user sets will be that much faster.
+optimizations for internal database, $Application, and $Session
creation.
+XSLTCache must be set for XSLT caching to begin using CacheDir
+CacheDB like StateDB bug sets dbm format for caching, which
defaults to MLDBM::Sync::SDBM_File, which works well for caching
output sizes < 50K
+CacheDir config for XSLT caching ... defaults to StateDir
+CacheSize in bytes determines whether the caches in CacheDir
are deleted at the end of the request. A cache will be
reset in this way back to 0 bytes. Defaults to 10000000 bytes
or about 10M.
+Caching infrastructure work that is being used in XSLT
can be leveraged later for output caching of includes,
or arbitrary user caching.
-t/server_mail.t test now uses valid email for testing
purposes ... doesn't actually send a mail, but for SMTP
runtime validation purposes it should be OK.
+fixed where POST data was read from under MOD_PERL,
harmless bug this was that just generated the wrong
system debugging message.
$VERSION = 2.19; $DATE="7/10/2001";
+update docs in various parts
+added ./make_httpd/build_httpds.sh scripts for quick builds
of apache + mod_perl + mod_ssl
++plain CGI mode available for ASP execution.
cgi/asp script can now be used to execute ASP
scripts in CGI mode. See CGI perldoc section for more info.
The examples in ./site/eg have been set up to run
in cgi mode if desired. Configuration in CGI section
only tested for Apache on Linux.
-Fixed some faulty or out of date docs in XML/XSLT section.
+added t/server_mail.t test for $Server->Mail(), requires
Net::SMTP to be configured properly to succeed.
+Net::SMTP debugging not enabled by Debug 1,2,3 configs,
not only when system debugging is set with Debug -1,-2,-3
However, a Debug param passed to $Server->Mail() will
sucessfully override the Debug -1,-2,-3 setting even
when its Debug => 0
-Check for undef values during stats for inline includes
so we don't trigger unintialized warnings
+Documented ';' may separate many directories in the IncludesDir
setting for creating a more flexible includes search path.
$VERSION = 2.17; $DATE="6/17/2001";
+Added ASP perl mmm-mode subclass and configuration
in editors/mmm-asp-perl.el file for better emacs support.
Updated SYNTAX/Editors documentation.
+Better debugging error message for Debug 2 or 3 settings
for global.asa errors. Limit debug output for lines
preceding rendered script.
-In old inline include mode, there should no longer
be the error "need id for includes" when using
$Response->Include() ... if DynamicIncludes were
enabled, this problem would not have likely occured
anyway. DynamicIncludes are preferrable to use so
that compiled includes can be shared between scripts.
This bug was likely introduced in version 2.11.
-Removed logging from $Response->BinaryWrite() in regular
debug mode 1 or 2. Logging still enabled in system Debug mode, -1 or -2
-Removed other extra system debugging call that is really not
necessary.
$VERSION = 2.15; $DATE="06/12/2001";
-Fix for running under perl 5.6.1 by removing parser optimization
introduced in 2.11.
-Now file upload forms, forms with ENCTYPE="multipart/form-data"
can have multiple check boxes and select items marked for
@params = $Request->Form('param_name') functionality. This
will be demonstrated via the ./site/eg/file_upload.asp example.
$VERSION = 2.11; $DATE="05/29/2001";
+Parser optimization from Dariusz Pietrzak
+Added ./eg/compiled_includes.htm example documenting new dynamic includes.
+Documented SSI: native file includes, and the rest with filtering
to Apache::SSI
+Turned the documentation of Filter config to value of Off so
people won't cut and paste the On config by default.
+Added SecureSession config option, which forces session cookie to
be sent only under https secured www page requests.
+Added StateDB config option allows use of DB_File for $Session, since
default use of SDBM_File is limited. See StateDB in README.
+file include syntax w/o quotes supported like <!--#include file=test.inc-->
+Nested includes are supported, with includes including each other.
Recursive includes are detected and errors out when an include has been
included 100 times for a script. Better to quit early than
have a process spin out of control. (PORTABLE ? probably not)
+Allow <!--include file=file.inc--> notation w/o quotes around file names
-PerlSetEnv apache conf setting now get passed through to
$Request->ServerVariables. This update has ServerVariables
getting data from %ENV instead of $r->cgi_env
+README FAQ for PerlHandler errors
$VERSION = 0.08; $DATE="02/06/1999";
++SSI with Apache::Filter & Apache::SSI, see config options & ./eg files
Currently filtering only works in the direction Apache::ASP -> Apache::SSI,
will not work the other way around, as SSI must come last in a set of filters
+SSI file includes may reference files in the Global directory, better
code sharing
- <% @array... %> no longer dropped from code.
+perl =pod comments are stripped from script before compiling, and associated
PodComments configuration options.
+Command line cgi/asp script takes various options, and allows execution
of multiple asp scripts at one time. This script should be used for
command line debugging. This is also the beginning of building
a static site from asp scripts with the -b option, suppressing headers.
+$Response->AddHeader('Set-Cookie') works for multiple cookies.
-$Response->Cookies('foo', '0') works, was dropping 0 because of boolean test
-Fixed up some config doc errors.
$VERSION = 0.07; $DATE="01/20/1999";
-removed SIG{__WARN__} handler, it was a bad idea.
-fixes file locking on QNX, work around poor flock porting
+removed message about Win32::OLE on UNIX platforms from Makefile.PL
-Better lock garbage collection. Works with StatINC seamlessly.
-Multiple select forms now work in array context with $Response->Form()
@values = $Response->Form('multi');
-Better CGI.pm compatibility with $r->header_out('Content-type'),
improved garbage collection under modperl, esp. w/ file uploads
$VERSION = 0.06; $DATE="12/21/1998";
+Application_OnStart & Application_OnEnd event handlers support.
-Compatible with CGI.pm 2.46 headers()
-Compatible with CGI.pm $q = new CGI({}), caveat: does not set params
+use strict; followed by use of objects like $Session is fine.
-Multiple cookies may be set per script execution.
+file upload implemented via CGI.pm
++global.asa implemented with events Session_OnStart and Session_OnEnd
working appropriately.
+StateDir configuration directive implemented.
StateDir allows the session state directory to be specified separately
from the Global directory, useful for operating systems with caching file
systems.
+StateManager config directive. StateManager specifies how frequently
Sessions are cleaned up, with 10 (default) meaning that old Sessions
will be cleaned up 10 times per SessionTimeout period (default 20 minutes).
+$Application->SessionCount() implemented, non-portable method.
: returns the number of currently active sessions
-STOP button fix. Users may hit STOP button during script
execution, and Apache::ASP will cleanup with a routine registered
in Apache's $r->register_cleanup. Works well supposedly.
+PerlScript compatibility work, trying to make ports smoother.
: Collection emulator, no ->{Count} property
: $.*(.*)->{Item} parsed automatically,
shedding the ->{Item} for Collection support (? better way ?)
: No VBScript dates support, just HTTP RFC dates with HTTP::Date
: Win32::OLE::in not supported, just use "keys %{$Collection}"
+./cgi/asp script for testing scripts from the command line
: will be upgraded to CGI method of doing asp
: is not "correct" in anyway, so not documented for now
but still useful
+strips DOS carriage returns from scripts automatically, so that
programs like FrontPage can upload pages to UNIX servers
without perl choking on the extra \r characters.
$VERSION = 0.05; $DATE="10/19/1998";
+Added PERFORMANCE doc, which includes benchmarks +hints.
+Better installation warnings and errors for other modules required.
( run in 0.496 second using v1.01-cache-2.11-cpan-acf6aa7dc9e )