Merge pull request #1159 from WalkerWatch/issues/1139

Issue #1139 - Documented new features and misc cleanup.
This commit is contained in:
Joakim Erdfelt 2016-12-14 13:10:28 -07:00 committed by GitHub
commit b2162cb347
5 changed files with 94 additions and 219 deletions

View File

@ -69,6 +69,8 @@ When executed `start.jar` performs the following actions:
==== start.jar Command Line Options
===== Command Line Options
--help::
Obtains the current list of command line options and some basic usage help.
--version::
@ -77,8 +79,6 @@ Shows the list of server classpath entries, and prints version information found
Similar to --version, shows the server classpath.
--list-config::
Lists the resolved configuration that will start Jetty.
+
* Java environment
* Jetty environment
* JVM arguments
@ -89,6 +89,15 @@ Lists the resolved configuration that will start Jetty.
Prints the resolved command line that `start.jar` should use to start a forked instance of Jetty.
--exec::
Starts a forked instance of Jetty.
--exec-properties=<filename>::
Assign a fixed name to the file used to transfer properties to the sub process.
This allows the generated properties file to be saved and reused.
Without this option, a temporary file is used.
--commands=<filename>::
Instructs `start.jar` to use each line of the specified file as arguments on the command line.
===== Debugg and Start Logging
--debug::
Enables debugging output of the startup procedure.
+
@ -98,22 +107,55 @@ For information on logging, please see the section on <<configuring-jetty-loggin
Sends all startup output to the filename specified.
Filename is relative to `${jetty.base}`.
This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error.
===== Module Management
--list-modules::
Lists all the modules defined by the system.
Looks for module files using the link:#startup-base-and-home[normal `${jetty.base}` and `${jetty.home}` resolution logic].
Also lists enabled state based on information present on the command line, and all active startup INI files.
--list-modules=<tag>(,<tag>)*::
List modules by link:#startup-modules[tag.]
Use '*' for all tags.
Prefix a tag with '-' to exclude the tag.
The special tag "internal" is always excluded unless it is explicitly included.
--list-all-modules::
List all modules.
--module=<name>,(<name>)*::
Enables one or more modules by name (use `--list-modules` to see the list of available modules).
This enables all transitive (dependent) modules from the module system as well.
If you use this from the shell command line, it is considered a temporary effect, useful for testing out a scenario.
If you want this module to always be enabled, add this command to your `${jetty.base}/start.ini.`
--create-startd::
Creates a `${jetty.base}/start.d/` directory.
If a `${jetty.base}/start.ini` file already exists, it is copied to the `${jetty.base}/start.d` directory.
--add-to-start=<name>,(<name>)*::
Enables a module by appending lines to the `${jetty.base}/start.ini` file.
The lines that are added are provided by the module-defined INI templates.
Note: Transitive modules are also appended.
If a module contains an .ini template with properties, you can also edit these properties when activating the module.
To do this, simply list the property and its value after the `-add-to-start` command, such as in the following example:
+
[source, screen, subs="{sub-order}"]
....
$ java -jar start.jar --add-to-start=http jetty.http.port=8379 jetty.http.host=1.2.3.4
....
+
Doing this will uncomment the property in the associated .ini file and set it to the value specified.
--update-ini::
Used to update a specified property or properties that exist in an existing .ini file.
Jetty scans the command line, `${jetty.base}` and `${jetty.home}` for .ini files that have the specified property and update it accordingly.
+
[source, screen, subs="{sub-order}"]
....
$ java -jar ../start.jar --update-ini jetty.http.port=8417
ConfigSource <command-line>
ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home}
....
+
--create-startd::
Creates a `${jetty.base}/start.d/` directory.
If a `${jetty.base}/start.ini` file already exists, it is copied to the `${jetty.base}/start.d` directory.
[NOTE]
--
@ -136,6 +178,25 @@ $ dot -Tpng -o modules.png modules.dot
+
See http://graphviz.org/[graphviz.org] for details on http://graphviz.org/content/command-line-invocation[how to post-process this dotty file] into the output best suited for your needs.
--create-files::
Create any missing files that are required by initialized modules.
This may download a file from the network if the module provides a URL.
--skip-file-validation=<modulename>(,<modulename)*::
Disable the [files] section validation of content in the `${jetty.base}` directory for a specific module.
Useful for modules that have downloadable content that is being overridden with alternatives in the `${jetty.base}`` directory.
____
[CAUTION]
This advanced option is for administrators that fully understand the configuration of their `${jetty.base}` and are willing to forego some of the safety checks built into the jetty-start mechanism.
____
--approve-all-licenses::
Approve all license questions.
Useful for enabling modules from a script that does not require user interaction.
===== Startup / Shutdown Command Line
--stop::
Sends a stop signal to the running Jetty instance.
+

View File

@ -253,7 +253,7 @@ If there are multiple entries in the `[tags]` section, it sorts by the first tag
____
[NOTE]
By default, the `--list-modules` command line argument shows all modules that do not include `internal` in the `[tags]` section of the associated `.mod` file.
If you would like to see *all* modules, use `--list-modules=*`
If you would like to see *all* modules, use `--list-all-modules`
____
Here's an example of the `--list-modules` command:

View File

@ -255,187 +255,11 @@ First notice the separation of `${jetty.base}` and `${jetty.home}`.
Notice that you have `--module=<name>` here and there; you have wrapped up the goal of a module (libs, configuration XMLs, and properties) into a single unit, with dependencies on other modules.
You can see the list of modules:
You can see the list of modules by appending `--list-modules` to the command line.
[source, screen, subs="{sub-order}"]
....
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-modules
Jetty All Available Modules:
----------------------------
Module: annotations
LIB: lib/jetty-annotations-${jetty.version}.jar
LIB: lib/annotations/*.jar
XML: etc/jetty-annotations.xml
depends: [plus]
Module: client
LIB: lib/jetty-client-${jetty.version}.jar
depends: []
Module: debug
XML: etc/jetty-debug.xml
depends: [server]
Module: deploy
LIB: lib/jetty-deploy-${jetty.version}.jar
XML: etc/jetty-deploy.xml
depends: [webapp]
enabled: ${jetty.base}/start.ini
Module: ext
LIB: lib/ext/*.jar
depends: []
Module: http
XML: etc/jetty-http.xml
depends: [server]
enabled: ${jetty.base}/start.ini
Module: http2
LIB: lib/http2/*.jar
XML: etc/jetty-http2.xml
depends: [ssl, alpn]
Module: http2c
LIB: lib/http2/*.jar
XML: etc/jetty-http2c.xml
depends: [http]
Module: https
XML: etc/jetty-https.xml
depends: [ssl]
Module: ipaccess
XML: etc/jetty-ipaccess.xml
depends: [server]
Module: jaas
LIB: lib/jetty-jaas-${jetty.version}.jar
XML: etc/jetty-jaas.xml
depends: [server]
Module: jaspi
LIB: lib/jetty-jaspi-${jetty.version}.jar
LIB: lib/jaspi/*.jar
depends: [security]
Module: jmx
LIB: lib/jetty-jmx-${jetty.version}.jar
XML: etc/jetty-jmx.xml
depends: []
Module: jndi
LIB: lib/jetty-jndi-${jetty.version}.jar
LIB: lib/jndi/*.jar
depends: [server]
Module: jsp
LIB: lib/jsp/*.jar
depends: [servlet]
Module: jvm
depends: []
Module: logging
XML: etc/jetty-logging.xml
depends: []
Module: lowresources
XML: etc/jetty-lowresources.xml
depends: [server]
Module: monitor
LIB: lib/jetty-monitor-${jetty.version}.jar
XML: etc/jetty-monitor.xml
depends: [client, server]
Module: npn
depends: []
Module: plus
LIB: lib/jetty-plus-${jetty.version}.jar
XML: etc/jetty-plus.xml
depends: [server, security, jndi]
Module: proxy
LIB: lib/jetty-proxy-${jetty.version}.jar
XML: etc/jetty-proxy.xml
depends: [client, server]
Module: requestlog
XML: etc/jetty-requestlog.xml
depends: [server]
Module: resources
LIB: resources
depends: []
Module: rewrite
LIB: lib/jetty-rewrite-${jetty.version}.jar
XML: etc/jetty-rewrite.xml
depends: [server]
Module: security
LIB: lib/jetty-security-${jetty.version}.jar
depends: [server]
Module: server
LIB: lib/servlet-api-3.1.jar
LIB: lib/jetty-schemas-3.1.jar
LIB: lib/jetty-http-${jetty.version}.jar
LIB: lib/jetty-continuation-${jetty.version}.jar
LIB: lib/jetty-server-${jetty.version}.jar
LIB: lib/jetty-xml-${jetty.version}.jar
LIB: lib/jetty-util-${jetty.version}.jar
LIB: lib/jetty-io-${jetty.version}.jar
XML: etc/jetty.xml
depends: []
enabled: ${jetty.base}/start.ini
Module: servlet
LIB: lib/jetty-servlet-${jetty.version}.jar
depends: [server]
Module: servlets
LIB: lib/jetty-servlets-${jetty.version}.jar
depends: [servlet]
Module: setuid
LIB: lib/setuid/jetty-setuid-java-1.0.1.jar
XML: etc/jetty-setuid.xml
depends: [server]
Module: ssl
XML: etc/jetty-ssl.xml
depends: [server]
enabled: ${jetty.base}/start.ini
Module: stats
XML: etc/jetty-stats.xml
depends: [server]
Module: webapp
LIB: lib/jetty-webapp-${jetty.version}.jar
depends: [servlet]
Module: websocket
LIB: lib/websocket/*.jar
depends: [annotations]
Module: xinetd
XML: etc/jetty-xinetd.xml
depends: [server]
Jetty Active Module Tree:
-------------------------
+ Module: server [enabled]
+ Module: http [enabled]
+ Module: servlet [transitive]
+ Module: ssl [enabled]
+ Module: webapp [transitive]
+ Module: deploy [enabled]
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --list-modules
....
These are the modules by name, the libraries they bring in, the XML configurations they use, the other modules they depend on (even optional ones), and if the module is in use, where it was enabled.
@ -458,6 +282,7 @@ ____
Notice that your `${jetty.base}/start.ini` has no references to the XML files.
That's because the module system and its graph of dependencies now dictate all of the XML files, and their load order.
Much more information on modules can be found in the section on link:#startup-modules[Managing Startup Modules.]
[[parameterizing]]
===== Parameters

View File

@ -17,19 +17,19 @@
[[quickstart-config-how]]
=== How to Configure Jetty
To understand Jetty configuration, you need to understand the "How" and the "What".
This section covers how to configure Jetty in terms of what mechanisms exist to perform configuration.
To understand Jetty configuration, you need to understand the "How" and the "What".
This section covers how to configure Jetty in terms of what mechanisms exist to perform configuration.
The link:#quickstart-config-what[next section] gives an overview of the action components and fields that you can configure with these mechanisms.
==== Jetty POJO Configuration
The core components of Jetty are Plain Old Java Objects (http://en.wikipedia.org/wiki/Plain_Old_Java_Object[POJOs])
The process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs.
The process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs.
This can be achieved by:
* Writing Java code to directly instantiate and assemble Jetty objects.
* Writing Java code to directly instantiate and assemble Jetty objects.
This is referred to as xref:embedding-jetty[].
* Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects.
* Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects.
The `etc/jetty.xml` file is the main Jetty XML configuration file, but there are many other `etc/jetty-__feature__.xml` files included in the Jetty distribution.
* Using a third party http://en.wikipedia.org/wiki/Inversion_of_Control[IoC] framework like http://en.wikipedia.org/wiki/Spring_Framework[Spring], to instantiate and assemble Jetty objects as Spring beans.
@ -40,9 +40,9 @@ Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API
The Jetty distribution uses the following configuration files to instantiate, inject and start server via the `start.jar` mechanism.
`ini` files::
The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments.
The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments.
Arguments may be:
* Module activations in the form `--module=name`
* Properties in the form of `name=value`, used to parameterize Jetty IoC XML
* XML files in Jetty IoC (or Spring) XML format
@ -53,31 +53,31 @@ The Jetty distribution uses the following configuration files to instantiate, in
____
[NOTE]
--
As of Jetty 9 it is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
It is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
--
____
`mod` files::
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
Each `mod` file defines:
* Module dependencies for ordering and activation
* The libraries needed by the module to be added to the classpath
* The XML files needed by the module to be added to the effective command line
* Files needed by the activated module
* A template `ini` file to be used when activating the `--add-to-start=name` option
+
Typically module files are rarely edited and only then for significant structural changes.
The `*.mod` files are normally located in `$JETTY_HOME/modules/`, but extra or edited modules may be added to `$JETTY_BASE/module`.
+
Typically module files are rarely edited and only then for significant structural changes.
The `*.mod` files are normally located in `$JETTY_HOME/modules/`, but extra or edited modules may be added to `$JETTY_BASE/module`.
If module changes are required, it is best practice to copy the particular `*.mod` file from `$JETTY_HOME/modules/` to `$JETTY_BASE/modules/` before being modified.
XML files::
XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format are listed either on the command line, in `ini` files, or are added to the effective command line by a module definition.
The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts.
XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format are listed either on the command line, in `ini` files, or are added to the effective command line by a module definition.
The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts.
Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding `ini` files.
XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`.
XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`.
*Note* If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified.
Below is an illustration of how the various Jetty configuration files (`ini`, `mod` and XML) are related:
image:images/Jetty_Configuration_File_Relationships.png[image,width=693]
@ -87,23 +87,23 @@ image:images/Jetty_Configuration_File_Relationships.png[image,width=693]
In addition to the configuration files described above, the configuration of the server can use the following file types:
Context XML files::
Any XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format that is discovered in the `/webapps` directory are used by the deploy module to instantiate and inject `HttpContext` instances to create a specific context.
Any XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format that is discovered in the `/webapps` directory are used by the deploy module to instantiate and inject `HttpContext` instances to create a specific context.
These may be standard web applications or bespoke contexts created from special purpose handlers.
web.xml::
The http://en.wikipedia.org/wiki/Servlet[Servlet] Specification defines the http://en.wikipedia.org/wiki/Web.xml[`web.xml`] deployment descriptor that defines and configures the filters, servlets and resources a http://en.wikipedia.org/wiki/Web_application[web application] uses.
The http://en.wikipedia.org/wiki/Servlet[Servlet] Specification defines the http://en.wikipedia.org/wiki/Web.xml[`web.xml`] deployment descriptor that defines and configures the filters, servlets and resources a http://en.wikipedia.org/wiki/Web_application[web application] uses.
The Jetty `WebAppContext` component uses this XML format to:
* Set up the default configuration of a web application context.
* Interpret the application-specific configuration supplied with a web application in the `WEB-INF/web.xml` file.
* Interpret descriptor fragments included in the `META-INF` directory of Jar files within `WEB-INF/lib.`
+
Normally the `web.xml` file for a web application is found in the `WEB-INF/web.xml` location within the war file/directory or as `web.xml` fragments with `.jar` files found in `WEB-INF/lib`.
Normally the `web.xml` file for a web application is found in the `WEB-INF/web.xml` location within the war file/directory or as `web.xml` fragments with `.jar` files found in `WEB-INF/lib`.
Jetty also supports multiple `web.xml` files so that a default descriptor may be applied before `WEB-INF/web.xml` (typically set to `etc/webdefault.xml` by the deploy module) and an override descriptor may be applied after `WEB-INF/web.xml` (typically set by a context XML file see `test.xml`)
Property Files::
Standard http://en.wikipedia.org/wiki/Java_properties[Java property files] are also used for Jetty configuration in several ways:
+
+
* To parameterize Jetty IoC XML via the use of the `Property` element.
* To configure the default logging mechanism (`StdErrLog`). Other logging frameworks can be utilized and also use property files (for example, `log4j`).
* As a simple database for login usernames and credentials.
@ -124,5 +124,5 @@ link:#jetty-xml-syntax[Jetty IoC XML format] allows you to instantiate and confi
include::{SRCDIR}/examples/embedded/src/main/resources/exampleserver.xml[]
----
//In practice, most commonly used Jetty features have XML files that are included in the standard distribution in the `/etc` directory.
//In practice, most commonly used Jetty features have XML files that are included in the standard distribution in the `/etc` directory.
//Thus configuring Jetty is often a matter of just editing existing XML files and altering the property values injected into them.

View File

@ -99,18 +99,7 @@ Module Management:
If the ini template contains properties, these may be
amended in the generated file by specifying those
properties on the command line.
FS.ensureDirectoryExists(startDir);
FS.ensureDirectoryExists(startDir);
modules that the specified module depends on are also
.
If the directory ${jetty.base}/start.d
exists then <modulename>.ini files are created within
that directory, otherwise then enabling configuration
is appended to the ${jetty.base}/start.ini file.
Lines that are added come from the ini template that
the module itself maintains.
Note: not all modules have ini templates and thus may
be transitively enabled and not explicitly enabled in
a ini file.