Oracle WebServer User's Guide

Contents Index Home Previous Next

Web Listener Administration

The Oracle Web Listener is a reliable, high-performance HTTP server suitable for high-traffic web applications where quick response is crucial.

From the Web Listener Administration page, shown in Figure 7 - 5, you can move to other pages that provide a convenient way for you to do the following:

Figure 7 - 5. Web Listener Administration Page

To create a new Oracle Web Listener, click Create New Oracle Web Listener. This takes you to the Listener Creation form.

To perform any of the other operations, choose the appropriate existing Web Listener from the list provided. This list uniquely identifies each Web Listener by the network port on which it is configured to listen. For your convenience, the directory in which the configuration file resides is specified beside the port number. Unlike the port number, this directory need not be unique.

If a Web Listener is running, the word "running" appears beside it in the list.

To modify an existing Oracle Web Listener, select it in the list and click Configure. This takes you to the Configure Extended Parameters form, with the current parameter values filled in. Effect the changes by writing over the current values. For information on the parameters themselves, see "Configure Extended Parameters," later in this chapter.

To start a currently-stopped Oracle Web Listener, select it in the list and click Start.

To stop a currently-running Oracle Web Listener, select it in the list and click Stop.

Note: You might need to perform a manual startup of an existing Web Listener if you inadvertently shut down the Web Listener that the Administration Utility itself is using. To find out how to do this, see "The WLCTL"[*].

The Oracle Web Listener Creation Form

Use this form, shown in the next two figures, to create a new Oracle Web Listener by filling in the listed parameters. These are the parameters the Web Listener requires in order to run. After filling in all required parameters, press the appropriate button to choose a Basic Configuration or an Advanced Configuration. In either case, the Web Listener is created. If you choose Basic Configuration, the parameters you fill in here are all that are needed, and you can start the Web Listener you have created. If you choose Advanced Configuration, you go to the Configure Extended Parameters form to provide optional information. This is equivalent to selecting an existing Web Listener from the list in the initial Web Listener Administration page and clicking Configure. For more information on the Configure Extended Parameters form, see "The Configure Extended Parameters Form" later in this chapter.

Figure 7 - 6. Listener Creation Form, Part 1

The Basic Configuration Parameters

The parameters required for a basic configuration are explained below:

Host Name This is the name of the machine on which the Oracle Web Listener is to reside. It can either be an actual machine name or an alias in the form of a domain name, such as:

www.oracle.com

Port Number The Oracle Web Listener listens for network messages on a particular port. Use this parameter to specify that port. Numbers can range from 0 to 65535 with numbers below 1024 requiring superuser privileges on UNIX systems.

Configuration Directory This is the directory where the configuration file for the Web Listener is to be located. A default is provided.

Figure 7 - 7. Listener Creation Form, Part 2

Web Listener Root (/) Directory This is the directory that serves as the root (/) directory for the Web Listener. This is often called the "Document Root". It is used to resolve client calls that do not specify a directory. Thus a URL that does not contain a directory, such as http://www.oracle.com/index.html, causes the Web Listener to retrieve the document "index.html" from the directory specified here.

User ID (UNIX only) The User ID specifies the user (or user identification number) under whose privileges the Web Listener executes. To acquire these privileges, the Web Listener must be owned by this user or by root with "Set user ID" set. The User ID can be either a username or a user ID number. The default is the effective ID. Specifying the Oracle owner or an Oracle user with the DBA role is not advised, as this compromises database security. For more information, see "roles" and "Database Administrators" in the Oracle7 Server Concepts Manual.

Group ID (UNIX only) The Group ID specifies the group (or group identification number) under whose privileges the Web Listener executes. To acquire these privileges, the Web Listener must be owned by this group or by root with "Set group ID" set. The Group ID can be either a group name or a GID number. The default is the effective GID.

Note that any Oracle Web Listener that invokes the Oracle Web Agent must have read access to the OWA configuration file (owa.cfg). However, since this file contains Oracle usernames and their corresponding passwords, it is recommended that read permissions only be given to the oracle owner and to one privileged group. This is the group that a Web Listener should run under if it is going to run the Oracle Web Agent.

A convenient group to use for this is the OracleDBA group. However, if you run an Oracle Web Listener under the DBA group, you will want to place strict controls on who can create CGI programs that will be invoked by that Web Listener. This is because the CGI program will run with group DBA privileges, and someone with malicious intent could potentially startup and shutdown your Oracle database, or even remove Oracle files. If you wish to avoid this potential security risk, then you need to do the following:

Note: If at any future point in time you remove the owa.cfg file, you must reset its group ownership when it is recreated.

Starting a New Oracle Web Listener

Once you have create a Web Listener, you are shown a Success! message. At this point, you are ready to start your new Oracle Web Listener. Ordinarily, you do this by navigating to the Oracle Web Listener Administration page and clicking start. Note that most web browsers buffer visited pages, and therefore do not reload them when you return to them using something like a Back button. For the new Web Listener to be listed as available for startup, you must navigate to it in such a way that the page is reloaded, for example by reentering the URL.

Reinitializing the Oracle Web Listener

If you selected Advanced Configuration and all the parameters you entered were valid, you will be shown a Success! message. You will then be presented with the Web Listener Configure Extended Parameters form which allows you to modify any of the Oracle Web Listener configuration parameters. It is important to remember that once the Web Listener is started, however, it does not automatically recognize new files added to its virtual file system or parameters changed in its configuration file. If you would like to add files to the Web Listener, you should navigate to the Web Listener Administration page and click Configure next to the Web Listener you want to modify.

The Configure Extended Parameters Form

This form provides a convenient way to customize an existing Oracle Web Listener for your particular environment. By using this form, you can avoid having to manually edit the Web Listener configuration file, thus eliminating the need to be familiar with the exact syntax for each parameter.

From this form, you will be able to customize the following:

To go to the form for any of these sets of parameters, click it in the list. Alternatively, you can scroll through the Configure Extended Parameters Form to visit each parameter set in sequence except Security Definitions, which you can reach only by clicking.

These parameter sets are explained later in this chapter. For more information, see "Configuration Parameters"[*].

Below each parameter set are three buttons. Click one to apply the changes you have made. The buttons are as follows:

Copy Web Listener If you select this button, you must first change the Port Number listed in the Network Parameters section on this form. Then, the entire contents of this form will be used to create a new configuration file and thus a new Oracle Web Listener, leaving the existing Web Listener's configuration file intact. If you reached this form as part of a "create" operation, two Web Listeners are created.

Modify Web Listener Pushing this button will overwrite the existing Oracle Web Listener's configuration file. This operation creates a new Web Listener and deletes the existing one. If you reached this form as part of a "create" operation, one Web Listener is created.

Delete Web Listener Pushing this button will bring up a dialog for you to confirm the deletion. Confirming will do the following:

Network Parameters

This section defines the following parameters:

Host Name The Host Name is the name of the machine on which the Web Listener executes. You must provide this parameter if the Web Listener cannot determine the host name or if the Web Listener executes under an alias. The Web Listener needs this information for logging purposes and to answer SNMP (Simple Network Management Protocol, an Internet standard protocol for checking the status of network components) requests for status. If no host name is specified here, the Web Listener uses the primary Internet address as the default.

Host Address The Host Address is the IP address on which the Web Listener accepts connections. Specifying this address enables a Web Listener residing on a multi-homed machine to designate explicitly the direction from which it receives connections. Multi-homed machines are machines that are configured to have more than one IP address. Specifying ANY, which is the default, indicates that the Web Listener is willing to accept connections arriving on any of its available IP addresses. Leave the parameter set to ANY unless you have a specific reason for changing it.

Port Number The Port Number is the advertised port on which the Web Listener listens for connections. Except for the value Port Number = 0, any port number is valid provided the Web Listener has the authority to use the requested port. Port numbers between 0 and 1023 are reserved ports and require root (or special) privileges in order to be used. Non-privileged processes can use any port greater than or equal to 1024 unless those ports are reserved for some other use. Ordinarily, the Web Listener uses 80 as the default port if no port number is specified

Max Connect Count The Maximum Connect Count is the maximum number of simultaneous connections to the Web Listener that the Web Listener will accept. After the maximum count is reached, the Web Listener ignores requests for new connections. The default value is 50. The maximum and optimal value is 338.

DNS Resolution Domain Name Service Resolution indicates whether and when the Web Listener will resolve hostnames from IP addresses. If the value of this parameter is set to ALWAYS, then the Web Listener always resolves the name. If it is set to LAZY, then the Web Listener resolves the name only on demand. If it is set to LAZY_WITH_CGI, then the Web Listener also resolves the name on demand for CGI applications. If it is set to NEVER, then the Web Listener never resolves the name, even on demand. The default is NEVER.

Web Listener PID The Web Listener PID file is a one-line file that contains the Web Listener's process identifier. There is no default. This information can be used from a UNIX shell command line to stop the Web Listener, determine its status, or reinitialize a Web Listener that is already running. Normally, however, you use the Administration Utility itself to do these things.

Log File Parameters

The following parameters are defined in this section:

Log File Directory The Log File Directory determines the directory where error and information logs are kept. You need to make sure that this directory actually exists, because the Web Listener will not create one if it does not. The Web Listener needs write permission on this directory and on the files it contains. There is no default.

Info File Name The Log Information File contains periodic and event-driven messages that the Web Listener generates to help WebServer Administrators monitor their web site. The Oracle Web Listener records connections in the industry-standard Common Log Format. This format includes the first line of the client's request, which specifies the action, URL, and protocol version. It also includes such information as the client's host address, whether the request was successful, and how many bytes were transmitted. This information may be used later to analyze what types of accesses are performed by which users, and to check for errors.

Error File Name The Log Error File contains event-driven error messages that the Web Listener generates as it encounters problems with clients, resource access, and various other internal problems. There is no default.

Miscellaneous Web Listener Parameters

The following parameters are defined in this section:

Configuration Directory This is the directory where the configuration file for the Web Listener is to be located. The current value is shown. If you change this value to a new directory, the file containing the changes you currently are making to all Web Listener parameters will be written to this new directory.

Initial File The Initial File specifies the file that the Web Listener looks for when it is sent a directory URL. For example, if the Initial file is welcome, a request for http://www/stuff causes the Web Listener to return the file /stuff/welcome. The default is initial.

User Directory The User Directory is applicable only to Web Listeners running under the UNIX Operating System. It specifies the subdirectory in a user's directory the Web Listener searches when it receives a URL that starts with /~username/. For example, if at www, this value is set to public_html, then a request for http://www/~charles/initial.htm causes the Web Listener to return the file ~charles/public_html/initial.htm. There is no default.

User Directory Initial File The User Directory Initial File is a special case. For directories accessed with a URL with /~username/, the Oracle Web Listener will not use HTTP incomplete file negotiation and so the Web Listener needs a complete filename in the URL. The default is initial.htm.

Default MIME Type The default MIME (Multimedia Internet Mail Extension) Type is the MIME type for the Web Listener to use if a URL uses a file name extension to request a MIME type the Web Listener does not support. MIME types specify the kind of file, such as image, audio, or video, and the subtype gives the precise file format. The default for this parameter is application/octet-stream, which means the Web Listener will regard any unsupported MIME type as a binary file. If you would like the Web Listener to regard unsupported MIME types as anything other than application/octet-stream, you need to set this parameter.

Default Character Set This is the character set that the Web Listener uses if it does not recognize the character set specified in the URL's file extension. For more information, see "Language Extensions", later in this chapter.

Preferred Language This is the language that the Web Listener uses if the specified or defaulted character set can apply to multiple languages, and the exact language is not specified. For more information, see "Language Extensions," later in this chapter.

Image Map The contents of this field denote the extension that the Web Listener expects image maps to have. Thus, if your image maps have .map as their extension, set this parameter to map.

An image map is a graphic that is specially configured to act as a selector for one or more hyperlinks, based on where the user clicks on the graphic as displayed on the browser. Oracle WebServer processes image maps internally, without creating a separate process to handle them. An example of an image map would be a map of the world that allows the user to bring up an HTML document on a specific country by clicking on the country on the map. The Oracle Web Listener supports the same image map file formats as are read by the NCSA server.

Secure Information Parameters

The following parameters are applicable only to Web Listeners running on the UNIX Operating System:

User ID The User ID specifies the user (or user identification number) under whose privileges the Web Listener executes. To acquire these privileges, the Web Listener must be owned by this user or by root with "Set user ID" set. The User ID can be either a user name or a userid number. The default is the effective ID.

Group ID The Group ID specifies the group (or group identification number) under whose privileges the Web Listener executes. To acquire these privileges, the Web Listener must be owned by this group or by root with "Set group ID" set. The Group ID can be either a group name or a GID number. The default is the effective GID. For further information on the use of Group ID for security, see "Basic Configuration Parameters," earlier in this chapter.

Directory Mappings

The Directory Mappings control the mapping of directories from the file system into the Web Listener's virtual file system. The Oracle Web Listener supports the concept of a "virtual" or mapped filesystem. This feature enables the URL used to reference a set of files (directory) to be kept constant even if the files are moved. The translation of the network visible "virtual" path to an actual path is performed at runtime based on the mappings set in this section.

You specify one mapping per line, putting the actual path on the left, the virtual path on the right, and selecting from the pop-up menu one of the following:

Although you can list parameters in most sections of the configuration file in any order, you must order the parameters in this section so that parent virtual directories are listed before the virtual subdirectories they contain. Hence, the first directory mapping must reference the virtual root directory. The following is an example for UNIX systems:

File-System Directory		R/N/C	Virtual Directory
---------------------		-----	-----------------
/html					R	/
/prodinfo				N	/products
/final/xr25				R	/products/xr25
/misc/people			R	/employees
/misc/routines			C	/scripts

In the example above, /html is the virtual root directory. This means that any URL that does not contain a directory gets mapped to /html. Thus, the URL http://www/foo.html will cause the Web Listener to look for foo.html in the /html directory. Since this particular mapping is set to be recursive, any URL which contains a directory other than /products, /employees, and /scripts will get mapped to / /html/directory. Thus, the URL http://www/foo/bar.html will cause the Web Listener to look for bar.html in the /html/foo directory. Since /prodinfo is set to non-recursive, any URL that contains a subdirectory of /products causes an error. The exception would be a URL that contains /products/xr25, because the third line maps this virtual directory to /final/xr25. The last line is an example of a mapping to a directory that contains CGI and other scripts. Thus, the URL http://www/scripts/baz will cause the Web Listener to execute /misc/routines/baz.

Note: If you change the directory mappings, you must reload the Web Listener to put the new mappings into effect. To do this, use the WLCTL utility, as described under "WLCTL"[*] of this document.

File Cache Definitions

This section designates cached files. Files listed here are kept open for the life of the Web Listener. Files not listed here are not cached, and the Web Listener releases the resources required to access them once there are no outstanding client references to them--that is, once their reference counts drop to zero.

File caching decreases the access time required for commonly-used files, but at the cost of increasing the memory that the WebServer process uses. For this reason, you should not cache very large files unless absolutely necessary.

You can specify files for caching in any of the following three ways:

File references must use virtual rather than actual paths. For more on virtual paths, see "Directory Mappings", earlier in this chapter.

Language Extensions

The Web Listener can recognize various character sets, which are associated with various languages. The character set and language to be associated with a file is indicated with an extension to the filename. This is the character set and language to be used for communication between the Web Listener and web browsers. It is independent of the character set used for the data itself, which is indicated by the Web Agent parameter NLS_LANG.

This section defines the filename extensions that the Web Listener recognizes and the languages and character sets to which those extensions map. Extensions are case-sensitive. Each line in this section of the configuration file contains a language identifier as described in RFC 1766, followed by a character set, such as those described in RFC 1521, followed by one or more extensions that represent this combination of language and character set to the Web Listener. Multiple extensions are separated by blanks. For more information on Oracle Web Listener's support for character sets, see "Oracle Web Listener Language Extensions"[*] of this manual.

An example follows:

Language Type	Character Set		File Extension(s)
-------------	-------------		-----------------
en				iso-8859-1		eng
en				unicode-1-1		engU uc
fr-CA			iso-8859-1		frc
fr-FR			iso-8859-1		fr
jp-JP			iso-2022-jp		jp
jp-JP			unicode-1-1-utf-8	jpU

Since character sets are used only on textual files, language extensions differing only in the character set are equivalent for non-textual files. For example, for a Web Listener configured with the type extensions shown in the example, the file image.eng.jpg and the file image.uc.jpg both indicate an International English version of an image.

You can find more information and further examples under "Oracle Web Listener Authentication Configuration"[*] of this manual.

MIME Types

The Multipurpose Internet Mail Extension protocol (MIME) defines a number of content types and subtypes that allow programs to recognize different kinds of files and deal with them appropriately. The MIME type specifies what kind of file it is, such as image, audio, or video, and the subtype gives the precise file format. For more information on MIME, you can look over the RFC documents that describe MIME at the following URL:

http://www.oac.uci.edu/indiv/ehood/MIME/MIME.html

This section defines MIME types known to the Web Listener by their file name extensions. Each line in this section names a MIME type and then lists extensions that map to that MIME type. Extensions are case-sensitive, and multiple extensions are separated by blanks.

Encoding Extensions

This section defines the Web Listener's known encoding types and their expected extensions. When the Web Listener encounters files with extensions defined here, it recognizes the file to be of the corresponding type. Each line in this section names an encoding type and the extensions that map to this type. Extensions are case-sensitive, and multiple extensions are separated by blanks.

Configure Security Form

Use this form to define the security protections for the Web Listener to use on various pages. The top of the form is shown in Figure 7 - 8. The rest of the form provides text fields in which to enter the security parameters and values of your choice.

Figure 7 - 8. Web Listener Configure Security Form

There are two considerations:

The first of the following sections describes the security schemes in the abstract, the second describes the forms used to specify the users, and the third describes the form used to associate the users with the protected files or sets of files.

Click on a security scheme to navigate to the form which specifies the users in the manner relevant to that scheme, as described in the second section below. When you have completed these definitions, click Protection Section to navigate to the form where you apply the security schemes by associating the specified users with the protected files. Alternatively, you can scroll down the Configure Security page to reach all these forms in sequence.

The Security Schemes

The four security schemes fall into two categories: authorization schemes and restriction schemes. Authorization schemes work on the principle of password protection--the user provides a password to verify his or her identity. Restriction schemes use the Internet itself to determine who the user is. Basic and Digest authentication are authorization schemes, while IP-based and Domain-based authentication are restriction schemes. All the schemes are explained in the paragraphs that follow.

Basic Authentication Basic authentication employs usernames and passwords to restrict access to certain files on the Web Listener. Because Basic authentication sends passwords in the clear across the network, it is not recommended for extremely sensitive information.

Digest Authentication Digest authentication works essentially the same way as Basic authentication, except that it does not send passwords in the clear. Instead, it uses a cryptographic checksum, often called a digest, to encode the password. This scheme is a significant improvement over Basic Authentication and should be used whenever possible. Unfortunately, this scheme depends on the cooperation of the browser to encrypt the password, and therefore does not work with older browsers that don't support this feature.

IP-based Restriction IP-based restriction uses the network Internet Protocol (IP) address of the client to determine whether to allow or deny access to the protected page. Individual IP addresses or entire IP subnetworks may be specified. IP-based restriction is significantly more convenient than Basic and Digest authentication because it avoids the problems associated with passwords, such as keeping the password file secure and users forgetting their passwords. However, it is also less secure than Digest authentication because it is possible for a clever intruder to arrange to falsify his or her network address. Furthermore, many users need proxy servers because they are behind firewalls. In order to allow access to such a user, the IP address of the proxy server needs to be specified. However, specifying the IP address of the proxy server provides access to the protected page to all users employing that proxy server.

Domain-based Restriction Domain-based restriction is similar to IP-based restriction, except that it uses symbolic hostnames rather than network addresses. The use of symbolic hostnames is preferable because it is immune to changes in the underlying network architecture, which can result in changes to network addresses. Domain-based restriction, like IP-based restriction, is more convenient than Basic and Digest authentication, but also less secure than Digest authentication. As in IP-based restriction, it suffers from the problem with proxy servers.

Specifying The Privileged Users

After you have selected the security scheme or schemes to use, you need to specify the members of the privileged groups. The exact information that needs to be provided depends on the security scheme used.

Basic and Digest Authentication For Basic and Digest Authentication, the information consists of a list of users, then groups, and then realms. Users and groups refer to the standard UNIX notion of users and groups. Realms are collections of groups that are assigned the same security privileges. In other words, they constitute a new (higher) level of the Unix grouping hierarchy. For example:

User Name	Password
---------	--------
mcarey:	achtung
mloaf:	anything
chines:	pretend
pgabriel:	shockmonk

Group Name	User(s)
---------	-------
temps:	mcarey chines
sales:	chines mloaf
analysts:	mloaf pgabriel

Realms	Group(s)
------	--------
red:		temps
blue:		sales temps
green:	analysts

In the above example, chines, whose password is pretend, belongs to the sales group, which is part of the blue realm. Thus, any files that are set to be accessible to the blue realm are accessible to chines as long as he types in pretend when prompted for his password. When specifying multiple users or groups, please make sure that they are separated by at least one space. Realms are non-exclusive, which is to say, users and groups can belong to multiple realms. A given realm can contain a mixture of users and groups.

IP-based Restriction For IP-based restriction, you define groups of IP addresses that do or do not have access to a set of documents. For example:

IP Group		IP Address(es)
--------		--------------
spyonly		+192.246.238.* +204.4.214.*
notspy		-192.246.238.* -204.4.214.* +*
friends		+10.0.0.11 +10.0.0.83 +10.0.0.117

A '+' before an IP address denotes that that particular IP address or subnet should be given access. A '-' before an IP address denotes that that particular IP address or subnet should be denied access. An asterisk, as usual, is a wildcard indicating that the entire subnet--that is, all IP addresses that begin with the preceding numbers--is included. You can later use the group names given here to refer to the entire complex of associated IP addresses, with their permissions or lack of same, and assign file permissions to these groups.

In the above example, documents in the spyonly group are accessible only from sytems within the two specified subnets. Documents in notspy are accessible only from systems outside the two specified subnets. Documents in friends are accessible only from the three specified systems.

Domain-based Restriction Domain-based restriction is similar to IP-based restriction. A list of groups and hostnames are specified listing which hosts should or should not have access to a set of documents. The following is an example of domain-based restriction:

Domain Group	Domain Name(s)
------------	--------------
oracle:		+*.oracle.com
misc:			+dilbert.redbull.com -*.redbull.com
				-liz.lotion.com +*

You later can use the group names given here to refer to the entire complex of associated domain names, just as in IP-based restriction.

In the above example, documents in the group oracle are accessible only to systems within the oracle domain. Documents in misc are accessible to connections from the specific system dilbert.redbull.com, but not any other system in the redbull.com domain. Documents in misc are also accessible to anyone outside of the redbull.com domain as long as they are not connecting from liz.lotion.com.

Performing the Security Assignments - The Protection Section

Each line in the Protection Section of the form contains a file specification followed by one or two security schemes to protect that group of one or more files.

You can specify files in any of the following three ways:

Fill in the file specification according to these criteria and use the pop-up menus to apply the security schemes. All files are specified using virtual, rather than actual, paths. Virtual paths are explained under "Directory Mappings," earlier in this chapter.

You can apply one authentication and/or one restriction scheme for each file specification. If you choose to use both, you must choose '&' or '|' from the '&|' pop-up menu to decide whether the user must satisfy both ('&') or only must satisfy either ('|') of the two schemes. Restriction schemes, naturally, are applied without user input.

To specify an authentication scheme, choose Basic or Digest from the pop-up menu. Then specify in the realm column the realm to which the scheme is to apply.

To specify a restriction scheme, choose IP or Domain from the pop-up menu. Then specify in the group column the group of IP addresses or Domain names, as appropriate, to which the scheme is to apply.

Here is an example:

Files		Basic/Digest	Realm	&/|	IP/Domain	Group
-----		------------	-----	---	---------	-----
/secret/	Basic		red	|	IP		spyonly
/misc/hot*	Basic		green	&	IP		spyonly
/company/*					IP		spyonly
/update.htm	Basic		blue

In this example, all of the files in /supersecret/, but not its subdirectories, can be accessed by any user who is either coming from the correct IP address or has a username and password for the red realm. In the second case, all files in /misc/ that start with "hot" can be accessed only by a user who has both the correct IP address and authentication for the green realm. Files in /company/, including subdirectories (as indicated by the asterisk (*)), are protected only by IP address. The single file update.htm is protected only by authorization in the blue realm.


Contents Index Home Previous Next