From a6179cd7cc27d7859b76733c9f21eb33c950df6b Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Thu, 8 Apr 2004 18:06:38 +0000 Subject: [PATCH] Make sure that the CGI tutorial answers all the CGI FAQs that I commonly see. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@103298 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/howto/cgi.html.en | 143 +++++++++++++++++++++----------- docs/manual/howto/cgi.xml | 151 +++++++++++++++++++++++----------- 2 files changed, 201 insertions(+), 93 deletions(-) diff --git a/docs/manual/howto/cgi.html.en b/docs/manual/howto/cgi.html.en index 6c51e61d49..a46c403c80 100644 --- a/docs/manual/howto/cgi.html.en +++ b/docs/manual/howto/cgi.html.en @@ -69,7 +69,7 @@ directive looks like:

- ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ + ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The example shown is from your default httpd.conf @@ -84,13 +84,13 @@ that everything under that URL prefix will be considered a CGI program. So, the example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from - the directory /usr/local/apache/cgi-bin/, and should be + the directory /usr/local/apache2/cgi-bin/, and should be treated as a CGI program.

For example, if the URL http://www.example.com/cgi-bin/test.pl is requested, Apache will attempt to execute the file - /usr/local/apache/cgi-bin/test.pl + /usr/local/apache2/cgi-bin/test.pl and return the output. Of course, the file will have to exist, and be executable, and return output in a particular way, or Apache will return an error message.

@@ -109,6 +109,11 @@ If they want to have their own CGI programs, but don't have access to the main cgi-bin directory, they will need to be able to run CGI programs elsewhere.

+ +

There are two steps to allowing CGI execution in an arbitrary + directory. First, the cgi-script handler must be + activated using the AddHandler or SetHandler directive. Second, + ExecCGI must be specified in the Options directive.

Explicitly using Options to permit CGI execution

@@ -119,7 +124,7 @@ directory:

- <Directory /usr/local/apache/htdocs/somedir>
+ <Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
 @@ -133,41 +138,49 @@ programs:

- AddHandler cgi-script cgi pl + AddHandler cgi-script .cgi .pl

.htaccess files

-

A .htaccess file is a way - to set configuration directives on a per-directory basis. When Apache - serves a resource, it looks in the directory from which it is serving - a file for a file called .htaccess, and, if it - finds it, it will apply directives found therein. +

The .htaccess tutorial + shows how to activate CGI programs if you do not have + access to httpd.conf.

+ + +

User Directories

- .htaccess files can be permitted with the - AllowOverride directive, - which specifies what types of directives can - appear in these files, or if they are not allowed at all. To - permit the directive we will need for this purpose, the - following configuration will be needed in your main server - configuration:

+ +

To allow CGI program execution for any file ending in + .cgi in users' directories, you can use the + following configuration.

- AllowOverride Options + <Directory /home/*/public_html>
+ + Options +ExecCGI
+ AddHandler cgi-script .cgi
+ + </Directory>

-

In the .htaccess file, you'll need the - following directive:

+

If you wish designate a cgi-bin subdirectory of + a user's directory where everything will be treated as a CGI + program, you can use the following.

- Options +ExecCGI + <Directory /home/*/public_html/cgi-bin>
+ + Options ExecCGI
+ SetHandler cgi-script
+ + </Directory>

-

which tells Apache that execution of CGI programs is - permitted in this directory.

+
top

Writing a CGI program

@@ -242,7 +255,9 @@
The output of your CGI program
-
Great! That means everything worked fine.
+
Great! That means everything worked fine. If the output is correct, + but the browser is not processing it correctly, make sure you have the + correct Content-Type set in your CGI program.
The source code of your CGI program or a "POST Method Not Allowed" message
@@ -286,30 +301,22 @@ files, those files will need to have the correct permissions to permit this.

-

The exception to this is when the server is configured to - use suexec. This program allows - CGI programs to be run under different - user permissions, depending on which virtual host or user - home directory they are located in. Suexec has very strict - permission checking, and any failure in that checking will - result in your CGI programs failing with an "Internal Server - Error". In this case, you will need to check the suexec log - file to see what specific security check is failing.

-

Path information

+

Path information and environment

When you run a program from your command line, you have certain information that is passed to the shell without you - thinking about it. For example, you have a path, which tells - the shell where it can look for files that you reference.

- -

When a program runs through the web server as a CGI - program, it does not have that path. Any programs that you - invoke in your CGI program (like 'sendmail', for example) - will need to be specified by a full path, so that the shell - can find them when it attempts to execute your CGI + thinking about it. For example, you have a PATH, + which tells the shell where it can look for files that you + reference.

+ +

When a program runs through the web server as a CGI program, + it may not have the same PATH. Any programs that you + invoke in your CGI program (like sendmail, for + example) will need to be specified by a full path, so that the + shell can find them when it attempts to execute your CGI program.

A common manifestation of this is the path to the script @@ -322,17 +329,37 @@

Make sure that this is in fact the path to the interpreter.

+ +

In addition, if your CGI program depends on other environment variables, you will need to + assure that those variables are passed by Apache.

+ -

Syntax errors

+

Program errors

Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make - the above two mistakes. Always attempt to run your program - from the command line before you test if via a browser. This - will eliminate most of your problems.

+ the above two mistakes. The first thing to do is to make + sure that your program runs from the command line before + testing it via the web server. For example, try:

+ +

+ cd /usr/local/apache2/cgi-bin
+ ./first.pl +

+ +

(Do not call the perl interpreter. The shell + and Apache should find the interpreter using the path information on the first line of + the script.)

+ +

The first thing you see written by your program should be + a set of HTTP headers, including the Content-Type, + followed by a blank line. If you see anything else, Apache will + return the Premature end of script headers error if + you try to run it through the server. See Writing a CGI program above for more + details.

Error logs

@@ -346,6 +373,30 @@ error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.

+ +

Suexec

+ + +

The suexec support program + allows CGI programs to be run under different user permissions, + depending on which virtual host or user home directory they are + located in. Suexec has very strict permission checking, and any + failure in that checking will result in your CGI programs + failing with Premature end of script headers.

+ +

To check if you are using suexec, run apachectl + -V and check for the location of SUEXEC_BIN. + If Apache finds an suexec binary there on startup, suexec will + be actived.

+ +

Unless you fully understand suexec, you should not be using it. + To disable suexec, simply remove (or rename) the suexec + binary pointed to by SUEXEC_BIN and then restart the + server. If, after reading about suexec, + you still wish to use it, then run suexec -V to find + the location of the suexec log file, and use that log file to + find what policy you are violating.

+
top

What's going on behind the scenes?

diff --git a/docs/manual/howto/cgi.xml b/docs/manual/howto/cgi.xml index 70094cf37a..ebcb173919 100644 --- a/docs/manual/howto/cgi.xml +++ b/docs/manual/howto/cgi.xml @@ -71,7 +71,7 @@ directive looks like:

- ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ + ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

The example shown is from your default httpd.conf @@ -88,13 +88,13 @@ that everything under that URL prefix will be considered a CGI program. So, the example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from - the directory /usr/local/apache/cgi-bin/, and should be + the directory /usr/local/apache2/cgi-bin/, and should be treated as a CGI program.

For example, if the URL http://www.example.com/cgi-bin/test.pl is requested, Apache will attempt to execute the file - /usr/local/apache/cgi-bin/test.pl + /usr/local/apache2/cgi-bin/test.pl and return the output. Of course, the file will have to exist, and be executable, and return output in a particular way, or Apache will return an error message.

@@ -114,6 +114,14 @@ If they want to have their own CGI programs, but don't have access to the main cgi-bin directory, they will need to be able to run CGI programs elsewhere.

+ +

There are two steps to allowing CGI execution in an arbitrary + directory. First, the cgi-script handler must be + activated using the AddHandler or SetHandler directive. Second, + ExecCGI must be specified in the Options directive.

@@ -125,7 +133,7 @@ directory:

- <Directory /usr/local/apache/htdocs/somedir>
+ <Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
 @@ -140,41 +148,49 @@ programs:

- AddHandler cgi-script cgi pl + AddHandler cgi-script .cgi .pl
.htaccess files -

A .htaccess file is a way - to set configuration directives on a per-directory basis. When Apache - serves a resource, it looks in the directory from which it is serving - a file for a file called .htaccess, and, if it - finds it, it will apply directives found therein. - - .htaccess files can be permitted with the - AllowOverride directive, - which specifies what types of directives can - appear in these files, or if they are not allowed at all. To - permit the directive we will need for this purpose, the - following configuration will be needed in your main server - configuration:

+

The .htaccess tutorial + shows how to activate CGI programs if you do not have + access to httpd.conf.

+
+ +
+ User Directories + +

To allow CGI program execution for any file ending in + .cgi in users' directories, you can use the + following configuration.

- AllowOverride Options + <Directory /home/*/public_html>
+ + Options +ExecCGI
+ AddHandler cgi-script .cgi
+ + </Directory> -

In the .htaccess file, you'll need the - following directive:

+

If you wish designate a cgi-bin subdirectory of + a user's directory where everything will be treated as a CGI + program, you can use the following.

- Options +ExecCGI + <Directory /home/*/public_html/cgi-bin>
+ + Options ExecCGI
+ SetHandler cgi-script
+ + </Directory> -

which tells Apache that execution of CGI programs is - permitted in this directory.

+
@@ -249,7 +265,9 @@
The output of your CGI program
-
Great! That means everything worked fine.
+
Great! That means everything worked fine. If the output is correct, + but the browser is not processing it correctly, make sure you have the + correct Content-Type set in your CGI program.
The source code of your CGI program or a "POST Method Not Allowed" message
@@ -293,30 +311,22 @@ files, those files will need to have the correct permissions to permit this.

-

The exception to this is when the server is configured to - use suexec. This program allows - CGI programs to be run under different - user permissions, depending on which virtual host or user - home directory they are located in. Suexec has very strict - permission checking, and any failure in that checking will - result in your CGI programs failing with an "Internal Server - Error". In this case, you will need to check the suexec log - file to see what specific security check is failing.

- Path information + Path information and environment

When you run a program from your command line, you have certain information that is passed to the shell without you - thinking about it. For example, you have a path, which tells - the shell where it can look for files that you reference.

- -

When a program runs through the web server as a CGI - program, it does not have that path. Any programs that you - invoke in your CGI program (like 'sendmail', for example) - will need to be specified by a full path, so that the shell - can find them when it attempts to execute your CGI + thinking about it. For example, you have a PATH, + which tells the shell where it can look for files that you + reference.

+ +

When a program runs through the web server as a CGI program, + it may not have the same PATH. Any programs that you + invoke in your CGI program (like sendmail, for + example) will need to be specified by a full path, so that the + shell can find them when it attempts to execute your CGI program.

A common manifestation of this is the path to the script @@ -329,17 +339,40 @@

Make sure that this is in fact the path to the interpreter.

+ +

In addition, if your CGI program depends on other environment variables, you will need to + assure that those variables are passed by Apache.

+
- Syntax errors + Program errors

Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make - the above two mistakes. Always attempt to run your program - from the command line before you test if via a browser. This - will eliminate most of your problems.

+ the above two mistakes. The first thing to do is to make + sure that your program runs from the command line before + testing it via the web server. For example, try:

+ + + cd /usr/local/apache2/cgi-bin
+ ./first.pl + + +

(Do not call the perl interpreter. The shell + and Apache should find the interpreter using the path information on the first line of + the script.)

+ +

The first thing you see written by your program should be + a set of HTTP headers, including the Content-Type, + followed by a blank line. If you see anything else, Apache will + return the Premature end of script headers error if + you try to run it through the server. See Writing a CGI program above for more + details.

@@ -353,6 +386,30 @@ error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.

+ +
+ Suexec + +

The suexec support program + allows CGI programs to be run under different user permissions, + depending on which virtual host or user home directory they are + located in. Suexec has very strict permission checking, and any + failure in that checking will result in your CGI programs + failing with Premature end of script headers.

+ +

To check if you are using suexec, run apachectl + -V and check for the location of SUEXEC_BIN. + If Apache finds an suexec binary there on startup, suexec will + be actived.

+ +

Unless you fully understand suexec, you should not be using it. + To disable suexec, simply remove (or rename) the suexec + binary pointed to by SUEXEC_BIN and then restart the + server. If, after reading about suexec, + you still wish to use it, then run suexec -V to find + the location of the suexec log file, and use that log file to + find what policy you are violating.

+
-- 2.50.1