The service-passthrough Service SAF forwards a request to another server for processing.
You can configure the number of times the service-passthrough directive tries to get a content from the web server before sending an error to the client by modifying the retries attribute in obj.conf:
<Object name="passthrough"> ObjectType fn="force-type" type="magnus-internal/passthrough" Service type="magnus-internal/passthrough" fn="service-passthrough" servers="http://xxx:8084/" poll-timeout="18000" retries="0" Error reason="Bad Gateway" fn="send-error" uri="/opt/iplanet/web41sp8/docs/badgateway.html" </Object>
The service-passthrough SAF accepts the following parameters:
servers - A quoted, space-delimited list of the servers that receive the forwarded requests. Individual server names may optionally be prefixed with http:// or https:// to indicate the protocol and suffixed with a colon and integer to indicate the port.
poll-timeout - Indicates the maximum time interval between two successive data for a single request. It is the waiting period for data to arrive from the client or the server. Reverse proxy plug-in waits for data to arrive from the client or the server. If there is no data written by either client or server, for poll-timeout interval, then the server logs an error and closes the connection. By default, the poll-timeout value is set to 5 minutes but can range between 1 second to 6 hours. poll-timeout does not represent maximum response time, as it could be much higher than poll-timeout value.
sticky-cookie - (Optional) The name of a cookie that will cause requests from a given client to stick to a particular server. Once a request containing a cookie with this name is forwarded to a given server, service-passthrough attempts to forward subsequent requests from that client to the same server by sending a JROUTE header back to the client. If not specified, sticky-cookie defaults to JSESSIONID.
user - (Optional) The username that service-passthrough uses to authenticate to the remote server through Basic-Auth.
‘user&rsquo' requires that ‘password’ also be specified.
password - (Optional) The password that service-passthrough uses to authenticate to the remote server via Basic-Auth.
‘password’ requires that ‘user’ also be specified.
client-cert-nickname - (Optional) Nickname of the client certificate that service-passthrough uses to authenticate to the remote server.
validate-server-cert - (Optional) Indicates whether service-passthrough should validate the certificate presented by the remote server. If not specified, validate-server-cert defaults to true.
rewrite-host - (Optional) Indicates whether service-passthrough should rewrite the Host header sent to remote servers, replacing the local server’s hostname with the remote server’s hostname. If not specified, rewrite-host defaults to false.
rewrite-location - (Optional) Indicates whether service-passthrough should rewrite the Location headers returned by a remote server, replacing the remote server’s scheme and hostname with the local server’s scheme and hostname. If not specified, rewrite-location defaults to true.
ip-header - (Optional) Name of the header that contains the client’s IP address, or “” if the IP address should not be forwarded. If not specified, ip-header defaults to Proxy-ip.
cipher-header - (Optional) Name of the header that contains the symmetric cipher used to communicate with the client (when SSL/TLS is used), or “” if the symmetric cipher name should not be forwarded. If not specified, cipher-header defaults to Proxy-cipher.
keysize-header - (Optional) Name of the header that contains the symmetric key size used to communicate with the client (when SSL/TLS is used), or “” if the symmetric key size name should not be forwarded. If not specified, keysize-header defaults to Proxy-keysize.
secret-keysize-header - (Optional) Name of the header that contains the effective symmetric key size used to communicate with the client (when SSL/TLS is used), or “” if the effective symmetric key size name should not be forwarded. If not specified, secret-keysize-header defaults to Proxy-secret-keysize.
ssl-id-header - (Optional) Name of the header that contains the client’s SSL/TLS session ID (when SSL/TLS is used), or “” if the SSL/TLS session ID should not be forwarded. If not specified, ssl-id-header defaults to Proxy-ssl-id.
issuer-dn-header - (Optional) Name of the header that contains the client certificate issuer DN (when SSL/TLS is used), or “” if the client certificate issuer DN should not be forwarded. If not specified, issuer-dn-header defaults to Proxy-issuer-dn.
user-dn-header - (Optional) Name of the header that contains the client certificate user DN (when SSL/TLS is used), or “” if the client certificate user DN should not be forwarded. If not specified, user-dn-header defaults to Proxy-user-dn.
auth-cert-header - (Optional) Name of the header that contains the DER-encoded client certificate in Base64 encoding (when SSL/TLS is used), or “” if the client certificate should not be forwarded. If not specified, auth-cert-header defaults to Proxy-auth-cert.
When multiple remote servers are configured, service-passthrough chooses a single remote server from the list on a request-by-request basis. If a remote server cannot be contacted or returns an invalid response, service-passthrough sets the status code to 502 Bad Gateway and returns REQ_ABORTED. This will return an error to the browser. This error can be customized in the Web Server by configuring a customized response for the 502 error code.
When user and password are specified, service-passthrough will use these credentials to authenticate to the remote server using HTTP basic authentication. When one or more of the servers in the servers parameter are configured with a https:// prefix, client-cert-nickname specifies the nickname of the client certificate service-passthrough will use to authenticate to the remote server.
service-passthrough generally uses HTTP/1.1 and persistent connections for outbound requests with the following exceptions:
When forwarding a request with a Range header that arrived through HTTP/1.0, service-passthrough issues an HTTP/1.0 request. This is done because the experimental Range semantics expected by Netscape HTTP/1.0 clients differ from the Range semantics defined by the HTTP/1.1 specification.
When forwarding a request with a request body (For example POST request), service-passthrough will not reuse an existing persistent connection. This is done because the remote server is free to close a persistent connection at any time, and service-passthrough will not retry requests with a request body.
In addition, service-passthrough encodes information about the originating client in the headers named by the ip-header, cipher-header, keysize-header, secret-keysize-header, ssl-id-header, issuer-dn-header, user-dn-header, and auth-cert-headerparameters (removing any client-supplied headers with the same name) before forwarding the request. Applications running on the remote server may examine these headers to extract information about the originating client.