Ported the old FastCGI documentation to the new operations guide.
Removed the old HTTP/2 and JMX documentation (already present in the new documentation). Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
d6750b0b25
commit
13bb75e041
|
|
@ -1,18 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[fastcgi]]
|
|
||||||
== FastCGI Support
|
|
||||||
|
|
||||||
include::fastcgi-intro.adoc[]
|
|
||||||
include::configuring-fastcgi.adoc[]
|
|
||||||
|
|
@ -1,175 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[configuring-fastcgi]]
|
|
||||||
=== Configuring Jetty for FastCGI
|
|
||||||
|
|
||||||
In this section you will see how to configure Jetty to serve WordPress via FastCGI.
|
|
||||||
|
|
||||||
The first step is to have WordPress installed on your server machine, for example under `/var/www/wordpress`.
|
|
||||||
For more information about how to install WordPress, please refer to the https://codex.wordpress.org/Installing_WordPress[WordPress Installation Guide].
|
|
||||||
|
|
||||||
The second step is to install `php-fpm` and make sure it is configured to listen on a TCP socket; typically it is configured to listen to `localhost:9000`.
|
|
||||||
|
|
||||||
The third step is to install Jetty, for example under `/opt/jetty`, called in the following `$JETTY_HOME`.
|
|
||||||
Refer to xref:jetty-downloading[] for more information about how to install Jetty.
|
|
||||||
|
|
||||||
The fourth step is to create a Jetty base directory (see xref:startup-base-and-home[]), called in the following `$JETTY_BASE`, where you setup the configuration needed to support FastCGI in Jetty, and configure the `fcgi`, `http` and `deploy` modules, so that Jetty will be able to accept HTTP requests from browsers, convert them in FastCGI, and proxy them to `php-fpm`:
|
|
||||||
|
|
||||||
[source, screen, subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
$ mkdir -p /usr/jetty/wordpress
|
|
||||||
$ cd /usr/jetty/wordpress
|
|
||||||
$ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy
|
|
||||||
....
|
|
||||||
|
|
||||||
Therefore `$JETTY_BASE=/usr/jetty/wordpress`.
|
|
||||||
|
|
||||||
The fifth step is to deploy the web application that provides the proxying of client requests to the FastCGI server, `php-fpm`.
|
|
||||||
Typically this is done by deploying a `*.war` file in the `$JETTY_BASE/webapps` directory.
|
|
||||||
For FastCGI there is no web application that needs developed - all the work has already been done for you by Jetty.
|
|
||||||
As such you only need to deploy a Jetty context XML file that configures the web application directly.
|
|
||||||
Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml`:
|
|
||||||
|
|
||||||
[source,xml,subs="{sub-order}"]
|
|
||||||
----
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://eclipse.dev/jetty/configure_9_3.dtd">
|
|
||||||
<Configure class="org.eclipse.jetty.ee9.servlet.ServletContextHandler">
|
|
||||||
|
|
||||||
<New id="root" class="java.lang.String">
|
|
||||||
<Arg>/var/www/wordpress</Arg>
|
|
||||||
</New>
|
|
||||||
|
|
||||||
<Set name="contextPath">/</Set>
|
|
||||||
<Set name="resourceBase"><Ref refid="root" /></Set>
|
|
||||||
<Set name="welcomeFiles">
|
|
||||||
<Array type="string"><Item>index.php</Item></Array>
|
|
||||||
</Set>
|
|
||||||
|
|
||||||
<Call name="addFilter">
|
|
||||||
<Arg>org.eclipse.jetty.ee9.fcgi.server.proxy.TryFilesFilterorg.eclipse.jetty.ee9.fcgi.server.proxy.TryFilesFilter</Arg>
|
|
||||||
<Arg>/*</Arg>
|
|
||||||
<Arg>
|
|
||||||
<Call name="of" class="java.util.EnumSet">
|
|
||||||
<Arg><Get name="REQUEST" class="jakarta.servlet.DispatcherType" /></Arg>
|
|
||||||
</Call>
|
|
||||||
</Arg>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>files</Arg>
|
|
||||||
<Arg>$path /index.php?p=$path</Arg>
|
|
||||||
</Call>
|
|
||||||
</Call>
|
|
||||||
|
|
||||||
<Call name="addServlet">
|
|
||||||
<Arg>
|
|
||||||
<New class="org.eclipse.jetty.ee9.servlet.ServletHolder">
|
|
||||||
<Arg>default</Arg>
|
|
||||||
<Arg>
|
|
||||||
<Call name="forName" class="java.lang.Class">
|
|
||||||
<Arg>org.eclipse.jetty.ee9.servlet.DefaultServlet</Arg>
|
|
||||||
</Call>
|
|
||||||
</Arg>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>dirAllowed</Arg>
|
|
||||||
<Arg>false</Arg>
|
|
||||||
</Call>
|
|
||||||
</New>
|
|
||||||
</Arg>
|
|
||||||
<Arg>/</Arg>
|
|
||||||
</Call>
|
|
||||||
|
|
||||||
<Call name="addServlet">
|
|
||||||
<Arg>org.eclipse.jetty.fcgi.server.proxy.FastCGIProxyServlet</Arg>
|
|
||||||
<Arg>*.php</Arg>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>proxyTo</Arg>
|
|
||||||
<Arg>http://localhost:9000</Arg>
|
|
||||||
</Call>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>prefix</Arg>
|
|
||||||
<Arg>/</Arg>
|
|
||||||
</Call>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>scriptRoot</Arg>
|
|
||||||
<Arg><Ref refid="root" /></Arg>
|
|
||||||
</Call>
|
|
||||||
<Call name="setInitParameter">
|
|
||||||
<Arg>scriptPattern</Arg>
|
|
||||||
<Arg>(.+?\\.php)</Arg>
|
|
||||||
</Call>
|
|
||||||
</Call>
|
|
||||||
|
|
||||||
</Configure>
|
|
||||||
|
|
||||||
----
|
|
||||||
|
|
||||||
An explanation of the above contents:
|
|
||||||
|
|
||||||
* Linne 6 specifies the WordPress installation directory, in this example `/var/www/wordpress` (as defined in the first step).
|
|
||||||
* Line 9 it is specified the context path at which WordPress will be served, in this example at the root context path `/`.
|
|
||||||
* Line 10 specifies the resource base of the context, also set to the WordPress installation directory.
|
|
||||||
This allows Jetty to serve static resources directly from the WordPress installation directory.
|
|
||||||
* Line 12 specifies the welcome file as `index.php`, so that Jetty can perform the proper redirects in case of URIs ending with the `/` character.
|
|
||||||
* Line 15 specifies the `TryFilesFilter`, a Servlet Filter that has been inspired by the http://wiki.nginx.org/HttpCoreModule#try_files[try_files] functionality offered by Nginx.
|
|
||||||
This filter tries to serve the resource from the file system first, and if the resource is not found it forwards the request as `index.php?p=$path`, which will match the proxy servlet defined below.
|
|
||||||
Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/TryFilesFilter.html[TryFilesFilter] documentation for further information.
|
|
||||||
* Line 29specifies Jetty's `DefaultServlet` to serve static content such as CSS files, JavaScript files, etc. `DefaultServlet` will serve these files by looking in the resource base of the context, defined at line 10 (see above).
|
|
||||||
* Line 47 specifies the `FastCGIProxyServlet`, a Servlet that proxies HTTP requests arriving from clients to FastCGI requests to the FastCGI server.
|
|
||||||
* Line 52 specifies the TCP address of the FastCGI server (`php-fpm`), where HTTP requests are forwarded as FastCGI requests.
|
|
||||||
* Line 60 specifies once again the WordPress installation directory, so that the `FastCGIProxyServlet` can pass this information to the FastCGI server.
|
|
||||||
* Line 64 specifies a regular expression that matches request URIs performed to this servlet, in addition to the standard URL mapping defined by Servlet at line 49.
|
|
||||||
Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServlet.html[FastCGIProxyServlet] documentation for further information.
|
|
||||||
|
|
||||||
The last step is to start Jetty (see xref:startup[]) and navigate to `http://localhost:8080` with your browser and enjoy WordPress:
|
|
||||||
|
|
||||||
[source, screen, subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
$ cd $JETTY_BASE
|
|
||||||
$ java -jar /opt/jetty/start.jar
|
|
||||||
....
|
|
||||||
|
|
||||||
[[configuring-fastcgi-http2]]
|
|
||||||
==== Configuring Jetty to Proxy HTTP/2 to FastCGI
|
|
||||||
|
|
||||||
In order to configure Jetty to listen for HTTP/2 requests from clients that are HTTP/2 enabled and forward them to the FastCGI server as FastCGI requests, you need to enable the `http2` module, which in turn will require a TLS connector and consequently a keystore to read the key material required by TLS.
|
|
||||||
|
|
||||||
Enabling the `http2` is easy; in additions to the modules you have enabled above, add the `http2` module:
|
|
||||||
|
|
||||||
[source, screen, subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
$ cd $JETTY_BASE
|
|
||||||
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2
|
|
||||||
....
|
|
||||||
|
|
||||||
The command above adds the `http2` module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
|
|
||||||
You will want to use your own keystore with your own private key and certificate for your own domain.
|
|
||||||
|
|
||||||
Remember that by adding the `http2` module, you will start two JVMs: one that reads the configuration, and one that has the ALPN boot boot jar in the boot classpath, as explained in xref:http2-configuring[].
|
|
||||||
|
|
||||||
Since now your site will run over TLS, you need to make sure that the WordPress URL is also configured so.
|
|
||||||
If you have followed the steps of the link:#configuring-fastcgi[previous section], your WordPress site is served at `http://localhost:8080`.
|
|
||||||
You will need to change that to be `https://localhost:8443` from the WordPress administration web interface, or follow the http://codex.wordpress.org/Changing_The_Site_URL[WordPress instructions] to do so without using the administration web interface.
|
|
||||||
|
|
||||||
The minimal modules required to run WordPress with Jetty on HTTP/2 are therefore: `http2`, `http`, `fcgi` and `deploy`.
|
|
||||||
These will setup a clear text connector on port 8080 for HTTP/1.1 and a TLS connector on port 8443 for HTTP/2 and HTTP/1.1.
|
|
||||||
|
|
||||||
At this point, you can start Jetty (see xref:startup[]), hit `http://localhost:8080` with your browser and enjoy WordPress via HTTP/2 using a HTTP/2 enabled browser:
|
|
||||||
|
|
||||||
[source, screen, subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
$ cd $JETTY_BASE
|
|
||||||
$ java -jar $JETTY_HOME/start.jar
|
|
||||||
....
|
|
||||||
|
|
||||||
If you don't have a HTTP/2 enabled browser, WordPress will still be available over HTTP/1.1.
|
|
||||||
|
|
@ -1,31 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[fastcgi-intro]]
|
|
||||||
=== FastCGI Introduction
|
|
||||||
|
|
||||||
FastCGI is a network protocol primarily used by a _web server_ to communicate to a __FastCGI server__.
|
|
||||||
FastCGI servers are typically used to serve web content generated by dynamic web languages, primarily http://www.php.net/[PHP], but also Python, Ruby, Perl and others.
|
|
||||||
|
|
||||||
Web servers that supports FastCGI are, among others, http://httpd.apache.org/[Apache], http://nginx.org/[Nginx], and Jetty.
|
|
||||||
Web servers typically act as proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
|
|
||||||
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
|
|
||||||
The web content is then formatted into a FastCGI response that is returned to the web server, which converts it to a HTTP response that is then returned to the client.
|
|
||||||
|
|
||||||
The most well known FastCGI server is the http://php-fpm.org/[PHP FastCGI Process Manager], or `php-fpm`.
|
|
||||||
In the following we will assume that `php-fpm` is used as FastCGI server.
|
|
||||||
|
|
||||||
Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
|
|
||||||
This allows users to leverage Jetty features such as HTTP/2, the unique support that Jetty provides for HTTP/2 Push, Jetty's scalability, and of course Jetty's native support for Java Web Standards such as Servlets, JSPs, etc.
|
|
||||||
|
|
||||||
With such configuration, users can not only deploy their Java Web Applications in Jetty, but also serve their http://wordpress.com/[WordPress] site or blog or their https://drupal.org/[Drupal] site without having to install and manage multiple web servers.
|
|
||||||
|
|
@ -1,17 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[http2]]
|
|
||||||
== HTTP/2
|
|
||||||
|
|
||||||
include::configuring-push.adoc[]
|
|
||||||
|
|
@ -1,64 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[http2-configuring-push]]
|
|
||||||
=== Configuring HTTP/2 Push
|
|
||||||
|
|
||||||
HTTP/2 Push is a spec deprecated mechanism that allows the server to send multiple resources to the client for a single client request.
|
|
||||||
This will reduce the amount of round-trips necessary to retrieve all the resources that make up a web page and can significantly improve the page load time.
|
|
||||||
|
|
||||||
HTTP/2 Push can be automated in your application by configuring a link:{JDURL}/org/eclipse/jetty/servlets/PushCacheFilter.html[`PushCacheFilter`] in the `web.xml`, in this way:
|
|
||||||
|
|
||||||
[source, xml, subs="{sub-order}"]
|
|
||||||
----
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<web-app
|
|
||||||
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
|
|
||||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
||||||
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
|
|
||||||
metadata-complete="true"
|
|
||||||
version="3.1">
|
|
||||||
|
|
||||||
...
|
|
||||||
<filter>
|
|
||||||
<filter-name>PushFilter</filter-name>
|
|
||||||
<filter-class>org.eclipse.jetty.ee9.servlets.PushCacheFilter</filter-class>
|
|
||||||
<async-supported>true</async-supported>
|
|
||||||
</filter>
|
|
||||||
<filter-mapping>
|
|
||||||
<filter-name>PushFilter</filter-name>
|
|
||||||
<url-pattern>/*</url-pattern>
|
|
||||||
</filter-mapping>
|
|
||||||
...
|
|
||||||
|
|
||||||
</web-app>
|
|
||||||
----
|
|
||||||
|
|
||||||
`PushCacheFilter` analyzes the HTTP requests for resources that arrive to your web application.
|
|
||||||
Some of these requests contain the HTTP `Referer` header that points to a resource that has been requested previously.
|
|
||||||
|
|
||||||
This allows the `PushCacheFilter` to organize resources in a tree, for example a root `index.html` resource having two children resources, `styles.css` and `application.js`, and `styles.css` having a child resource, `background.png`.
|
|
||||||
The root resource is called the _primary_ resource, while descendant resources are called _secondary_ resources.
|
|
||||||
|
|
||||||
The resource tree is built using a time window so that when a root resource is requested, only subsequent requests that are made within the time window will be added to the resource tree.
|
|
||||||
The resource tree can also be limited in size so that the number of secondary resources associated to a primary resource is limited.
|
|
||||||
|
|
||||||
By default, only the resource _path_ (without the _query_ string) is used to associate secondary resources to the primary resource, but you can configure `PushCacheFilter` to take the query string into account.
|
|
||||||
|
|
||||||
`PushCacheFilter` can be configured with the following `init-params`:
|
|
||||||
|
|
||||||
* `associatePeriod`: the time window, in milliseconds, within which a request for a secondary resource will be associated to a primary resource; defaults to 4000 ms
|
|
||||||
* `maxAssociations`: the max number of secondary resources that may be associated to a primary resource; defaults to 16
|
|
||||||
* `hosts`: a comma separated list of hosts that are allowed in the `Referer` header; defaults to the host in the `Host` header
|
|
||||||
* `ports`: a comma separated list of ports that are allowed in the `Referer` header; defaults to the port in the `Host` header
|
|
||||||
* `useQueryInKey`: a boolean indicating whether the query string of the request should be considered when associating secondary resources to primary resources; defaults to `false`
|
|
||||||
|
|
@ -1,29 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[jmx-chapter]]
|
|
||||||
== Java Management Extensions (JMX)
|
|
||||||
|
|
||||||
|
|
||||||
The http://java.sun.com/products/JavaManagement/[Java Management Extensions (JMX) API] is a standard API for managing and monitoring resources such as applications, devices, services, and the Java virtual machine.
|
|
||||||
|
|
||||||
Typical uses of the JMX technology include:
|
|
||||||
|
|
||||||
* Consulting and changing application configuration
|
|
||||||
* Accumulating and making available statistics about application behavior
|
|
||||||
* Notifying of state changes and erroneous conditions
|
|
||||||
|
|
||||||
The JMX API includes remote access, so a remote management program can interact with a running application for these purposes.
|
|
||||||
|
|
||||||
include::jetty-jmx-annotations.adoc[]
|
|
||||||
include::jetty-jconsole.adoc[]
|
|
||||||
|
|
@ -1,113 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[jetty-jconsole]]
|
|
||||||
=== Managing Jetty with JConsole and JMC
|
|
||||||
|
|
||||||
JConsole and the Java Mission Control (JMX) are graphical tools; they allow you to remotely manage and monitor your server and web application status using JMX.
|
|
||||||
When following the instructions given below, please also ensure that you make any necessary changes to any anti-virus software you may be using which may prevent JConsole or JMC from running.
|
|
||||||
|
|
||||||
==== Starting Jetty Standalone
|
|
||||||
|
|
||||||
The simplest way to enable support is to add the JMX-Remote support module to your `{$jetty.base}`.
|
|
||||||
|
|
||||||
[source,screen,subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=jmx-remote, jmx
|
|
||||||
INFO: jmx-remote initialised in ${jetty.base}/start.ini
|
|
||||||
INFO: jmx initialised in ${jetty.base}/start.ini
|
|
||||||
....
|
|
||||||
|
|
||||||
Then open the `{$jetty.base}/start.ini` (or `{$jetty.base}/start.d/jmx-remote.ini`) file and edit the properties to suit your needs:
|
|
||||||
|
|
||||||
[source, screen, subs="{sub-order}"]
|
|
||||||
....
|
|
||||||
#
|
|
||||||
# Initialize module jmx-remote
|
|
||||||
#
|
|
||||||
--module=jmx-remote
|
|
||||||
## JMX Configuration
|
|
||||||
## Enable for an open port accessible by remote machines
|
|
||||||
jetty.jmxrmihost=localhost
|
|
||||||
jetty.jmxrmiport=1099
|
|
||||||
....
|
|
||||||
|
|
||||||
[[jetty-jconsole-monitoring]]
|
|
||||||
==== Monitoring Jetty with JConsole
|
|
||||||
|
|
||||||
To monitor Jetty's server status with JConsole, start Jetty and then start JConsole by typing `jconsole` on the command line.
|
|
||||||
|
|
||||||
===== Connecting to your server process
|
|
||||||
|
|
||||||
After you start Jetty, you will see a dialog box in JConsole with a list of running processes to which you can connect.
|
|
||||||
It should look something like so:
|
|
||||||
|
|
||||||
image:jconsole1.jpg[image,width=576]
|
|
||||||
|
|
||||||
____
|
|
||||||
[IMPORTANT]
|
|
||||||
If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
|
|
||||||
This forces JConsole to refresh the list, and recognize your newly-started Jetty process.
|
|
||||||
____
|
|
||||||
|
|
||||||
Select the start.jar entry and click the "Connect" button.
|
|
||||||
A new JConsole window opens:
|
|
||||||
|
|
||||||
image:jconsole2.jpg[image,width=576]
|
|
||||||
|
|
||||||
From this window you can monitor memory usage, thread usage, classloading and VM statistics.
|
|
||||||
You can also perform operations such as a manual garbage collect.
|
|
||||||
JConsole is an extremely powerful and useful tool.
|
|
||||||
|
|
||||||
==== Managing Jetty Objects with JConsole
|
|
||||||
|
|
||||||
The MBean tab of JConsole allows access to managed objects within the Java application, including MBeans the JVM provides.
|
|
||||||
If you also want to interact with the Jetty JMX implementation via JConsole, you need to start Jetty JMX in a form that JConsole can access.
|
|
||||||
See xref:using-jmx[] for more information.
|
|
||||||
|
|
||||||
image:jconsole3.png[image,width=576]
|
|
||||||
|
|
||||||
[[jetty-jmc-monitoring]]
|
|
||||||
==== Monitoring Jetty with JMC
|
|
||||||
|
|
||||||
To monitor Jetty's server status with JMC, start Jetty and then start JMC by typing `jmc` on the command line.
|
|
||||||
|
|
||||||
===== Connecting to your server process
|
|
||||||
|
|
||||||
After you start Jetty, you will see a dialog box in JMC with a list of running processes to which you can connect.
|
|
||||||
It should look something like so:
|
|
||||||
|
|
||||||
image:jmc1.png[image,width=576]
|
|
||||||
|
|
||||||
____
|
|
||||||
[IMPORTANT]
|
|
||||||
If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
|
|
||||||
This forces JMC to refresh the list, and recognize your newly-started Jetty process.
|
|
||||||
____
|
|
||||||
|
|
||||||
Double-click the start.jar entry or right-click the start.jar entry and select "Start JMX Console".
|
|
||||||
A new JMC window opens on the right:
|
|
||||||
|
|
||||||
image:jmc2.png[image,width=576]
|
|
||||||
|
|
||||||
From this window you can monitor memory usage, thread usage, classloading and VM statistics.
|
|
||||||
You can also perform operations such as a manual garbage collect.
|
|
||||||
JMC is an extremely powerful and useful tool.
|
|
||||||
|
|
||||||
==== Managing Jetty Objects with JConsole
|
|
||||||
|
|
||||||
The MBean tab of JMC allows access to managed objects within the Java application, including MBeans the JVM provides.
|
|
||||||
If you also want to interact with the Jetty JMX implementation via JMC, you need to start Jetty JMX in a form that JMC can access.
|
|
||||||
See xref:using-jmx[] for more information.
|
|
||||||
|
|
||||||
image:jmc3.png[image,width=576]
|
|
||||||
|
|
@ -1,135 +0,0 @@
|
||||||
//
|
|
||||||
// ========================================================================
|
|
||||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
|
||||||
//
|
|
||||||
// This program and the accompanying materials are made available under the
|
|
||||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
||||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
|
||||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
|
||||||
//
|
|
||||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
|
||||||
// ========================================================================
|
|
||||||
//
|
|
||||||
|
|
||||||
[[jetty-jmx-annotations]]
|
|
||||||
=== Jetty JMX Annotations
|
|
||||||
|
|
||||||
When the `jetty-jmx` libraries are present on startup and the wiring is enabled for exposing Jetty MBeans to JMX, there are three annotations that govern when and how MBeans are created and exposed.
|
|
||||||
|
|
||||||
[[jmx-annotation-introspection]]
|
|
||||||
==== Annotation Introspection
|
|
||||||
|
|
||||||
When JMX is configured and enabled in Jetty, any time an object is registered with the Server it is introspected as a potential MBean to be exposed.
|
|
||||||
This introspection proceeds as follows assuming the class is named `com.acme.Foo`:
|
|
||||||
|
|
||||||
1. All influences for `com.acme.Foo` determined.
|
|
||||||
These include each class in the chain of super classes, and by convention each of these classes following a form of `com.acme.jmx.FooMBean`.
|
|
||||||
All super classes and their corresponding MBean representations are then used in the next step.
|
|
||||||
2. Each potential influencing class is checked for the `@ManagedObject` annotation.
|
|
||||||
Should this annotation exist at any point in the chain of influencers then an MBran is created with the description of the version `@ManagedObject` discovered.
|
|
||||||
3. Once a MBean has been created for an object then each potential influencing object is introspected for `@ManagedAttribute` and `@ManagedOperation` annotations and the corresponding type is exposed to the MBean.
|
|
||||||
|
|
||||||
The convention of looking for `@ManagedObject` annotations on `.jmx.ClassMBean` allows for a normal POJOs to be wrapped in an MBean without itself without requiring it being marked up with annotations.
|
|
||||||
Since the POJO is passed to these wrapped derived Mbean instances and is an internal variable then the MBean can be used to better expose a set of attributes and operations that may not have been anticipated when the original object was created.
|
|
||||||
|
|
||||||
[[jmx-managed-object]]
|
|
||||||
==== @ManagedObject
|
|
||||||
|
|
||||||
The `@ManagedObject` annotation is used on a class at the top level to indicate that it should be exposed as an MBean.
|
|
||||||
It has only one attribute to it which is used as the description of the MBean.
|
|
||||||
Should multiple `@ManagedObject` annotations be found in the chain of influence then the first description is used.
|
|
||||||
|
|
||||||
The list of attributes available are:
|
|
||||||
|
|
||||||
value::
|
|
||||||
The description of the Managed Object.
|
|
||||||
|
|
||||||
[[jmx-managed-attribute]]
|
|
||||||
==== @ManagedAttribute
|
|
||||||
|
|
||||||
The `@ManagedAttribute` annotation is used to indicate that a given method exposes a JMX attribute.
|
|
||||||
This annotation is placed always on the reader method of a given attribute.
|
|
||||||
Unless it is marked as read-only in the configuration of the annotation a corresponding setter is looked for following normal naming conventions.
|
|
||||||
For example if this annotation is on a method called `getFoo()` then a method called `setFoo()` would be looked for and if found wired automatically into the JMX attribute.
|
|
||||||
|
|
||||||
The list of attributes available are:
|
|
||||||
|
|
||||||
value::
|
|
||||||
The description of the Managed Attribute.
|
|
||||||
name::
|
|
||||||
The name of the Managed Attribute.
|
|
||||||
proxied::
|
|
||||||
Value is true if the corresponding MBean for this object contains the method of this JMX attribute in question.
|
|
||||||
readonly::
|
|
||||||
By default this value is false which means that a corresponding setter will be looked for an wired into the attribute should one be found.
|
|
||||||
Setting this to true make the JMX attribute read only.
|
|
||||||
setter::
|
|
||||||
This attribute can be used when the corresponding setter for a JMX attribute follows a non-standard naming convention and it should still be exposed as the setter for the attribute.
|
|
||||||
|
|
||||||
[[jmx-managed-operation]]
|
|
||||||
==== @ManagedOperation
|
|
||||||
|
|
||||||
The `@ManagedOperation` annotation is used to indicate that a given method should be considered a JMX operation.
|
|
||||||
|
|
||||||
The list of attributes available are:
|
|
||||||
|
|
||||||
value::
|
|
||||||
The description of the Managed Operation.
|
|
||||||
impact::
|
|
||||||
The impact of an operation.
|
|
||||||
By default this value is "UNKNOWN" and acceptable values are "ACTION", "INFO", "ACTION_INFO" and should be used according to their definitions with JMX.
|
|
||||||
proxied::
|
|
||||||
Value is true if the corresponding MBean for this object contains the method of this JMX operation in question.
|
|
||||||
|
|
||||||
[[jmx-name-annotation]]
|
|
||||||
==== @Name
|
|
||||||
|
|
||||||
A fourth annotation is often used in conjunction with the JMX annotations mentioned above.
|
|
||||||
This annotation is used to describe variables in method signatures so that when rendered into tools like JConsole it is clear what the parameters are.
|
|
||||||
For example:
|
|
||||||
|
|
||||||
The list of attributes available are:
|
|
||||||
|
|
||||||
value::
|
|
||||||
The name of the parameter.
|
|
||||||
description::
|
|
||||||
The description of the parameter.
|
|
||||||
|
|
||||||
[[jmx-annotation-example]]
|
|
||||||
==== Example
|
|
||||||
|
|
||||||
The following is an example of each of the annotations mentioned above in practice.
|
|
||||||
|
|
||||||
[source, java, subs="{sub-order}"]
|
|
||||||
----
|
|
||||||
|
|
||||||
package com.acme;
|
|
||||||
|
|
||||||
import org.eclipse.jetty.util.annotation.ManagedAttribute;
|
|
||||||
import org.eclipse.jetty.util.annotation.ManagedObject;
|
|
||||||
import org.eclipse.jetty.util.annotation.ManagedOperation;
|
|
||||||
import org.eclipse.jetty.util.annotation.Name;
|
|
||||||
|
|
||||||
@ManagedObject("Test MBean Annotations")
|
|
||||||
public class Derived extends Base implements Signature
|
|
||||||
{
|
|
||||||
String fname="Full Name";
|
|
||||||
|
|
||||||
@ManagedAttribute(value="The full name of something", name="fname")
|
|
||||||
public String getFullName()
|
|
||||||
{
|
|
||||||
return fname;
|
|
||||||
}
|
|
||||||
|
|
||||||
public void setFullName(String name)
|
|
||||||
{
|
|
||||||
fname=name;
|
|
||||||
}
|
|
||||||
|
|
||||||
@ManagedOperation("Doodle something")
|
|
||||||
public void doodle(@Name(value="doodle", description="A description of the argument") String doodle)
|
|
||||||
{
|
|
||||||
System.err.println("doodle "+doodle);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
@ -37,9 +37,10 @@ include::protocols-http2.adoc[]
|
||||||
include::protocols-http2s.adoc[]
|
include::protocols-http2s.adoc[]
|
||||||
include::protocols-http2c.adoc[]
|
include::protocols-http2c.adoc[]
|
||||||
include::protocols-http3.adoc[]
|
include::protocols-http3.adoc[]
|
||||||
|
include::protocols-websocket.adoc[]
|
||||||
|
include::protocols-fcgi.adoc[]
|
||||||
include::protocols-ssl.adoc[]
|
include::protocols-ssl.adoc[]
|
||||||
include::protocols-proxy.adoc[]
|
include::protocols-proxy.adoc[]
|
||||||
include::protocols-websocket.adoc[]
|
|
||||||
|
|
||||||
// TODO: old_docs/connectors/*.adoc
|
// TODO: old_docs/connectors/*.adoc
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,156 @@
|
||||||
|
//
|
||||||
|
// ========================================================================
|
||||||
|
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||||
|
//
|
||||||
|
// This program and the accompanying materials are made available under the
|
||||||
|
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||||
|
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||||
|
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||||
|
//
|
||||||
|
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||||
|
// ========================================================================
|
||||||
|
//
|
||||||
|
|
||||||
|
[[og-protocols-fcgi]]
|
||||||
|
==== FastCGI
|
||||||
|
|
||||||
|
FastCGI is a network protocol primarily used by a _web server_ to communicate to a __FastCGI server__.
|
||||||
|
|
||||||
|
FastCGI servers are typically used to serve web content generated by dynamic web languages, primarily http://www.php.net/[PHP], but also Python, Ruby, Perl and others.
|
||||||
|
|
||||||
|
Web servers that supports FastCGI are, among others, http://httpd.apache.org/[Apache], http://nginx.org/[Nginx], and Jetty.
|
||||||
|
Web servers typically act as reverse proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
|
||||||
|
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
|
||||||
|
The web content is then formatted into a FastCGI response that is returned to the web server, which converts it to an HTTP response that is then returned to the client.
|
||||||
|
|
||||||
|
The most well known FastCGI server is the http://php-fpm.org/[PHP FastCGI Process Manager], or `php-fpm`.
|
||||||
|
In the following we will assume that `php-fpm` is used as FastCGI server.
|
||||||
|
|
||||||
|
This is a diagram of what described above:
|
||||||
|
|
||||||
|
[plantuml]
|
||||||
|
----
|
||||||
|
skinparam backgroundColor transparent
|
||||||
|
skinparam monochrome true
|
||||||
|
skinparam shadowing false
|
||||||
|
|
||||||
|
Browser -> Jetty : GET /path (HTTP)
|
||||||
|
Jetty -> "php-fpm" : GET /path (FastCGI)
|
||||||
|
"php-fpm" -> PHP : spawn PHP interpreter
|
||||||
|
PHP -> "index.php" : execute PHP script
|
||||||
|
"index.php" -> "php-fpm" : HTML
|
||||||
|
"php-fpm" -> Jetty : 200 OK + HTML (FastCGI)
|
||||||
|
Jetty -> Browser : 200 OK + HTML (HTTP)
|
||||||
|
|
||||||
|
----
|
||||||
|
|
||||||
|
Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
|
||||||
|
This allows users to leverage Jetty features such as the support for HTTP/1.1, HTTP/2 and HTTP/3, Jetty's scalability, and of course Jetty's native support for Java Web Standards such as Servlets, JSPs, etc.
|
||||||
|
|
||||||
|
With such configuration, users can not only deploy their Java Web Applications in Jetty, but also serve their http://wordpress.com/[WordPress] site or blog or their https://drupal.org/[Drupal] site without having to install and manage multiple web servers.
|
||||||
|
|
||||||
|
[[og-protocols-fcgi-configure]]
|
||||||
|
===== Configuring WordPress
|
||||||
|
|
||||||
|
This section explains how to configure Jetty to serve your link:https://wordpress.com/[WordPress] site.
|
||||||
|
|
||||||
|
The prerequisites are:
|
||||||
|
|
||||||
|
* Have `php-fpm` installed on your server host, and configured to listen either on a Unix-Domain socket (such as `/run/php/php-fpm.sock`), or on a TCP socket (such as `localhost:9000`).
|
||||||
|
* Have WordPress installed on your server host, for example under `/var/www/wordpress`.
|
||||||
|
For more information about how to install WordPress and the necessary PHP modules, please refer to the link:https://wordpress.org/support/article/how-to-install-wordpress/[WordPress Installation Guide].
|
||||||
|
|
||||||
|
Then, the xref:og-protocols-https[secure HTTP] and/or the xref:og-protocols-http2[secure HTTP/2] Jetty modules should be enabled to allow browsers to connect to Jetty.
|
||||||
|
|
||||||
|
Lastly, enable the `fcgi-proxy` module to provide FastCGI support (to convert HTTP requests from browsers to FastCGI for `php-fpm` and vice versa), and the `core-deploy` module to deploy your WordPress web application as a xref:og-deploy-jetty[Jetty context XML file].
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
----
|
||||||
|
$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,https,fcgi-proxy,core-deploy
|
||||||
|
----
|
||||||
|
|
||||||
|
TIP: The `https` Jetty module requires a KeyStore. If you do not already have one configured, you can add the `test-keystore` Jetty module to the command line above to create a KeyStore on-the-fly.
|
||||||
|
|
||||||
|
Now you can deploy a Jetty context XML file that represents your WordPress web application.
|
||||||
|
|
||||||
|
Use the following file as example, copy it as `$JETTY_BASE/webapps/wordpress.xml` and customize it as necessary:
|
||||||
|
|
||||||
|
[source,xml,options=nowrap]
|
||||||
|
----
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_10_0.dtd">
|
||||||
|
<Configure class="org.eclipse.jetty.server.handler.ContextHandler">
|
||||||
|
|
||||||
|
<New id="root" class="java.lang.String">
|
||||||
|
<Arg>/var/www/wordpress</Arg> <!--1-->
|
||||||
|
</New>
|
||||||
|
|
||||||
|
<Set name="contextPath">/</Set> <!--2-->
|
||||||
|
<Set name="baseResourceAsString"><Ref refid="root" /></Set>
|
||||||
|
|
||||||
|
<Set name="handler">
|
||||||
|
<New class="org.eclipse.jetty.server.handler.TryPathsHandler">
|
||||||
|
<Set name="originalPathAttribute">wordpress.originalPath</Set>
|
||||||
|
<Set name="originalQueryAttribute">wordpress.originalQuery</Set>
|
||||||
|
<Set name="paths">
|
||||||
|
<Call class="java.util.List" name="of">
|
||||||
|
<Arg>$path</Arg>
|
||||||
|
<Arg>/index.php</Arg>
|
||||||
|
</Call>
|
||||||
|
</Set>
|
||||||
|
|
||||||
|
<Set name="handler">
|
||||||
|
<New class="org.eclipse.jetty.server.handler.PathMappingsHandler">
|
||||||
|
<Call name="addMapping">
|
||||||
|
<Arg>
|
||||||
|
<New class="org.eclipse.jetty.http.pathmap.ServletPathSpec"><Arg>*.php</Arg></New>
|
||||||
|
</Arg>
|
||||||
|
<Arg>
|
||||||
|
<New class="org.eclipse.jetty.fcgi.proxy.FastCGIProxyHandler"> <!--3-->
|
||||||
|
<Arg>(https?)://([^/]+)(.*)</Arg> <!--4-->
|
||||||
|
<Arg>http://localhost:9000$3</Arg> <!--5-->
|
||||||
|
<Arg><Ref refid="root" /></Arg>
|
||||||
|
|
||||||
|
<Set name="originalPathAttribute">wordpress.originalPath</Set>
|
||||||
|
<Set name="originalQueryAttribute">wordpress.originalQuery</Set>
|
||||||
|
<Set name="scriptPattern"><Call class="java.util.regex.Pattern" name="compile"><Arg>(.+?\\.php)</Arg></Call></Set>
|
||||||
|
<Set name="fastCGISecure">true</Set>
|
||||||
|
<Set name="unixDomainPath"><Call class="java.nio.file.Path" name="of"><Arg>/run/php/php-fpm.sock</Arg></Call></Set> <!--6-->
|
||||||
|
</New>
|
||||||
|
</Arg>
|
||||||
|
</Call>
|
||||||
|
<Call name="addMapping">
|
||||||
|
<Arg>
|
||||||
|
<New class="org.eclipse.jetty.http.pathmap.ServletPathSpec"><Arg>/</Arg></New>
|
||||||
|
</Arg>
|
||||||
|
<Arg>
|
||||||
|
<New class="org.eclipse.jetty.server.handler.ResourceHandler"> <!--7-->
|
||||||
|
<Set name="welcomeFiles"><Call class="java.util.List" name="of"><Arg>/index.php</Arg></Call></Set>
|
||||||
|
<Set name="welcomeMode"><Call class="org.eclipse.jetty.server.ResourceService$WelcomeMode" name="valueOf"><Arg>REHANDLE</Arg></Call></Set>
|
||||||
|
<Set name="dirAllowed">false</Set>
|
||||||
|
</New>
|
||||||
|
</Arg>
|
||||||
|
</Call>
|
||||||
|
</New>
|
||||||
|
</Set>
|
||||||
|
</New>
|
||||||
|
</Set>
|
||||||
|
|
||||||
|
</Configure>
|
||||||
|
----
|
||||||
|
<1> Specify the WordPress installation path.
|
||||||
|
<2> Specify the context path of your web application.
|
||||||
|
<3> The `FastCGIProxyHandler` forwards requests whose URI path matches `+*.php+` to `php-fpm`.
|
||||||
|
<4> The client URI regex pattern to match.
|
||||||
|
<5> The URI used to forward the request to `php-fpm`, where `+$3+` is the 3rd matching group of the client URI regex pattern (int this example, the client URI path).
|
||||||
|
If `php-fpm` is configured to listen on a TCP socket, the host and port must match the listening TCP socket.
|
||||||
|
If `php-fpm` is configured to listen on a Unix-Domain socket, the host and port values are ignored but must be present.
|
||||||
|
<6> If `php-fpm` is configured to listen on a Unix-Domain socket, specify the Unix-Domain socket path, otherwise omit this line.
|
||||||
|
<7> The `ResourceHandler` serves static files from WordPress, such as `+*.css+`, `+*.js+` and image files.
|
||||||
|
|
||||||
|
Now you can start Jetty and navigate to `+http://localhost:8080+` with your browser to enjoy WordPress:
|
||||||
|
|
||||||
|
----
|
||||||
|
$ java -jar $JETTY_HOME/start.jar
|
||||||
|
----
|
||||||
Loading…
Reference in New Issue