Virtual hosts
The tag Engine is mainly an aggregation of host tags used to configure virtual hosts. The terms 'virtual host' or 'name-based virtual host' describe the fact that several hosts share one and the same IP-based host. The decision which virtual host will be used, is taken by the HTTP header field 'Host' of the request. (See also http://www.ietf.org/rfc/rfc2616.txt.)
The tag Engine (see table below) may contain one or several host definitions. One of them must be the default. That is the one that will be accessed if no match can be found.
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| defaultHost | string required, advanced, supports variable replacement default: DNS name of the machine | This attribute specifies the virtual host used if no other virtual host matches. |
| generalResourceDir | string basic feature, optional, supports variable replacement | You can use the attribute generalResourceDir to configure a directory. If this directory contains a file with the name navajo_style_sheet.css, the system will use it as style sheet. A file with the name Nevis_f2.gif is used as a GIF file. These two resources are referenced in every HTML response generated by the server. If the system cannot find one of these resources in the configured directory, it it will use the compiled resource. |
| useStyleSheet | string basic feature, optional default: false | Set this attribute to "true" to restore original behavior. The following nevisProxy components reference the style sheet: DeflateFilter, StatusServlet, UserStatusServlet LoginRendererServlet if the builtin login page will be rendered |
HTTP session
Fading out
HTTP sessions are an element of the Container Session Handling. The Container Session Handling is replaced by the Dynamic Session Engine and therefore in the process of being faded out. Accordingly, HTTP sessions are also fading out. Do not use the Container Session Handling, including HTTP sessions, anymore. Instead, switch to the Dynamic Session Engine. For more information on the Dynamic Session Engine, see the chapter Dynamic Session Management Engine.
The HTTP protocol is stateless by design. Access control, however, can only be implemented if it is possible for the requests from a particular client to be associated with each other. This association or identification has to be achieved via the configured client identification. In other words, the Connector receiving the request determines which identification mechanism is to be used. Based on that decision, the respective information is 'bound' to a particular client in a certain manner. The term HttpSession, as specified in the Java 2.3 Servlet Specification, is used to describe the binding of this information. You can think of HTTP session as a user session.
The security of a particular HttpSession is governed by the underlying client identification type. A local, in-memory HTTP session cache is configured via the HttpSession tag, which has the following configuration attributes:
| Name | Type, usage constraints, defaults | Description |
|---|---|---|
| maxAttributes | integer optional, scaling default: 20 | The attribute ’maxAttributes’ configures the number of attributes that can be attached to the HttpSession via HttpSession::setAttribute(...) |
| maxEntries | integer optional, scaling default: 2000 | The attribute ‘maxEntries’ specifies the maximum number of HttpSessions that can be stored, i.e., the maximum number of initiated or authenticated user sessions. |
| maxEntrySize | integer optional, scaling default: 32000 | The attribute ‘maxEntrySize’ specifies the size of the memory in bytes that will be used by one particular HttpSession. |
| maxInactiveInterval | integer optional, security/comfortdefault: 300 | The attribute ‘maxInactiveInterval’ configures the inactivity interval in seconds. After maxInactiveInterval, the HttpSession is removed. The inactivity interval of the underlying client identification is adjusted accordingly. |
| limitMaxInactiveInterval | integer optional, securitydefault: 0 (unlimited) | The attribute ’limitMaxInactiveInterval’ configures an upper limit for the maximum inactivity interval of HttpSessions. |
| maxLifeTimeCheck | boolean optional, advanced default: false | The attribute ‘maxLifeTimeCheck’ enables a renegotiation of the client identifications when the lifetime of one of them ends (needs ‘renegotiation’ attribute of SSLCache to be ‘true’).This means that if the remaining time to live of the identification is less than the inactive interval, a renegotiation of the client identification is executed. |
| clientTypeCheck | boolean optional, advanced default: true | The attribute ’clientTypeCheck’ permits configuring whether or not the client-type, i.e. the ’User-Agent’ header, is checked every time the HttpSession is accessed. |
Web applications
Inside the tag Engine, one or several Host tags are used to configure the virtual host:
| Name | Engine, type, usage constraints, defaults | Description |
|---|---|---|
| name | string required, basic connectivity, supports variable replacement default: DNS name of the machine | The attribute name specifies the name of the host as seen from the client. It therefore needs to match the one in the server certificate and DNS. |
Context path
One or several web applications may be declared with the tag Context inside a Host tag:
| Name | Context , engine, usage constraints, defaults | Description |
|---|---|---|
| unsecureConnection | enum: deny, redirect, allow optional, basic feature default: allow | The attribute 'unsecureConnection' configures the policy if a request is sent using an insecure connection: deny: The access is denied and a respective response is sent to the client; redirect: If at least one secure Connector is configured, a redirect is sent to the client. If no secure Connector is configured, access is deniedallow: the request is processed |
| unsecureConnectionRedirect | enum: deny, redirect, allow optional, basic feature, supports variable replacement default: allow | The attribute 'unsecureConnectionRedirect ' allows configuration of a secure or additional URL. |
| trailingSlashRedirect | boolean optional, advanced, default: false | The attribute 'trailingSlashRedirect' offers support for legacy URL namespaces: nevisProxy generates redirects to the same resource with a '/' appended, in case a servlet mapping only matches, when the trailing '/' is present. This behavior is necessary for browser clients to correctly handle relative URLs. |
| entryURI | string optional, supports variable replacement must start with '/' | With the attribute 'entryURI' the entry point to that web application is specified in the following way: If the request is '/' and there is no matching Context or Servlet found, a redirect with the configured value is sent to the browser. |
| filePreload | boolean optional, advanced default: false | The attribute 'filePreload' specifies if the files is preloaded at start-up. If set to 'true', any modification of the files during runtime does not have any effect. Due to memory consumption, it is not recommended to preload if there are many or large files. |
| path | string required, advanced, supports variable replacement default: empty string | The attribute 'path' configures the top-level URL namespace of the corresponding web application. The term 'context path' is often used for this attribute. An empty context path means '/', i.e., the web application is invoked for every request. If the context is not empty, it must start with '/', and must not end with '/'. |
| docBase | string required, advanced, supports variable replacement default: <spool_dir>/work | The attribute docBase defines the path to the directory from where the web application is deployed. It also specifies the path to the web application's WEB-INF directory, which is located inside the <docBase> directory. For security reasons, never put a file containing secret information (like a secret key or some Lua code) into the directory configured as <docBase> in the navajo.xml file. This is because the DefaultFilter can easily access such a file. An exception is the WEB-INF directory inside the <docBase> directory. The WEB-INF directory is protected against the DefaultFilter and cannot be accessed. Proceed as follows if you change this attribute in an existing instance: 1. First, stop the nevisProxy. 2. Then copy the existing files to the new location. You need to do this manually because nevisAdmin does not support this use case. 3. Finally, restart the proxy. Do not restart it earlier, otherwise the necessary files will not be found. |
| allowedMethods | string array required, advanced, supports variable replacement default: GET,POST | The attribute allowedMethods configures the allowed HTTP methods. The following aliases are allowed besides real method names: ALL-HTTP: ALL-HTTP is a shortcut for all HTTP methods: GET, POST, HEAD, DELETE, TRACE, CONNECT, OPTIONS, PUT, PATCH; ALL-WEBDAV: ALL-WEBDAV is a shortcut for all webdav methods: MERGE, UNCHECKOUT, MKACTIVITY, PROPPATCH, LOCK, CHECKOUT, SEARCH, COPY, MKCOL, MKWORKSPACE, PROPFIND, UPDATE, REBIND, BASELINE-CONTROL, UNBIND, CHECKIN, VERSION-CONTROL, UNLOCK, LABEL,MOVE, ACL, BIND, REPORT Methods can also be removed by configuring -<method>. With the attribute allowedMethods, you configure the HTTP methods allowed by the frontend, to connect to nevisProxy. This in contrast to the AllowedMethods parameter of the HttpConnectorServlet, with which you configure the HTTP methods allowed by nevisProxy, to connect to the backend. As the AllowedMethods parameter of the HttpConnectorServlet is mapped to the request, you may also have to adapt it if you modify the allowedMethods attribute described here. For a description of the AllowedMethods parameter, see the chapter HttpConnectorServlet. |
| caseSensitiveMapping | boolean default: true | Makes the mapping of URIs case sensitive. |
| rejectIfMaxThreads | boolean default: false | If the attribute 'rejectIfMaxThreads' is set to 'true', the last available worker thread will send an error response with status code 503, i.e. the request is rejected. Note: The page to be sent can be configured with the normal error-code page in the web.xml. |
| standardFilterOrdering | booleansupports variable replacement default: true | Deprecated The attribute standardFilterOrdering is deprecated and will be ignored. The attribute standardFilterOrdering specifies the ordering of the invoked filters. If set to "false", the ordering will be derived from the url-pattern of the configured filter-mapping. Otherwise, ordering is as configured, that is, in agreement with the servlet specification, the first configured filter that matches is invoked first. |
| additionalStatusCodes | integer array supports variable replacement default: empty | Allow non-standard HTTP status codes. The configuration of additional status codes is required, e.g., when using WebDav (HTTP status code 207 is used by WebDav). |
Below you will find a short overview of how web applications are configured. Loading filters and servlets To cause the nevisProxy servlet container to load a filter, the following configuration definition has to be included in the web.xml of a web application:
<filter>
<filter-name>TestFilter</filter-name>
<filter-class>ch::nevis::navajo::servlet::example::TestFilter</filter-class>
<filter-lib>libTestServlet.so.1</filter-lib>
<init-param>
<param-name>SomeName</param-name>
<param-value>some-value</param-value>
<description>some configuration for the test filter</description>
</init-param>
</filter>
<filter-name>specifies a logical name for the filter. This is the name that will be used for the mapping of the respective filter. See Mapping filters and servlets below.<filter-class>specifies the class name that will be used for loading the filter, i.e., the class name of the filter in the sense of C++.<filter-lib>The tags filter-lib and servlet-lib are the only extensions made to the web-app_2_3.dtd. specifies the library containing the specified filter. The library is searched in the subdirectory 'WEB-INF/lib' of the configured docBase directory.<init-param>may occur several times and is used for the configuration of the filter. The value of<param-name>must be unique within the respective filter configuration.
The configuration of servlets is similar:
<servlet>
<servlet-name>TestServlet</servlet-name>
<servlet-class>ch::nevis::navajo::servlet::example::TestServlet</servlet-class>
<servlet-lib>libTestServlet.so.1</servlet-lib>
<init-param>
<param-name>SomeName</param-name>
<param-value>some-value</param-value>
<description>some configuration for the test servlet</description>
</init-param>
</servlet>
If a filter/servlet cannot be loaded, the servlet container writes a log message and continues processing. See the chapter Viewing log files for information on how to view log files.There is some configuration data that has to be shared with different filters/servlets of a web application. This data is configured in the <context-param> tag, as shown in the example below:
<context-param>
<param-name>SectokenUserIdTag</param-name>
<param-value>userid</param-value>
</context-param>
As for the filter/servlet configuration, the value of <param-name> must be unique.
Mapping filters and servlets
The mapping of a servlet into a URL namespace looks as follows:
<servlet-mapping>
<servlet-name>TestServlet</servlet-name>
<url-pattern>/test/*</url-pattern>
</servlet-mapping>
<servlet-name>is used to describe the logical name of the servlet that will be mapped.<url-pattern>configures the path of the servlet (servlet path). The configured value must start with the character '/' and end with the characters '/*'. A value containing only the '/' character indicates the 'default' servlet of the web application.
The term path mapping is often used for the mapping described above.
Mapping requests to servlets Mapping of requests to servlets in the servlet container is done as follows:
- The servlet container selects the web application with the context path that best matches the request URL.
- To map a servlet, the request URL minus the context path is used.
- The servlet container takes the resulting path and selects the servlet with the servlet path that has the longest match. This is done by stepping down the path tree one directory at a time, using the '/' character as a path separator. The longest match determines the servletIn the Java 2.3 Servlet Specification, the term 'path mapping' is used to describe this procedure..
- After a servlet has been selected, the filter chain is constructed. It is important to keep in mind that no filter will be invoked unless a servlet has been selected.
Mapping filters The mapping of filters is quite similar:
<filter-mapping>
<filter-name>TestFilter</filter-name>
<url-pattern>/test/*</url-pattern>
<exclude-url-regex>/test/foo/.*</exclude-url-regex>
</filter-mapping>
Additionally to the servlet-mappings it is possible to define exceptions based on a regular expression. If the regular expression, defined within the <exclude-url-regex> tag, matches on the URL, the specified filter will not be called.
Additionally, a filter mapping may have one or more IP-addresses where the filter should be called (or not):
IP: A newline, spaces, or comma separated list of IP addresses (cidr format) for which the filter has to match.
exclude-IP: A newline, spaces, or comma separated list of IP-addresses (cidr-format) for which the filter should NOT match.
A filter is considered to match, if the following conditions are all true:
- the
<url-pattern>has to match - if one or more IPs are set: at least one of those has to match
- if one or more exclude-IPs are set: none of those have to match
- if one or more exclude-url-regex are set: none of those have to match
It is also possible to define the mapping of a filter directly on a servlet (i.e., not based on an url pattern). Such a filter will be called each time the specified servlet is called:
<filter-mapping>
<filter-name>TestFilter</filter-name>
<servlet-name>ServlteName</servlet-name>
</filter-mapping>
Constructing the filter chain The filter chain is an assembly of filter mappings. Every filter mapping with a URL pattern that matches the beginning of the path is added to the filter chain. The ordering of the filter chain is according the ordering of the filter mapping configuration in the web.xml.
It is important to realize that a filter or servlet can have several mappings, i.e., that it may occur in several filter or servlet mappings.
An example: Let us assume that the context path of a web application is 'store', and that there are several filters/servlets configured with the following mapping:
| URL Pattern | Servlet Name | Filter Name(s) |
|---|---|---|
| /test/* | TestServlet1 | TestFilter1 |
| /test/foo/* | TestServlet2 | TestFilter1, TestFilter2 |
| /test/bar/* | TestServlet2 |
Example URL mapping
This will result in the following URL mapping:
| Request URL | Invoked Servlet | Invoked Filter Chain |
|---|---|---|
| /store/test/ | TestServlet1 | TestFilter1 |
| /store/test | ||
| /store/test/egal* | TestServlet1 | TestFilter1 |
| /store/test/foo/doit | TestServlet2 | TestFilter1, TestFilter1, TestFilter2 |
| /store/test/bar/egal | TestServlet2 | TestFilter1 |
Error-Mapping
In the web.xml file a mapping between the HTTP status code and a configured file can be specified. As an example:
<error-page>
<error-code>500</error-code>
<location>/server_error.html</location>
</error-page>
For a more fine-grained error mapping, see the chapter "ErrorFilter".
Some versions of the Microsoft Internet Explorer don't display an error response whose size is smaller than approximately 600 bytes. Therefore the files used as error page must be large enough. Static Content As described above, the attribute 'docBase' configures the path where the WEB-INF directory of the web application will be searched. All files in that directory and any subdirectory, except the WEB-INF directory will be loaded at startup. The 'Content-Type' of a file is given by its suffix and the respective mime-mapping in the web.xml.
After startup of the server none of these files must be added or removed.
If there is no matching servlet mapping found, an attempt will be made to find a file that matches exactly.
The filter chain will only be constructed and invoked if there is a matching file.
See also the chapter DefaultServlet for serving static content.