Configuration for the IisProxy Module: IisProxy.dtd (SAP Library

Configuration for the IisProxy Module: IisProxy.dtd

Definition

This document type definition (DTD) describes how to configure the IisProxy module.

Structure

The IisProxy.dtd defines the following elements:

This graphic is explained in the accompanying text

The usage of each element is explained below:

<!--

The ISAPI-config element is the root element for this configuration. It contains the declarations for the filter component, the extension component and the mappings between requests and their targets.

-->

<!ELEMENT ISAPI-config (filter, extension, (mapping | config)*)>

<!--

The version attribute specifies the version of this configuration.

This element is mandatory. The value that should be used for the current implementation is "1.3" (no quotes).

This value is checked against the first two numbers in the four-number file version (e.g. DLL version 1.2.3.0 needs configuration "1.2").

-->

<!ATTLIST ISAPI-config version CDATA #REQUIRED>

<!--

The filter element specifies the configuration for the ISAPI filter part. This element is required.

The filter element may have a subelement that defines:

log-path path for the log file

-->

<!ELEMENT filter (log-path?)>

<!--

The filter element has the following attributes:

name display name for the element.

log-level level of detail that shall be written to the log file.

log-flags bit field for fine-grain logging control. Each log.level value maps to some bits that are set in this bit field. For debugging, additional bits can be set here.

debug-flags bit field for controlling diagnostic output. This output is written using the OutputDebugString() function and can be monitored in an attached Debugger or using a DebugView tool (for example, the debug tool from www.sysinternals.com).

priority priority of the filter in the IIS filter chain. Valid values are "high", "medium" and "low".

extension-url
path to the extension (relative to the Inetpub directory). This value can be changed if the DLL is located in another directory.

-->

<!ATTLIST filter
      name CDATA #IMPLIED
      log-level CDATA "2"
      log-flags CDATA "0"
      debug-flags CDATA "0"
      priority ( high | medium | low ) "high"
      extension-url CDATA "/scripts/IisProxy.dll"
>

<!--

The log-path element specifies the path and the name of the file used for log output. This element is optional, the default value is "IisProxy_%y%m%d.log".

If the value does not contain an absolute path, it will be evaluated relative to the directory where the IisProxy.dll is located. If the element value specifies an existing directory, the default file name is appended to the resulting directory name.

The resulting path is used as a format string to strftime(), it may contain the following formatting codes:

%a Abbreviated weekday name

%A Full weekday name

%b Abbreviated month name

%B Full month name

%c Date and time representation appropriate for locale

%d Day of month as decimal number (01 – 31)

%H Hour in 24-hour format (00 – 23)

%I Hour in 12-hour format (01 – 12)

%j Day of year as decimal number (001 – 366)

%m Month as decimal number (01 – 12)

%M Minute as decimal number (00 – 59)

%p Current locale's A.M./P.M. indicator for 12-hour clock

%S Second as decimal number (00 – 59)

%U Week of year as decimal number, with Sunday as first day of the week (00 – 53)

%w Weekday as decimal number (0 – 6; Sunday is 0)

%W Week of year as decimal number, with Monday as first day of the week (00 – 53)

%x Date representation for current locale

%X Time representation for current locale

%y Year without century, as decimal number (00 – 99)

%Y Year with century, as decimal number

%z, %Z Time-zone name or abbreviation; no characters if time zone is unknown

%% Percent sign

The value is evaluated each time a record is written to the log file. This implies that the formatting codes can be used for a time-based log file rollover.

The log file and all directories of the resulting path will be created if they do not exist.

-->

<!ELEMENT log-path (#PCDATA)>

<!--

The extension element defines the configuration for the ISAPI extension part. This element is required.

The extension element may have subelements that define:

keystore-dir
directory of the SECUDE keystore for certificate authentication between the IisProxy extension and the J2EE Engine

log-path path for the log file

data-path path for the communication data file

trace-path path for the SAP network trace file

-->

<!ELEMENT extension (keystore-dir?, log-path?, data-path?, trace-path?)>

<!--

The extension element has these attributes:

name display name for the element.

log-level level of detail that shall be written to the log file.

log-flags bit field for fine-grain logging control. Each log.level value maps to some bits that are set in this bit field. For debugging, additional bits can be set here.

debug-flags bit field for controlling diagnostic output. This output is written using the OutputDebugString() function and can be monitored in an attached Debugger or using the DebugView tool from www.sysinternals.com.

access defines whether the extension accepts requests which have been preprocessed by the filter part or whether unfiltered requests are accepted and mapped, too.

-->

<!ATTLIST extension
      name CDATA #IMPLIED
      log-level CDATA "2"
      log-flags CDATA "0"
      debug-flags CDATA "0"
      access ( filter | direct | both ) "filter"
>

<!--

The keystore-dir element specifies the path to the directory which contains the SAPSSLC.pse file for the extension. This file is needed to initialize the SSL library. This element is optional; its default value is taken from the SECUDIR environment variable. If the SECUDIR variable doesn’t exist, the default value is "C:\sec".

-->

<!ELEMENT keystore-dir (#PCDATA)>

<!--

The data-path element specifies the path and the name of the file used for data output. This element is optional; its default value is "IisProxy_%y%m%d.data".

HTTP protocol data (header and body data) is written to this file if the DATA bit in the log-flags variable is set (implicitly by setting the log-level attribute to 3 or by setting the appropriate bit explicitly in the log-flags attribute).

The resulting path is used as a format string to strftime(). See the description of the log-path element above for formatting codes.

The value is evaluated each time a record is written to the log file. This implies that the formatting codes can be used for a time-based log file rollover.

The data file and all directories of the resulting path will be created if they do not exist.

-->

<!ELEMENT data-path (#PCDATA)>

<!--

The trace-path element specifies the path and the name of the SAP network trace file. This element is optional; its default value is "IisProxy.trace".

Creation and detail level of the SAP network trace file is controlled by the low order 4 bits of the debug-flags attribute. Common values are:

0 no tracing

1 some tracing

3 developer tracing.

The file will be created if it doesn't exist, but all directories of the resulting path must be accessible.

-->

<!ELEMENT trace-path (#PCDATA)>

<!--

The mapping element specifies the configuration for the ISAPI extension part.

The mapping element has subelements that define:

source the request URL that shall be forwarded

target the forwarding destination

The mapping element may have subelements that define:

compress-types
list of mime types for response compression

protocol-header
header for the protocol used by the client browser

certificate-header
header for the client browser certificate

cert-chain-header
header for the client browser certificate chain

cipher-header
header for the cipher used between browser and IIS

keysize-header
header for the keysize used between browser and IIS

keystore-path
path to the SECUDE keystore for certificate authentication between the IisProxy extension and the J2EE Engine

log-path path for the log file. If not specified, the value is inherited from the log-path subelement of the extension element.

data-path path for the communication data file. If not specified, the value is inherited from the log-path subelement of the extension element.

-->

<!ELEMENT mapping (source+, target, compress-types?,
      protocol-header?, certificate-header?, cert-chain-header?,
      cipher-header?, keysize-header?, keystore-path?, log-path?,
      data-path?)>

<!--

The mapping element has these attributes:

name display name for the element.

log-level level of detail that shall be written to the log file.

log-flags bit field for fine-grain logging control. Each log.level value maps to some bits that are set in this bit field. For debugging, additional bits can be set here.

keep-alive controls whether the target connection uses HTTP keep-alive.

Connection pooling is disabled and each target request will have a "Connection: close" header if this attribute is "false".

use-continue
controls the use of the "Expect: 100-continue" header.

If set to "true", the extension adds a "Expect: 100-continue" header field, send the request header to the target and waits for a response before sending the request message body to the target. If the value is "false", the extension immediately forwards the request message body to the target.

close-socket
controls the workaround for the problem that Microsoft IE sends an additional CR/LF pair for requests with a message body.

If set to "true", the extension attempts to read the obsolete CR/LF pair before closing the client socket when it sends a response message with the "Connection: close" header to the client browser.

close-socket-delay
if close-socket is "true", the extension attempts to read the obsolete CR/LF pair before closing the client socket. This delay specifies the delay (in milliseconds) between reading from and closing the client socket.

thread-count
integer value representing the number of worker threads in the pool for this mapping target. If the value is negative, its absolute value will be multiplied by the number of processors in the machine to get the total number of threads. If the value is zero, the number of threads will be two times the number of processors in the machine.

max-socket-age
maximum age for a pooled connection (in seconds). If a connection from the connection pool has not been used for more than max-socket-age seconds, it will not be used anymore.

-->

<!ATTLIST mapping
      name CDATA #IMPLIED
      log-level CDATA "2"
      log-flags CDATA "0"
      debug-flags CDATA "0"
      keep-alive ( true | false ) "true"
      use-continue ( true | false ) "true"
      close-socket ( true | false ) "true"
      close-socket-delay CDATA "1000"
      thread-count CDATA "10"
      max-socket-age CDATA "10"
>

<!--

The source element specifies a request URI pattern for forwarding. One or more source elements are required.

The source element has required subelements that define:

protocol the client protocol in the URI ("http" or "https")

prefix the character sequence that the abs_path in the URL starts with

The source element may have subelements that define:

host the host part in the request URL.

port the port number in the request URL

new-prefix a replacement sequence for the character sequence matched by the prefix value

-->

<!ELEMENT source (protocol, host?, port?, prefix, new-prefix?)>

<!--

The access attribute specifies whether a source element is valid for the filter, for direct mapping or for both. This reflects in the "Source mappings" list as logged from the filter and from the extension.

-->

<!ATTLIST source access ( filter | direct | both ) "both">

<!--

The target element specifies the destination for forwarding. This element is required.

The target element has subelements that define:

protocol the client protocol for the new request ("http" or "https")

host the target host

port the target port number

-->

<!ELEMENT target (protocol, host, port)>

<!--

The protocol element specifies which protocol ("http" or "https") a source element shall match. This element is required.

-->

<!ELEMENT protocol (#PCDATA)>

<!--

The host element specifies a host name; either a short name or a fully qualified domain name or an IP address.

-->

<!ELEMENT host (#PCDATA)>

<!--

The port element specifies a TCP port number.

-->

<!ELEMENT port (#PCDATA)>

<!--

The prefix element specifies the path prefix that the abs_path of the URL has to match. This element is required.

-->

<!ELEMENT prefix (#PCDATA)>

<!--

The new-prefix element specifies a replacement sequence for the character sequence matched by the prefix value in the source element.

Prefix replacement happens only when matching requests – the resulting URL is passed to the target, and the response is not changed at all.

-->

<!ELEMENT new-prefix (#PCDATA)>

<!--

The compress-types element contains a list of content types that shall be compressed. Different values are separated by semicolon (‘;’) or comma (‘,’) characters.

-->

<!ELEMENT compress-types (#PCDATA)>

<!--

The min-size attribute specifies the minimum size in bytes for a response body to be compressed.

-->

<!ATTLIST compress-types min-size CDATA "1024">

<!--

The protocol-header element specifies the name of the header that shall be used to inform the target about the protocol used between client and IIS.

-->

<!ELEMENT protocol-header (#PCDATA)>

<!--

The certificate-header element specifies the name of the header that shall be used to forward the client certificate supplied by the client browser.

The certificate is encoded as a base-64 encoded binary structure.

-->

<!ELEMENT certificate-header (#PCDATA)>

<!--

The cert-chain-header element specifies the common name of the headers that shall be used to forward the chain of certificates used to validate the client certificate. Each chain element is passed in a separate header, numbered from 1 onwards. The (self-signed) anchor of the chain is not forwarded.

The certificates are encoded as a base-64 encoded binary structure.

-->

<!ELEMENT cert-chain-header (#PCDATA)>

<!--

The cipher-header element specifies the name of the header that shall be used to forward the name of the cipher specification used to encrypt the SSL/TLS connection between client and IIS.

-->

<!ELEMENT cipher-header (#PCDATA)>

<!--

The keysize-header element specifies the name of the header that shall be used to forward the encryption strength (number of bits used in the key) used to encrypt the SSL/TLS connection between client and IIS.

-->

<!ELEMENT keysize-header (#PCDATA)>

<!--

The keystore-path element specifies the path and the name of PSE file for SSL/TLS authentication between the extension and the J2EE Engine. If this element is missing, the SAPSSLC.pse file from the keystore-dir directory is used.

The PSE file must contain the certificates needed to authenticate the server certificate of the J2EE Engine as well as the client certificate for the IisProxy extension.

-->

<!ELEMENT keystore-path (#PCDATA)>

<!--

The config element specifies the URLs that can be used to access the IisProxy module itself.

The config element has subelements that define:

source the request URL that shall be processed

-->

<!ELEMENT config (source+)>