NCSA HTTPd's Virtual Directory Structure

NCSA HTTPd allows you to present a unified directory structure to the public, but allows for a fairly flexible structure of mapping this view onto the actual filesystem. This tutorial attempts to help you understand what NCSA HTTPd is capable of.

Constructing URLs to your Server

 Before you do anything, you should read this URL primer to familiarize yourself with URLs. You will want to pay attention to the section referring to HTTP URLs in particular. The short version is given below:

Definition

HTTP URLs have the basic form:

http://servername:port/path#section

servername
Your server's full hostname. It can be the server's real name or a DNS alias. It might also be the servername of one of the VirtualHosts your system is carrying.
port
This is the port which your server is listening on. Specifying it in the URL is optional. If omitted, it is assumed to be 80.
path
This is the virtual path to the document on your server.
section
The document you reference might be split into sections using the <A NAME="section"> HTML directive. You can cause a browser to jump to that section of the page by placing a # and the section name after the path

What Port am I running on?

The standard HTTP port, as mentioned above, is port 80. The standard port for an SSL server is 443.

If you are not running the server as root, then it can not be on any port below 1024.

If you are running a test server, or a personal server, you might want to choose a higher port number. Some common port numbers for these types of servers are 8001, 8080, and 1234. You can only set the port number using the Port directive if you set the ServerType to standalone. If you set it to inetd, then the server number is set in the /etc/services file.

How does the Server translate the URL Path?

The server translates the URL path as follows:

  1. It looks for any globally defined translation in the order presented in the Server Resource Map. A translation is any Alias, ScriptAlias, Redirect, RedirectPermanent, or RedirectTemp in the Server Resource Map. It compares the URL path with the translations, and will replace the matching portion of the translation with the mapping in the Server Resource Map. If the translation is one of the Redirects, then the server replies to the browser telling it to procede to the new URL. If the translation is a ScriptAlias, then the server will attempt to execute the file it references, and will return an error if that file is not executable.
    Note: In versions of NCSA HTTPd prior to 1.5, there was a limit of 20 for the number of available translations. There is no such limit in NCSA HTTPd 1.5 and beyond

  2. If the URL path doesn't match any of the translations, then It looks for a prefix of /~, and if UserDir is not DISABLED, it will look in the user's public_html subdirectory for the file.

  3. The default is to add the DocumentRoot to the beginning of URL path and process the request.

Sounds easy? Well, there is one more complication due to CGI and SSI. Both CGI scripts and SSI documents allow for path information to be passed to them in the URL. After the server has determined the filename using the above heuristic, it attempts to find the file on disk that matches. It will start with the full path, and then remove a directory at a time (as denoted by the / character) until it finds an existing file. If that file is either a CGI script or SSI document, then the server will serve that document and set the PATH_INFO environment variable for use in the CGI script or SSI document. If you are providing a directory index, PATH_INFO will only be provided if the index is referenced (ie, /index.cgi/path/info). See the CGI, SSI, and Index documentation.

What does the server present if the URL translates to a directory?

 If the URL maps to a directory, the server provides an Index. The server first searches (in order) for a file in that directory which matches the files listed in the DirectoryIndex directive.

If it cannot find one of these, it then checks to see if you have enabled Indexes for that directory using the Options directive. (Options Indexes). If the Indexes option is allowed, the server will generate a directory index. See the Index Tutorial for more information on controlling how the server creates the Index.

[Back] Return to Tutorial Index
[Back] Return to Installation overview
[Back] Return to Imagemapping
[Back] Return to Includes Tutorial
NCSA HTTPd Development Team / httpd@ncsa.uiuc.edu / 04-08-96