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 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.
Before using server-side includes on your server, consider performance, security, and risk issues:
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:
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.
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.
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]
Example:
<!-- #config errmsg="[An error occurred]" -->
Default: "[An error occurred while processing this directive]"
Example 1:
<!--#config sizefmt=bytes -->
<!--#fsize file=foo.html -->
Result: 1024
Example 2:
<!--#config sizefmt=abbrev -->
<!--#fsize file=foo.html -->
Result: 1K
Default: "abbrev"
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:
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:
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" -->
<!--#flastmod file="/path/file" -->
<!--#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 ê so that it is not recognized as a variable. Instead, it is used as a string to create the value frêd, or fred with a circumflex over the e. The variable ê is a client-side variable.
<!--#set var="index" value="1" -->
<!--#set var="var&index;" value="fr\ê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 |
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.
This applies to reverse proxy configurations only.
WebSphere® Application Server, Version 8.5 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.
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.
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.
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.
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.