docs/manual/cgi_path.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
<!-- $Revision: 1.7 $ -->

<!--
 Copyright 2002-2004 The Apache Software Foundation

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="cgi_path.xml.meta">

  <title>PATH_INFO Changes in the CGI Environment</title>

  <summary>
    <p>As implemented in Apache 1.1.1 and earlier versions, the
    method Apache used to create PATH_INFO in the CGI environment
    was counterintuitive, and could result in crashes in certain
    cases. In Apache 1.2 and beyond, this behavior has changed.
    Although this results in some compatibility problems with
    certain legacy CGI applications, the Apache 1.2 behavior is
    still compatible with the CGI/1.1 specification, and CGI
    scripts can be easily modified (<a href="#compat">see
    below</a>).</p>
  </summary>

  <section id="prob"><title>The Problem</title>
    <p>Apache 1.1.1 and earlier implemented the PATH_INFO and
    SCRIPT_NAME environment variables by looking at the filename,
    not the URL. While this resulted in the correct values in many
    cases, when the filesystem path was overloaded to contain path
    information, it could result in errant behavior. For example,
    if the following appeared in a config file:</p>

    <example>
      Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
    </example>    

    <p>In this case, <code>user.cgi</code> is the CGI script, the
    "/ralph" is information to be passed onto the CGI. If this
    configuration was in place, and a request came for
    "<code>/cgi-ralph/script/</code>", the code would set PATH_INFO
    to "<code>/ralph/script</code>", and SCRIPT_NAME to
    "<code>/cgi-</code>". Obviously, the latter is incorrect. In
    certain cases, this could even cause the server to crash.</p>
  </section>

  <section id="solution"><title>The Solution</title>
    <p>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO
    by looking directly at the URL, and determining how much of the
    URL is client-modifiable, and setting PATH_INFO to it. To use
    the above example, PATH_INFO would be set to
    "<code>/script</code>", and SCRIPT_NAME to
    "<code>/cgi-ralph</code>". This makes sense and results in no
    server behavior problems. It also permits the script to be
    guaranteed that
    "<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>"
    will always be an accessible URL that points to the current
    script, something which was not necessarily true with previous
    versions of Apache.</p>

    <p>However, the "<code>/ralph</code>" information from the
    <code>Alias</code> directive is lost. This is unfortunate, but
    we feel that using the filesystem to pass along this sort of
    information is not a recommended method, and a script making
    use of it "deserves" not to work. Apache 1.2b3 and later,
    however, do provide <a href="#compat">a workaround.</a></p>
  </section>

  <section id="compat">
    <title>Compatibility with Previous Servers</title>

    <p>It may be necessary for a script that was designed for
    earlier versions of Apache or other servers to need the
    information that the old PATH_INFO variable provided. For this
    purpose, Apache 1.2 (1.2b3 and later) sets an additional
    variable, FILEPATH_INFO. This environment variable contains the
    value that PATH_INFO would have had with Apache 1.1.1.</p>

    <p>A script that wishes to work with both Apache 1.2 and
    earlier versions can simply test for the existence of
    FILEPATH_INFO, and use it if available. Otherwise, it can use
    PATH_INFO. For example, in Perl, one might use:</p>

    <example>
      $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
    </example>

    <p>By doing this, a script can work with all servers supporting
    the CGI/1.1 specification, including all versions of
    Apache.</p>
  </section>
</manualpage>