Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/jetty-9.3.x' into jetty-9.4.x

This commit is contained in:
Greg Wilkins 2016-07-27 10:35:37 +10:00
parent d381573d67 117cbc2bd1
commit 8d380220c4
20 changed files with 326 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
jetty-documentation/src/main/asciidoc/administration/extras/balancer-servlet.adoc
View File

@ -28,11 +28,11 @@
[[balancer-servlet-usage]]
==== Usage
The Balancer servlet allows for simple, sticky round robin load balancing leveraging the ProxyServlet that is distributed with Jetty.
The Balancer servlet allows for simple, sticky round robin load balancing leveraging the `ProxyServlet` that is distributed with Jetty.
In addition to the parameters for ProxyServlet, the following are available for the balancer servlet:
In addition to the parameters for `ProxyServlet`, the following are available for the balancer servlet:
stickySessions::
true if sessions should be sticky for subsequent requests
True if sessions should be sticky for subsequent requests
balancerMember.<name>.proxyTo::
One of more of these are required and will be the locations that are used to proxy traffic to.
One of more of these are required and will be the locations that are used to proxy traffic to.

15
jetty-documentation/src/main/asciidoc/administration/extras/cgi-servlet.adoc
View File

@ -28,17 +28,16 @@
[[cgi-servlet-usage]]
==== Usage
The CGI servlet class extends the abstract HttpServlet class.
When the init parameter is called, the cgi bin directory is set with the cgibinResourceBase.
Otherwise, it defaults to the resource base of the context.
See CGI javadoc.
The CGI servlet class extends the abstract HttpServlet class.
When the init parameter is called, the cgi bin directory is set with the `cgibinResourceBase`.
Otherwise, it defaults to the resource base of the context.
The cgi bin uses three parameters:
commandPrefix::
The init parameter obtained when there is a prefix set to all commands directed to the method exec.
The init parameter obtained when there is a prefix set to all commands directed to the method exec.
Path::
An init parameter passed to the exec environment as a PATH.
This must be run unpacked somewhere in the filesystem.
An init parameter passed to the exec environment as a PATH.
This must be run unpacked somewhere in the filesystem.
ENV_::
An init parameter that points to an environment variable with the name stripped of the leading ENV_ and using the init parameter value.
An init parameter that points to an environment variable with the name stripped of the leading ENV_ and using the init parameter value.

46
jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
View File

@ -32,7 +32,7 @@ HTTP requests made from a script are subject to well known restrictions, the mos
Firefox 3.5 introduced support for W3C's Access Control for Cross-Site Requests specification, which requires a compliant client (for example, Firefox 3.5) and a compliant server (via this servlet filter).
This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object.
This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object.
If the client does not issue a compliant cross-domain request, this filter does nothing, and its overhead is the check of the presence of the cross-domain HTTP header.
This is extremely useful in CometD web applications where it is now possible to perform cross-domain long polling without using script injection (also known as the JSONP transport), and therefore removing all the downsides that the JSONP transport has (it's chattier, does not react quickly to failures, has a message size limit, uses GET instead of POST, etc.).
@ -40,46 +40,46 @@ This is extremely useful in CometD web applications where it is now possible to
[[cross-origin-setup]]
==== Setup
You will need to put the jetty-servlets.jar file onto your classpath.
If you are creating a webapp, ensure that this jar is included in your webapp's WEB-INF/lib.
Or, if you are running jetty embedded you will need to ensure that jetty-servlets.jar is on the execution classpath.
You can download the jetty-servlets.jar from the Maven Central Repository at http://central.maven.org/maven2/org/eclipse/jetty/jetty-servlets/.
You will need to put the `jetty-servlets.jar` file onto your classpath.
If you are creating a webapp, ensure that this jar is included in your webapp's `WEB-INF/lib`.
Or, if you are running Jetty embedded you will need to ensure that `jetty-servlets.jar` is on the execution classpath.
You can download the `jetty-servlets.jar` from the Maven Central Repository at http://central.maven.org/maven2/org/eclipse/jetty/jetty-servlets/.
It is also available as part of the Jetty distribution in the `$JETTY_HOME/lib` directory.
[[cross-origin-config]]
==== Configuration
This is a regular servlet filter that must be configured in web.xml.
This is a regular servlet filter that must be configured in `web.xml`.
It supports the following configuration parameters:
allowedOrigins::
a comma separated list of origins that are allowed to access the resources.
Default value is: * (all origins)
A comma separated list of origins that are allowed to access the resources.
Default value is: * (all origins)
allowedMethods::
a comma separated list of HTTP methods that are allowed to be used when accessing the resources.
Default value is: GET,POST,HEAD
A comma separated list of HTTP methods that are allowed to be used when accessing the resources.
Default value is: GET,POST,HEAD
allowedHeaders::
a comma separated list of HTTP headers that are allowed to be specified when accessing the resources.
Default value is: X-Requested-With,Content-Type,Accept,Origin
A comma separated list of HTTP headers that are allowed to be specified when accessing the resources.
Default value is: X-Requested-With,Content-Type,Accept,Origin
allowCredentials::
a boolean indicating if the resource allows requests with credentials.
Default value is: true
A boolean indicating if the resource allows requests with credentials.
Default value is: true
preflightMaxAge::
the number of seconds that preflight requests can be cached by the client.
Default value is 1800 seconds (30 minutes)
The number of seconds that preflight requests can be cached by the client.
Default value is 1800 seconds (30 minutes)
chainPreflight::
if true preflight requests are chained to their target resource for normal handling (as an OPTION request).
Otherwise the filter will response to the preflight.
Default is true.
If true preflight requests are chained to their target resource for normal handling (as an OPTION request).
Otherwise the filter will response to the preflight.
Default is true.
exposedHeaders::
a comma separated list of HTTP headers that are allowed to be exposed on the client.
Default value is the empty list.
A comma separated list of HTTP headers that are allowed to be exposed on the client.
Default value is the empty list.
A typical configuration could be:
[source, xml, subs="{sub-order}"]
----
<web-app>
<filter>
@ -92,6 +92,4 @@ A typical configuration could be:
</filter-mapping>
</web-app>
----

11
jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
View File

@ -28,13 +28,12 @@
[[debug-handler-usage]]
==== Usage
A simple handler that is useful to debug incoming traffic.
It will log entry and exit points of http requests as well as the response code.
A simple handler that is useful to debug incoming traffic.
It will log entry and exit points of HTTP requests as well as the response code.
==== Usage in standard distribution
Simply include jetty-debug.xml in your *.ini configs.
For example in start.ini.
The debug handler can be added to Jetty by activating the debug module.
==== Embedded usage
@ -49,10 +48,9 @@ debugHandler.setHandler(server.getHandler());
server.setHandler(debugHandler);
server.start();
----
==== Some example output
==== Example output
[source,bash]
----
@ -66,5 +64,4 @@ server.start();
15:14:07.248:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:07.251:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico RESPONSE 404 text/html;charset=ISO-8859-1
15:14:09.330:qtp551889550-57 CLOSED HttpConnection@e910ee4{INTERESTED},g=HttpGenerator{s=START},p=HttpParser{s=START,0 of -1}
----

13
jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
View File

@ -28,19 +28,18 @@
[[default-handler-usage]]
==== Usage
A simple handler that is useful to terminate handler chains with a clean fashion.
As in the example below, if a resource to be served is not matched within the resource handler, the DefaultHandler will take care of producing a 404 page.
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an link:#error-handler[Error Handler] that services errors related to the servlet api specification so it is best to not get the two confused.
A simple handler that is useful to terminate handler chains with a clean fashion.
As in the example below, if a resource to be served is not matched within the resource handler the `DefaultHandler` will take care of producing a 404 page.
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an link:#error-handler[Error Handler] that services errors related to the servlet api specification, so it is best to not get the two confused.
_____
[NOTE]
The DefaultHandler will also handle serving out the flav.ico file should a request make it through all of the other handlers without being resolved.
The `DefaultHandler` will also handle serving out the `flav.ico` file should a request make it through all of the other handlers without being resolved.
_____
[source, java, subs="{sub-order}"]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
ResourceHandler resourceHandler = new ResourceHandler();
@ -49,6 +48,4 @@ _____
{ resourceHandler, new DefaultHandler() });
server.setHandler(handlers);
server.start();
----

40
jetty-documentation/src/main/asciidoc/administration/extras/default-servlet.adoc
View File

@ -28,39 +28,39 @@
[[default-servlet-usage]]
==== Usage
The DefaultServlet implements the ResourceFactory interface and extends the HttpServlet abstract class.
It is usually mapped to / and provides handling for static content, OPTION and TRACE methods for the context.
The MOVE method is allowed if PUT and DELETE are allowed.
See DefaultServlet link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[javadoc].
The `DefaultServlet` implements the `ResourceFactory` interface and extends the `HttpServlet` abstract class.
It is usually mapped to "/" and provides handling for static content, `OPTION` and `TRACE` methods for the context.
The `MOVE` method is allowed if `PUT` and `DELETE` are allowed.
See the `DefaultServlet` link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[javadoc].
[[default-servlet-init]]
==== Init Parameters
Jetty supports the following initParameters:
Jetty supports the following `initParameters`:
acceptRanges::
If true, range requests and responses are supported.
If true, range requests and responses are supported.
dirAllowed::
If true, directory listings are returned if no welcome file is found.
Otherwise 403 Forbidden displays.
If true, directory listings are returned if no welcome file is found.
Otherwise 403 Forbidden displays.
redirectWelcome::
If true, welcome files are redirected rather that forwarded.
If true, welcome files are redirected rather that forwarded.
gzip::
If set to true, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".
If set to true, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".
resourceBase::
Set to replace the context resource base.
Set to replace the context resource base.
aliases::
If true, aliases of resources are allowed (that is, symbolic links and caps variations) and may bypass security constraints.
If true, aliases of resources are allowed (that is, symbolic links and caps variations) and may bypass security constraints.
maxCacheSize::
Maximum total size of the cache or 0 for no cache.
Maximum total size of the cache or 0 for no cache.
maxCachedFileSize::
Maximum size of a file to cache.
Maximum size of a file to cache.
maxCachedFiles::
Maximum number of files to cache.
Maximum number of files to cache.
useFileMappedBuffer::
If set to true, mapped file buffer serves static content.
Setting this value to false means that a direct buffer is used instead of a mapped file buffer.
By default, this is set to true.
If set to true, mapped file buffer serves static content.
Setting this value to false means that a direct buffer is used instead of a mapped file buffer.
By default, this is set to true.
otherGzipFileExtensions::
A comma separated list of other file extensions that signify that a file is gzip compressed.
If you don't explicitly set this, it defaults to ".svgz".
A comma separated list of other file extensions that signify that a file is gzip compressed.
If you don't explicitly set this, it defaults to ".svgz".

69
jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
View File

@ -28,35 +28,34 @@
[[dos-filter-usage]]
==== Usage
The Denial of Service (DoS) filter limits exposure to request flooding, whether malicious, or as a result of a misconfigured client.
The DoS filter keeps track of the number of requests from a connection per second.
If the requests exceed the limit, Jetty rejects, delays, or throttles the request, and sends a warning message.
The filter works on the assumption that the attacker might be written in simple blocking style, so by suspending requests you are hopefully consuming the attacker's resources.
The Denial of Service (DoS) filter limits exposure to request flooding, whether malicious, or as a result of a misconfigured client.
The DoS filter keeps track of the number of requests from a connection per second.
If the requests exceed the limit, Jetty rejects, delays, or throttles the request, and sends a warning message.
The filter works on the assumption that the attacker might be written in simple blocking style, so by suspending requests you are hopefully consuming the attacker's resources.
The DoS filter is related to the QoS filter, using Continuations to prioritize requests and avoid thread starvation.
[[dos-filter-using]]
==== Using the DoS Filter
Jetty places throttled requests in a priority queue, giving priority first to authenticated users and users with an HttpSession, then to connections identified by their IP addresses.
Connections with no way to identify them have lowest priority.
Jetty places throttled requests in a priority queue, giving priority first to authenticated users and users with an HttpSession, then to connections identified by their IP addresses.
Connections with no way to identify them have lowest priority.
To uniquely identify authenticated users, you should implement the The extractUserId(ServletRequest request) function.
===== Required JARs
To use the DoS Filter, these JAR files must be available in WEB-INF/lib:
* $JETTY_HOME/lib/ext/jetty-util.jar
* $JETTY_HOME/lib/ext/jetty-servlets.jar
* $JETTY_HOME/lib/jetty-util.jar
* $JETTY_HOME/lib/jetty-servlets.jar
===== Sample Configuration
Place the configuration in a webapp's web.xml or jetty-web.xml.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:
[source, xml, subs="{sub-order}"]
----
<filter>
<filter-name>DoSFilter</filter-name>
<filter-class>org.eclipse.jetty.servlets.DoSFilter</filter-class>
@ -65,53 +64,49 @@ This example allow 30 requests at a time:
<param-value>30</param-value>
</init-param>
</filter>
----
[[dos-filter-init]]
===== Configuring DoS Filter Parameters
The following init parameters control the behavior of the filter:
The following `init` parameters control the behavior of the filter:
maxRequestsPerSec::
Maximum number of requests from a connection per second.
Requests in excess of this are first delayed, then throttled.
Default is 25.
Maximum number of requests from a connection per second.
Requests in excess of this are first delayed, then throttled.
Default is 25.
delayMs::
Delay imposed on all requests over the rate limit, before they are considered at all:
+
Delay imposed on all requests over the rate limit, before they are considered at all:
* 100 (ms) = Default
* -1 = Reject request
* 0 = No delay
* any other value = Delay in ms
maxWaitMs::
Length of time, in ms, to blocking wait for the throttle semaphore.
Default is 50 ms.
Length of time, in ms, to blocking wait for the throttle semaphore.
Default is 50 ms.
throttledRequests::
Number of requests over the rate limit able to be considered at once.
Default is 5.
Number of requests over the rate limit able to be considered at once.
Default is 5.
throttleMs::
Length of time, in ms, to async wait for semaphore. Default is 30000L.
Length of time, in ms, to async wait for semaphore. Default is 30000L.
maxRequestMs::
Length of time, in ms, to allow the request to run. Default is 30000L.
Length of time, in ms, to allow the request to run. Default is 30000L.
maxIdleTrackerMs::
Length of time, in ms, to keep track of request rates for a connection, before deciding that the user has gone away, and
discarding it.
Default is 30000L.
Length of time, in ms, to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
Default is 30000L.
insertHeaders::
If true, insert the DoSFilter headers into the response.
Defaults to true.
If true, insert the DoSFilter headers into the response.
Defaults to true.
trackSessions::
If true, usage rate is tracked by session if a session exists.
Defaults to true.
If true, usage rate is tracked by session if a session exists.
Defaults to true.
remotePort::
If true and session tracking is not used, then rate is tracked by IP+port (effectively connection).
Defaults to false.
If true and session tracking is not used, then rate is tracked by IP and port (effectively connection).
Defaults to false.
ipWhitelist::
A comma-separated list of IP addresses that will not be rate limited.
A comma-separated list of IP addresses that will not be rate limited.
managedAttr::
If set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via ContextHandler.MANAGED_ATTRIBUTES) to manage the configuration of the filter.
If set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via `ContextHandler.MANAGED_ATTRIBUTES`) to manage the configuration of the filter.

6
jetty-documentation/src/main/asciidoc/administration/extras/error-handler.adoc
View File

@ -28,6 +28,6 @@
[[error-handler-usage]]
==== Usage
A handler that is used to report errors from servlet contexts and webapp contexts to report error conditions.
Primarily handles setting the various servlet spec specific response headers for error conditions.
Can be customized by extending, for more information on this see xref:custom-error-pages[].
A handler that is used to report errors from servlet contexts and webapp contexts to report error conditions.
Primarily handles setting the various servlet spec specific response headers for error conditions.
Can be customized by extending; for more information on this see xref:custom-error-pages[].

44
jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc
View File

@ -29,18 +29,18 @@
[[gzip-filter-usage]]
==== Usage
The Jetty GzipHandler is a compression handler that you can apply to any dynamic resource (servlet).
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length.
We have tested it with Jetty continuations and suspending requests.
The Jetty `GzipHandler` is a compression handler that you can apply to any dynamic resource (servlet).
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length.
It has been tested with Jetty continuations and suspending requests.
Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).
The GzipHandler is added to the entire server by the etc/jetty-gzip.xml file from the gzip.mod module.
The `GzipHandler` is added to the entire server by the `etc/jetty-gzip.xml` file from the `gzip.mod` module.
It may also be added to individual contexts in a context xml file.
[[gzip-filter-rules]]
==== Gzip Rules
GZIP Handler will gzip or deflate the content of a response if:
`GzipHandler` will gzip or deflate the content of a response if:
* It is mapped to a matching path
* The request method is configured to support gzip
@ -53,33 +53,35 @@ GZIP Handler will gzip or deflate the content of a response if:
If both gzip and deflate are specified in the accept-encoding header, then gzip will be used.
Compressing the content can greatly improve the network bandwidth usage, but at a cost of memory and CPU cycles.
The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed static content, which saves memory and CPU.
By default, the GzipHandler will check to see if pre-compressed content exists, and pass the request through to be handled by the DefaultServlet.
Compressing the content can greatly improve the network bandwidth usage, but at the cost of memory and CPU cycles.
The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed static content, which saves memory and CPU.
By default, the `GzipHandler` will check to see if pre-compressed content exists, and pass the request through to be handled by the `DefaultServlet`.
[[gzip-filter-init]]
==== Gzip Configuration
minGzipSize::
Content will only be compressed if content length is either unknown or greater than minGzipSize.
Content will only be compressed if content length is either unknown or greater than `minGzipSize`.
checkGzExists::
True by default. If set to false, the handler will not check for pre-compressed content.
True by default.
If set to false, the handler will not check for pre-compressed content.
compressionLevel::
The compression level used for deflate compression. (0-9).
The compression level used for deflate compression. (0-9).
includedMethods::
List of HTTP methods to compress. If not set, only GET requests are compressed.
List of HTTP methods to compress.
If not set, only `GET` requests are compressed.
includedMimeTypes::
List of mime types to compress.
List of MIME types to compress.
excludedMimeTypes::
List of mime types not to compress.
List of MIME types not to compress.
excludedAgentPatterns::
A list of regex patterns for User-Agent names from which requests should not be compressed.
A list of regex patterns for User-Agent names from which requests should not be compressed.
excludedPaths::
List of paths to exclude from compression.
Does a String.startsWith(String) comparison to check if the path matches.
If it does match -> no compression.
To match subpaths use excludePathPatterns instead.
List of paths to exclude from compression.
Performs a `String.startsWith(String)` comparison to check if the path matches.
If it does match then there is no compression.
To match subpaths use excludePathPatterns instead.
includedPaths::
List of paths to consider for compression.
List of paths to consider for compression.
includePaths::
List of paths to definitely consider for compression.
List of paths to definitely consider for compression.

18
jetty-documentation/src/main/asciidoc/administration/extras/ipaccess-handler.adoc
View File

@ -28,8 +28,8 @@
[[ipaccess-handler-usage]]
==== Usage
Controls access to the wrapped handler by the real remote IP.
Control is provided by white/black lists that include both internet addresses and URIs.
Controls access to the wrapped handler by the real remote IP.
Control is provided by white/black lists that include both internet addresses and URIs.
This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.
Typically, the black/white lists will be used in one of three modes:
@ -38,8 +38,8 @@ Typically, the black/white lists will be used in one of three modes:
* Allowing only some specific IPs/URLs by specifying several white lists entries.
* Allowing a general range of IPs/URLs by specifying several general white list entries, that are then further refined by several specific black list exceptions.
An empty white list is treated as match all.
If there is at least one entry in the white list, then a request must match a white list entry.
An empty white list is treated as match all.
If there is at least one entry in the white list, then a request *must* match a white list entry.
Black list entries are always applied, so that even if an entry matches the white list, a black list entry will override it.
Internet addresses may be specified as absolute address or as a combination of four octet wildcard specifications (a.b.c.d) that are defined as follows.
@ -51,11 +51,11 @@ Internet addresses may be specified as absolute address or as a combination of f
** - => 0-255
* a,b,... - a list of wildcard specifications
Internet address specification is separated from the URI pattern using the "|" (pipe) character.
Internet address specification is separated from the URI pattern using the "|" (pipe) character.
URI patterns follow the servlet specification for simple * prefix and suffix wild cards (e.g. /, /foo, /foo/bar, /foo/bar/*, *.baz).
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Both of these features have been deprecated in the current version.
Examples of the entry specifications are:
@ -68,6 +68,6 @@ Examples of the entry specifications are:
* 10.10.0-.-255|/foo/bar - all requests from IPs within 10.10.0.0/16 subnet to URI /foo/bar
* 10.10.0-3,1,3,7,15|/foo/* - all requests from IPs addresses with last octet equal to 1,3,7,15 in subnet 10.10.0.0/22 to URIs starting with /foo/
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Both of these features have been deprecated in the current version.

17
jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc
View File

@ -30,25 +30,24 @@
[[moved-context-handler-usage]]
==== Usage
You can use the MovedContextHandler to relocate or redirect a context that has changed context path and/or virtual hosts.
You can use the `MovedContextHandler` to relocate or redirect a context that has changed context path and/or virtual hosts.
You can configure it to _permanently_ redirect the old URL to the new URL, in which case Jetty sends a Http Status code of 301 to the browser with the new URL.
You can configure it to _permanently_ redirect the old URL to the new URL, in which case Jetty sends a Http Status code of 301 to the browser with the new URL.
Alternatively, you can make it non-permanent, in which case Jetty sends a 302 Http Status code along with the new URL.
In addition, as with any other context, you can configure a list of virtual hosts, meaning that this context responds only to requests to one of the listed host names.
Suppose you have a context deployed at /foo, but that now you want to deploy at the root context / instead.
Suppose you have a context deployed at `/foo`, but that now you want to deploy at the root context `/` instead.
* First you reconfigure and redeploy the context on Jetty.
* Next you need a way to redirect all the browsers who have bookmarked /foo to the new path.
You create a new context xml file in $JETTY_HOME/contexts and configure the MovedContextHandler to do the redirection from /foo to /.
* Next you need a way to redirect all the browsers who have bookmarked `/foo` to the new path.
You create a new xref:configuring-contexts[context xml] file in `{$jetty/.base}/webapps` and configure the `MovedContextHandler` to do the redirection from `/foo` to `/`.
Here's an example.
This is a permanent redirection, which also preserves pathinfo and query strings on the redirect:
Below is an example.
This is a permanent redirection, which also preserves `pathinfo` and query strings on the redirect:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
@ -69,6 +68,4 @@ This is a permanent redirection, which also preserves pathinfo and query strings
</Array>
</Set>
</Configure>
----

30
jetty-documentation/src/main/asciidoc/administration/extras/proxy-servlet.adoc
View File

@ -28,9 +28,10 @@
[[proxy-servlet-usage]]
==== Usage
An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy. Internally it uses the async jetty-client.
An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy.
Internally it uses the async jetty-client.
To facilitate JMX monitoring, the HttpClient instance is set as context attribute, prefixed with the servlet's name and exposed by the mechanism provided by ContextHandler.MANAGED_ATTRIBUTES.
To facilitate JMX monitoring, the `HttpClient` instance is set as context attribute, prefixed with the servlet's name and exposed by the mechanism provided by `ContextHandler.MANAGED_ATTRIBUTES`.
[[proxy-servlet-init]]
==== Init Parameters
@ -47,35 +48,30 @@ blackList::
comma-separated list of forbidden proxy hosts
In addition, there are a number of init parameters that can be used to configure the HttpClient instance used internally for the proxy.
In addition, there are a number of init parameters that can be used to configure the `HttpClient` instance used internally for the proxy.
maxThreads::
Default Value: 256
+
Default Value: 256
The max number of threads of HttpClient's Executor
maxConnections::
Default Value: 32768
+
The max number of connections per destination.
RFC 2616 suggests that 2 connections should be opened per each destination, but browsers commonly open 6 or more. If this HttpClient is used for load testing, it is common to have only one destination (the server to load test), and it is recommended to set this value to a high value (at least as much as the threads present in the executor).
Default Value: 32768
The max number of connections per destination.
RFC 2616 suggests that 2 connections should be opened per each destination, but browsers commonly open 6 or more.
If this `HttpClient` is used for load testing, it is common to have only one destination (the server to load test), and it is recommended to set this value to a high value (at least as much as the threads present in the executor).
idleTimeout::
Default Value: 30000
+
Default Value: 30000
The idle timeout in milliseconds that a connection can be idle, that is without traffic of bytes in either direction.
timeout::
Default Value: 60000
+
Default Value: 60000
The total timeout in milliseconds for the request/response conversation.
requestBufferSize::
Default Value: 4096
+
Default Value: 4096
The size of the request buffer the request is written into.
responseBufferSize::
Default Value: 4096
+
Default Value: 4096
The size of the response buffer the response is written into.

94
jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc
View File

@ -28,64 +28,62 @@
[[qos-filter-usage]]
==== Usage
Jetty supports Continuations, which allow non-blocking handling of HTTP requests, so that threads can be allocated in a managed way to provide application specific Quality of Service (QoS).
The QoSFilter is a utility servlet filter that implements some QoS features.
Jetty supports Continuations, which allow non-blocking handling of HTTP requests, so that threads can be allocated in a managed way to provide application specific Quality of Service (QoS).
The `QoSFilter` is a utility servlet filter that implements some QoS features.
[[qos-understanding]]
==== Understanding the Problem
===== Waiting for Resources
Web applications frequently use JDBC Connection pools to limit the simultaneous load on the database.
Web applications frequently use JDBC Connection pools to limit the simultaneous load on the database.
This protects the database from peak loads, but makes the web application vulnerable to thread starvation.
Consider a thread pool with 20 connections, being used by a web application that that typically receives 200 requests per second and each request holds a JDBC connection for 50ms.
Consider a thread pool with 20 connections, being used by a web application that that typically receives 200 requests per second and each request holds a JDBC connection for 50ms.
Such a pool can service on average 200*20*1000/50 = 400 requests per second.
However, if the request rate rises above 400 per second, or if the database slows down (due to a large query) or becomes momentarily unavailable, the thread pool can very quickly accumulate many waiting requests.
If, for example, the website is slashdotted or experiences some other temporary burst of traffic and the request rate rises from 400 to 500 requests per second, then 100 requests per second join those waiting for a JDBC connection.
Typically, a web server's thread pool contains only a few hundred threads, so a burst or slow DB need only persist for a few seconds to consume the entire web server's thread pool.
This is called thread starvation.
The key issue with thread starvation is that it effects the entire web application, and potentially the entire web server.
Even if the requests using the database are only a small proportion of the total requests on the web server, all requests are blocked because all the available threads are waiting on the JDBC connection pool.
This represents non graceful degradation under load and provides a very poor quality of service.
However, if the request rate rises above 400 per second, or if the database slows down (due to a large query) or becomes momentarily unavailable, the thread pool can very quickly accumulate many waiting requests.
If, for example, the website is "slashdotted" or experiences some other temporary burst of traffic and the request rate rises from 400 to 500 requests per second, then 100 requests per second join those waiting for a JDBC connection.
Typically, a web server's thread pool contains only a few hundred threads, so a burst or slow DB need only persist for a few seconds to consume the entire web server's thread pool; this is called thread starvation.
The key issue with thread starvation is that it effects the entire web application, and potentially the entire web server.
Even if the requests using the database are only a small proportion of the total requests on the web server, all requests are blocked because all the available threads are waiting on the JDBC connection pool.
This represents non-graceful degradation under load and provides a very poor quality of service.
===== Prioritizing Resources
Consider a web application that is under extreme load.
This load might be due to a popularity spike (slashdot), usage burst (Christmas or close of business), or even a denial of service attack.
Consider a web application that is under extreme load.
This load might be due to a popularity spike (slashdot), usage burst (Christmas or close of business), or even a denial of service attack.
During such periods of load, it is often desirable not to treat all requests as equals, and to give priority to high value customers or administrative users.
The typical behaviour of a web server under extreme load is to use all its threads to service requests and to build up a backlog of unserviced requests.
The typical behavior of a web server under extreme load is to use all its threads to service requests and to build up a backlog of unserviced requests.
If the backlog grows deep enough, then requests start to timeout and users experience failures as well as delays.
Ideally, the web application should be able to examine the requests in the backlog, and give priority to high value customers and administrative users.
But with the standard blocking servlet API, it is not possible to examine a request without allocating a thread to that request for the duration of its handling.
Ideally, the web application should be able to examine the requests in the backlog, and give priority to high value customers and administrative users.
But with the standard blocking servlet API, it is not possible to examine a request without allocating a thread to that request for the duration of its handling.
There is no way to delay the handling of low priority requests, so if the resources are to be reallocated, then the low priority requests must all be failed.
[[qos-applying]]
==== Applying the QoSFilter
The Quality of Service Filter (QoSFilter) uses Continuations to avoid thread starvation, prioritize requests and give graceful degradation under load, to provide a high quality of service.
When you apply the filter to specific URLs within a web application, it limits the number of active requests being handled for those URLs.
Any requests in excess of the limit are suspended. When a request completes handling the limited URL, one of the waiting requests resumes and can be handled.
The Quality of Service Filter (QoSFilter) uses Continuations to avoid thread starvation, prioritize requests and give graceful degradation under load, to provide a high quality of service.
When you apply the filter to specific URLs within a web application, it limits the number of active requests being handled for those URLs.
Any requests in excess of the limit are suspended. When a request completes handling the limited URL, one of the waiting requests resumes and can be handled.
You can assign priorities to each suspended request, so that high priority requests resume before lower priority requests.
===== Required JARs
To use the QoS Filter, these JAR files must be available in WEB-INF/lib:
To use the QoS Filter, these JAR files must be available in `WEB-INF/lib`:
* $JETTY_HOME/lib/ext/jetty-util.jar
* $JETTY_HOME/lib/ext/jetty-servlets.jar–contains QoSFilter
* $JETTY_HOME/lib/jetty-util.jar
* $JETTY_HOME/lib/jetty-servlets.jar – contains QoSFilter
===== Sample Configuration
Place the configuration in a webapp's web.xml or jetty-web.xml.
The default configuration processes ten requests at a time, servicing more important requests first, and queuing up the rest.
Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration processes ten requests at a time, servicing more important requests first and queuing up the rest.
This example processes fifty requests at a time:
[source, xml, subs="{sub-order}"]
----
<filter>
<filter-name>QoSFilter</filter-name>
<filter-class>org.eclipse.jetty.servlets.QoSFilter</filter-class>
@ -94,68 +92,62 @@ This example processes fifty requests at a time:
<param-value>50</param-value>
</init-param>
</filter>
----
[[qos-filter-init]]
===== Configuring QoS Filter Parameters
A semaphore polices the "maxRequests" limit.
The filter waits a short time while attempting to acquire the semaphore.
The "waitMs" init parameter controls the wait, avoiding the expense of a suspend if the semaphore is shortly available.
If the semaphore cannot be obtained, Jetty suspends the request for the default suspend period of the container or the value set as the "suspendMs" init parameter.
A semaphore polices the `maxRequests` limit.
The filter waits a short time while attempting to acquire the semaphore.
The `waitMs` init parameter controls the wait, avoiding the expense of a suspend if the semaphore is shortly available.
If the semaphore cannot be obtained, Jetty suspends the request for the default suspend period of the container or the value set as the `suspendMs` init parameter.
The QoS filter uses the following init parameters:
maxRequests::
the maximum number of requests to be serviced at a time. The default is 10.
The maximum number of requests to be serviced at a time. The default is 10.
maxPriority::
the maximum valid priority that can be assigned to a request.
A request with a high priority value is more important than a request with a low priority value. The default is 10.
The maximum valid priority that can be assigned to a request.
A request with a high priority value is more important than a request with a low priority value. The default is 10.
waitMS::
waitMS–length of time, in milliseconds, to wait while trying to accept a new request.
Used when the maxRequests limit is reached.
Default is 50 ms.
The length of time, in milliseconds, to wait while trying to accept a new request.
Used when the maxRequests limit is reached.
Default is 50 ms.
suspendMS::
length of time, in milliseconds, that the request will be suspended if it is not accepted immediately.
If not set, the container's default suspend period applies. Default is -1 ms.
Length of time, in milliseconds, that the request will be suspended if it is not accepted immediately.
If not set, the container's default suspend period applies. Default is -1 ms.
managedAttr::
If set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via ContextHandler.MANAGED_ATTRIBUTES) to manage the configuration of the filter.
If set to true, then this servlet is set as a `ServletContext` attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via `ContextHandler.MANAGED_ATTRIBUTES`) to manage the configuration of the filter.
===== Mapping to URLs
You can use the `<filter-mapping>` syntax to map the QoSFilter to a servlet, either by using the servlet name, or by using a URL pattern.
You can use the `<filter-mapping>` syntax to map the QoSFilter to a servlet, either by using the servlet name, or by using a URL pattern.
In this example, a URL pattern applies the QoSFilter to every request within the web application context:
[source, xml, subs="{sub-order}"]
----
<filter-mapping>
<filter-name>QoSFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
----
===== Setting the Request Priority
Requests with higher values have a higher priority.
Requests with higher values have a higher priority.
The default request priorities assigned by the QoSFilter are:
* 2 -- For any authenticated request
* 1 -- For any request with a non-new valid session
* 0 -- For all other requests
To customize the priority, subclass QoSFilter and then override the getPriority(ServletRequest request) method to return an appropriate priority for the request.
You can then use this subclass as your QoS filter.
Here's a trivial example:
To customize the priority, subclass QoSFilter and then override the `getPriority(ServletRequest request)` method to return an appropriate priority for the request.
You can then use this subclass as your QoS filter.
Here's an example:
[source, java, subs="{sub-order}"]
----
public class ParsePriorityQoSFilter extends QoSFilter
{
protected int getPriority(ServletRequest request)
@ -166,6 +158,4 @@ public class ParsePriorityQoSFilter extends QoSFilter
return 0;
}
}
----

57
jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc
View File

@ -17,7 +17,8 @@
[[rewrite-handler]]
=== Rewrite Handler
The RewriteHandler matches a request against a set of rules, and modifies the request accordingly for any rules that match. The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.
The `RewriteHandler` matches a request against a set of rules, and modifies the request accordingly for any rules that match.
The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.
[[rewrite-handler-metadata]]
==== Info
@ -31,9 +32,7 @@ The standard Jetty distribution bundle contains the `jetty-rewrite` link:#startu
[source, screen, subs="{sub-order}"]
....
$ java -jar start.jar --add-to-startd=rewrite
$ java -jar start.jar --add-to-start=rewrite
....
_____
@ -43,14 +42,14 @@ _____
==== Usage
The rewrite module enables the following jetty xml config file on the execution path:
The rewrite module enables the following Jetty xml config file on the execution path:
[source, xml, subs="{sub-order}"]
----
include::{SRCDIR}/jetty-rewrite/src/main/config/etc/jetty-rewrite.xml[]
----
As the commented out code shows, you configure the RewriteHandler by adding various rules.
As the commented out code shows, you configure the `RewriteHandler` by adding various rules.
There is an example of link:#rewrite-rules[rules] configuration in the standard distribution in the `demo-base/etc/demo-rewrite-rules.xml` file:
@ -65,32 +64,29 @@ This is an example for embedded Jetty, which does something similar to the confi
[source, java, subs="{sub-order}"]
----
Server server = new Server();
RewriteHandler rewrite = new RewriteHandler();
rewrite.setRewriteRequestURI(true);
rewrite.setRewritePathInfo(false);
rewrite.originalPathAttribute("requestedPath");
RedirectPatternRule redirect = new RedirectPatternRule();
redirect.setPattern("/redirect/*");
redirect.setReplacement("/redirected");
redirect.setReplacement("/redirected");
rewrite.addRule(redirect);
RewritePatternRule oldToNew = new RewritePatternRule();
oldToNew.setPattern("/some/old/context");
oldToNew.setReplacement("/some/new/context");
rewrite.addRule(oldToNew);
RewriteRegexRule reverse = new RewriteRegexRule();
reverse.setRegex("/reverse/([^/]*)/(.*)");
reverse.setReplacement("/reverse/$2/$1");
rewrite.addRule(reverse);
server.setHandler(rewrite);
----
[[rewrite-rules]]
@ -103,45 +99,46 @@ There are several types of rules that are written extending useful base rule cla
Matches against the request URI using the servlet pattern syntax.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/CookiePatternRule.html[CookiePatternRule]::
Adds a cookie to the response.
Adds a cookie to the response.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/HeaderPatternRule.html[HeaderPatternRule]::
Adds/modifies a header in the response.
Adds/modifies a header in the response.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/RedirectPatternRule.html[RedirectPatternRule]::
Redirects the response.
Redirects the response.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/ResponsePatternRule.html[ResponsePatternRule]::
Sends the response code (status or error).
Sends the response code (status or error).
link:{JXURL}/org/eclipse/jetty/rewrite/handler/RewritePatternRule.html[RewritePatternRule]::
Rewrite the URI by replacing the matched request path with a fixed string.
Rewrite the URI by replacing the matched request path with a fixed string.
===== RegexRule
Matches against the request URI using regular expressions.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/RedirectRegexRule.html[RedirectRegexRule]::
Redirect the response.
Redirect the response.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/RewriteRegexRule.html[RewriteRegexRule]::
Rewrite the URI by matching with a regular expression.
(The replacement string may use Template:$n to replace the nth capture group.)
Rewrite the URI by matching with a regular expression.
(The replacement string may use `Template:$n` to replace the nth capture group.)
===== HeaderRule
Match against request headers. Match either on a header name + specific value, or on the presence of a header (with any value).
Match against request headers. Match either on a header name and specific value, or on the presence of a header (with any value).
link:{JXURL}/org/eclipse/jetty/rewrite/handler/ForwardedSchemeHeaderRule.html[ForwardedSchemaHeaderRule]::
Set the scheme on the request (defaulting to https).
Set the scheme on the request (defaulting to HTTPS).
===== Others
Oddball rules that defy classification.
Extra rules that defy standard classification.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/MsieSslRule.html[MsieSslRule]::
Disables the keep alive for SSL from IE5 or IE6.
Disables the keep alive for SSL from IE5 or IE6.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/LegacyRule.html[LegacyRule]::
Implements the legacy API of RewriteHandler
Implements the legacy API of RewriteHandler
===== RuleContainer
Groups rules together. The contained rules will only be processed if the conditions for the RuleContainer evaluate to true.
Groups rules together.
The contained rules will only be processed if the conditions for the `RuleContainer` evaluate to true.
link:{JXURL}/org/eclipse/jetty/rewrite/handler/VirtualHostRuleContainer.html[VirtualHostRuleContainer]::
Groups rules that apply only to a specific virtual host or a set of virtual hosts
Groups rules that apply only to a specific virtual host or a set of virtual hosts

17
jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc
View File

@ -28,30 +28,27 @@
[[shutdown-handler-usage]]
==== Usage
A handler that shuts the server down on a valid request.
Used to do "soft" restarts from Java.
If _exitJvm is set to true a hard System.exit() call is being made.
A handler that shuts the server down on a valid request.
This is used to perform "soft" restarts from Java.
If `_exitJvm` is set to true a hard `System.exit()` call is being made.
This is an example of how you can setup this handler directly with the Server, it can be added as a part of handler chain or collection as well.
This is an example of how you can setup this handler directly with the Server.
It can also be added as a part of handler chain or collection.
[source, java, subs="{sub-order}"]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
handlers.setHandlers(new Handler[]
{ someOtherHandler, new ShutdownHandler(server,"secret password") });
server.setHandler(handlers);
server.start();
----
And this is an example that you can use to call the shutdown handler from within java.
This is an example that you can use to call the shutdown handler from within java.
[source, java, subs="{sub-order}"]
----
public static void attemptShutdown(int port, String shutdownCookie) {
try {
URL url = new URL("http://localhost:" + port + "/shutdown?token=" + shutdownCookie);
@ -66,6 +63,4 @@ And this is an example that you can use to call the shutdown handler from within
throw new RuntimeException(e);
}
}
----

41
jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc
View File

@ -31,14 +31,13 @@
Jetty currently has two levels of request statistic collection:
* Subclasses of AbstractConnector class optionally can collect statistics about connections as well as number of requests.
* The StatisticsHandler class may be used to collect request statistics.
* Subclasses of `AbstractConnector` class optionally can collect statistics about connections as well as number of requests.
* The `StatisticsHandler` class may be used to collect request statistics.
In addition to that, subclasses of AbstractSessionHandler class optionally can collect session statistics.
In addition to these, subclasses of the `AbstractSessionHandler` class optionally can collect session statistics.
AbstractConnector and AbstractSessionHandler statistics are turned off by default and must either be configured manually for each instance or
turned on via JMX interface.
The Statistics Handler is not included in default Jetty configuration, and needs to be configured manually.
`AbstractConnector` and `AbstractSessionHandler` statistics are turned off by default and must either be configured manually for each instance or turned on via JMX interface.
The `StatisticsHandler` is not included in default Jetty configuration, and needs to be configured manually.
_____
[NOTE]
@ -48,16 +47,15 @@ _____
[[connector-statistics]]
==== Connector statistics
Detailed statistics on connection duration and number of requests are only collated when a connection is closed.
The current and maximum number of connections are the only "live" statistics.
To learn how to turn on connector statistics please see Jetty Statistics tutorial, although this is not recommended and it is best to use a JMX agent to select statistics only when needed.
Detailed statistics on connection duration and number of requests are only collated when a connection is closed.
The current and maximum number of connections are the only "live" statistics.
//To learn how to turn on connector statistics please see the Jetty Statistics tutorial, although this is not recommended and it is best to use a JMX agent to select statistics only when needed.
The following example shows how to turn on connector statistics in jetty xml.
The following example shows how to turn on connector statistics in Jetty xml.
This example comes from within `jetty-http.xml`.
[source, xml, subs="{sub-order}"]
----
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ServerConnector">
@ -83,44 +81,37 @@ This example comes from within `jetty-http.xml`.
</New>
</Arg>
</Call>
----
[[request-statistics]]
==== Request Statistics
To collect request statistics a StatisticsHandler must be configured as one of the handlers of the server.
Typically this can be done as the top level handler, but you may choose to configure a statistics handler for just one context by creating a context configuration file.
Please note that `jetty-stats.xml` has to appear in the command line after the main Jetty configuration file as shown below.
It should be able to be uncommented in the start.ini file.
To collect request statistics a `StatisticsHandler` must be configured as one of the handlers of the server.
Typically this can be done as the top level handler, but you may choose to configure a statistics handler for just one context by creating a context configuration file.
You can enable the `StatisticsHandler` by activating the `stats` modules on the command line.
[source, screen, subs="{sub-order}"]
....
$ java -jar start.jar OPTIONS=default etc/jetty.xml etc/jetty-stats.xml
$ java -jar {$jetty.home}/start.jar --add-to-start=stats
....
Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own jetty xml configuration.
Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration.
The following fragment shows how to configure a top level statistics handler:
[source, xml, subs="{sub-order}"]
----
<Get id="oldhandler" name="handler" />
<Set name="handler">
<New id="StatsHandler" class="org.eclipse.jetty.server.handler.StatisticsHandler">
<Set name="handler"><Ref refid="oldhandler" /></Set>
</New>
</Set>
----
[[session-statistics]]
==== Session Statistics
Session handling is built into Jetty for any servlet or webapp context.
Detailed statistics on session duration are only collated when a session is closed.
The current, minimum, and maximum number of sessions are the only "live" statistics.
Detailed statistics on session duration are only collated when a session is closed.
The current, minimum, and maximum number of sessions are the only "live" statistics.
The session statistics are enabled by default and do not need to be configured.

4
jetty-documentation/src/main/asciidoc/administration/runner/chapter.adoc
View File

@ -17,6 +17,6 @@
[[runner]]
== Jetty Runner
This chapter explains how to use the jetty-runner to run your webapps without needing an installation of jetty.
This chapter explains how to use the `jetty-runner` to run your webapps without needing an installation of Jetty.
include::jetty-runner.adoc[]
include::jetty-runner.adoc[]

143
jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc
View File

@ -17,37 +17,36 @@
[[jetty-runner]]
=== Use Jetty without an installed distribution
The idea of the jetty-runner is extremely simple – run a webapp directly from the command line using a single jar and as much default configuration as possible.
Of course, if your webapp is not so straightforward, the jetty-runner has command line options which allow
you to customize the execution environment.
The idea of the `jetty-runner` is extremely simple – run a webapp directly from the command line using a single jar file and as much default configuration as possible.
Of course, if your webapp is not so straightforward, the `jetty-runner` has command line options which allow you to customize the execution environment.
[[jetty-runner-preparation]]
==== Preparation
You will need the jetty-runner jar:
You will need the `jetty-runner` jar:
1. http://central.maven.org/maven2/org/eclipse/jetty/jetty-runner/[Get] the jetty-runner jar, from http://search.maven.org/#browse[maven central]
1. http://central.maven.org/maven2/org/eclipse/jetty/jetty-runner/[Get] the `jetty-runner` jar available at http://search.maven.org/#browse[maven central].
==== Deploying a simple context
Let's assume we have a very simple webapp, that does not need any resources from its environment, nor any configuration apart from the defaults.
Starting it is as simple as doing the following:
Let's assume we have a very simple webapp that does not need any resources from its environment, nor any configuration apart from the defaults.
Starting it is as simple as performing the following:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar simple.war
> java -jar jetty-runner.jar simple.war
....
This will start jetty on port 8080, and deploy the webapp to "/".
This will start Jetty on port 8080, and deploy the webapp to `/`.
Your webapp does not have to be packed into a war, you can deploy a webapp that is a directory instead in the same way:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar simple
> java -jar jetty-runner.jar simple
....
In fact, the webapp does not have to be a war or even a directory, it can simply be a jetty link:#using-context-provider[context xml] file that describes your webapp:
In fact, the webapp does not have to be a war or even a directory, it can simply be a Jetty link:#using-context-provider[context xml] file that describes your webapp:
[source, screen, subs="{sub-order}"]
....
@ -61,63 +60,58 @@ ____
==== Deploying multiple contexts
If you have more than one webapp that must be deployed, simply provide them all on the command line.
You can control the context paths for them using the "--path" parameter.
If you have more than one webapp that must be deployed, simply provide them all on the command line.
You can control the context paths for them using the `--path` parameter.
Here's an example of deploying 2 wars (although either or both of them could be unpacked directories instead):
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --path /one my1.war --path /two my2.war
> java -jar jetty-runner.jar --path /one my1.war --path /two my2.war
....
If you have context xml files that describe your webapps, you can fully configure your webapps in them, and hence you don't need to use the command line switches.
If you have context xml files that describe your webapps, you can fully configure your webapps in them and hence you don't need to use the command line switches.
Just provide the list of context files like so:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml
....
____
[NOTE]
The command line switches override configuration file settings. So, for example, you could set the context path for the webapp inside the context xml file, and use the --path switch to override it on the command line.
Switched used on the command line override configuration file settings.
So, for example, you could set the context path for the webapp inside the context xml file, and use the `--path` switch to override it on the command line.
____
===== Changing the default port
By default the jetty-runner will listen on port 8080.
You can easily change this on the command line using the "--port" command.
By default the `jetty-runner` will listen on port 8080.
You can easily change this on the command line using the `--port` command.
Here's an example that runs our simple.war on port 9090:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --port 9090 simple.war
> java -jar jetty-runner.jar --port 9090 simple.war
....
===== Using jetty.xml files
Instead of, or in addition to using command line switches, you can use one or more jetty.xml files to configure the environment for your webapps.
Here's an example where we apply two different jetty.xml files:
Instead of, or in addition to, using command line switches, you can use one or more `jetty.xml` files to configure the environment for your webapps.
Here's an example where we apply two different `jetty.xml` files:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war
> java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war
....
____
[NOTE]
Switches on the command line take precedence over those defined in configuration files, so you can use the command line as overrides.
____
===== Full configuration reference
You can see the fill set of configuration options using the --help switch:
You can see the fill set of configuration options using the `--help` switch:
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --help
> java -jar jetty-runner.jar --help
....
Here's what the output will look like:
@ -141,128 +135,118 @@ Server opts:
[--config file]*n - each tuple specifies the name of a jetty xml config file to apply (in the order defined)
Context opts:
[[--path /path] context]*n - WAR file, web app dir or context xml file, optionally with a context path
----
Printing the version:::
Print out the version of jetty and then exit immediately.
Print out the version of Jetty and then exit immediately.
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --version
> java -jar jetty-runner.jar --version
....
Configuring a request log:::
Cause jetty to write a request log with the given name.
If the file is prefixed with yyyy_mm_dd then the file will be automatically rolled over.
Note that for finer grained configuration of the link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[request log], you will need to use a jetty xml file instead.
Cause Jetty to write a request log with the given name.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
Note that for finer grained configuration of the link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[request log], you will need to use a Jetty xml file instead.
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war
> java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war
....
Configuring the output log:::
Redirect the output of jetty logging to the named file.
If the file is prefixed with yyyy_mm_dd then the file will be automatically rolled over.
Redirect the output of jetty logging to the named file.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war
> java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war
....
Configuring the interface for http:::
Like jetty standalone, the default is for the connectors to listen on all interfaces on a machine.
You can control that by specifying the name or ip address of the particular interface you wish to use with the --host argument:
Like Jetty standalone, the default is for the connectors to listen on all interfaces on a machine.
You can control that by specifying the name or ip address of the particular interface you wish to use with the `--host` argument:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --host 192.168.22.19 my.war
....
Configuring the port for http:::
The default port number is 8080.
To link:#how-to-configure-connectors[configure a https connector], use a jetty xml config file instead.
The default port number is 8080.
To link:#how-to-configure-connectors[configure a https connector], use a Jetty xml config file instead.
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --port 9090 my.war
> java -jar jetty-runner.jar --port 9090 my.war
....
Configuring stop:::
You can configure a port number for jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the --stop-port and --stop-key parameters as arguments to the jetty-runner:
You can configure a port number for jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `--stop-port` and `--stop-key` parameters as arguments to the `jetty-runner`:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --stop-port 8181 --stop-key abc123
....
+
Then, to stop jetty from a different terminal, you need to supply the same port and key information.
For this you'll either need a local installation of jetty, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or write a custom class.
Here's how to use a jetty installation to perform a stop:
Then, to stop Jetty from a different terminal, you need to supply the same port and key information.
For this you'll either need a local installation of Jetty, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class.
Here's how to use a Jetty installation to perform a stop:
+
[source, screen, subs="{sub-order}"]
....
> java -jar start.jar --stop-port 8181 --stop-key abc123 --stop
....
Configuring the container classpath:::
With a local installation of jetty, you add jars and classes to the container's classpath by putting them in the $JETTY_HOME/lib directory.
With the jetty-runner, you can use the --lib, --jar and --classes arguments instead to achieve the same thing.
With a local installation of Jetty, you add jars and classes to the container's classpath by putting them in the `{$jetty.base}/lib` directory.
With the `jetty-runner`, you can use the `--lib`, `--jar` and `--classes` arguments instead to achieve the same thing.
+
--lib adds the location of a directory which contains jars to add to the container classpath.
You can add 1 or more. Here's an example of configuring 2 directories:
`--lib` adds the location of a directory which contains jars to add to the container classpath.
You can add 1 or more.
Here's an example of configuring 2 directories:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --lib /usr/local/external/lib --lib $HOME/external-other/lib my.war
....
+
--jar adds a single jar file to the container classpath.
You can add 1 or more.
`--jar` adds a single jar file to the container classpath.
You can add 1 or more.
Here's an example of configuring 3 extra jars:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --jar /opt/stuff/jars/jar1.jar --jar $HOME/jars/jar2.jar --jar /usr/local/proj/jars/jar3.jar my.war
....
+
--classes add the location of a directory containing classes to add to the container classpath.
You can add 1 or more.
`--classes` add the location of a directory containing classes to add to the container classpath.
You can add 1 or more.
Here's an example of configuring a single extra classes dir:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --classes /opt/stuff/classes my.war
....
Gathering statistics:::
If statistics gathering is enabled, then they are viewable by surfing
to the context /stats. You may optionally protect access to that
context with a password. Here's an example of enabling statistics,
with no password protection:
If statistics gathering is enabled, then they are viewable by surfing to the context `/stats`.
You may optionally protect access to that context with a password.
Here's an example of enabling statistics, with no password protection:
+
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --stats unsecure my.war
....
+
If we wished to protect access to the /stats context, we would provide the location of a jetty realm configuration file containing authentication and authorization information.
For example, we could use the following example realm file from the jetty distribution:
If we wished to protect access to the `/stats` context, we would provide the location of a Jetty realm configuration file containing authentication and authorization information.
For example, we could use the following example realm file from the Jetty distribution:
+
[source, screen, subs="{sub-order}"]
....
jetty: MD5:164c88b302622e17050af52c89945d44,user
admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin
@ -271,7 +255,6 @@ plain: plain,user
user: password,user
# This entry is for digest auth. The credential is a MD5 hash of username:realmname:password
digest: MD5:6e120743ad67abfbc385bc2bb754e297,user
....
+
Assuming we've copied it into the local directory, we would apply it like so
@ -279,10 +262,9 @@ Assuming we've copied it into the local directory, we would apply it like so
[source, screen, subs="{sub-order}"]
....
> java -jar jetty-runner.jar --stats realm.properties my.war
....
+
After surfing to http://localhost:8080/ a few times, we can surf to the stats servlet on http://localhost:8080/stats to see the output:
After navigating to http://localhost:8080/ a few times, we can point to the stats servlet on http://localhost:8080/stats to see the output:
+
....
Statistics:
@ -337,6 +319,5 @@ Total messages out: 7
Memory:
Heap memory usage: 49194840 bytes
Non-heap memory usage: 12611696 bytes
Non-heap memory usage: 12611696 bytes
....

2
jetty-server/src/main/java/org/eclipse/jetty/server/AbstractNCSARequestLog.java
View File

@ -242,7 +242,7 @@ public abstract class AbstractNCSARequestLog extends AbstractLifeCycle implement
String agent = request.getHeader(HttpHeader.USER_AGENT.toString());
if (agent == null)
b.append("\"-\" ");
b.append("\"-\"");
else
{
b.append('"');

22
jetty-server/src/test/java/org/eclipse/jetty/server/handler/RequestLogTest.java
View File

@ -188,11 +188,31 @@ public class RequestLogTest
assertThat(log,containsString("GET /foo "));
assertThat(log,containsString(" 400 0 "));
}
@Test
public void testUseragentWithout() throws Exception
{
_connector.getResponses("GET http://[:1]/foo HTTP/1.1\nReferer: http://other.site\n\n");
String log = _log.exchange(null,5,TimeUnit.SECONDS);
assertThat(log,containsString("GET http://[:1]/foo "));
assertThat(log,containsString(" 400 0 \"http://other.site\" \"-\" - "));
}
@Test
public void testUseragentWith() throws Exception
{
_connector.getResponses("GET http://[:1]/foo HTTP/1.1\nReferer: http://other.site\nUser-Agent: Mozilla/5.0 (test)\n\n");
String log = _log.exchange(null,5,TimeUnit.SECONDS);
assertThat(log,containsString("GET http://[:1]/foo "));
assertThat(log,containsString(" 400 0 \"http://other.site\" \"Mozilla/5.0 (test)\" - "));
}
private class Log extends AbstractNCSARequestLog
{
{
super.setExtended(true);
super.setLogLatency(true);
super.setLogCookies(true);
}
@Override