Customize server processing

This topic describes how to use server-side includes to insert information into CGI programs and HTML documents that are delivered to a client. Customizing the server's error messages and resource mapping are also discussed.

Server-side includes

Server-side includes allow you to add information to CGI programs and HTML documents that the server sends to the client when acting as an origin server (that is, not to proxied or cached objects). The current date, the size of a file, the date of last change to a file are examples of the kind of information that can be sent to the client. This section describes the command format for server-side includes and explains how to make server-side include commands work in your CGI programs and HTML documents. You can also use server-side includes to customize error pages.

Considerations for server-side includes

Before using server-side includes on your server, consider performance, security, and risk issues:

Configuration for server-side includes

To enable server-side includes, in the Configuration and Administration forms, select Server Configuration -> Basic Settings. Use this form to specify which of the following types of server-side includes are acceptable:

Use this form also to specify whether to do server-side include processing for text or HTML documents in addition to other file types.

In addition, ensure that the file extension that you use for the include is recognized. In the Configuration and Administration forms, select Server Configuration -> MIME Types and Encoding, and use the MIME Types form. Note that the shtml and htmls extensions are recognized by default.

To configure your server for server-side includes by editing the directives in the proxy configuration file, see the reference sections for the following directives:

Format for server-side includes

Include commands must be included in the HTML document or CGI program as comments. The commands have the following format:

<!--#directive tag=value ... --> 
or 
<!--#directive tag="value" ... -->  

The quotation marks around values are optional, but they are required in order to embed spaces.

Directives for server-side includes

This section explains the directives that are accepted by the server for server-side includes. (Do not confuse these directives with the directives for the proxy configuration file, which are documented in Appendix B. Configuration file directives.)

config--control file processing

Use this directive to control certain aspects of file processing. Valid tags are cmntmsg, errmsg, sizefmt, and timefmt.

cmntmsg
Use this tag to specify a message that precedes the beginning of comments added by other directives. For any directive that contains text between a directive specification and "-->", that text is treated as a comment and is added to the file that the server sends to the client.

Example:

<!--#config cmntmsg="[This is a comment]" -->
<!-- #echo var="  " extra text -->

Result: <!--[This is a comment] extra text -->

Default: [the following was extra in the directive]

errmsg
Use this tag to specify the message that is sent to the client if an error occurs while a file is being processed. The message is logged in the server's error log.

Example:

<!-- #config errmsg="[An error occurred]" -->

Default: "[An error occurred while processing this directive]"

sizefmt
Use this tag to specify the format in which file size is displayed. In the following examples, bytes is the value used to display the number of bytes, and abbrev is the value used to display the number of kilobytes or megabytes.

Example 1:

<!--#config sizefmt=bytes -->
<!--#fsize file=foo.html -->

Result: 1024

Example 2:

<!--#config sizefmt=abbrev -->
<!--#fsize file=foo.html -->

Result: 1K

Default: "abbrev"

timefmt
Use this tag to specify the format used to provide dates.

Example:

<!--#config timefmt="%D %T" -->
<!--#flastmod file=foo.html -->

Result: "10/18/95 12:05:33"

Default: "%a, %d %b %Y %T %Z"

The following strftime() formats are valid with the timefmt tag:

Specifier Meaning
%% Replace with %
%a Replace with the abbreviated weekday name
%A Replace with the full weekday name
%b Replace with the abbreviated month name
%B Replace with the full month name
%c Replace with the date and time
%C Replace with the century number (year divided by 100 and truncated)
%d Replace with the day of the month (01-31)
%D Insert the date as %m/%d/%y
%e Insert the month of the year as a decimal number (01-12) (Under C POSIX only, it is a 2-character, right-justified, blank-filled field)
%E[cCxyY] If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %EC is mapped to %C)
%Ec Replace with the alternative date and time representation
%EC Replace with the name of the base year (period) in the alternative representation
%Ex Replace with the alternative date representation
%EX Replace with the alternative time representation
%Ey Replace with the offset from %EC (year only) in the alternative representation
%EY Replace with the full alternative year representation
%h Replace with the abbreviated month name (the same as %b)
%H Replace with hour (23-hour clock) as a decimal number (00-23)
%I Replace with hour (12-hour clock) as a decimal number (00-12)
%j Replace with the day of the year (001-366)
%m Replace with the month (01-12)
%M Replace with minute (00-59)
%n Replace with a new line
%O[deHlmMSUwWy] If the alternative date/time format is not available, the %E descriptors are mapped to their unextended counterparts (For example, %Od is mapped to %d)
%Od Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading zeroes if there is any alternative symbol for zero, otherwise with leading spaces
%Oe Replace with the day of the month, using the alternative numeric symbols, filled as needed with leading spaces
%OH Replace with the hour (24-hour clock), using the alternative numeric symbols
%OI Replace with the hour (12-hour clock), using the alternative numeric symbols
%Om Replace with the month, using the alternative numeric symbols
%OM Replace with the minutes, using the alternative numeric symbols
%OS Replace with the seconds, using the alternative numeric symbols
%OU Replace with the week number of the year (Sunday as the first day of the week, rules corresponding to %U), using the alternative numeric symbols
%Ow Replace with the weekday (Sunday=0), using the alternative numeric symbols
%OW Replace with the week number of the year (Monday as the first day of the week), using the alternative numeric symbols
%Oy Replace with the year (offset from %C) in the alternative representation and using the alternative numeric symbols
%p Replace with the local equivalent of AM or PM
%r Replace with the string equivalent to %I:%M:%S %p
%R Replace with time in 24-hour notation (%H:%M)
%S Replace with seconds (00-61)
%t Replace with a tab
%T Replace with a string equivalent to %H:%M:%S
%u Replace with the weekday as a decimal number (1-7), with 1 representing Monday
%U Replace with the week number of the year (00-53), where Sunday is the first day of the week
%V Replace with the week number of the year (01-53), where Monday is the first day of the week
%w Replace with the weekday (0-6), where Sunday is 0
%W Replace with the week number of the year (00-53), where Monday is the first day of the week
%x Replace with the appropriate date representation
%X Replace with the appropriate time representation
%y Replace with the 2-digit year number within the century
%Y Replace with the full 4-digit year number
%Z Replace with the name of the time zone or no characters if the time zone is unknown

The operating system configuration determines the full and abbreviated month names and years.

echo--display variable values

Use this directive to display the value of environment variables specified with the var tag. If a variable is not found, a (None) is displayed. Also, echo can display a value set by the set or global directives. The following environment variables can be displayed:

DATE_GMT
The current date and time in Greenwich Mean Time. The formatting of this variable is defined using the config timefmt directive.
DATE_LOCAL
The current date and local time. The formatting of this variable is defined using the config timefmt directive.
DOCUMENT_NAME
The name of the topmost document. If the HTML was generated by a CGI, this variable contains the name of the CGI.
DOCUMENT_URI
The full URL requested by the client, without the query string.
LAST_MODIFIED
The date and time that the current document was last modified. The formatting of this variable is defined using the config timefmt directive.
QUERY_STRING_UNESCAPED
The search query sent by the client. This is undefined unless HTML was generated by a CGI.
SSI_DIR
The path of the current file, relative to SSI_ROOT. If the current file is in SSI_ROOT, this value is "/".
SSI_FILE
The file name of the current file.
SSI_INCLUDE
The value used in the include command that retrieved the current file. This is not defined for the topmost file.
SSI_PARENT
The path and file name of the file containing the include command that retrieved the current file, relative to SSI_ROOT.
SSI_ROOT
The path of the topmost file. All include requests must be in this directory or a child of this directory.

Example:

<!--#echo var=SSI_DIR -->

exec--specify CGI programs

Use this directive to include the output of a CGI program. The exec directive discards any HTTP headers that the CGI outputs except for the following:

Content-type
Determines whether to parse the body of the output for other includes
Content-encoding
Determines whether translation from EBCDIC to ASCII needs to be done
Last-modified
Replaces the current last-modified header value unless the current value is later than the specified value

cgi--specify CGI program URL

Use this directive to specify the URL of a CGI program.

In this example, program is the CGI program to be executed, and path_info and query_string represent one or more parameters passed to the program as environment variables:

<!--#exec cgi="/cgi-bin/program/path_info?query_string" -->

This example shows the use of variables:

<!--#exec cgi="&path;&cgiprog;&pathinfo;&querystring;" -->

flastmod--display date and time document was last changed

Use this directive to display the last date and time the document was changed. The formatting of this variable is defined by the config timefmt directive. The file and virtual tags are valid with this directive, and their meanings are defined as follows.

Directive formats:

<!--#flastmod file="/path/file" --> 
<!--#flastmod virtual="/path/file" -->
file
Use this tag to specify the name of a file. For flastmod, fsize, and include, file is assumed to be relative to SSI_ROOT if preceded by a '/'. Otherwise, it is relative to SSI_DIR. The file specified must exist either in SSI_ROOT or in one of its descendants. For example:
<!--#flastmod file="/path/file" -->
virtual
Use this tag to specify the URL of a virtual path to a document. For flastmod, fsize, and include, virtual is always passed through the server's mapping directives. For example:
<!--#flastmod virtual="/path/file" -->

Example:

<!--#flastmod file="foo.html" -->

Result: 12May96

fsize--display file size

Use this directive to display the size of the specified file. The formatting of this variable is defined by the config sizefmt directive. The file and virtual tags are valid with this directive, and their meanings are the same as defined previously for the flastmod directive.

Example:

<!--#fsize file="/path/file" -->
<!--#fsize virtual="/path/file" -->

Result: 1K

global--defines global variables

Use this directive to define global variables that can be echoed later by this file or by any included files.

Example:

<!--#global var=VariableName value="SomeValue" -->

For example, to reference a parent document across the virtual boundary, you need to set a global variable DOCUMENT_URI. You also need to reference the global variable in the child document. This example shows the HTML coding you need to insert in the parent document:

<!--#global var="PARENT_URI" value=&DOCUMENT_URI; -->

This example shows the HTML coding you need to insert in the child document:

<!--#flastmod virtual=&PARENT_URI; -->

include--includes a document in output

Use this directive to include the text from a document in the output. The file and virtual tags are valid with this directive, and their meanings are the same as defined above for the flastmod directive.

set--set variables to be echoed

Use this directive to set a variable that can be echoed later, but only by this file.

Example:

 <!--#set var="Variable 2" value="AnotherValue" -->

While defining a directive, you can echo a string in the middle of value. For example:

<!--#include file="&filename;" -->

Variables: A server-side set directive is generally followed by an echo directive, so that it looks for the set variable, echoes where the variable is found, and proceeds with the function. It can contain multiple references to variables. Server-side sets also allow you to echo a variable already set. If a set variable is not found, nothing is displayed.

When a server-side set encounters a variable reference inside a server-side include directive, it attempts to resolve it on the server side. In the second line of the following example, the server-side variable &index; is used with the string var to construct the variable name var1. The variable &var1; is then assigned a value by escaping the & in &ecirc; so that it is not recognized as a variable. Instead, it is used as a string to create the value fr&ecirc;d, or fred with a circumflex over the e. The variable &ecirc; is a client-side variable.

<!--#set var="index" value="1" --> 
<!--#set var="var&index;" value="fr\&ecirc;d" --> 
<!--#echo var="var1" -->

Characters that can be escaped (called escaped variables) are preceded with a backslash (\) and include the following:

Character Meaning
\a Alert (bell)
\b Backspace
\f Form feed (new page)
\n New line
\r Carriage return
\t Horizontal tab
\v Vertical tab
\' Single quotation mark
\" Double quotation mark
\? Question mark
\\ Backslash
\- Hyphen
\. Period
\& Ampersand

Customizing error messages

You can customize the error messages that Caching Proxy returns, and you can define specific messages for particular error conditions. In the Configuration and Administration forms, select Server Configuration -> Error Message Customization. Use this form to select an error condition and specify a particular HTML file to use for that condition.

To customize error messages by editing directives in the proxy configuration file, see the reference section for the directive ErrorPage -- Specify a customized message for a particular error condition.

Real Time Streaming Protocol (RTSP) redirection

This applies to reverse proxy configurations only.

WebSphere® Application Server, Version 8.0 introduces streaming media support in the form of the RTSP Redirector. RTSP enables Caching Proxy to act as a first point of contact with media players and to redirect their requests to an appropriate proxy server or to a content server that provides the requested media content.

RTSP, the Real Time Streaming Protocol, is defined in RFC 2326. It is an Internet standard protocol for controlling data streams. Although it does not include technology for delivering streams, it is flexible enough that it can be used to control data streams that are unrelated to video or audio playback.

About RTSP redirection

The RTSP redirection feature allows Caching Proxy to redirect requests for any streaming media sessions controlled by RTSP. These include the following types of media:

Any player that can be configured to contact a proxy server on its RTSP port (typically 554) can use this framework in Caching Proxy to have its requests handled by the RTSP redirector.

The RTSP redirector does not cache or directly proxy media presentations. The RTSP redirector must be used in conjunction with a third-party streaming media server to provide either or both of those functions. Caching Proxy with RTSP redirector must have network access to one or more RTSP proxy servers.

RTSP limitation

This feature is subject to the following limitation:

Currently, only RealNetworks technologies are supported. These include the RealProxy proxy server, the RealServer origin server, and the RealPlayer media player.

RTSP enhancement

Previously, the RTSP Redirector was subject to the limitation that all requests to the same origin server for any URL were redirected the same way. Redirection based on file names or other portions of the requested URL was not possible. This limitation no longer applies. The RTSP Redirector now uses the complete URL from received requests along with the threshold value (rtsp_proxy_threshold) set in the Caching Proxy configuration file to determine whether to redirect the client request to the origin server or to a proxy server. Requests to the same origin server are now handled individually.

Configuring RTSP redirection

The following configuration file directives are used to control RTSP redirection. The settings for these directives are not refreshed by a server restart. The server must be completely stopped and then started again before changes to these directives take effect.