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-http2c.adoc[]
|
||||
include::protocols-http3.adoc[]
|
||||
include::protocols-websocket.adoc[]
|
||||
include::protocols-fcgi.adoc[]
|
||||
include::protocols-ssl.adoc[]
|
||||
include::protocols-proxy.adoc[]
|
||||
include::protocols-websocket.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
|
||||
----
|
||||
|
|
@ -43,7 +43,7 @@ Apache HTTP Server and Nginx can only speak HTTP/1.1 to backend servers such as
|
|||
====
|
||||
|
||||
In these setups, typically the proxy performs TLS offloading, and the communication with backend servers happens in clear-text.
|
||||
It is possible, however, to configure the proxy so that all the bytes arriving from the client are tunnelled opaquely to the backend Jetty server (that therefore needs to perform the TLS offloading) and viceversa the bytes arriving from the Jetty server are tunnelled opaquely to the client.
|
||||
It is possible, however, to configure the proxy so that all the bytes arriving from the client are tunnelled opaquely to the backend Jetty server (that therefore needs to perform the TLS offloading) and vice versa the bytes arriving from the Jetty server are tunnelled opaquely to the client.
|
||||
|
||||
Also in these setups, the TCP/IP connection terminating on the Jetty servers does not originate from the client, but from the proxy, so that the remote IP address and port number may be reported incorrectly in backend server logs, or worse applications may not work because they need to be able to differentiate different clients based on the client IP address.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue