ActivePerl User Guide
|
|
ActivePerl User Guide
|
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):
http://www.apache.org
mod_perl home page: http://perl.apache.org
http://www.microsoft.com/iis/
http://www.iplanet.com/
If you want to put all of your CGI scripts into one directory, add the following line to your srm.conf file (You can choose any directory you'd like, but make sure it exists):
ScriptAlias /cgi-bin/ "C:/Program Files/Apache Group/Apache/cgi-bin/"
After you have made this change, stop and restart the Apache service.
Apache provides an emulation of the UNIX shebang (#!/path/to/perl) syntax, so the next step is easy. You can put you Perl scripts into your cgi-bin directory, as long as you have a path to a valid interpreter at the top. For example:
#!C:\PERL\5.00464\bin\MSWin32-x86\perl.exe
use CGI qw(:standard) ;
print header();
print "Hello, world";
If you want to enable CGI scripts based on an extension, such as .pl, you need to add the following line to srm.conf:
AddHandler cgi-script .pl
By default, CGI scripts are not allowed in your DocumentRoot directory, but they are allowed in other document directories. Document directories are created with the Alias command in srm.conf:
Alias /ResourceKit/ "E:/utilsamp/"
You can then include files that end in .pl within a document directory. You will still need to include the #! line with the full path to the perl.exe interpreter, as shown earlier.
If you want to allow CGI scripts in the DocumentRoot directory, add the ExecCGI option to the Options directive between the <Directory> and </Directory> entry for your DocumentRoot in access.conf (these appear directly after the comment titled:
# This should be changed to whatever you set DocumentRoot to.
After you have updated it, your Options directive may look something like:
Options Indexes FollowSymLinks ExecCGI
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:
Associate the extension for your scripts with the appropriate interpreter in the script map for IIS. This is under the Registry key HKEY_LOCAL_SYSTEM, with the sub-key ``System\CurrentControlSet\Services\W3SVC\Parameters\Script Map''. 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 Service 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 Service Manager; it is set to IUSR_[your server name] by default. See also What is a Windows NT service? and How do I set permissions on a file?.
Ensure that all supporting files, like 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?.
You need to restart the web service after making the Registry changes or installing Perl.
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 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/iis/
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 Service Manager. This will bring up the Microsoft Management Console with the Internet Service 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 appear. 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 appears. 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 appears. 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 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
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 .plx (or whatever 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 Service Manager.
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.
To set up ActivePerl to run on FastTrack Server, follow these steps:
Install FastTrack Server, and make sure you can retrieve HTML pages.
Associate Perl scripts with the perl interpreter, if you haven't already. See How do I associate Perl scripts with perl? for how to do this. Re-start the server after making the association.
Set up a Shell CGI directory to run Perl scripts. A regular CGI directory will not work -- that is only for executable files. You set this up with the FastTrack Administrator; see the documentation for details.
If you would like to access Perl CGI scripts in other directories, you need to associate an extension, such as .pl, with the shellcgi MIME type. Before you follow these steps, you must add at least one Shell CGI directory - this will enable shellcgi on your server (you can delete this directory, and shellcgi will remain enabled). Follow these steps to associate .pl with the shellcgi MIME type:
In the Server Administrator, click Server Preferences, then select MIME Types from the frame on the left.
If you want to use .pl as the extension for Perl scripts, find and remove the application/x-perl MIME type (this is mapped to .pl by default).
Add a new MIME Type with magnus-internal/shellcgi as the Content Type, and pl as the File Suffix. If a type for magnus-internal/shellcgi already exists, simply add pl to the list of File Suffixes. Don't include the leading dot on the file suffix.
Save and apply these changes, then re-start the server. You should be able to put a Perl CGI script in any directory, provided the script ends with the .pl suffix.
If you are having trouble running Perl scripts on your iPlanet server, check the following:
Ensure that the script is readable by the account used by the iPlanet service. Generally, this means you should make the script readable by the Everyone group.
Ensure that all supporting files, like the perl binary files, the perl library files, and the modules that you use, are all readable by the account used by the iPlanet service (i.e., the Everyone group).
One nice thing about FastTrack server is that the Error Log will give detailed reasons why your CGI script isn't running, so this is a good thing to check first when you are having configuration problems.
Because iPlanet servers run as services (see What is a Windows NT service?), you need to take special steps to make sure that files and environment variables are available to them.
Some people have reported problems with handling POST'ed data with Perl programs with iPlanet servers. Since iPlanet apparently uses associations to run scripts, and POST'ed data is sent on STDIN to a program. This may be related to the problems with redirection.
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 that the web server uses can 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 make sure that files and environment variables are available to them.
Usually, this means one of two things: either you have misconfigured your system, or your script does not output the right stuff to be 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/2000.
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.
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 stuff 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: DON'T 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.
Anyone with a devious mind and a little knowledge of Perl can see that with
this configuration, hackers could start doing all kinds of horrible 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 stuff 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 so 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
Tom Christiansen has also written a good discussion of the subject:
http://www.perl.com/perl/news/latro-announce.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 GOOD. Most of the primitive 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.
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 |