<P>Install the EMWAC server. Ensure that EMWAC can serve HTML files correctly.</P>
</LI>
<LI>
<P>Make sure that the bin subdirectory of your Perl directory is in the system <CODE>PATH</CODE>
variable. This should be the subdirectory where perl.exe is located, such as <EM>C:\Perl\bin</EM>.
Note that this must be set in the Control Panel, not on the command line, and it must be a
system environment variable, not a user environment variable.</P>
</LI>
<LI>
<P>Make sure that your script has the extension <CODE>.pl</CODE>. This is the only way that the
https service recognizes the file as a Perl script.</P>
</LI>
<LI>
<P>Ensure that the script is readable by the account used by the EMWAC server. Generally, this
means you should make the script readable by the Everyone group.</P>
</LI>
<LI>
<P>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 EMWAC server (i.e., the
Everyone group).</P>
</LI>
</OL>
<P>When the EMWAC server gets an HTTP request for a file with a <EM>.pl</EM> extension, it tries to
execute <CODE>perl [filename]</CODE>. This is the only way you can get Perl scripts to work on the
EMWAC server, so you need to follow the above directions.</P>
<P>By default, the ActivePerl installation puts the path to <EM>perl.exe</EM> in <CODE>@INC</CODE>.</P>
<P>Because the EMWAC server runs as a service (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make files and environment
variables like <CODE>PATH</CODE> accessible. Just because you can read a script and run it from the
command line doesn't mean that the server can.</P>
<HR>
<H2><A name="How_do_I_configure_IIS_3_0_or_lo">How do I configure IIS 3.0 or lower to support
ActivePerl?</A></H2>
<P>By default, the ActivePerl installation maps the <EM>.plx</EM> 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.</P>
<P>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.</P>
<P>You need to follow these steps to get ActivePerl scripts to run under IIS:</P>
<OL>
<LI>
<P>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 <EM>perl.exe</EM> (for example, <EM>.pl</EM>) and
another to <EM>PerlIS.dll</EM> (for example, <EM>.plx</EM>). Note that mapping an extension in
the script map is <EM>not</EM> the same as associating the extension in Explorer. Use the full
paths to the executable files in the script map.</P>
</LI>
<LI>
<P>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 <EM>cgi-bin</EM> virtual directory and a
real <EM>cgi-bin</EM> subdirectory of the WWW root.</P>
</LI>
<LI>
<P>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 <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A> and <A href="ActivePerl-Winfaq4.html#How_do_I_set_permissions_on_a_fi">How
do I set permissions on a file?</A>.</P>
</LI>
<LI>
<P>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 <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A> and <A href="ActivePerl-Winfaq4.html#How_do_I_set_permissions_on_a_fi">How
do I set permissions on a file?</A>.</P>
</LI>
</OL>
<P>You need to restart the web service after making the Registry changes or installing Perl.</P>
<P>Because IIS runs as a service (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to it.</P>
<HR>
<H2><A name="How_do_I_configure_Microsoft_IIS">How do I configure Microsoft IIS 4.0 to support
ActivePerl?</A></H2>
<P>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 <A href="http://www.microsoft.com/iis/">http://www.microsoft.com/iis/</A></P>
<P>To configure IIS or PWS 4.0 to run Perl scripts:</P>
<OL>
<LI>
<P>Open the IIS 4.0 Internet Service Manager. This will bring up the Microsoft Management
Console with the Internet Service Manager snap-in selected.</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>Select Properties from the Action menu.</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>Click the Configuration button. This opens the Application Configuration dialog.</P>
</LI>
<LI>
<P>Select the App Mappings tab and click the Add button. You see the Add/Edit Application
Extension Mapping dialog.</P>
</LI>
<LI>
<P>To run Perl as a CGI application, type the full path to <EM>Perl.EXE</EM> followed by <CODE>%s
%s</CODE>. When a script is executed, the first <CODE>%s</CODE> will be replaced by the full
path to the script, and the second <CODE>%s</CODE> will be replaced by the script parameters.</P>
</LI>
<LI>
<P>To run Perl for ISAPI, type the full path to <EM>PerlIS.DLL</EM>. The <CODE>%s %s</CODE> is
not required for ISAPI DLLs.</P>
</LI>
<LI>
<P>In the Extension field, type <EM>.pl</EM> or <EM>.plx</EM> (or whatever extension you want to
use).</P>
</LI>
<LI>
<P>The application mapping is now complete. Click the OK button and click OK to dismiss any
remaining dialogs/property sheets.</P>
</LI>
<LI>
<P>Close the IIS 4.0 Internet Service Manager.</P>
</LI>
</OL>
<P>Because IIS runs as a service (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to it.</P>
<HR>
<H2><A name="How_do_I_configure_Netscape_web_">How do I configure Netscape web servers to support
ActivePerl?</A></H2>
<P>If you're using Netscape 1.x servers, you must wrap your Perl scripts in batch files. Refer to
<P>The following information is for Netscape FastTrack Server 2.0. Other 2.0 and 3.0 Netscape
Servers (Communications, Enterprise) should be similar.</P>
<P>To set up ActivePerl to run on FastTrack Server, follow these steps:</P>
<OL>
<LI>
<P>Install FastTrack Server, and make sure you can retrieve HTML pages.</P>
</LI>
<LI>
<P>Associate Perl scripts with the perl interpreter, if you haven't already. See <A href="ActivePerl-Winfaq4.html#How_do_I_associate_Perl_scripts_">How
do I associate Perl scripts with perl?</A> for how to do this. You may need to re-start the
server after making the association.</P>
</LI>
<LI>
<P>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.</P>
</LI>
</OL>
<P>If you would like to access Perl CGI scripts in other directories, you need to associate an
extension, such as <EM>.pl</EM>, 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 <EM>.pl</EM> with
the shellcgi MIME type:</P>
<OL>
<LI>
<P>In the Server Administrator, click Server Preferences, then select MIME Types from the frame
on the left.</P>
</LI>
<LI>
<P>If you want to use <EM>.pl</EM> as the extension for Perl scripts, find and remove the
application/x-perl MIME type (this is mapped to <EM>.pl</EM> by default).</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>Save and apply these changes. You should be able to put a Perl CGI script in any directory,
provided the script ends with the <EM>.pl</EM> suffix.</P>
</LI>
</OL>
<P>If you are having trouble running Perl scripts on your Netscape server, check the following:</P>
<UL>
<LI>
<P>Ensure that the script is readable by the account used by the Netscape service. Generally,
this means you should make the script readable by the Everyone group.</P>
</LI>
<LI>
<P>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 Netscape service (i.e., the
Everyone group).</P>
</LI>
</UL>
<P>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.</P>
<P>Because Netscape servers run as services (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to them.</P>
<P>Some people have reported problems with handling POST'ed data with Perl programs with Netscape
servers. Since Netscape 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.</P>
<HR>
<H2><A name="How_do_I_configure_WebSite_1_0_t">How do I configure WebSite 1.0 to support ActivePerl?</A></H2>
<P>The following information is for setting up O'Reilly WebSite to use ActivePerl for standard CGI
(not PerlIS).</P>
<OL>
<LI>
<P>Install WebSite. Make sure you can retrieve HTML pages before continuing.</P>
</LI>
<LI>
<P>Associate Perl scripts with the perl interpreter, if you haven't already. See <A href="ActivePerl-Winfaq4.html#How_do_I_associate_Perl_scripts_">How
do I associate Perl scripts with perl?</A> for how to do this. You may need to re-start the
server after making the association.</P>
</LI>
<LI>
<P>Set up a Standard CGI directory to hold your Perl scripts. You can use the Server Properties
dialog box do to this.</P>
</LI>
<LI>
<P>Ensure that the script is readable by the account used by the WebSite service. Generally,
this means you should make the script readable by the Everyone group.</P>
</LI>
<LI>
<P>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 WebSite service (i.e., the
Everyone group).</P>
</LI>
</OL>
<P>Because WebSite servers run as services (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to them.</P>
<HR>
<H2><A name="How_do_I_configure_WebSite_Profe">How do I configure WebSite Professional to support
ActivePerl?</A></H2>
<P>The following information is for setting up O'Reilly WebSite Professional to use ActivePerl CGI
(not PerlIS).</P>
<OL>
<LI>
<P>Install WebSite Professional. Make sure you can retrieve HTML pages before continuing.</P>
</LI>
<LI>
<P>Open Server Properties and click the Mapping tab. Server Properties is in the WebSite
Professional folder on the Start menu.</P>
</LI>
<LI>
<P>From the List Selector on the Mapping tab, choose Content Types.</P>
</LI>
<LI>
<P>If there is an existing mapping for the extension you want to use (such as <EM>.pl</EM>),
highlight the mapping and click Delete. Click Apply to immediately apply the change.</P>
</LI>
<LI>
<P>Choose a file extension for Perl, such as <EM>.pl</EM>, and type it into the File Extension
field. Make sure you include the leading period/full stop (.) in the file extension.</P>
</LI>
<LI>
<P>Type wwwserver/shellcgi in the Media or Server-Side Content Type field.</P>
</LI>
<LI>
<P>Click Add. Click Apply to immediately apply the change.</P>
</LI>
<LI>
<P>Change the List Selector to Associations.</P>
</LI>
<LI>
<P>If there is an existing mapping for the extension you want to use (such as <EM>.pl</EM>),
highlight the mapping and click Delete. Click Apply to immediately apply the change.</P>
</LI>
<LI>
<P>Type the file extension you chose in step 5 in the File Extension field. Make sure you
include the leading period/full stop (.) in the file extension.</P>
</LI>
<LI>
<P>Type the full path to Perl.exe, such as <EM>C:\Perl\5.00500\bin\MSWin32-x86\Perl.exe</EM>, in
the Associated EXE or DLL field.</P>
</LI>
<LI>
<P>Click Add. Click Apply to immediately apply the change.</P>
</LI>
<LI>
<P>Close Server Properties. Reply appropriately to ``Terminate active connections and update the
server settings?''. The server is now configured to execute Perl CGI scripts in directories
marked as cgi-bin as well as document directories.</P>
</LI>
</OL>
<P>If you have trouble running scripts, ensure that the script is readable by the account used by
the WebSite service. Generally, this means you should make the script readable by the Everyone
group. Also, 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 WebSite service (i.e., the
Everyone group).</P>
<P>Because WebSite servers run as services (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to them.</P>
<HR>
<H2><A name="How_do_I_configure_Purveyor_to_s">How do I configure Purveyor to support ActivePerl?</A></H2>
<P>The following instructions are for Purveyor 1.2 for Windows NT. Other Purveyor products should be
similar.</P>
<OL>
<LI>
<P>In the Purveyor Control Panel, use the CGI Mapping tab to map the <EM>.pl</EM> extension to <EM>perl.exe</EM>.
Make sure that you use the full path to the executable.</P>
</LI>
<LI>
<P>Also in the Purveyor Control Panel, use the Virtual Servers section to set your CGI Scripts
directory. You need one scripts directory for each virtual server you support. The scripts
directory must be in the data path for the server. Also, make sure that the Disable CGI
Extension checkbox is unchecked.</P>
</LI>
<LI>
<P>Ensure that the script is readable by the account used by the Purveyor service. Generally,
this means you should make the script readable by the Everyone group.</P>
</LI>
<LI>
<P>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 Purveyor service (i.e., the
Everyone group).</P>
</LI>
</OL>
<P>If you have problems while configuring Purveyor to use ActivePerl, you can use the Enable Tracing
checkbox in the Logging tab of the Purveyor Control Panel applet to trace HTTP requests and
responses.</P>
<P>Because Purveyor runs as a service (see <A href="ActivePerl-Winfaq4.html#What_is_a_Windows_NT_service_">What
is a Windows NT service?</A>), you need to take special steps to make sure that files and
environment variables are available to it.</P>
<HR>
<H2><A name="How_do_I_configure_Microsoft_Per">How do I configure Microsoft Personal Web Server 1.0x
for Windows 95 to support ActivePerl?</A></H2>
<P>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 <A href="#How_do_I_configure_IIS_3_0_or_lo">How
do I configure IIS 3.0 or lower to support ActivePerl?</A>.</P>
<HR>
<H2><A name="How_do_I_configure_other_web_ser">How do I configure other web servers to support
ActivePerl?</A></H2>
<P>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:</P>
<UL>
<LI>
<P>Associate a file extension like <EM>.pl</EM> with the perl binary, and let the server know
where the binary is. This may be a shell association, (see <A href="ActivePerl-Winfaq4.html#How_do_I_associate_Perl_scripts_">How
do I associate Perl scripts with perl?</A>), or a custom association.</P>
</LI>
<LI>
<P>Set up a directory where executable scripts go, and put your Perl script there.</P>
</LI>
<LI>
<P>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.</P>
</LI>
</UL>
<P>Because most web servers run as services (see <A href="#How_do_I_configure_IIS_3_0_or_lo">How do
I configure IIS 3.0 or lower to support ActivePerl?</A>), you need to take special steps to make
sure that files and environment variables are available to them.</P>
<HR>
<H2><A name="My_program_runs_fine_from_the_co">My program runs fine from the command line, but bombs
out when run as a CGI script.</A></H2>
<P>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.</P>
<P>Before you do anything else, check this list:</P>
<UL>
<LI>
<P>Make sure you have correctly configured your server for <EM>perl.exe</EM> or <EM>perlis.dll</EM>.
This is often accomplished by mapping a specific extension, such as <EM>.pl</EM> or <EM>.plx</EM>,
to <EM>perl.exe</EM> or <EM>perlis.dll</EM>. Usually, web servers rely on their own mappings,
rather than the Windows command-line mappings.</P>
</LI>
<LI>
<P>If your web server depends on the <CODE>PATH</CODE> variable to find <EM>perl.exe</EM>, make
sure that you put <EM>perl.exe</EM> in your system <CODE>PATH</CODE>, not just your user <CODE>PATH</CODE>.
This only applies to Windows NT/2000.</P>
</LI>
<LI>
<P>If your web server requires directories to be marked as executable, make sure the directory
that contains the script is marked as such.</P>
</LI>
<LI>
<P>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.</P>
</LI>
<LI>
<P>If <EM>Perl.exe</EM> or Perl for ISAPI fail to work as expected check your event logs for
clues.</P>
</LI>
</UL>
<P>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.</P>
<P>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:</P>
<PRE>
# 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);
}
</PRE>
<P>If your script has an error, you may see something like this in the browser:</P>
<PRE>
[Wed Jun 3 09:32:28 1998] C:\inetpub\scripts\test.pl: Error message! at
C:\inetpub\scripts\test.pl line 38.
</PRE>
<P>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.</P>
<P>LWP includes the powerful <EM>lwp-request</EM> script, which lets you see things from the
browser's perspective. Invoke <EM>lwp-request</EM> with the name of a URL to see the content of the
response, as in <CODE>lwp-request http://localhost</CODE>. To inspect the headers of an HTTP
response, invoke <EM>lwp-request</EM> with the <CODE>-de</CODE> switch:</P>
<PRE>
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
</PRE>
<P>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.</P>
<HR>
<H2><A name="This_is_all_such_a_hassle_why_c">This is all such a hassle; why can't I just put
perl.exe in my CGI directory and use it in my URL?</A></H2>
<P>First, the warning: DON'T DO THIS. REALLY. EVEN IF YOU DON'T UNDERSTAND WHY NOT, DON'T.</P>
<P>Now the explanation: the idea here is to put <EM>perl.exe</EM> in your CGI directory (however you
configure that on your server), and use URL syntax like the following:</P>
