2 Concepts

This chapter introduces you to the Oracle HTTP Server directory structure, configuration files, configuration file syntax, modules, and directives.

Topics discussed are:

Understanding Oracle HTTP Server Directory Structure
Accessing Configuration Files
Configuration Files Syntax
Classes of Directives
Scope of Directives
Understanding Modules
About .htaccess Files

2.1 Understanding Oracle HTTP Server Directory Structure

Oracle HTTP Server is installed in the ORACLE_HOME/Apache directory on UNIX or ORACLE_HOME\Apache directory on Windows.

Figure 2-1 illustrates Oracle HTTP Server directory structure.

Figure 2-1 Oracle HTTP Server Directory Structure

Description of "Figure 2-1 Oracle HTTP Server Directory Structure"

The Apache directory is located at the top level under the ORACLE_HOME. It contains subdirectories for configuring modules such as mod_plsql, and mod_oradav. It also contains another directory called Apache, which is the base directory of Oracle HTTP Server. Table 2-1 contains information about the subdirectories within the ORACLE_HOME/Apache/Apache directory.

Table 2-1 Apache Subdirectories

Directory Name	Contents
`bin`	Contains Oracle HTTP Server executables.
`cgi-bin`	Contains the CGI scripts. These are programs or shell scripts that can be executed by Oracle HTTP Server on the behalf of its clients.
`conf`	Contains the configuration files.
`fastcgi`	Contains the fastcgi runtime libraries, the necessary bits that you need to build your own fastcgi applications.
`fcgi-bin`	Contains FastCGI scripts.
`htdocs`	Contains the HTML scripts. The `htdoc` directory and its subdirectories are accessible to anyone on the Web, and therefore pose a severe security risk if used for anything other than publicly available data.
`icons`	Contains the icons that Oracle HTTP Server uses when displaying information or error messages.
`include`	Contains header files for building custom modules.
`libexec`	Contains the shared library files for modules.
`log`	Contains the log data, for both access and errors.
`man`	Contains the `man` page for Oracle HTTP Server
`mod_perl`	Contains sample code for `mod_perl`. It also contains `mod_perl` specific libraries, and `man` pages.
`php`	Contains sample code for `mod_php`. On UNIX, the `php` directory also contains the PHP CLI (PHP executables), `man` pages, and headers. The headers enable you to build your own PHP extensions. On Windows, it contains the PHP CLI, and OCI extension to PHP (on UNIX, the OCI extension is compiled into `mod_php`).

2.2 Accessing Configuration Files

The main configuration file for Oracle HTTP Server is httpd.conf. This file, along with other configuration files used by the server are located in:

UNIX: ORACLE_HOME/Apache/Apache/conf
Windows: ORACLE_HOME\Apache\Apache\conf

Some of these files are read only once when the server starts or is reloaded, whereas some files are read every time a related file or directory is requested.

The configuration files which are read only once are called server-wide configuration files.

2.3 Configuration Files Syntax

Directives are configuration instructions for Oracle HTTP Server. Directives are placed in httpd.conf and other configuration files to determine the behavior of the server.

Oracle HTTP Server configuration files should contain one directive per line. The back-slash "\" can be used as the last character on a line to indicate that the directive continues onto the next line. There must be no other characters or white space between the back-slash and the end of the line.

Directives in the configuration files are case-insensitive, but arguments to directives are often case-sensitive. Lines which begin with the character "#" are considered comments, and are ignored. Comments may not be included on a line after a configuration directive. Blank lines and white space occurring before a directive are ignored, so you may indent directives for clarity.

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 "/private1/oracle/Apache/Apache/htdocs"
 
#
# Each directory to which Apache has access, can be configured with respect
# to which services and features are allowed and/or disabled in that
# directory (and its subdirectories). 
#
# First, we configure the "default" to be a very restrictive set of 
# permissions.  
#
<Directory />
    Options FollowSymLinks MultiViews
    AllowOverride None
</Directory>

2.4 Classes of Directives

Table 2-2 classifies directives according to the context in which they can be used: global, per-server, and per-directory.

Table 2-2 Classes and Directives

Class	Context	Where Used
global	server configuration	Inside server configuration files, but only outside of container directives (directives such as `VirtualHost` that have a start and end directive).
per-server	server configuration, virtual host	Inside server configuration files, both outside (for the main server) and inside `VirtualHost` directives.
per-directory	server configuration, virtual host, directory	Everywhere; particularly inside the server configuration files.

Note:

In Table 2-2, each class is a subset of the class preceding it. For example, directives from the per-directory class can also be used in the per-server and global contexts, and directives from the per-server class can be used in the global context.

2.5 Scope of Directives

Directives placed in the main configuration files apply to the entire server. If you wish to change the configuration for only a part of the server, you can scope your directives by placing them in specific sections.

There are two types of directives:

Container Directives
Block Directives

2.5.1 Container Directives

Container directives specify the scope within which directives take effect. The following container directives are discussed in detail in subsequent sections:

<Directory>
<DirectoryMatch>
<Files>
<FilesMatch>
<Limit>
<LimitExcept>
<Location>
<LocationMatch>
<VirtualHost>

2.5.1.1 <Directory>

Encloses a group of directives that apply only to the named directory and subdirectories of that directory. Any directory that is allowed in a directory context may be used. The directory is either the full path to a directory, or a wildcard string. In a wildcard string, ? matches any single character, and * matches any sequence of characters. It is important to note that <Directory /> operates on the whole file system, where as <Directory dir> refers to absolute directories. <Directory> containers cannot be nested inside each other, but can refer to directories in the document root that are nested.

2.5.1.2 <DirectoryMatch>

Specifies regular expressions, instead of using the tilde form of <Directory> with wildcards in the directory specification. The following two examples have the same result, matching directories starting with web and ending with a number from 1 to 9:

<Directory ~/web[1-9]/>
<DirectoryMatch "/web[1-9]/">

2.5.1.3 <Files>

The <Files file> and </Files> directives support access control by filename. It is comparable to the <Directory> and <Location> directives. The directives given within this section can be applied to any object within a base name (the last component of the filename) matching the specified file name. <Files> sections are processed in the order that they appear in the configuration file, after the <Directory> sections, and .htaccess files are read, but before <Location> sections. Note that the <Files> directives can be nested inside <Directory> sections to restrict the portion of the file system to which they apply.

2.5.1.4 <FilesMatch>

Provides access control by filename, just as the <Files> directive does. However, it accepts regular expressions.

2.5.1.5 <Limit>

<Limit method> defines a block according to the HTTP method of the incoming request. The following example limits the application of the directives that follow scripts that use the specified method:

<Limit POST PUT OPTIONS>
  order deny, allow
  deny from all
  allow from 127.0.0.192
</Limit>

Generally, <Limit> should not be used unless needed. It is useful only for restricting directives to particular methods. <Limit> is frequently used with other containers, and it is contained in any of them.

2.5.1.6 <LimitExcept>

Restricts access controls to all HTTP methods except the named ones.

2.5.1.7 <Location>

Limits the application of the directives within a block to those URLs specified, rather than to the physical file location like the <Directory> directive. <Location> sections are processed in the order that they appear in the configuration file, after the <Directory> sections, and .htaccess files are read, and after the <Files> sections. <Location> accepts wildcard directories and regular expressions with the tilde character.

2.5.1.8 <LocationMatch>

Functions in an identical manner to <Location>. You should use it for specifying regular expressions instead of the tilde form of <Location> with wildcards in the location specification.

For example:

<LocationMatch "/(extra|special)/data">

matches the URLs that contained the /extra/data or /special/data sub string.

2.5.1.9 <VirtualHost>

Oracle HTTP Server has the capabilities to serve many different Web sites simultaneously. Directives can also be scoped by placing them inside <VirtualHost> sections, so that they will only apply to requests for a particular Web site.

Virtual host refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent hostname. For example, it is often desirable for companies sharing a Web server to have their own domain, and Web servers accessible, for example, www.oracle1.com and www.oracle2.com, without requiring you to know any extra path information.

Oracle HTTP Server supports both IP-based virtual hosts and name-based virtual hosts. The latter variant is sometimes also called host-based or non-IP virtual hosts.

Each virtual host can have its own name, IP address, and error and access logs. Within a <VirtualHost> container, you can set up a large number of individual servers run by a single invocation of the Oracle HTTP Server. With virtual hosting, you can specify a replacement set of the server-level configuration directives that define the main host, and are not allowed in any other container.

2.5.2 Block Directives

Specify a condition which must be true in order for directives within to take effect.

<IfModule> and <IfDefine> are block directives rather than container directives because they do not limit the scope of the directives they contain. They define whether Oracle HTTP Server parses the directives inside the block into its configuration, and the directives are ignored once the server is running.

2.6 Understanding Modules

Oracle HTTP Server is a modular server. Modules extend the basic functionality of the Web server, and support integration between Oracle HTTP Server and other Oracle Application Server components. Oracle HTTP Server includes Apache modules as well as Oracle HTTP Server modules.

You can add modules using the LoadModule directive. Here is an example of LoadModule usage:

LoadModule status_module modules/mod_status.so

2.7 About .htaccess Files

Oracle HTTP Server allows for decentralized management of configuration through special files places inside the Web tree. The special files are usually called .htaccess, but can be specified in the AccessFileName directive. Directives placed in .htaccess files apply to the directory where you place the file, and all subdirectories. The .htaccess files follow the same syntax as the main configuration files. Since .htaccess files are read on every request, changes made in these files take immediate effect.

The server administrator further controls what directives may be placed in .htaccess files by configuring the AllowOverride directive in the main configuration files.