Dispatcher Properties

allowSpecialURLs

< true | false >

If <false> this service is disabled.

If <true> then the dispatcher can be hit with:

1. /.statistics
   
   This returns a simple html status page over the application servers which are defined in the system as well as their UP/DOWN status.
   
   Actual server names are not shown. It is the servers alias which is shown in the list.
   This service is not password protected.
2. /.urlstatistics
   
   This service returns a more detailed page with the URL's which the dispatcher server is hit with. The URL list corresponds to the list which can be seen in the dispatcher servers "details view".
   
   This service is password protected with the static user id / password: stats/giveme
3. /.errorstatistics
   
   
   Shows the last 100 errors that has occurred, errors such as connection to application servers that failed are shown.
   This service is password protected with the static user id / password: stats/giveme
   
   IMPORTANT NOTE:
   As these services return information about the system, it is recommended that this property be set to <false>, as this information can be used by a hacker to get information about the system and its setup.

checkURLs

< true | false >

If <false> then the dispatcher does not validate URL's against rights on the session.

If <true> then the dispatcher validates URL's against rights on the session. If a user (session) does not have access to the URL then the dispatcher will redirect the user to the URL defined in urlAccessFailedURL.

This could for example be used in logon situations, where access to certain URLs are managed by rights which the user has.

Example:
A user is not yet logged on and has therefore an anonymous session. The user attempts to reach a page which requires the user to be logged on. The dispatcher executes:

Agent.getInstance().isURLAllowed()

If this call fails, then the user does not have access to hit the specified URL and this will result in a redirect to a urlAccessFailedUrl which could be a logon page, but it can also be an error page.

<cookie name> - default: sessionid

Name of session cookie to use for storing session ID for requests with http (non-ssl) scheme.

Example:
sessionid

<cookie name> - default: sslsessionid

Name of session cookie to use for storing session ID for requests with https (ssl / tls) scheme.

Note that session cookies for http and https must be different to ensure that any requests originating with http and later switching to https are not mixed - doing so would result in the contents of the session cookie have been transmitted unencrypted across the network.

Also refer to the properties sessionfixationdefence and sessionfixationdefensecookiename

Example:
sslsessionid

cookiename

<cookie name>

Default is <selectedServer>. The value of this cookie is the name of the server which all the following URLS should hit and is set by the dispatcher the first time a request hits the dispatcher.
Note that the actual cookieName will be the name of the alternateserver (or default if not alternateserver) – e.g. "merchantselectedServer=xxxxx"

Note that if stickyservers=false, this cookie is not set.

This cookie is stored in-memory in the browser and the value is the applications servers name selected by the dispatcher (reverse proxy).

The value is a hash of the servername selected, not the actual name.

<true | false>

By default, sticky cookies are not secure, but if samesite=none or if this is set to true, then they are marked as secure to comply with newer browser changes that are starting to ignore non-secure cookies with the samesite attribute set.

usecookiedomain

<true | false>

If true, the domain of the webserver, which the user is sending the request to, will be added to the cookie. This means it can be shared between different servers on the same domain, e.g. server1.domain.com and server2.domain.com. The domain will then e set to ".domain.com".

If set to false, the cookie will not get a domain, so it will only work for the same server, and will not be shared between different domains.

errorpage

<html filename>

This html page is loaded dynamically by the dispatcher. The dispatcher will return this page to the browser if the dispatcher can not get an answer from the application server at the back end.

This page must contain therefore an error page which shows "technical problems" in a user friendly way.

Example:
./webapps/ROOT/technical_error.html

Note that it must point to a file on the filesystem, and not within the webapp, since it is loaded directly from the disk.

alternateErrorpages

<host pattern>=<html filename>[;<host pattern>=<html filename>;…]

This can be used to specify alternate error pages for certain hosts.

If no match is found, the default error page will be shown.

Example:
.portalprotect.dk=./html/pp_error.html;.otherdomain.com=./html/other_error.html

Note that it must point to a file on the filesystem, and not within the webapp, since it is loaded directly from the disk.

invalidSessionidURL

<URL>

This property is used when a session is timed out or in another way invalidated and one will redirect to an end page or a front-page or a logon page.

The dispatcher deletes an invalidated session.

This property only takes effect if the session is invalid corresponding to
PTServer.getInstance().isValid() gives an error

<URL> specifies the URL which the dispatcher will redirect to if there is no valid session on the request. Before redirect the session-cookie is deleted and the original request is stored in a cookie "originalRequest".
If this URL is empty, the dispatcher will create a new session and redirect to the URL the dispatcher was hit by. In this case the application server must handle the error itself or redirect to a logon or error page.

Example:
http://invalid.session.id

In this example the dispatcher will delete the session-cookie and send a redirect (http://invalid.session.id) back to the browser. The browser will call http://invalid.session.id which will present the user for a timeout message.

Example
http://logon.page

In this example the dispatcher will redirect to http://logon.page . The dispatcher will delete the invalid session cookie and set a cookie "originalRequest" which contains the original request. The logon page can then after logon is XXXestable redirect back to the original request, by reading "originalRequest" and send a redirect back to the browser.

Example:
<blank>

In this example a new session is created and the request is forwarded to the applications server. It is expected that the called application handles logon and logoff.

urlAccessFailedRedirect

<URL>

This property holds the URL which the dispatcher redirects to if access to an URL was not allowed, which happens if URL is protected and the user did not have access to it.

Example:
http://no.access.to.this.url

In this example the user is redirected to an "access denied" page.

Example
http://logon.page

In this example the dispatcher will redirect to http://logon.page . The dispatcher will set a parameter "originalUrl" which contains the original request. The logon page can after logon redirect back to the original request, by reading "originalUrl" and sending a redirect back to the browser.

urlAuthRequired

<URL>

The dispatcher will redirect to this URL if the application server returns a HTTP error 401 Unauthorised.

The dispatcher will append the original request URL to the redirect request, so that a logon page can redirect back to the original request.

Example:
The applications server requests BasicAuth in order to identify the user.

As the http request does not contain the http header "Authorization", the application server will answer with a http error 401 Unauthorized.

If the answer from the application server contains the HTTP header
xx-ppignore401response
the dispatcher will not redirect to <URL> but send HTTP error 401 Unauthorized back to the browser.

urlSSLAuthFailedRedirect

<URL> - Default is blank

The dispatcher redirects to this URL if SSL authentication is enabled, and if it fails.

The URL will get the parameters "originalUrl", "errorcode" and "errortext" appended to it which contains the original URL the user attempted to reach, along with the error code and error text explaining why the authentication failed.
The possible error codes are listed in the interface dk.itp.security.passticket.server.AuthErrorCodes and the current list is shown here:

/** No user could be found */
public static final short ERROR_USERNOTFOUND = 1;
/** Invalid password */
public static final short ERROR_INVALIDCREDENTIALS = 2;
/** General error trying to login */
public static final short ERROR_GENERALERROR = 3;
/** User is locked */
public static final short ERROR_LOCKED = 4;
/** User is marked as inactive */
public static final short ERROR_INACTIVE = 5;
/** Userid already exists (when creating new user) */
public static final short ERROR_USEREXISTS = 6;
/** Certificate could not be read/parsed */
public static final short ERROR_CERTIFICATE_UNREADABLE = 7;
/** Certificate is not yet valid */
public static final short ERROR_CERTIFICATE_NOTYETVALID = 8;
/** A certificate in the chain which is not allowed to sign another certificate has been used to do it anyway, so the chain is not trusted */
public static final short ERROR_CERTIFICATE_CHAINBROKEN = 11;
/** The certificate did not match the one in our database */
public static final short ERROR_WRONG_CERTIFICATE = 12;
/** The signed text did not match expected text */
public static final short ERROR_SIGNTEXTINVALID = 13;
/** CA (certificates issuer) was not found and is unknown to current configuration */
public static final short ERROR_UNKNOWN_CA = 1001;
/** PID service not implemented by CA, could not validate connection between CPR and PID */
public static final short ERROR_PID_SERVICE_NOT_AVAILABLE = 1002;
/** general PID error, check log */
public static final short ERROR_PID_ERROR = 1003;
/** certificate was found on revocation list */
public static final short ERROR_CERTIFICATE_REVOKED = 1004;
/** certificate expired or not yet valid */
public static final short ERROR_CERTIFICATE_EXPIRED= 1005;
/** certificate error, ex. Key errors or signature error, check log */
public static final short ERROR_CERTIFICATE_ERROR= 1006;
/** certificate error, ex. Key errors or signature error, check log */
public static final short ERROR_CRL_NOT_FOUND= 1007;
/** general PID error, check log */
public static final short ERROR_PID_CPR_NOT_MATCH = 1008;
/** Attribute lookup service not implemented by CA */
public static final short ERROR_ATTR_SERVICE_NOT_AVAILABLE = 1009;


If the URL is blank or not configured, the user will continue as an anonymous user.

modifyHostHeader

< true | false >

If <true> the dispatcher will change the HTTP requests HOST header. The dispatcher will change it to what is in targetServers.

If <false> the dispatcher will not change the HTTP requests HOST header.

Example:
If an application server, for example, BEA WebLogic with an Apache server in front is defined to listen on the VirtualHost myserver.mydomain.com, then the content in the HOST header must be exactly myserver.mydomain.com in order to get the Apache server to send the request on to WebLogic.

If modifyHostHeader = false, then the call from the browser must be set to http://myserver.mydomain.com. Host myserver.mydomain.com points at the dispatcher and the dispatcher forwards the request unmodified to one of the servers defined in targetServers.

Example:
If modifyHostHeader = true, then the URL from the browser be the dispatchers IP address or a DNS name which is converted to the dispatchers IP address.

The dispatcher will now change the HTTP requests HOST header to be the chosen targetServer – the back end application server.

That is targetServer should be according to the example myserver.mydomain.com

modifyRedirectLocation

<true | false>

If true, the dispatcher will look at the redirect location on the header sent from the application server, and if it starts with "http://" and if it is not a redirect to another webserver, it will change it to a relative URL to prevent changing protocol from https:// to http://

Your application server might believe that only http and not https was used by the end user (since the dispatcher will talk to it using http), and if it sends fully specified redirects back (with http:// in front) then this will fix it. Setting it to false will prevent the dispatcher from modifying the location parameter in the HTTP response header.

The default value is true.

stripRedirectPort

<true | false>

If true, the dispatcher will look at the redirect location on the header sent from the application server, and if it starts with "servername:" – ie. If the application server adds a port number to the location header, the URL is changed to a relative URL, e.g. "Location:

http://servername:8081/images/abc.gif

" is changed into "Location: /images/abc.gif" – this works around a potential problem where some application servers (which are accessed by the dispatcher via http protocol, and often not on port 80) does full redirects to the hostname and port they believe to be running on.

The default value is false.

pingurl

<application part of the URL or http://hostname/url> - default: /

Example:
/servlet/pingServlet

In this example the dispatcher will connect the or those target servers which are defined in the targetServers on the specified <URL>

This "ping" works as "are-you-there" and to establish if the server is up'n running, if the server returns the HTTP response "200 OK", it is assumed to be alive and well, any other responses are treated as a failure.

If the specified URL starts with http://hostname, then the hostname will be added to the Host header before the ping is sent to the application server.

pingRetryCount

<integer> - default 0

Number of times to retry ping in case it fails. If set to nonzero, ping will be retried a number of times in case of failure to give the server a chance of replying successfully before taking it down.

Normally you do not need to change this setting, but in case you have an unstable server that you do not want to mark as down, this gives you a chance to retry in case of failures.

Note that you can also change this setting for a specific alternate server definition.

httpsessionkeepalivepingurl

<URL> - default is the value of pingurl.

This URL is used if the HTTP Session keepalive feature is enabled (done by setting httpSessionKeepAlivePingInterval to a value larger than 0 in the session controller).

The session controller will then periodically ask dispatchers to ping this URL on behalf of the user – this is done to keep the http session alive on all the backend servers the user has accessed even if he is only active on a single backend application.

dispatchergroup

<name of group of dispatcher> - Default is "default"

String containing name of dispatcher group, e.g. "group1", "internal", "external", "segment4" – this name must be shared between all dispatchers in a group for http session keepalive pinging to work.

In environments with multiple different dispatcher setups, e.g. a set of dispatchers for internal users and another set for external users, this is used to identify which dispatchers shares a set of backend servers.

When doing http session keepalive pings, the session controllers will select a random live dispatcher from within a dispatcher group and ask it to ping http sessions on application servers on behalf of the user – it needs the group name to be able to see which dispatcher share the same list of accessible application servers.

pingurlinterval

<time in seconds>

This property specified the interval between the "pings" from the dispatcher to the application server.

Example:
30

In this example the dispatcher will send ping requests to the or those application servers defined in targetServers every 30 seconds.

sessioncookieforwardname

<name of sessions cookie>

This property specifies the name of the cookie which contains the security systems sessionid. The application on the application server needs to read a cookie with the specified name on the HTTP request.

Example of code which reads the cookie.

Public String getSessionID(HttpServletRequest req, HttpServletResponse resp) throws PTException {
Cookie[] cookies = req.getCookies();
Cookie sessionCookie = null;
for (int I = 0; sessionCookie == null && I < cookies.length; i++) {
if (cookies[i].getName().equals("ppSessionID"))
sessionCookie = cookies[i];
}
return sessionCookie.getValue();
}


Example:
ppSessionID

In this example a cookie is put on the request to the application server with the name "ppSessionID". The value of the cookie is the security systems session ID.

useridHeaderName

<name of HTTP header>

This property specifies the name of an HTTP header, where the userid of the currently identified user will be placed. If the user is anonymous, this header won't be present in the request when it reaches the application server.

Example:
PPUserID

In this example, the userid (if the user is identified) will be placed in the PPUserID HTTP header, where the application can retrieve it from.

usernameHeaderName

<name of HTTP header>

This property specifies the name of an HTTP header, where the user name of the currently identified user will be placed. If the user is anonymous, this header won't be present in the request when it reaches the application server.

Example:
PPUserName

In this example, the user name (if the user is identified) will be placed in the PPUserName HTTP header, where the application can retrieve it from.

usergroupsHeaderName

<name of HTTP header>

This property specifies the name of an HTTP header, where a comma separated list of user groups for the currently identified user will be placed. If the user is anonymous, this header won't be present in the request when it reaches the application server.

Example:
PPUserGroups

In this example, the list of user groups (if the user is identified) will be placed in the PPUserGroups HTTP header, where the application can retrieve it from.

customHttpHeaders

<name of HTTP header>, <name of session variable>, [true/false] [ <;><name of HTTP header>, <name of session variable>, [true/false] [….] ]

This property allows for setting HTTP headers towards the application server. This is typically used when the dispatcher server is replacing an existing front end and the dispatcher server needs to emulate the behaviour of that server.

The first parameter is the name of the HTTP header, the second is a name of the state variable in the user session, the third and optional parameter specifies whether this header only should be present when the session is logged on (default is true). Each parameter is separated by a semicolon and all HTTP header names and state variable names are trimmed when read. When configuring this value keep in mind not to overwrite standard HTTP headers or have duplicate values. To make sure the the state variables are replicated to restricted dispatchers use the "safeStateVariables" configuration on the session server to list required variables for your applications.

If the value starts with "__" (two underscores) then it is taken literal and not assumed to be the contents of a state variable.
You can use this to hardcode the value of a new HTTP header, e.g. "WL-Proxy-SSL,__true,false" will always add the HTTP header with the value "true" like "WL-Proxy-SSL: true".

Some specific values will be detected since there a standard session state variables that are not accessible through their names. These values does not require "safeStateVariables " configuration.

• uniqueid
  The users full unique ID, with session ID, request ID etc.
• sessionid
  The users Session ID
• userid
  Will point to the userid in the session e.g. Agent.getUser( )
• groups
  Includes a comma separated list of user groups in the header
• username
  Will point to the username in the session, e.g. Agent.getUsername()
• userip
  Will point to the remote IP address in the session e.g. Agent.getUserIP( )
• channeltype
  Channel type from request ID, 1=HTTP, 2=SSL, 3=SCL
• isloggedon
  Defines whether the user is logged on or not (true/false) e.g. Agent.isLoggedOn( )
• isinternal
  True/false value depending on whether the session represents an internal user Agent.isInternalUser( )
• agreementid
  Agreement ID – from Agent.getAgreementID()
• customerid
  Customer ID – from Agent.getCustomerID()
• authlvl
  Points to the authenticationlevel of an authenticated session e.g. Agent.getAuthenticationLevel( )
• authmethod
  Will point to the authenticationMethod in the session e.g. Agent.getAuthenticationMethod( ). By default this value will be mapped directly to the ID representing the authenticationplugin. If the ID is given in the authenticationMethodMap list, the name represented there will be used instead.
  
  

authenticationMethodMap

<auth-method>=<name>[;<auth-method>=<name> [;…] ]

This property can contain a list of name-mappings for authentication methods. These names will be used if filling out custom HTTP headers. If an authentication method matches the id given here the name represented here will be used instead of the normal authentication method type (which is number).

sockettimeout

<time in milliseconds>

This property specified the number of milliseconds before the PortalProtect dispatcher will wait for an answer from the application server.

Example:
60000

In this example the PortalProtect dispatcher will wait 60 seconds for an answer from the application server before the dispatcher will respond with an error page which is defined by the property: errorpage.

If the answer from the application server is greater that 60 seconds in replying this values needs to be set up.
In some cases it can be helpful to set this value high. Some applications, which compile JSP pages first time they are hit can take longer than 60 seconds to process. In these cases one can either precompile JSP pages or set the value up.

Note that if using HTTP 1.1, this property is not used, in that case use "http11.responseTimeout" instead.

targetservers

<host :port,alias> [< ;> <host :port,alias> […] ]

This property defines the backend application servers which the dispatcher needs to forward requests to. The first time the dispatcher is hit by a request from a browser, the dispatcher chooses the applications server which is least loaded. The load is calculated by looking at the servers response time and its ping time. The chosen server is stored in a cookie which is sent back to the browser. The next time the dispatcher is hit, the server name is read from the cookie and the dispatcher will send the request on to the same server. Therefore saving session state on the application server. It is therefore not necessary to run the application server in a session shared setup.

The name in the cookie which is sent to the browser is the aliasname. Thereby ensuring that the browser does not receive physical host names and ports. Note that the alias on a target server must be unique, as the dispatcher uses the alias alone to find the correct target server.

By setting up consul (www.consul.io) you can ask PortalProtect to query it periodically to dynamically change the list of available application servers by adding and removing services within consul. This is useful for scaling up or down in cloud services.
Do this by using the macro ${consul:/consul_url} in the "targetservers" configuration – e.g. ${consul:/v1/catalog/service/appservers}

Example:
server1:8080,appserver1;server2:8081,appserver2

In this example there are two target servers defined: and application server with the alias appserver1 on host server1 and port 8080 and an application server with the alias named appserver2 on host server2 and port 8081.

applicationName

<comma separated list of applications>

Contains one or more application names that the default targetservers are protected by. The application name must correspond directly to what is stored in LDAP – ACLs/Operations will be checked in order for each application until a match is found, or until all applications have been checked.

performanceTrace

<true | false>

If <true> the dispatcher will store a timestamp "A" when the dispatcher is hit. "B" is stored when the dispatcher forwards a request to the chosen targetserver. "C" is stired when the answer comes back from the application server and "D" when the dispatcher sends the answer back to the browser.

The information is stored in a HTTP response header under the name "X-TunnelStamp". This timestamp information is read by WebLoad and used in WebLoads report generation.

This trace has no detectable measurable overhead.

Example:
<true>
The dispatcher will store timestamps for the 4 checkpoints and store the result in the HTTP response header.

<false>
The dispatcher does not execute the performance trace.

agentvalidator

<java class>

This implementation of IagentValidator implements access control functionality in the PortalProtect agents.

Example:
dk.itp.security.authentication.passticket.DefaultValidator

sessioncontrollers
ptsserver

<host:port> [ <,|;> <host:port> […] ]

This property is the list of session controller servers that the dispatcher server can connect to to create valid sessions. As the dispatcher server typically will be in an insecure DMZ, this type of connection is a restricted-peer connection.

A restricted-peer connection is a connection where the session controller will remove person related information stored on the session before data is sent to the dispatcher in the insecure DMZ.

Connections to session controller servers must therefore correspond to Session controller > General > server.restrictedport

Example:
sessioncontroller1:8081, sessioncontroller2:8081

In this example the dispatcher server connections to the two session controller servers. Both session controller servers will listen on restricted-peer port 8081.

useSSLForRestrictedPeer

<true | false>-

This property specifies whether the dispatcher should connect to the session controller via an SSL encrypted line or if the connection should be established unencrypted.

If the dispatcher is in the DMZ, it is recommended due to security reasons to connect the dispatcher in the DMZ to the session controller in the secure intranet zone via an encrypted connection. In this case the property is set to <true>
If the dispatcher is on the secure intranet then encryption is not necessary. In this case the property is set to <false>
NOTE: If the dispatcher is connecting to a restricted port on the session controller, then it is not able to login users.
IMPORTANT: This property must be set in the same way in the session controllers configuration. Either both servers run unencrypted or both servers run encrypted. The dispatcher will not establish a stable connection to the session controller if this is the case.

Note that this setting is no longer used, instead the schema on the connection URL decides – e.g. tcps://server:port or nios://server:port for SSL encrypted blocking or nonblocking UI.

tunnelplugins

<semicolon separated list of class names>

Defines the list of dispatcher plug-in's, which are able to perform their own ACL checking and/or modification of the requests/responses.

Example:
com.msl.security.dispatcher.HttpUserCookiePlugin

SSLencryptionheader

<http header name>

Name of an http header that is set, if the request has previously been encrypted, and decrypted by e.g. a hardware SSL device.

Note that this should only be used with e.g. a hardware SSL box such as Intel, Netscaler, Ingrian, Kemp, Nokia or similar.

SSLclientcertificateheader

<http header name>

Name of an http header, from where the dispatcher will read the clients certificate. If the request came from an IP address listed in SSLacceleratorlist, and if the specified header contains an X509 certificate, it will be used as the client certificate.
Note that this option only applies for use with e.g. a hardware SSL box, or similar device which forwards the users client certificate in an HTTP header.

SSLacceleratorlist

<List of servers / IP addresses>

List of servers from which the 3 headers mentioned in "SSLencryptionheader", "SSLclientcertificateheader" and "clientipheader" is accepted.

Note that this should only be used with e.g. a hardware SSL box..
The dispatcher will use these headers to get the clients real IP address, and to see if the request was encrypted when it arrived.

[disabled;][ignorecase;]<rule1>;<rule2>;....> 
xxxx is replaced by a number between 1 and 512

SSL Accelerator rules – requests matching these rules are considered to be originating from the SSL accelerator, just like the SSLacceleratorlist property - but with this rule, you can check against the presense of HTTP header or specific URLs.

Rule matching is by default case sensitive, but if "ignorecase;" is specified, case will be ignored in comparisons for this rule. 
The key can either be "url", "scheme" (http/https) or the name of a http header to match – if all the rules match, the request is considered to be originating from the SSL accelerator, and the headers listed in SSLacceleratorlist property above will be checked .

clientipheader

<http header name>

Name of an http header that contain the client's real IP address.

Note that this should only be used with e.g. a hardware SSL dispatcher.

addauthorizationheader

<true | false> - Default false

If set to true, an "Authorization: Basic" header will be added to the request when sent to the application server, which contains either the session ID of the current user, and the password "password", or the authenticated users userid and password depending on the value of addedAuthorizationHeaderContainsSessionID.

When forwarding the session ID, this will cause "request.getRemoteUser()" on the application server to return the session ID for the current user, depending on the security filters and plugins installed on the application server. Note that this is the default value used for all alternate servers, but it can be overwritten by adding the property "alternateserver.xxxx.addauthorizationheader".

Example:
false

addauthorizationheaderonlyforidentified

<true | false> - Default false

If true, and addauthorizationheader is set to true, then the header will only be added if the user is identified. If false, the header will still be there both for identified and unidentified users. It is used by e.g. weblogic authentication plugin to authenticate the user to the weblogic server. Note that because of a bug in weblogic 8.1 SP6, you should set this property to true if the application server is running this version, since without it you will not be able to view even unprotected pages.

addedAuthorizationHeaderContainsSessionID

<true | false> - Default true

If true, and if addauthorizationheader is set to true also, then the dispatcher will add the session ID to the authorization password, if false the dispatcher will add the users userid and password (assuming the user is authenticated) instead.

Note that for this to work, the dispatcher needs access to the password, so you might need to set the property hidePasswordFromDispatcher=false in the session controller.

Note that his property can be overwritten for each alternateserver definition by setting
alterserver.xxxx. addedAuthorizationHeaderContainsSessionID.

restrictAuthorizationHeaderToUrls

<pattern> - Default null

If configured and nonblank, Authorization: Basic header will only be added to the URLs which match the pattern defined.

The pattern can contain wildcard characters * and ?, and can be used to separate multiple matches, ^ can be used as the first character to negate the match.

Examples:
/secure/*|*.jsp
^*.css|*.gif|*.jpg|*.js

addviaheader

<true | false> - Default: true

Add the "Via:" header to the http response.

By default, PortalProtect adds a Via: header to the http response, containing the dispatcher name, e.g.
Via: 1.1 dispatcher1

This can be turned off by setting addviaheader to false.

addppversioninviaheader

<true | false> - Default: false

If set to true, and if addviaheader is enabled, the PortalProtect version is added to the Via: header – e.g.
Via: 1.1 dispatcher1 (PortalProtect/v4.199)

This can be useful for diagnosing which route a request has taken through complex setups, but be care ful about turning it on since it reveals which portalprotect version is running to clients.

alternateservers

<list of server names>

List of alternate servers, that can be used instead of the default servers mentioned in the targetservers property.

alternateserver.xxxx.targets

<host :port,alias> [< ;> <host :port,alias> […] ]

Replace xxxx with the name of the alternate server

This property defines the backend application servers which the dispatcher needs to forward requests to. The first time the dispatcher is hit by a request from a browser, the dispatcher chooses the applications server which is least loaded. The load is calculated by looking at the servers response time and its ping time. The chosen server is stored in a cookie which is sent back to the browser. The next time the dispatcher is hit, the server name is read from the cookie and the dispatcher will send the request on to the same server. Therefore saving session state on the application server. It is therefore not necessary to run the application server in a session shared setup.

The name in the cookie which is sent to the browser is the aliasname. Thereby ensuring that the browser does not receive physical host names and ports. Note that the alias on a target server must be unique, as the dispatcher uses the alias alone to find the correct target server.

By setting up consul (www.consul.io) you can ask PortalProtect to query it periodically to dynamically change the list of available application servers by adding and removing services within consul. This is useful for scaling up or down in cloud services.
Do this by using the macro ${consul:/consul_url} in the configuration – e.g. ${consul:/v1/catalog/service/appservers}

Example:
server1:8080,appserver1;server2:8081,appserver2
server1:8080,appserver1;[unavailable]server2:8081,appserver2

In the first example there are two target servers defined: and application server with the alias appserver1 on host server1 and port 8080 and an application server with the alias XXXesta appserver2 on host server2 and port 8081.
In the second example, server2 is initially marked as being unavailable by the tunnel, which can be used if the server is out-of-service for any length of time, but we still wish to keep it in the configuration.

alternateserver.xxxx.pingurl

alternateserver.xxxx.pingDisabled

<true or false> - Default is false

Set to true to disable pinging for this server, no matter what the pingurl is set to.
If ping is disabled, all server instances are assumed to be up and running.

alternateserver.xxxx.pingRetryCount

<integer> - Default is the value of pingRetryCount which default is 0

See description of pingRetryCount for information.

alternateserver.xxxx.httpsessionkeepalivepingurl

<URL to ping when using the http session keepalive feature> (Default: the value of "alternateserver.xxxx.pingurl")

Used if another URL than the pingurl should be used for keeping the http session alive on behalf of the user if this feature is enabled in the session controller.

alternateserver.xxxx.clusterID

<integer 0-255> (Default 0)

In multi-cluster setups, when new sessions are created they are created in the default cluster specified using clusterID inthe agent configuration. This option allows it to be overwritten, so new sessions for certain applications are created in another cluster than the default.

alternateserver.xxxx.urlAccessFailedRedirect

<URL>

Allows you to override the default URLs for each alternate server.
See the description for the property urlAccessFailedRedirect.

alternateserver.xxxx.concurrentConnectionsWarning
alternateserver.xxxx.concurrentConnectionsLimit

<Number or percentage>

Can be used to change the default warning and hard limits on the number of concurrent connections for this particular application. If a percentage is specified, the percentage will be taken from the value of dispatcherThreads,

alternateserver.xxxx.modifyHostHeader

<true | false>

Allows you to override the default modifyHostHeader setting for an individual server, see description of "modifyHostHeader" for details on what it does.

alternateserver.xxxx.ignore401

<true | false>

If set to true, 401 responses will pass through the dispatcher, instead of ending up in redirects to a login pages. This can be used for alternate servers that the dispatcher simply dispatches requests to, but doesn't protect – e.g. if the servers have their own authentication scheme.

alternateserver.xxxx.addauthorizationheader

<true | false>

See addauthorizationheader – it can be used to switch authorization headers on or off for specific servers.

alternateserver.xxxx.addauthorizationheaderonlyforidentified

<true | false>

See addauthorizationheaderonlyforidentified – can be used to switch it on or off for specific servers. If not specified, the default as specified in addauthorizationheaderonlyforidentified is used.

alternateserver.xxxx.addedAuthorizationHeaderContainsSessionID

<true | false> Default is what addedAuthorizationHeaderContainsSessionID is set to

See addedAuthorizationHeaderContainsSessionID – used to set the value different from the default for specific alternate servers.

alternateserver.xxxx.restrictAuthorizationHeaderToUrls

<pattern> Default is what restrictAuthorizationHeaderToUrls is set to

See restrictAuthorizationHeaderToUrls – used to set the value different from the default for specific alternate servers.

alternateserver.xxxx.supportWeblogicClustering
alternateserver.xxxx.weblogicCookieName

Override the default for supportWeblogicClustering and weblogicCookieName for the specific server – see description on those properties for details.

alternateserver.xxxx. generateWeblogicPluginHeaders

Overrides the value for generateWeblogicPluginHeaders for an individual alternate server – see the description of generateWeblogicPluginHeaders for details.

alternateserver.xxxx.pingrule.yyyy

Defines a ping rule for this alternate server – see the pingrule.x description for details

xxxx is the name of the alternate server,
yyyy is a number, where the first rule has number 1, the second 2 etc. – maximum is 512.

alternateserver.xxxx.invalidSessionidURL

Defines an URL to redirect to if the session ID is invalid.

Xxxx is the name of the alternate server.

Overrides the value of invalidSessionidURL for this specific alternate server – see description of invalidSessionidURL for details.

alternateserver.xxxx. urlSSLAuthFailedRedirect

Defines the URL the user is redirected to if SSL certificate authentication fails.

Xxxx is the name of the alternate server.

Overrides the value of urlSSLAuthFailedRedirect for this specific alternate server – see description of the urlSSLAuthFailedRedirect property for details.

alternateserver.xxxx.sslRequired

If true, the server can only be accessed using SSL and not unencrypted http.

Xxxx is the name of the alternate server.

Overrides the value of sslRequired for this specific alternate server – see description of the sslRequired property for details.

alternateserver.allowedHttpMethods

List of allowed HTTP methods – defaults to the value of the property allowedHttpMethods

Xxxx is the name of the alternate server.

Overrides the value of allowedHttpMethods – see description of allowedHttpMethods property for details.

alternateserver.xxxx.urlAuthRequired

URL user is redirected to if authentication is required – defaults to the value of the property urlAuthRequired

Xxxx is the name of the alternate server.

Overrides the value of urlAuthRequired – see description of urlAuthRequired property for details.

alternateserver.xxxx.modifyRedirectLocation

Specify if the redirect location header should be modified – defaults to the value of the property modifyRedirectLocation

Xxxx is the name of the alternate server.

Overrides the value of modifyRedirectLocation – see description of modifyRedirectLocation property for details.

alternateserver.xxxx.pingUsingSession

Specify if a session ID should be used when pinging the application server – defaults to the value of the property pingUsingSession

Xxxx is the name of the alternate server.

Overrides the value of pingUsingSession – see description of pingUsingSession property for details.

alternateserver.xxxx.service.window.url
alternateserver.xxxx.service.window.begin
alternateserver.xxxx.service.window.end

Overrides the service window settings for a specific alternate server. The service.window.* properties are used as default values if nothing is specified per alternateserver.

Xxxx is the name of the alternate server.

See the description of the service.window.* properties for details.

alternateserver.xxxx.allowipswitchwithinranges

Overrides the property configured for the dispatcher – see the description of allowipswitchwithinranges for details.

Xxxx is the name of the alternate server.

The default is what is configured for the dispatcher.

alternateserver.xxxx.customHttpHeaders

Overrides the customHttpHeaders property configured for the dispatcher. This allows it to specify it for individual alternate servers.

Xxxx is the name of the alternate server.

alternateserver.xxxx.addviaheader

Overrides the addviaheader property configured for the dispatcher – this allows it to be specified for each individual alternate server.

Xxxx is the name of the alternate server.

alternateserver.xxxx.storeUserAgentInSession

Overrides the storeUserAgentInSession property configured for the dispatcher – this allows it to be only enabled for some specific alternate servers.

Xxxx is the name of the alternate server.

If set to true, the dispatcher will check the session, and if it does not contain the state variable "httpUserAgent" then it will create it and add the value of the HTTP header User-Agent to it.
Note that only the first 512 characters of the User-Agent header will be stored in the session in case its value exceeds 512 characters in length.

The value in the session can then be used by authentication plugins or applications for user-agent specific behaviour or logging.

serverrule.xxxx

[disabled;][ignorecase;]<alternateservername;<rule1>;<rule2>>

<rule> = key=<pattern>

xxxx is a number, where the first rule has number 1, the second 2 etc. – maximum is 512.

Rule matching is by default case sensitive, but if "ignorecase;" is specified, case will be ignored in comparisons for this rule.
The key can either be "url", "scheme" (http/https) or the name of a http header to match – if all the rules match, the specified alternateserver will be used instead of the default server.

Note: The serverrules are used to select one of the alternate servers, if a given http header in the request matches the pattern, or if the url matches the defined pattern. This way the dispatcher can sit in front of multiple separate application servers, and handle the dispatching to them based on the URL or host, or another http header.

The pattern can contain * to match 0 or more characters, ? to match exactly one character, and to provide alternative matches. If the pattern starts with ^ then the pattern is a negative match – it can be used to create rules which are executed if a given value does NOT match the pattern.

Example
server1;host=.somedomain.com;url=/some/
ignorecase;server2;host=*.PortalProtect.dk
defaultserver;url=^/contexturl/*|/contexturl2/* (must match neither /contexturl/* nor /contexturl2/* )

server1;ignorecase;host=*.mydomain.com;scheme=https

oauthrule.xxxx

[disabled;][ignorecase;]<required | optional;<rule1>;<rule2>>

OAuth2.0 rules – requests matching these rules are scanned for an OAuth bearer token either in the HTTP Authorization header, or as an URL parameter named access_token.

Rule matching is by default case sensitive, but if "ignorecase;" is specified, case will be ignored in comparisons for this rule.
The key can either be "url", "scheme" (http/https) or the name of a http header to match – if all the rules match, the specified alternateserver will be used instead of the default server.

If required is specified, then an access token needs to be present, and if not the request will be denied with a 401 Authentication Required, and a WWW-Authenticate header requesting Bearer token authentication according to the OAuth standard.
If optional is specified instead, the bearer token is not required, and default processing continues if it is not present in the request.

Note that if a matching access token is found in the request, and if an authentication plugin then creates a new session based upon this access token, then this session will be used and no sessionid ticket is created. The session is cached by the agent as any normal session.

oauth.realmname

<string – only US-ASCII characters should be used> - default "portalprotect"

Specify the realm name to use if sending a 401 Authentication required request based upon the oauthrule.xxxx rules.

disableIPChecking

<true | false> - Default: false

If true, IP address checking is disabled, this means that the dispatcher will accept session Ids from any IP address, without checking if the browser came from the same address as the session ID indicates.

It is NOT recommended to disable IP checking, since it increases risk of session hijacking, but in some situations where SSL is always used to encrypt communication, and where a pool of proxy servers that are not using stickiness are in place, it might be needed.

But, first look at allowipswitchwithinranges and ipranges – it might solve your need.
Also, look at allowgeoipswitching which is easier to manage than specific IP ranges, and allows switching within certain countries, ISPs or based on other parameters.

Important
Note that if you place a state variable in the users session with the name "pp_disable_ipchecking" and the value "true", then IP checking will not be performed by the dispatcher for this particular session, so this is a method to override the IP check only for specific sessions.
It also works if disableIPChecking is set to true, and you need to enforce IP checking for a particular session, then you can set pp_disable_ipchecking=false as a state variable in the session you wish to be exempted from the disabled check.

Example
disableIPChecking=true

maximumIPAdresses

<integer> - Default: 0

If IP switching is enabled, Specify the maximum different IP addresses a session is allowed to switch between.
If this is set to 0, it is disabled and no maximum is enforced.

allowipswitchwithinranges

<true | false> - Default : false

If this property is set to true, the user is allowed to switch IP addresses between IPs within any single configured ip range. The user cannot switch IP addresses between addresses specified in separate ranges.

Note that this property has no effect if disableIPChecking is set to true.
Note that for alternate servers, the value of this property can be overwritten individually.

If the client switches IP address, the state variable "clientipaddresslist" will contain the list of IP addresses (other than the one embedded in the session ID) that the client has used previously. Note that this state variable is only updated if it is less than 2048 characters to ensure a client cannot flood the session size by changing IPs.

Example:
allowipswitchwithinranges=true

ipranges

<List of range names, separated by ; or ,> - Default empty list.
Contains a list of individual IP range names.

If allowipswitchwithinranges=true either globally for a dispatcher, or for an individual alternateserver definition, then a user is allowed to switch client IP address from one of the IP addresses inside the range to another within the same range.

Example:
ipranges=tdc;denmark;local

iprange.xxxx.rangefile

<filename> - xxxx is the name of the range as defined in ipranges

Points to a file which contains a list of IP addresses to add to the named range

4 different notations are supported:

Single IP Address - e.g. 127.0.0.1
IP Range - e.g. 192.168.1.1-192.168.1.16
CIDR bits notation - e.g. 192.168.1.0/30
CIDR netmask notation - e.g. 192.168.1.0/255.255.255.0

Example:
ipranges.denmark.rangefile=${portalprotect.home}/config/daniship.txt

iprange.xxxx.zzz

<IP range> - xxxx is the name of the range as defined in ipranges. zzz is an ID between 1 and 512

The syntax of a given range is the same as for the rangefile described above.

Example:
iprange.denmark.1=192.168.0.0/24
iprange.denmark.2=10.0.0.0-10.0.255.255

<Name of range> - no default.

If specified, must contain the name of a configured IP range - any requests from this range are then valid for all sessions, so if a request originates from an IP in the range no further checking is done.

This can be used if you have e.g. a range of local IPs which do some kind of action on behalf of sessions created for users from other IP addresses.

Example:allowAllFromIPRange=local

allowgeoipswitching

<NONE, ISP, ORGANIZATION, COUNTRY, CITY, DISTANCE or COMPLEX> - Default: NONE

Allows switching of IP addresses based on GeoIP data.

NONE: No swithing allowed.
ISP: Switch within same Internet Service Provider allowed.
ORGANIZATION: Switching between IPs belonging to the same organization allowed.
COUNTRY: Switching between IP addresses in the same country allowed.
CITY: Switching between IP addresses in the same city is allowed.
DISTANCE: Switching between IP addresses nore more than maximumgeoipdistance from the original IP address is allowed.
COMPLEX: Complex rules are possible – this enables the user of complexgeoiprule.xxxx

Note that setting allowgeoipswitching to anything other than NONE requires that the GeoIP databases are loaded by the session controller – see geoip.database setting for the session controller for details.

Also note that GeoIP data are not entirely accurate, depending on which level you look at. The Country and ISP data are fairly accurate, but organization, city and location accuracy is not as good.

If the client switches IP address, the state variable "clientipaddresslist" will contain the list of IP addresses (other than the one embedded in the session ID) that the client has used previously. Note that this state variable is only updated if it is less than 2048 characters to ensure a client cannot flood the session size by changing IPs.

We cannot guarantie the accuracy of the GeoIP data. You can purchase more accurate databases than the default ones, contact support if you need that, or purchase directly from https://www.maxmind.com

maximumgeoipdistance

<Distance in kilometers> – Default: 100

If allowgeoipswitching is set to DISTANCE, this is the maximum distance in kilometers from the original IP address that we allow switching to take place for.

<true or false> - Default is false (Requires minimum version 5.67)

If set to true, anonymous users are allowed to switch IP address - note that if those users later authenticate, and do not use the original IP, then the request will fail. Use GeoIP matching instead if possible.

urlInvalidIPRedirect

<URL or 403> - Default is blank.

If the user is not allowed to switch to the new IP, this parameter controls what happens. If it is blank, the default behaviour occurs where the dispatcher sends an error with HTTP 400 indicating an invalid request.
If this URL is set to 403, an HTTP 403 error is sent back to the client instead.

Otherwise, the session cookie will be removed from the browser, and it will be redirected to the URL. Once the request comes in again with the URL the user will then get a new anonymous session.

Before redirecting to the URL, the parameter "originalUrl" is added to the request with the user's original URL, and the parameter "hadSessionID" is added with the old session ID. Since that ID still exists, it is possible for the error page to use that to determine how best to inform the user what happened.

Please note that because the client might switch IP a lot of times, e.g. if he is behind a cluster of loadbalanced proxy servers with no stickiness, the error URL should be kept simple and contain embedded css and images to avoid more than a single HTTP request.

alternateserver.xxxx.urlInvalidIPRedirect

<xxxx is the name of the alternateserver>

Override the value of urlInvalidIPRedirect for a specific alternate server.

complexgeoiprule.xxxx

<rule entry – xxxx is replaced with a number between 1 and 512 for maximum of 512 rules>

If allowgeoipswitching is set to COMPLEX, then these rules are enabled – here you can specify up to 512 different rule that allow very detailed control over which IP addresses it is possible for a user to switch between.

The format is: keyword=keyword OR keyword="string pattern" or distance=km – multiple conditions can be added separated by &

These keywords exists: ip1, ip2, country1, country2, isp1, isp2, organization1, organization2, city1, city2,postal1, postal2, region1, region2, distance

The ones ending with "1" represent the original IP address and the ones with "2" represent the new IP that the user is switching to.

Let's take a few simple rules….
country1=country2
Here, there is a match if both IP addresses are in the same country.

isp1=isp2
Here, there is a match if both IP addresses are behind the same ISP.

Now a little more complex…
country1=country2&country1="SE|DK|FI|NO"

Here, switch is allowed within the same country, but ONLY if the country is Sweden, Denmark, Finland or Norway – users in other countries cannot switch IP.

country1=country2&country1="SE|DK|FI|NO"&distance=200
Same as before, but only within a distance of 200 kilometers.

ip1="2.104."&ip2="2.104."&isp1="Tele*|Telia"
Here, switch is allowed for IP addresses 2.104.xxx.xxx but only if the original ISP matches the pattern "Tele*" or "Telia".

So, as you can see you can create some quite powerful and details rules to control exactly when switching is allowed.

If a single rule in the list matches, access is allowed and no further checking is done against the other rules in the list. The log in the dispatcher contains detailed information when IP switching was allowed, including the name of the rule that allowed access.

After changing these rules (especially the more complex ones), it is a good idea to monitor the logs to verify that they work as intended.

environmentID

<0..255> - Default: 0

ID of the environment in which this server is located, the environment ID can be used by applications for authorization, allowing access to certain resources only if the request originated in a certain environment.

Example
environmentID=1

segmentID

<0..255>

ID of the segment in which the server is located – the segment is part of the session ID and can be used to ensure that e.g. internal and external users are impossible to mixup if the dispatchers are kept separate.

The dispatcher will check all incoming requests against the configured segment ID, and consider the session to be invalid if the ID doesn't match, even though the session itself might be valid.
On the session controller, access to authentication plugins can also be restricted by segment ID.

Example
XXXestableXXX=1

dispatcherThreads

<Number>

Maximum number of simultaneous requests allowed by the webserver – this number can be used together with limitTriggerLevel, concurrentConnectionsWarning and concurrentConnectionsLimit to limit the number of simultaneous connections a single application can use.

If dispatcherThreads or limitTriggerLevel is set to 0, the max connections check is disabled. Also, if concurrentConnectionsLimit for a single application is set to 0, that application will not have a limit to the number of concurrent connections.

Example:
dispatcherThreads=200

limitTriggerLevel

<Number or percentage>

Used together with dispatcherThreads, if the number of simultaneous connections goes beyond the limit, and if the number of connections to a single application goes beyond the applications limit (concurrentConnectionsLimit) then no more connections to that application will be allowed, until the number of concurrent connections goes below the limit again.

Example:
limitTriggerLevel=100
limitTriggerLevel=80%

serverBusyErrorPage

<Filename of errorpage>

If the server is busy (the limit is exceeded) then this error page will be returned instead of the default one – if no server busy errorpage is defined, the default one will be returned.
Please note that the error page must point to a filename of a file containing the error page, it cannot be a link or URL.

Example:
serverBusyErrorPage=/wwwroot/errorpages/serverbusy.html

serverBusyAlternateErrorpages

<host pattern>=<html filename>[;<host pattern>=<html filename>;…]

This can be used to specify alternate error pages shown when the server is busy, for certain hosts.

If no match is found, the default server busy error page will be shown.

Example:
.portalprotect.dk=./html/pp_error.html;.otherdomain.com=./html/other_error.html

Note that it must point to a file on the filesystem, and not within the webapp, since it is loaded directly from the disk.

supportWeblogicClustering

<true | false> (default is false)

If set to true, Weblogic cluster failover is supported – Weblogic replicates sessions between a primary and secondary server – if the primary server fails, it is more efficient to redirect requests for already existing sessions to the secondary server, since it will already have a copy of the HTTP session.

Example:
supportWeblogicClustering=true

weblogicCookieName

<Name of session cookie> (default is JSESSIONID)

Name of the cookie that weblogic uses for its session ID – it will have the following format xxxx!yyyy!zzzz – xxxx is the session ID, and yyyy is the primary server ID, and zzzz is the JVMID of the secondary server. If supportWeblogicClustering is set to true, and the primary server fails then the request will be redirected to the secondary server if it is available.

Example:
weblogicCookieName=JSESSIONID

generateWeblogicPluginHeaders

<true | false> (default is false)

If set to true, the dispatcher will create the HTTP headers "WL-Proxy-Client-IP" with the users client IP address, and "WL-Proxy-SSL: true" if SSL is used.
This will enable a weblogic application server to trust the dispatcher headers and provide the information for the applications as if there was a weblogic http server plugin in front of it.

reconnectToPrimarySessionCtrl

If set to true, the PP Agent will attempt to reconnect to the primary session controller, even after it has connected to a secondary session controller, to even out load in a clustered environment. The default value is false.

Not that if dynamic loadbalancing is used, the value for this property will be ignored and forced to false.

Example:
reconnectToPrimarySessionCtrl=true

In this case, the agent will after 5 minutes of being connected to a secondary session controller attempt to reconnect to the primary one each minute – if a successful connection is archived, all new activity will go to the primary server, and it will give the currently executing commands 30 seconds to complete before disconnecting from the secondary server.

redirectrule.xxxx

[disabled;][ignorecase;]<newurl>;<rule1>;<rule2>>

<rule> = key=<pattern>

xxxx is a number, where the first rule has number 1, the second 2 etc. – maximum is 512.

Rule matching is by default case sensitive, but if "ignorecase;" is specified, case will be ignored in comparisons for this rule.
The key can either be "url", "scheme" (http/https) or the name of a http header to match – if all the rules match, the request will be redirected to the specified URL.

Note: The redirect rules are used to redirect certain URLs to other servers, if a given http header in the request matches the pattern, or if the URL matches the defined pattern.

By using redirect rules parts of the applications sitting behind the server can be shut down by temporarily redirecting to another server if the request matches the defined pattern.

See serverrule.* for information about the pattern.

Note that by putting "disabled;" in front, the rule is disabled, but it does still exist – this can be used for toggling rules on and off when required.

Example
/temporarilydown.html;host=.somedomain.com;url=/some/
ignorecase;

disabled;ignorecase;

forwardrule.xxxx

[disabled;][ignorecase;]<filename>;<rule1>;<rule2>>

<rule> = key=<pattern>

xxxx is a number, where the first rule has number 1, the second 2 etc. – maximum is 512.

The forwarding rule works exactly like the redirect rule, with the exception that the user is not redirected if the rule matches, but the content of the file mentioned in the rule is returned to the user – this ensures that the URL stays the same in the browser, even though the intended server isn't contacted.

Refer to the redirectrule.xxxx description above for details.

When the dispatcher evaluates the rules, it starts with the redirect rules, then the forward rules.
Note that the rule can be disabled, by putting "disable;" in front – this can be used to keep rules in the configuration, but disable them when they are not needed.

Example:
ignorecase;c:\unavailableerror.html;host=*.portalprotect.dk

pingrule.xxxx

rule=<name of rule>;url=<url to ping>;failures=<number of failures>;onfailure=<enable | disable>

The ping rule is used to automatically enable or disable other defined rules depending on the availability of other URLs.

It can both enable and disable defined rules of type: serverrule, redirectrule and forwardrule.
The specified URL is pinged, and if it has more than <failures> consecutive failures, then the specified rule will be enabled or disabled depending on the "onfailure" parameter. If the URL later comes available again (HTTP 200 is returned upon pinging it) then the action will be reversed.

Example:
rule=redirectrule.2;failures=2;onfailure=enable;url=/index.jsp
failures=1;onfailure=disable;url=/something.html;rule=serverrule.1

ntlmEnabled

<true | false> (default is false)

If set to true, this dispatcher will be enabled to support NTLM SMB challenges and authentication (provided the session server is setup to support this as well).

Protecting with NTLM will never protect the URI configured through the "urlAccessFailedRedirect" property.

Protecting with NTLM requires the dk.itp.security.authentication.ntlm.NTLMAuthenticationPlugin to be enabled for the same segment as the Dispatcher is running on.

spnegoEnabled

<true | false> (default is false)

If set to true, this tunnel will enable support of SPNEGO authentication – note that there is a number of restrictions on the JDK version used by the session controller – refer to the SPNEGO section on page for more information.

Protecting with SPNEGO requires the dk.itp.security.authentication.spnego.SpnegoAuthenticationPlugin to be enabled for the same segment as the Dispatcher is running on.

spnegoAuthenticationPluginType

<integer>

ID of the SPNEGO plugin to use for authenticating – defaults to 26, which is AuthTypes.AUTHTYPE_SPNEGO.
Can be overwritten for individual alternate servers.

Example:
spnegoAuthenticationPluginType=26

basicAuthenticationEnabled

<true | false> (default is false)

If set to true, the dispatcher will support incoming HTTP Basic Authorization, and attempt to authenticate users using the userid/password sent by the client in the Authorization HTTP request header.

The authentication plugin used, is configured by setting basicAuthenticationPluginType
Refer to the Basic Authentication section on page for details.

Note that this property can be overridden for specific alternate servers by setting alternateserver.xxxx.basicAuthenticationEnabled.

basicAuthenticationRealmName

<String> (default is "Secure")

Name of the basic authentication realm sent back to the client if the dispatcher prompts for HTTP basic authentication – this name is typically shown to the user when he enters his credentials.

basicAuthenticationPluginType

<Number> (default is 6)

If HTTP basic authentication is enabled, this is the ID of the authentication plugin on the session controller which is called with the userid/password sent from the client to authenticate the user.

Note that this property can be overridden for specific alternate servers by setting
alternateserver.xxxx. basicAuthenticationPluginType.

alternateserver.xxxx.basicAuthenticationEnabled
alternateserver.xxxx.basicAuthenticationRealmName
alternateserver.xxxx.basicAuthenticationPluginType

<Alternate server entries> - xxxx is replaced by the name of the alternate server.

Allows you to override the defaults for specific alternateserver entries, so you can set it differently on different servers definitions.

basicauthrule.*

[disabled;][ignorecase;]<newurl|401>;<rule1>;<rule2>>

<rule> = key=<pattern>

xxxx is a number, where the first rule has number 1, the second 2 etc. – maximum is 512.

Rule matching is by default case sensitive, but if "ignorecase;" is specified, case will be ignored in comparisons for this rule.
The key can either be "url", "scheme" (http/https) or the name of a http header to match – if all the rules match, the request will be redirected to the specified URL.

Note: These rules are used when determining if we should prompt for basic authentication, or when basic authentication fails, and we need to either redirect the client to an URL which can show information about the failure or possibly allow another way of authenticating.

See serverrule.* for information about the pattern.

Note that by putting "disabled;" in front, the rule is disabled, but it does still exist – this can be used for toggling rules on and off when required.

Refer to the Basic Authentication section on page for details.

The URL gets 1 or 3 parameters added to it, the originalUrl, the errorcode and the errortext – errorcode/errortext originate from the authentication plugin, and will not be present if no error occurred.

Example
Ignorecase;401;host=.somedomain.com;url=/some/

http://login.domain.com/authrequired;host=*.portalprotect.dk

disabled;ignorecase;

http://emergencyserver.domain.com/authrequired;host=*.portalprotect.dk

ntlmRedirectURL

<URL> (default value equals the value of urlAccessFailedRedirect)

This URL will be used when the NTLM authentication procedure fails. This URL will receive the same parameters as when redirected to urlAccessFailedRedirect (originalurl). Also if the NTLM authentication failed with any errorcode or messages from the domain controller the session parameters "errorcode" and "errortext" will be available from the client session.

ntlmCachePolicy

This option is deprecated !!

ntlmAllowAnonymousAccess

<true | false> (default is false)

This property will allow session that failed NTLM logins to continue to the backend application if the isUrlProtected() method call to the authorization plug-in allows it. This property will only work when the "ntlmCacheAnonymousAccess" is set on the session controller (this allows for this session information to be communicated to the dispatcher).

ntlmAllowedUrlList

<filename>

A filename of a file containing a list of urls that will be allowed through the tunnel even though NTLM is enabled. This file can be either in the classpath (recommended) or on the filesystem. The content of the file should look like this:

/favicon.ico
/errorpages/*
. . .

For each line a specific file or a pattern can be written. If a pattern is written (ending with ) all url's starting with whats written will be allowed through. This should also be used if access should be allowed to pages that could contain HTTP parameters (e.g. /errorpages/internalerror.jsp?errortype=4 should be configured like /errorpages/internalerror.jsp).

By default the value of the "ntlmRedirectURL" parameter will be allowed through without challenging the browser.

Since Microsoft Internet Explorer requires NTLM re-authentication on some requests the url's configured in this file will be ignored if the client browser forces a challenge on a request.

cookiesToHideFromBrowser

<List of cookie names, separated by , or ;>

Contains a list of cookie names which are going to be hidden from the browser. If the dispatcher sees one of the cookies listed in the HTTP response from a webserver, it removes it and stores it within the PP session instead.
One advantage of hiding the cookies from the browser, is that the HTTP session will then follow PP's session 100%.
This fixes the problem where data from a previous session might be stored within the HTTP session on a webserver.
The cookies are saved in the session per host, so domain-wide cookies are not supported with this option.
The "Secure" flag on the cookie is ignored, since the cookie never reaches the browser anyway. Expiration dates etc. Are also not supported, it should only be used for session cookies. If a webserver sets max-age=0 then the
cookie is deleted from the session.

Example: JSESSIONID;JSESSIONID_APP2;ASP.NET_SessionId

cookiesAreAlternateServerBased

<true | false> Default is false.

If set to true, cookies hidden from the browser via cookiesToHideFromBrowser are saved per hostname and alternate server instead of just per hostname. This will mean that separate alternate servers will have separate instances of the same cookie.

loginWithSSLClientCert

<true | false> Default is false.

If set to true, the dispatcher will attempt to authenticate the user if a client SSL certificate is present on the request and if the user is anonymous.

If authentication does not succeed, the request will just continue with an anonymous user.

Note: Normally an application should itself handle these kinds of logins (by calling Agent.login()), but this method of authenticating is a convenience method that can be used if the application (e.g. a .NET application) wants to avoid the hazzle, and just react to the users identity.

useSSLClientCertAsTicket

<true | false> - default is false.

if set to true, SSL client certificate can be used as a ticket to obtain a session, similar to an OAuth2 ticket.

This is useful for API calls protected by SSL client certificates where a regular session is not used - in this case, the overhead of creating a new session and logging into it can be avoided since the same session is reused over and over for the same SSL client certificate. Note that in this case, multiple clients sharing the same SSL client certificate will also be sharing the same session.

In order for this to work, an authentication plugin of type: AuthTypes.AUTHTYPE_SSLCLIENTCERT must be installed and supporting creating a new session from a ticket.

sslRequired

<true | false> - default is false.

If set to true, the server can only be accessed using secure http (SSL) – if the dispatcher gets a normal unencrypted http request from the browser, it will redirect the user to https with the same URL.

<None | Lax | Strict> - default is not set

If set to None, Lax or Strict, the "SameSite" cookie attribute is added with the specified value to all session cookies, fixation or sticky cookies generated by the dispatcher.

disableHttpOnlyCookies

<true | false> - default is true

If true, HttpOnly cookies will be disabled – otherwise cookies will get "; HttpOnly" appended which to some browsers hide the values of the cookies from javascript.

httpOnlyFilter

<pattern, including * or ?> - default is "*"

If httpOnly cookies are enabled (see disableHttpOnlyCookies, only hostnames matching the specified filter will have httpOnly set.

Use | to separate multiple values where only one of them need to match.

Note: When usedomain=true session cookies are set for the domain and not the individual host name.
Be careful about different domains – if you set a filter like this: _www1.mydomain.com|www2.mydomain.com_ then if the browser first hits www1.mydomain.com, and then later www.mydomain.com then the session cookie created by www1.mydomain.com will still have httpOnly set when the request later hits www.mydomain.com. This might cause issues with JNLP java launcher which might not pick up the cookie on www.mydomain.com even though it doesn't match the filter.
If however the browser first hits www.mydomain.com and later www1.mydomain.com the session cookie will be created without httpOnly, and this will also effect www1.mydomain.com.

Example:
httpOnlyFilter=*.somesite.com|*.someothersite.com

httpStatusUnableToConnect
httpStatusTimeout
httpStatusServerError
httpStatusUnknownError

<Integer, HTTP response status codes> Defaults to 500

Changes the HTTP response status codes to a custom error code for each type of error. This can be used to e.g. provide a loadbalancer sitting in front of the dispatcher servers with information about which kind of error occurred so it can react accordingly.

httpStatusUnableToConnect - Unable to connect to application server
httpStatusTimeout - Timeout reading reply from application server
httpStatusServerError - IO Error while sending request or reading reply
httpStatusUnknownError - Unknown error, such as an internal error in the dispatcher or
an otherwise unhandled error.

Note that they must be 3-digit error codes, and should usually begin with 5 – refer to http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more information about status codes.

Example
httpStatusTimeout=516

http11

<true | false> - default is false

If set to true, HTTP 1.1 protocol is enabled, otherwise HTTP 1.0 is used when connecting to backend web/app servers.

HTTP 1.1 provides persistent connections which can be reused for multiple requests, thus allowing an already opened socket connection to be reused for other users requests.
If this property is set to false, all the remaining http11.* options are ignored.

Example
http11=true

http11.maxIdleSeconds

<Seconds> - default 10

Number of seconds a connection is allowed to stay idle before it is closed – this should ideally be set to a lower value than the web servers corresponding timeout, so the client times out before the server does.

Example:
http11.maxIdleSeconds=5
http11.maxIdleSeconds=300

http11.maxUseCount

<Integer> - default 100

The maximum number of times an individual connection is reused for new requests – in theory there is no real reason to limit this number, but most application servers have a limit on how many requests they will accept using the same socket connection. If using SSL, keep this value as large as possible to keep the number of SSL handshakes down.

If set to 0, there is no limit to the number of times a connection can be reused.

Example:
http11.maxUseCount=1000

http11.maxUseSeconds

<Seconds> - default 0

The maximum number of seconds a connection can be open and reused – not idle, but counted from the moment the
connection is created.
This should most often be set to 0 to disable it, but some application servers might have a limit on how long the maximum lifetime of a connection can be, so this value should be set lower than that.

http11.responseTimeout

<Timeout in seconds> - default 60

Sets the maximum number of seconds to wait for a reply from the server before giving up and sending an error to the client.

Note that this value replaces sockettimeout when using HTTP1.1 connections.

http11.httpProxyHost

<hostname or IP address> - default blank

HTTP 1.1 traffic to the backend application server can be sent via an HTTP proxy server if specified – this is the hostname of the proxy server to use, if any.
If left blank, no proxy will be used, and the configuration values for port, user and password are ignored.

Examplehttp11.httpProxyHost=my.proxy.com

http11.httpProxyPort

<TCP port number> - default 8080

Port number of the HTTP proxy server, only used if http11.httpProxyHost is not left blank.

http11.httpProxyUser

<Userid> - default empty

User ID for proxy authentication if HTTP proxy servers requires it – if left blank, the password is also ignored.

http11.httpProxyPassword

<Password>

Password to send to the proxy server if it requires proxy authentication.

http11.socksGatewayHost

<Hostname or IP address>

If SOCKS gateway is required for forwarding HTTP traffic to the application server, instead, place the name of the SOCKS gateway server here.

http11.socksGatewayPort

<TCP port number> - default 1080

Port number of the SOCKS gateway to use.

http11.ssl

<true | false> - default false

If set to true, HTTP traffic to the web/application server will be encrypted with SSL (HTTPS) – if set to false the remaining http11.ssl.* properties are ignored.

This can be used if you require encrypted traffic from the dispatcher (typically in a DMZ zone) to the web/app server. Note that when using SSL it is important to reuse the sockets/connections as much as possible, so make sure to set the timeout values high to minimize the number of SSL handshakes which has to take place for each now socket connection.

http11.ssl.acceptedIssuerCertificates

<List of files>

A list of .pfx, .cer or .der encoded files containing server or issuer certificates. The servers SSL certificate or the certificate of its issuer must either be in this list, or in the JVMs cacerts file, or the certificate will be rejected by the dispatcher when making the connection to the server.

http11.ssl.enabledCipherSuites

<List of SSL enabled cipher suites – separated by comma or semicolon>

If specified, restricts the number of enabled cipher suites to use when creating SSL connections to backend application servers.

http11.ssl.enabledProtocols

<List of SSL enabled protocols – separated by comma or semicolon>

If specified, restricts the number of enabled protocols when establishing SSL connections to backend application servers.

http11.ssl.useclientcert

<true | false> - default false

If set to true, the dispatcher will use an SSL client certificate when negotiation the SSL connection to the backend web/application server.
If not set to true, the remaining http11.ssl.clientcert.* properties are ignored.

http11.ssl.clientcert.file

<Filename>

Name of keystore file to load SSL client certificate from.

http11.ssl.clientcert.keymanagerprovider

<JCE keymanager provider name> - default empty

Name of JCE keymanager provider, or leave blank to use platform default.

http11.ssl.clientcert.password

<Password>

Password to the keystore – can optionally be encoded or encrypted or encrypted using "java dk.itp.utils.PasswordUtils".

http11.ssl.clientcert.provider

<JCE provider name> - default BC

Name of JCE provider to use when loading the keystore

http11.ssl.clientcert.provider.type

<JCE keystore type> - default PKCS12

Type of keystore file – could be Java, PKCS12 or any other JCE supported keystore type.

alternateserver.xxxx.http11
alternateserver.xxxx.http11.*

<Alternate server entries> - xxxx is replaced by the name of the alternate server.

All the http11.* settings can be overwritten per alternate server – if not specified per alternate server, the following properties will use their default values:

alternateserver.xxxx.http11.ssl
alternateserver.xxxx.http11.ssl.*, except for http11.ssl.acceptedIssuerCertificates
alternateserver.xxxx.http11.httpProxyHost
alternateserver.xxxx.http11.httpProxyPort
alternateserver.xxxx.http11.httpProxyUser
alternateserver.xxxx.http11.httpProxyPassword
alternateserver.xxxx.http11.socksGatewayHost
alternateserver.xxxx.http11.socksGatewayPort

The remaining alternateserver.xxxx.http11.* properties will use the values of their corresponding http11.* property as default if not overwritten.
This means that you will have to specify SSL, SSL client certificate, and proxy/socks servers per alternateserver definition since they will not inherit the values for their corresponding http11.* properties.

But values for e.g. http11, http11.ssl.acceptedIssuerCertficates, http11.maxIdleSeconds, http11.maxUseCount etc. options not listed above only have to be specified once, but can still be overwritten for each alternate server if desired.

alternateserver.xxxx.spnegoEnabled
alternateserver.xxxx. spnegoAuthenticationPluginType

<true | false> - xxxx is replaced by the name of the alternate server

Override the spnegoEnabled or spnegoAuthenticationPluginType setting for a single alternateserver.

allowedHttpMethods

<List of HTTP methods, separated by ;> - Default is GET;HEAD;POST

Defines the list of allowed HTTP methods – add any methods you need supported to this list, such as OPTIONS and TRACE.

ntlmAuthenticationPluginType

<integer>

ID of the NTLM plugin to use for authenticating – defaults to 35, which is AuthTypes.AUTHTYPE_NTLM.
Can be overwritten for individual alternate servers.

Example:
ntlmAuthenticationPluginType=35

alternateserver.xxxx.ntlmAuthenticationPluginType

<Alternate server entry> - xxxx is replaced by the name of the alternate server.

Specify which NTLM authentication plugin to use for a particular alternate server – can be used to use different NTLM plugins depending on which server is accessed.
When using this, beware of "hidden" URLs like /favicon.ico which can mess this up. Usually you need to add /favicon.ico to the file pointed to in the configuration parameter ntlmAllowedUrlList to avoid problems.

Example:
alternateserver.xxxx.ntlmAuthenticationPluginType=35

alternateserver.xxxx.ntlmEnabled
alternateserver.xxxx.ntlmAllowAnonymous
alternateserver.xxxx.ntlmRedirectURL

<Alternate server entries> - xxxx is replaced by the name of the alternate server.

Override the values specified for the dispatcher in ntlmEnabled, ntlmAllowAnonymous and ntlmRedirectURL values for each individual alternate server.

Be very careful about changing ntlmEnabled !!!!!

If you do, make sure that all alternateservers serving requests from a given hostname has the same enabled setting, or you will risk problems with they way Internet Explorer handles POST requests after doing NTLM authentication against a given hostname.

For any POST request, MSIE first ends a POST request with no content data, and an NTML type 1 message – it expects to receive a NTLM type 2 reply, and then it finally sends an NTLM type 3 message along with a new POST request this time containing the POST data.

If you have enable NTLM for e.g. /abc/* but NOT for /* on the same host then subsequent POST requests to URLs other than /abc/* will fail since NTML will be disabled for the other URL.

accessloggingenabled

<true | false> - Default is false

If set to true, all HTTP requests will be logged to a log4j appender called "accesslog", with the same format as displayed in the PP admin GUI, "UserId IP-Address URL ResponseCode ContentLength ReplySize zippedReplySize TimeInMiliseconds".
If an exception occured, it will also be logged, just like it is shown in the admin GUI.

This can be really useful to diagnose problems, although it does add a small amount of overhead to the tunnel logs.
When using it, it is recommended to configure log4j to dump those log entries to different appender - preferably a
dk.itp.peer2peer.log.BufferedRollingFileAppender since it performs quite better than log4j's default file appenders.

Also, make you do not want to send the access log to the logserver because of the number of log events it will generate on busy systems.

nocachesetcookieforurls

<pattern> - Default is "^*.crl|*.pdf" which matches all URLs exception *.crl or *.pdf
If the URL matches this pattern, then an HTTP header "Cache-Control: no-cache=set-cookie" will be sent when the dispatcher sets the session cookie on the response to avoid caching by proxy servers or similar.

But, because of a bug in Microsoft Internet Explorer (see http://support.microsoft.com/kb/323308) this does not work if the first URL being hit is a file which should be downloaded, e.g. a PDF file.

So by changing this property, you can define which URLs the http header is set for.

The pattern can contain ? and * to match any or a sequence of any characters, and it can contain | to separate multiple entries.
If the pattern starts with ^ then negative matching is used – the pattern is matched if the URLs then do NOT match the following pattern.

Example:
nocachesetcookieforurls=^* - Disable for all URLs
nocachesetcookieforurls=* - Enable for all URLs
nocachesetcookieforurls=^*.doc|*.docx|*.pdf|*.crl – Enable for everything, but disable for the given extensions.

dumpRequest

<true | false> - Default is false

If set to true, the contents of all requests (HTTP headers and content) will be printed out to system.out an the content of all response headers will be printet out to system.err for debugging.

plugin.error.uri

<URI> - Default blank.

If specified, the user will be redirected to this URL if a dispatcher plugin fails with an exception. Normally a plugin should handle all its errors internally so this should not occur, but if a plugin does fail with an exception and this uri is specified then the browser will be redirected to this URI.

Exampleplugin.error.uri=/errorpages/internalerror.html

urlrewrite.xxxx

<Rewrite Rule – xxxx is a number between 1 and 512> - No default

Can be used to specify URL rewrite rules, an URL rewrite rule is similar in syntax to Apaches mod_rewrite module.
You can specify up to 512 entries, which are executed in order, starting with 1. Any gaps are ignored, so you can create e.g. urlrewrite.10, urlrewrite.15 etc. to leave space for adding new rules in between later.

Supported statements are:

Refer to Apache mod_rewrite module documentation for further explanation and examples, also look at the URL Rewriting Section in this document for more details.

Example:
<property name="urlrewrite.1" value="RewriteCond %{HTTP_REFERER} (viagra) [NC,OR]" description=""/>
<property name="urlrewrite.2" value="RewriteCond %{HTTP_REFERER} (xxx) [NC]" description=""/>
<property name="urlrewrite.3" value="RewriteRule .* - [F]" description="If referer URL contains viagra or xxx, deny the request"/>
<property name="urlrewrite.4" value="RewriteRule ^/google/(.*)$ http://www.google.com/search?q=$1 [R]" description="Redirect links to /google/xxxxxx to google search with xxxxxx as parameter"/>

saveSelectedServerInSession

<true | false> Default is true.

If true, the name of the selected application server for this user will be stored in the session in addition to in a cookie. The information in the session is needed by the session controller for the http session keepalive feature; see the chapter about this for details.

Set it to false if you do not need http session keepalive and want to save a bit of memory in the sessions.

service.window.begin
service.window.end
service.window.url

<Time – format: HHMMSS>

<URL>

If both service.window.begin and service.window.end are specified, and if service.window.url is specified then all requests to the dispatcher will be redirected to the URL when the service window is active.

The service window is active in the specified time interval between the begin and end times.

Exampleservice.window.begin=020000
service.window.end=063000
service.window.url=

Note that the URL should point to another server elsewhere, since all requests are considered being in service window.
The exception to this, is if you have specified an URLRewrite rule or a forwardrule that covers this URL, since these rules are processed first, so you could e.g. define a forwardrule to service the contents of the file /tmp/closed.html for the URL /sorry_we_are_closed.html – when a request for another URL is received by the dispatcher it will redirect to /sorry_we_are_closed.html if in the service window.

When the dispatcher receives the request for /sorry_we_are_closed.html it matches the forwardrule which is checked before the service window, so the contents of the file is sent back.

supportIntegratedWindowsAuthentication

<true | false> - Default false

If true, support for Integrated Windows Authentication between PortalProtect Dispatcher and backend web server is enabled.

See section 9 on page for more information about what this is.

Note that a userid and password must either be setup in the session for the authenticated user, or be configured here using integratedWindowsAuthenticationUserid / integratedWindowsAuthenticationPassword.

integratedWindowsAuthenticationLoginContextName

<section name> - default "kerberos-client"

Name of section to use in login.conf – allows a single login.conf file to be shared between various configurations in the same process by using different sections.

integratedWindowsAuthenticationUserid

<userid>

User ID of technical user to use when doing SPNEGO against backend webserver. Only used if session of authenticated user does not contain the state variable integratedWindowsAuthenticationUserid.

spnego.login.conf

<login.conf file location>

Login module configuration file, refer to Java 1.6 documentation for details about the format.

spnego.krb5.conf

<krb5.conf file location>

Must point to a kerberos5 configuration file, refer to Java 1.6 documentation for format of it.

integratedWindowsAuthenticationPassword

<password>

Password of technical user to use when doing SPNEGO against backend webserver. Only used if session of authenticated user does not contain the state variable integratedWindowsAuthenticationPassword.

The Password can optionally be obfuscated / encrypted.

alternateserver.xxxx.supportIntegratedWindowsAuthentication

<true | false> - default is the value of supportIntegratedWindowsAuthentication

xxxx must be replaced with the name of the alternate server.

This overrides the value of the property supportIntegratedWindowsAuthentication for a specific alternate server.

alternateserver.xxxx.integratedWindowsAuthenticationUserid

<userid> - default is the value of integratedWindowsAuthenticationUserid

xxxx must be replaced with the name of the alternate server.

This overrides the value of the property integratedWindowsAuthenticationUserid for a specific alternate server.

alternateserver.xxxx.integratedWindowsAuthenticationPassword

<password> - default is the value of integratedWindowsAuthenticationPassword

xxxx must be replaced with the name of the alternate server.

This overrides the value of the property integratedWindowsAuthenticationPassword for a specific alternate server.

maximumRequestSize

<Maximum size> - default is 67108864 (64Mb)

Specify the maximum allowed request content size in bytes. This is the maximum allowed size for content being sent through the dispatcher, if a request exceeds this size, an HTTP error 400 will be sent back to the client, and the request will be aborted.

This setting only concerns the request on HTTP requests with content, such as POST or PUT requests, the reply has no limit, since the reply is streamed to the browser.

urlchecker.enabled

<true | false> - default is true

Enable or disable URL checker – set to false to disable all the urlchecker.* parameters.

urlchecker.urlencoding.verify

<true | false> - default is true

Verify URL encoding is valid – i.e. that all %xx characters are valid hexadecimal characters. This is verified both on the URI path, and on all query parameters.

urlchecker.url.maxlength

<integer> - default is 0 (disabled)

If set to a value larger than 0, it specifies the maximum length (before URLencoded characters are resolved) of the URL including all query parameters.
By default this is set to 0, which means the dispatcher does not restrict the length in any way – note though that the webserver the dispatcher is running within might put restrictions on URL length.

In case the URL exceeds the length, an http error "414 Invalid URL Length" is sent to the client.

uUrlchecker.param.key.maxlength

<integer> - default is 0 (disabled)

If set to a value larger than 0, it restricts the maximum length of the key for any query parameter.

In case the value exceeds the length, an http error "414 Invalid URL Length" is sent to the client.

urlchecker.param.value.maxlength

<integer> - default is 0 (disabled)

If set to a value larger than 0, it restricts the maximum length of the value for any query parameter.

In case the value exceeds the length, an http error "414 Invalid URL Length" is sent to the client.

storeUserAgentInSession

<true | false> - Default is false.

If set to true, the dispatcher will check the session, and if it does not contain the state variable "httpUserAgent" then it will create it and add the value of the HTTP header User-Agent to it.
Note that only the first 512 characters of the User-Agent header will be stored in the session in case its value exceeds 512 characters in length.

The value in the session can then be used by authentication plugins or applications for user-agent specific behaviour or logging.

Note that the value can be overridden for specific alternateservers by specifying alternateserver.xxxx.storeUserAgentInSession.

browserauth.ignoreurls

<URL pattern> - default is blank

If specified, then if the URL matches this pattern then the dispatcher will not attempt to do browser authentication (SSL client cert, basic auth, NTLM or SPNEGO) for this particular request. This can be used for e.g. "ping urls" or parts of the site you want to be accessible anonymously where you want to avoid prompting for browser authentication.

alternateserver.xxxx.browserauth.ignoreurls

<URL pattern> - default is the value of browserauth.ignoreurls

Replace xxxx with the name of the alternate server.
Overrides the value of browserauth.ignoreurls for a specific alternate server.

gzipResponse

<true | false> - default is false

If true, and if browser sends accept-encoding: gzip, then response is sent compressed using gzip.
Note that if the url ends with .js, .css, .wml, .cab, .pdf, .zip or .gz then gzip compression will not be used to ensure compatability with older MSIE versions that does not support gzip compression for these filetypes, although the browser claims it does by sending the Accept-Encoding HTTP header.
Also, if the response content-type is image/, binary/*or application/ then gzip compression will not be attempted. Note that both the url and content-type pattern is controlled by disableGzipUrlFilter and disableGzipContentTypeFilter configuration settings, so it can be change there.

disableGzipUrlFilter

<URL pattern> - default is "*.js|*.css|*.wml|*.cab|*.pdf|*.zip|*.gz"

If gzipResponse is set to true, response will be compressed unless the URL matches this pattern.

disableGzipContentTypeFilter

<content type pattern> - default is "image/*|binary/*|application/*"

If gzipResponse is set to true, response will be compressed unless the content type matches this pattern.

alternateserver.xxxx.gzipResponse
alternateserver.xxxx. disableGzipUrlFilter
alternateserver.xxxx. disableGzipContentTypeFilter

<xxxx is replaced with the name of the alternateserver entry>

Overrides the values of gzipResponse, disableGzipUrlFilter and disableGzipContentTypeFilter per alternateserver. For any alternateservers where nothing is specified, the default is used.

consul.servers

<One or more URLs to a consul server, separated by semicolon>

When using the macro ${consul:/v1/catalog/service/appservers} (or other url with different service name) then consul will be queried for active services, and they will be used to forward requests to from the dispatcher.

Example: http://10.1.2.3:8500;https://10.1.3.4:8501

consul.pollinterval

<Interval in seconds, default is 10>

Number of seconds between polling consul server when checking for the list of current active services. Please note that list of servers are automatically checked every "pingurlinterval" seconds. So setting the value below pingurlinterval has no effect, you need to decrease pingurlinterval too to check more often.

By setting it to a higher amount, e.g .60 you can ensure that consul is only asked every minute for new services.

stickyserver

<true | false, default is true>

If true (the default) then a server selected for the user is sticky, using cookie stickiness – a selectedServer cookie is then created with a hash of the server cookiename, which is used on subsequent requests to route the request to the same server.
Sticky servers are usually preferred since it often gives better performance, but in some cases, e.g. for REST APIs it does not make sense to use server stickiness.

alternateserver.xxxx.stickyserver

<true | false – default is the value for the property "stickyserver">

Used to override stickyserver value for any given alternateserver.

pingUser
pingPassword

Userid and password to use when pinging an application server, if addauthorizationheader=true and addedAuthorizationHeaderContainsSessionID=false.

If both userid and password are set, they will be added as basic authentication (Authentication: Basic xxxxxxx HTTP header) when pinging the application server.

Password can optionally be encrypted/obfuscated.

alternateserver.XXXX.pingUser
alternateserver.XXXX.pingPassword

Override pingUser/pingPassword per alternateserver definition.

alternateserver.xxxx.basicAuthUserid
alternateserver.xxxx.basicAuthPassword

Userid and password to use when sending basic authentication to an application server, if addauthorizationheader=true and addedAuthorizationHeaderContainsSessionID=false.

If one of these values are set to an empty string, the corresponding value from the users session will be used instead – e.g. if only basicAuthPassword is set, then the users userid, along with the configured password will be set.

Password can optionally be encrypted/obfuscated.

sessionfixationdefensecookiename

<cookie name> - default sslsessionid_sf

Name of session fixation defense cookie.

Session Fixation Attack is an attack where an attacker on a public computer establishes a session with a server, then records the session ID and walks away. If a 2^nd person later uses the same computer and authenticates into the already present session, the attacker will now have a key to the 2^nd persons authenticated session.

To protect against this, PortalProtect Dispatcher can automatically create a session fixation cookie with an ID stored in both the session and the cookie.

On all requests for an authenticated session, it can now compare the two values to ensure they are equal – this will mean that the attackers previously recorded session ID is useless without the additional cookie value which is only created at the time of authentication.

See more information at https://www.owasp.org/index.php/Session_fixation

sessionfixationdefense

<true | false> - default is true

See the documentation for sessionfixationdefensecookiename above.

If set to true, all incoming requests which has the state variable pp_sessionfixation in the session and where the session is authenticated must have a sslsessionid_sf cookie (or other name, depending on the cookie name configured) with the same value in, otherwise the session is assumed to be invalid, and the user will get a new anonymous session instead.

Note that this is only valid where a session is kept in a cookie – if a session originates from e.g. a bearer token or SSL client certificate this validation does not take place.

sessionfixationdefenseaddcookie

<true | false> - default is false for compatibility reasons, recommended value is true.

See the documentation for sessionfixationdefensecookiename above.

If set to true, the dispatcher will look at all incoming requests – if the user is unauthenticated initially, and authenticates during the session – e.g. because a login application authenticates the user – then the dispatcher will create a unique ID and place it in the state variable pp_sessionfixation within the session, and it will create a corresponding sslsessionid_sf (actual name decided by configuration) cookie with the same value.
If sessionfixationdefense is set to true, all future requests will then be checked to verify the new cookie has the expected value.

<true | false> - default is false for compatibility reasons.

If set to true, all requests with the OPTIONS method bypass authentication - meaning NTLM, SPNEGO or BasicAuth authentication will not be done for this method - instead the request is proxied onwards to the target server. Setting this to true, enables supporting CORS preflight requests where the browser does not send any credentials.

Note: requires PortalProtect versions > 5.53

<true | false> - default is false

Should normally not be set to true, since dispatcher is running in a webserver such as Jetty where OpenTelemetry should instrument it

<true | false> - default is false (Note that OpenTelemetry options require minimum version 6.5.10)

Set to true to enable OpenTelemetry support - when enabled, OpenTelemetry API is called with information about outgoing requests, and the traces can be picked up by tools supporting OpenTelemetry such as Dynatrace or Jaeger.