ActivePerl FAQ - Web Server Information

# Web Server Information

- NAME
- DESCRIPTION
  - General Web Server Configuration Issues
  - What web servers support ActivePerl?
  - Why does my ActivePerl script run from the command line, but not as a CGI script?
  - Can't I put perl.exe in my CGI directory and call it in the URL? NO!
  - Using the Apache Web Server
  - How do I configure Apache 2.0.x to support ActivePerl?
  - How do I configure Apache 1.3.x to support ActivePerl?
  - Using IIS
  - Using Other Web Servers
  - How do I configure other web servers to support ActivePerl?
  - Testing Your Web Server Configuration
- AUTHOR AND COPYRIGHT

## NAME

ActivePerl-faq6 - Web server information

## DESCRIPTION

ActivePerl Web Server Configuration and Troubleshooting

### General Web Server Configuration Issues

#### What web servers support ActivePerl?

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

#### Why does my ActivePerl script run from the command line, but not as a CGI script?

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.

#### Can't I put perl.exe in my CGI directory and call it in the URL? No!

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.

### Using the Apache Web Server

#### How do I configure Apache 2.0.x to support ActivePerl?

These instructions assume that you have installed the Apache web server according to the instructions for the 2.0.x Windows version.

1. 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.
2. 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

3. Save your changes to the httpd.conf file, and restart the Apache Service using the Apache Service Monitor.
4. Test your configuration as described in the Testing Your Web Server Configuration section below.

#### How do I configure Apache 1.3.x to support ActivePerl?

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:

1. 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.
2. 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.
3. 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";

4. 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:

1. 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.
2. 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

3. After you have made these changes, stop and restart the Apache service.
4. Test your configuration as described in the Testing Your Web Server Configuration section, below.

### Using IIS

The ActivePerl MSI installer can configure script mappings for IIS during installation, and options for doing so are made available if IIS is detected on the system. To configure or re-configure IIS to use ActivePerl after installation, use the ap-iis-config utility.

      ap-iis-config add all
      ap-iis-config delete all
      ap-iis-config list sites

      ap-iis-config add map --ext .cgi --type isapi
      ap-iis-config delete map --ext .plex

      ap-iis-config add vdir --site 1 --name Sample --path C:\www\samples
      ap-iis-config delete vdir --site 2 --name "My Site"

See the ap-iis-config documentation for complete descriptions of all the options.

### Using Other Web Servers

#### How do I configure other web servers 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.

### Testing Your Web Server Configuration

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:

1. 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

2. 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...

## AUTHOR AND COPYRIGHT

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