Web Site rules and global Web settings

Substitution rules

A substitution rule replaces one or more parts of the incoming URL with new strings. Substitution rules should be used when you want to reorganize your Web site, and you don't want to have to rewrite all the links in the site, or when you want to provide user-friendly aliases for complex URLs.

For example, a substitution rule would be useful if you moved a number of files on your Web site from one directory to another. Instead of fixing all the links that refer to the old directory, your substitution rule would map the old directory to the new directory.

The incoming and replacement patterns in substitution rules must each specify at least one wildcard. If you do not explicitly include a wildcard somewhere in a pattern, the HTTP task automatically appends /* to the pattern when it stores the rule in its internal table.

Redirection rules

Redirection rules redirect incoming URLs to other URLs. There are two types of redirection rules: external redirection and internal redirection. An external redirection rule causes the server to inform the browser that a file or other resource requested by the browser is located at another URL. If the incoming URL path matches an external redirection rule, the HTTP task generates a new URL based on the redirection pattern and immediately returns that URL to the browser. Using external redirection rules allows existing links and bookmarks to keep working, but insures that new bookmarks point to the new location.

An internal redirection rule acts like a substitution rule, as the HTTP task generates a new URL and then re-normalizes it. There are two differences, however. First, the redirection table is searched recursively, so you can create and nest multiple redirection rules. Second, an internal redirection rule does not require the use of a wildcard character. Thus, you can choose to use an internal redirection rule instead of a substitution rule if you want to force an exact match on the URL path.

If the incoming URL path matches an internal redirection rule, the HTTP task generates a new path, normalizes the path, and searches the redirection rule table again. Because the HTTP task does a recursive search through the redirection rule table, you can write broad redirection rules that capture URLs no matter what substitution or redirection has been applied.

Wildcards are allowed in redirection rules, but are not required.

Directory rules

A directory rule maps a file-system directory to a URL pattern. When the Web server receives a URL that matches the pattern, the server assumes that the URL is requesting a resource from that directory.

When you install a Domino® Web server, several file-resource directories are created automatically. These default directories are mapped by directory rules that are defined on the Configuration tab of the Web Site document. When the Web server starts up, it automatically creates internal rules to map these directories to URL patterns. The three default directories are:

• HTML directory for non-graphic files
• Icon directory for graphic images such as .GIFs
• CGI directory for CGI programs

Directory rules can only be used to map the location of files that are to be read directly (such as HTML files and graphic files) and executable programs to be loaded and run by the operating system (such as CGI programs). Directory rules cannot be used to map the location of other types of resources, such as Domino databases or Java™ servlets.

When you create a Directory Web Site rule, you specify read or execute access to a file-system directory. It is critically important to choose the correct access. Only directories that contain CGI programs should be enabled for Execute access. All other directories should have Read access. If you specify the wrong access level, unexpected results will occur. For example, if you mark a CGI directory for Read access, when a browser user sends a URL for a CGI program, the server will return the source code of the program instead of executing it, which could be a serious security breach.

Directory rules cannot override file-access permissions enforced by the operating system.

HTTP response header rules

Every HTTP browser request and server response begins with a set of headers that describe the data that is being transmitted. An HTTP response header rule allows an application designer to customize the headers that Domino sends -- such as an Expires header or custom headers to HTTP responses -- with responses to requests that match the specified URL pattern.

The most important use of response rules is to improve the performance of browser caching. An application designer can add headers that provide the browser with important information about the volatility of the material being cached.

The caching headers include the Last-Modified header, Expires header, and Cache-Control header. The Last-Modified header indicates when the resource or resources used to generate a response were last changed. The Expires header tells the browser when resources are expected to change. A designer can define a rule to add Expires headers to responses based on when the designer expects resources to change. The Cache-Control header provides explicit instructions to browser and proxy server caches, such as "no-cache" for responses that should not be cached, or "private" for responses that are cacheable but are specific to a particular browser configuration.

You can also use response rules to customize headers. For example, you can create response rules for custom headers that display specific error messages -- for example, when a user is not authorized to access an application.

Unlike other Web site rules, response rules are applied to the outgoing response, just before the HTTP task transmits the response to the browser. For response header rules, the pattern is matched against the final form of a URL, after substitution and redirection rules have been applied to it. For example, if you have a substitution rule that transforms /help/* to /support.nsf/helpview/* and you want to create a response rule to match the response, the pattern for the response rule should be /support.nsf/helpview/*.

The pattern can include one or more asterisks as wildcard characters. For example, the pattern /*/catalog/*.htm will match the URLs /petstore/catalog/food.htm, /clothing/catalog/thumbnails.htm, and so on. A wildcard is not required in a response rule. This allows you to create a rule that matches a specific resource, for example, /cgi-bin/account.pl. Also, as with all rules, the incoming pattern cannot contain a query string.

Response header rules are different from other rules in that not only do they have to match a URL pattern, they also have to match the HTTP response status code. You need to specify one or more status codes in the HTTP response codes field.

Global Web Settings

Global Web Settings enable you to apply Web rules to multiple Web sites. You define a name for the Global Web settings document, and specify the servers to which the Global Web settings apply. You then create Web Rules documents for a Global Web Settings document. The Web rules then apply to all Web sites hosted by the servers specified in the Global Web settings document.

Global Web Settings document and associated Web Site rule documents are not automatically created. If you want to use the Global Web Settings document and Web Site rules in your Web environment, you need to manually create them.