Web Server Information
ActivePerl-faq6 - Web server information
ActivePerl Web Server Configuration and Troubleshooting
Most Windows web servers that use the CGI standard or ISAPI will run
ActivePerl scripts. The following servers are known to work with ActivePerl
(known protocols in brackets):
- Apache for Win32 [CGI, mod_perl]
- http://www.apache.org
mod_perl home page: http://perl.apache.org
- Microsoft Internet Information Server [CGI, ISAPI]
- http://www.microsoft.com/WindowsServer2003/iis/default.mspx
Usually, this means one of two things: either your system is misconfigured,
or your script does not send the correct output for a CGI script.
Before you do anything else, check this list:
- Make sure you have correctly configured your server for perl.exe
or PerlIS.dll. This is often accomplished by mapping a specific
extension, such as .pl or .plx, to perl.exe or
PerlIS.dll.
Usually, web servers rely on their own mappings, rather than the Windows
command-line mappings.
- If your web server depends on the
PATH variable to find perl.exe,
make sure that you put perl.exe in your system PATH,
not just your user PATH. This only applies to Windows NT/200x/XP.
- If your web server requires directories to be marked as executable, make
sure the directory that contains the script is marked as such.
- Since the web server can be configured to run as a local user, be sure
that the user has access to the script file and the Perl binaries and
libraries. Many web servers run as the ``Local System'' account, which
generally has sufficient permissions.
- If Perl.exe or Perl for ISAPI fail to work as expected check
your event logs for clues.
- Ensure that HTTP headers are being output correctly. Use the following
script as a test:
#!C:\perl\bin\perl.exe
# previous line added to support Apache 1/2
# please adjust to your own Perl path!
use strict;
use CGI;
my $page = new CGI;
my $msg = "Hello from ActivePerl CGI!";
# print header and start the markup output
print $page->header( "text/html" ),$page->start_html( $msg );
print $page->h2($msg);
print $page->end_html;
# end code
Check the information above with a script that you know produces the right
output for the CGI protocol (scripts in this FAQ are a good first choice). Try
it with your own script after you're sure the test script will work.
If you are sure the server is running the script, but it only generates error
messages in your browser, there are some tools that may help you out. CGI::Carp
is used to send debugging information to the browser or log file. Even if your
script has a compilation error, it can usually intercept and report errors. To
use CGI::Carp, include the following lines in your program:
# The code in the BEGIN block will be executed very early
# on, even before the rest of this script is parsed.
#
BEGIN {
# Use the CGI::Carp module and import the carpout() function.
#
use CGI::Carp qw(carpout);
# Send warnings and die messages to the browser.
#
carpout(STDOUT);
}
If your script has an error, you may see something like this in the browser:
[Wed Jun 3 09:32:28 1998] C:\inetpub\scripts\test.pl: Error message! at
C:\inetpub\scripts\test.pl line 38.
Sometimes, it can be helpful to put yourself in somebody else's position. The
libwww-perl bundle (LWP) is available from CPAN, but you can install it using
the Perl Package Manager (PPM). LWP may be included with future releases of
ActivePerl.
LWP includes the powerful lwp-request script, which lets you see
things from the browser's perspective. Invoke lwp-request with the name
of a URL to see the content of the response, as in lwp-request
http://localhost. To inspect the headers of an HTTP response, invoke lwp-request
with the -de switch:
C:\>lwp-request -de http://localhost
Date: Wed, 03 Jun 1998 13:37:31 GMT
Accept-Ranges: bytes
Server: Microsoft-IIS/4.0
Content-Length: 4325
Content-Location: http://localhost/Default.htm
Content-Type: text/html
ETag: "0c1e58b063bd1:1237"
Last-Modified: Thu, 09 Apr 1998 12:09:28 GMT
Client-Date: Wed, 03 Jun 1998 13:37:31 GMT
Client-Peer: 127.0.0.1:0
This tool can be very helpful in figuring out exactly what your scripts are
doing. Whatever you do, don't give up hope. It is, in fact, possible to get a
Perl script running on your web server. Really.
First, the warning: do not do this. Really. Even if you don't
understand why not, don't.
Now the explanation: the idea here is to put perl.exe in your CGI
directory (however you configure that on your server), and use URL syntax like
the following:
http://soon.to.be.a.victim.net/cgi-bin/perl.exe?myscript.pl
to run myscript.pl. This keeps you from having to figure out how to
configure your server to associate extensions like .pl with an
interpreter like perl.exe.
In fact, on some early Win32-based web servers (iPlanet 1.x servers in
particular), it was impossible to associate a script file with an interpreter.
This method was recommended by vendors as a viable approach to running Perl
scripts on your web server.
With this configuration, anyone with a devious mind and a little knowledge of
Perl could start doing all kinds of destructive things on the server. All they'd
have to do is send made-up URLs, using the
-e command line switch in perl.exe, in order to do things
like delete all files on a drive:
http://aaaugh.that.hurts.net/cgi-bin/perl.exe?-e?'del%20c:\*.*%20/S%20/Q'
Of course, a true computer criminal would never do something this crude and
obvious, but would instead use this as a launching point to cause irreparable
harm to your organization.
The following URL covers this issue in more depth:
http://www.cert.org/advisories/CA-1996-11.html
Note that one suggested solution to this problem is wrapping your Perl script
in a batch file using pl2bat or your own custom batch code. This is also not
a good idea. Most servers that won't allow file associations are also susceptible to a bug that
allows a user to enter any DOS command after the bat file.
These instructions assume that you have installed the Apache web server
according to the instructions for the 2.0.x Windows version.
- Open the httpd.conf file for editing by selecting Start >
Programs > Apache HTTP Server > Configure Apache Server > Edit the Apache
httpd.conf Configuration File.
This will open your httpd.conf file in the notepad editor.
- Make the following changes to the httpd.conf file:
- In the DocumentRoot section, set the value of
DocumentRoot
to the directory in which your web site files will be located on your system's
hard drive(s). Ensure that you use forward slashes (/) in the path, as
Apache doesn't understand backward slashes (\) in paths. For example:
# DocumentRoot: The directory out of which you will serve your
# documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
DocumentRoot "C:/apacheroot"
- In the main directory section, add
ExecCGI to the
Options line. For example:
Options FollowSymLinks ExecCGI
- Search for the following line and remove the hash mark character (#) to
uncomment this line. (You can also change .cgi to
.pl if you prefer.) For example:
#AddHandler cgi-script .cgi
Should look like:
AddHandler cgi-script .pl
- Save your changes to the httpd.conf file, and restart the Apache
Service using the Apache Service Monitor.
- Test your configuration as described in the
Testing Your Web Server Configuration section below.
There are two ways to configure Apache to support CGI scripts: by setting the
directory in which the ActivePerl scripts reside, or by setting the file
extension that Apache will associate with CGI scripts.
To add a directory in which all of your CGI scripts will reside, do the
following:
- Open the httpd.conf file for editing by selecting Start >
Programs > Apache HTTP Server > Configure Apache Server > Edit the Apache
httpd.conf Configuration File.
This will open your httpd.conf file in the notepad editor.
- Make the following changes to the httpd.conf file:
ScriptAlias /cgi-bin/ "C:/Program Files/Apache Group/Apache/cgi-bin/"
You can choose any directory that you like, but you must ensure that it exists.
- After you have made this change, stop and restart the Apache service.
Note: Apache provides an emulation of the UNIX ``shebang'' syntax,
where the first two characters on the first line of a script begin with the
hash mark ("#") and bang ("!") characters, which is then followed by the path to the script
interpreter. This will ensure that the proper interpreter will always be used to run your
script. You should begin each ActivePerl script that you place in your cgi-bin
directory with a valid path to the ActivePerl interpreter. For example:
#!C:\PERL\5.00464\bin\MSWin32-x86\perl.exe
use CGI qw(:standard) ;
print header();
print "Hello, world";
- Test your configuration as described in the
Testing Your Web Server Configuration section,
below.
To enable CGI scripts based on an extension, such as .pl or
.cgi, do the following:
- Add the following line to the httpd.conf file:
AddHandler cgi-script .pl
Note: By default, CGI scripts are not allowed to be in your
DocumentRoot directory, but they are allowed in other document directories.
Document directories are created with the Alias command in httpd.conf.
For example:
Alias /ResourceKit/ "E:/utilsamp/"
You can then include files that end in .pl (or .cgi, if
you set that as the extension in the AddHandler line) within a document
directory. You will still need to include the #! line with the full valid
path to the perl.exe interpreter, as shown in the previous procedure.
- If you want to allow CGI scripts in the DocumentRoot directory, add the
ExecCGI option to the Options directive in the <Directory> section for
your DocumentRoot in the httpd.conf file; this section appears
directly after the comment titled:
# This should be changed to whatever you set DocumentRoot to.
After you have updated it, your Options directive should look similar to this:
Options Indexes FollowSymLinks ExecCGI
- After you have made these changes, stop and restart the Apache service.
- Test your configuration as described in the
Testing Your Web Server Configuration section,
below.
To configure ActivePerl to work with IIS 6 on Windows 2003:
- Load the Internet Information Services (IIS) Manager
applet from Window's Administrative Tools menu.
- Select the desired system, then select Web Service
Extensions. Click Add New Web Service Extension.
- Enter a descriptive Extension Name (such as "Perl
CGI"), then enter the following string in the Required Files
field:
C:\Perl\bin\perl.exe "%s" %s
As necessary, modify the path to the Perl executable on the selected system.
Check Set Extension Status to Allowed, then click
OK.
- Expand the Web Sites directory in the IIS Manager and
right-click Default Web Site. Select New |
Virtual Directory.... Use the wizard to specify the location
of your Perl CGI programs. On the Access Permissions
page, ensure that Read, Run Scripts
and Execute are enabled.
- Right-click the new virtual directory and select Properties.
On the Mappings tab of the Application
Configuration page, ensure that the .pl or .cgi extension is
mapped to the Perl interpreter specified above. (Enter the same string in
the Executable Path field as shown in step 3.)
- In order to run ASP scripts, ensure that Active Server
Pages are "allowed". Under the Web Service Extensions
directory, select Active Server Pages. Change the status from
"Prohibited" to "Allowed".
- Restart the IIS service.
- Test your configuration as described in Testing
Your Web Server Configuration.
Microsoft IIS 4.0 ships with Windows NT Server 5.0, and PWS 4.0 ships with
Windows NT Workstation 5.0. Both IIS and PWS are available as part of the
Microsoft Windows NT 4.0 Option Pack. You can find a link to the Option Pack at
http://www.microsoft.com/WindowsServer2003/iis/default.mspx
Microsoft IIS 5.0 is not automatically installed on all Windows 2000 systems.
Check your Windows 2000 documentation on how to install IIS 5.0.
To configure IIS or PWS 4.0 to run Perl scripts:
- Open the Internet Services Manager. This will bring up the
Microsoft Management Console with the Internet Services Manager snap-in
already selected.
- From the tree display on the left, select the level at which to apply the
mappings. You can choose an entire server, web site, or a given virtual
directory.
- Select Properties from the Action menu.
- If you chose to administer the properties for the entire server, the
Server Properties dialog will be displayed. Select WWW Service from
the Master Properties pull-down menu and click the
Edit button under Master Properties.
This opens WWW Service Master Properties. Select the Home Directory tab and
proceed to step 7.
- If you chose to administer the properties for an entire web site, the Web
Site Properties sheet is displayed. Select the Home Directory
tab and proceed to step 7.
- If you chose to administer the properties for a virtual directory, the
Virtual Directory Properties sheet is displayed. Select the Virtual
Directory tab and proceed to step 7.
- Click the Configuration button. This opens the Application Configuration
dialog.
- Select the App Mappings tab and click the Add button.
You now see the Add/Edit Application Extension Mapping dialog.
- To run Perl as a CGI application, type the full path to Perl.exe
followed by
"%s" %s. When a script is executed, the
first "%s" (double-quoted)
will be replaced by the full path to the script, and the second %s
will be replaced by the script parameters.
- To run Perl for ISAPI, type the full path to PerlIS.dll. The
%s
%s is not required for ISAPI DLLs.
- In the Extension field, type .pl or .cgi (or whichever
extension you want to use).
- The application mapping is now complete. Click the OK button and
click OK to dismiss any remaining dialogs/property sheets.
- Close the IIS Internet Services Manager.
- After you have made these changes, stop and restart the IIS service.
- Test your configuration as described in the
Testing Your Web Server Configuration section,
below.
Because IIS runs as a service (see
What
is a Windows NT service?), you need to take special steps to make sure that
files and environment variables are available to it.
By default, the ActivePerl installation maps the .plx extension to
Perl for ISAPI. You can override the extension used during installation. Because
the installation does this only when IIS is already installed, you must install
IIS first, then install ActivePerl. If you need to reconfigure these settings,
or if you must set these by hand, the instructions in this section will prove
useful.
Microsoft Internet Information Server (IIS) ships with Windows NT Server.
Peer Web Services (PWS) ships with Windows NT Workstation. Configuring the
products is essentially the same. First, you should consult Chapter 8,
Publishing Information and Applications, in the IIS documentation.
You need to follow these steps to get ActivePerl scripts to run under IIS:
- Open the Registry Editor by clicking Start > Run and
typing regedit in the Open field of the
Run dialog, and then click OK.
- In the registry tree on the left, expand HKEY_LOCAL_MACHINE >
SYSTEM > CurrentControlSet > Services > W3SVC > Parameters and
click on Script Map.
- Associate the extension for your scripts with the appropriate interpreter
in the script map for IIS. Many people map two extensions: one to
perl.exe %s (for example, .pl) and another to PerlIS.dll
(for example, .plx). Note that mapping an extension in the script
map is not the same as associating the extension in Explorer. Use the
full paths to the executable files in the script map.
- Put your scripts in a virtual directory on the server that has Execute
access but not Read access. You can add virtual directories or view their
access with the Internet Services Manager. Remember that the URLs for your
virtual directories can't overlap with URLs to directories in the WWW root
directory. For example, You can't have a cgi-bin virtual directory
and a real cgi-bin subdirectory of the WWW root.
- Ensure that your scripts are readable by the account used by the IIS
server. You set this account in Internet Services Manager; by default, it is
set to IUSR_[your server name].
- Ensure that all supporting files, such as the perl binary files, the perl
library files, and the modules that you use, are all readable by the account
used by the IIS server. See also
What
is a Windows NT service? and
How
do I set permissions on a file?.
- After you have made these changes, stop and restart the IIS service.
- Test your configuration as described in the
Testing Your Web Server Configuration section
below.
Because IIS runs as a service (see
What
is a Windows NT service?), you need to take special steps to make sure that
files and environment variables are available to it.
Microsoft Personal Web Server for Windows 95 is a scaled-down version of
Microsoft Internet Information Server. Although it is not documented, it appears
that the method used to support ActivePerl with IIS will also work with Personal
Web Server. See How do I
configure IIS 3.0 or lower to support ActivePerl?.
If your web server isn't listed, check the server's documentation on how to
set up a CGI interpreter. In general, the process is as follows:
- Associate a file extension like .pl with the perl binary, and
let the server know where the binary is. This may be a shell association,
(see How
do I associate Perl scripts with perl?), or a custom association.
- Set up a directory where executable scripts go, and put your Perl script
there.
- Ensure that the user account used by the web server has permission to read
the script as well as any ancillary files (perl binary files, library files,
modules, etc.). This usually means making the files available to the Everyone
group.
Because most web servers run as services (see
How
do I configure IIS 3.0 or lower to support ActivePerl?), you need to take
special steps to ensure that files and environment variables are available to
them.
Regardless of which of the above configurations you performed, you should test your
configuration to ensure that your web server properly handles ActivePerl
CGI scripts. The following script provides a simple test of your configuration:
- Save the following test script in your DocumentRoot directory as
test.pl or test.cgi (depending on your configuration of the
AddHandler line) and modify the first line as required to point
to your ActivePerl interpreter:
#!c:\perl\bin\perl.exe
# ^^^ this must be the first line of the script! ^^^
# start code
use strict;
use CGI;
my $q = new CGI;
# print header and start the markup output
print $q->header( "text/html" ),$q->start_html( "hello from perl cgi!" );
print $q->h2("hello dave...");
print $q->end_html;
# end code
- Open the script in your browser to test your configuration. You should
see a page that displays a level two heading with the following text:
hello dave...
This FAQ was originally assembled and maintained by Evangelo Prodromou.
It has been revised and updated by Brian Jepson of O'Reilly and Associates, and
David Grove and David Dmytryshyn of ActiveState.
This FAQ is in the public domain. If you use it, however, please ensure that
you give credit to the original authors.
|
ActivePerl FAQ - Web Server Information
|
|
