Customize server processing
Customizing server processing 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 (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 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
- Performance can be significantly impaired when the server is processing files while sending them.
- Security can be compromised if you allow ordinary users to run commands on your server. Be careful when deciding which directories you place server-side includes and in which directories you place the exec command. You can minimize the security risk if you do not enable the exec command.
- Using server-side includes can cause some problems. For example, files cannot be referenced recursively: if you are running the file sleepy.html and the program finds <-- !#include file="sleepy.html" --> , the server does not detect the error and can fail. (Referencing files nonrecursively within other files is not a problem.)
Configuration for server-side includes
- CGI scripts
- Files
- All except CGI scripts that use the exec command
- None
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. The shtml and htmls extensions are recognized by default.
Format for server-side includes
<!--# 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
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:
Result: <!--[This is a comment] extra text --><!--#config cmntmsg="[This is a comment]" --> <!-- #echo var=" " 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:
Default: "[An error occurred while processing this directive]"<!-- #config errmsg="[An error occurred]" -->
- sizefmt
- Use this tag to specify the format in which file size is displayed. In
the following examples, bytes is the value that is
used to display the number of bytes, and abbrev is
the value that is used to display the number of kilobytes or megabytes. Example 1:
Result: 1024<!--#config sizefmt=bytes --> <!--#fsize file=foo.html -->
Example 2:
Result: 1K<!--#config sizefmt=abbrev --> <!--#fsize file=foo.html -->
Default: "abbrev"
- timefmt
- Use this tag to specify the format that is used to provide dates. Example:
Result: "10/18/95 12:05:33"<!--#config timefmt="%D %T" --> <!--#flastmod file=foo.html -->
Default: "%a, %d %b %Y %T %Z"
The following strftime() formats are valid with the timefmt tag:The operating system configuration determines the full and abbreviated month names and years.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-align, 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 zeros 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
echo—display variable values
- DATE_GMT
- The current date and time in Greenwich Mean Time. The formatting of this variable is defined by using the config timefmt directive.
- DATE_LOCAL
- The current date and local time. The formatting of this variable is defined by 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 by using the config timefmt directive.
- QUERY_STRING_UNESCAPED
- The search query that is sent by the client. This query 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 that is used in the include command that retrieved the current file. This value is not defined for the topmost file.
- SSI_PARENT
- The path and file name of the file that contains 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.
<!--#echo var=SSI_DIR -->
exec—specify CGI programs
- 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.
<!--#exec cgi="/cgi-bin/program/path_info?query_string" -->
<!--#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.
<!--#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 that
is 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 " -->
<!--#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.
<!--#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.
<!--#global var= VariableName
value=" SomeValue
" -->
<!--#global var="PARENT_URI" value=&DOCUMENT_URI; -->
<!--#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 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.
<!--#set var="Variable 2" value=" AnotherValue
" -->
<!--#include file="& filename
;" -->
Variables: A server-side set directive is 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 that is already set. If a set variable is not found, nothing is displayed.
<!--#set var="index" value="1" -->
<!--#set var="var&index;" value="fr\êd" -->
<!--#echo var="var1" -->
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.
Real Time Streaming Protocol (RTSP) redirection
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.
About RTSP redirection
- RealNetworks recorded audio
- RealNetworks recorded video
- RealNetworks live streams (audio and video)
- Microsoft Media Player files
- Apple QuickTime media files
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 that are handled by the RTSP redirector.
The RTSP redirector does not cache or directly proxy media presentations. The RTSP redirector must be used 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 technologies 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 that is 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 stopped and then started again before changes to these directives take effect.