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:
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".
Figure 7 - 6. Listener Creation Form, Part 1
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:
From this form, you will be able to customize the following:
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:
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 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.
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.
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.
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:
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 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:
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.
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.
Figure 7 - 8. Web Listener Configure Security Form
There are two considerations:
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.
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.
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.
You can specify files in any of the following three ways:
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.