Chapter 9 clean up and fixes Part I
Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch
parent
83d99159f6
commit
00551d73b2
|
|
@ -18,10 +18,10 @@
|
|||
== Starting Jetty
|
||||
|
||||
include::startup-overview.adoc[]
|
||||
include::start-jar.adoc[]
|
||||
include::startup-base-vs-home.adoc[]
|
||||
include::startup-xml-config.adoc[]
|
||||
include::startup-classpath.adoc[]
|
||||
include::startup-modules.adoc[]
|
||||
include::startup-base-vs-home.adoc[]
|
||||
include::start-jar.adoc[]
|
||||
include::startup-unix-service.adoc[]
|
||||
include::startup-windows-service.adoc[]
|
||||
include::startup-windows-service.adoc[]
|
||||
|
|
|
|||
|
|
@ -20,13 +20,13 @@
|
|||
|
||||
Java Environment:
|
||||
-----------------
|
||||
java.home = /lib/jvm/jdk-8u45/jre
|
||||
java.home = /lib/jvm/jdk-8u92/jre
|
||||
java.vm.vendor = Oracle Corporation
|
||||
java.vm.version = 25.45-b02
|
||||
java.vm.version = 25.45-b14
|
||||
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
|
||||
java.vm.info = mixed mode
|
||||
java.runtime.name = Java(TM) SE Runtime Environment
|
||||
java.runtime.version = 1.8.0_45-b14
|
||||
java.runtime.version = 1.8.0_92-b14
|
||||
java.io.tmpdir = /tmp
|
||||
user.dir = /home/jetty/mybase
|
||||
user.language = en
|
||||
|
|
|
|||
|
|
@ -16,6 +16,14 @@
|
|||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[jetty]$ mkdir mybase
|
||||
[jetty]$ cd mybase
|
||||
[mybase]$ ls -la
|
||||
total 0
|
||||
drwxr-xr-x 2 staff staff 68 Jul 12 17:29 .
|
||||
drwxr-xr-x 20 staff staff 680 Jul 12 17:29 ..
|
||||
|
||||
[mybase]$ java -jar $JETTY_HOME/start.jar
|
||||
WARNING: Nothing to start, exiting ...
|
||||
|
||||
Usage: java -jar start.jar [options] [properties] [configs]
|
||||
|
|
|
|||
|
|
@ -17,9 +17,7 @@
|
|||
[[start-jar]]
|
||||
=== Using start.jar
|
||||
|
||||
The most basic way of starting the Jetty standalone server is to execute
|
||||
the `start.jar`, which is a bootstrap for starting Jetty with the
|
||||
configuration you want.
|
||||
The most basic way of starting the Jetty standalone server is to execute the `start.jar`, which is a bootstrap for starting Jetty with the configuration you want.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -28,153 +26,114 @@ configuration you want.
|
|||
...
|
||||
....
|
||||
|
||||
Jetty is a highly modularized web server container. Very little is
|
||||
mandatory and required, and most components are optional; you enable or
|
||||
disable them according to the needs of your environment.
|
||||
Jetty is a highly modularized web server container.
|
||||
Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.
|
||||
|
||||
At its most basic, you configure Jetty from two elements:
|
||||
|
||||
1. A set of libraries and directories that make up the server
|
||||
classpath.
|
||||
2. A set of Jetty XML configuration files (IoC style) that establish
|
||||
how to build the Jetty server and its components.
|
||||
1. A set of libraries and directories that make up the server classpath.
|
||||
2. A set of Jetty XML configuration files (IoC style) that establish how to build the Jetty server and its components.
|
||||
|
||||
Starting with Jetty 9.1 you have more options on how to configure Jetty
|
||||
(these are merely syntactic sugar that eventually resolve into the two
|
||||
basic configuration components).
|
||||
Instead of editing these directly, Jetty 9.1 introduced more options on how to configure Jetty (these are merely syntactic sugar that eventually resolve into the two basic configuration components).
|
||||
|
||||
Jetty 9.1 Startup Features include:
|
||||
|
||||
* A separation of the Jetty distribution binaries in `${jetty.home}` and
|
||||
the environment specific configurations (and binaries) found in
|
||||
`${jetty.base}` (detailed in
|
||||
link:#startup-jetty-base-and-jetty-home[Managing Jetty Base and Jetty
|
||||
Home.])
|
||||
* You can enable a set of libraries and XML configuration files via the
|
||||
newly introduced link:#startup-modules[module system.]
|
||||
* All of the pre-built XML configuration files shipped in Jetty are now
|
||||
parameterized with properties that you can specify in your
|
||||
`${jetty.base}/start.ini` (demonstrated in
|
||||
link:#quick-start-configure[Quick Start Configuration]).
|
||||
+
|
||||
There is no longer a
|
||||
* A separation of the Jetty distribution binaries in `${jetty.home}` and the environment specific configurations (and binaries) found in `${jetty.base}` (detailed in link:#startup-jetty-base-and-jetty-home[Managing Jetty Base and Jetty Home.])
|
||||
* You can enable a set of libraries and XML configuration files via the newly introduced link:#startup-modules[module system.]
|
||||
* All of the pre-built XML configuration files shipped in Jetty are now parameterized with properties that you can specify in your `${jetty.base}/start.ini` (demonstrated in link:#quick-start-configure[Quick Start Configuration]).
|
||||
|
||||
These are powerful new features, made to support a variety of styles of
|
||||
configuring Jetty, from a simple property based configuration, to
|
||||
handling multiple installations on a server, to customized stacks of
|
||||
technology on top of Jetty, and even the classic, custom XML
|
||||
configurations of old.
|
||||
These are powerful new features, made to support a variety of styles of configuring Jetty, from a simple property based configuration, to handling multiple installations on a server, to customized stacks of technology on top of Jetty, and even the classic, custom XML configurations of old.
|
||||
|
||||
For example, if you use the `${jetty.base}` concepts properly, you can
|
||||
upgrade the Jetty distribution without having to remake your entire tree
|
||||
of modifications to Jetty. Simply separate out your specific
|
||||
modifications to the `${jetty.base}`, and in the future, just upgrade
|
||||
your `${jetty.home}` directory with a new Jetty distribution.
|
||||
For example, if you use the `${jetty.base}` concepts properly, you can upgrade the Jetty distribution without having to remake your entire tree of modifications to Jetty.
|
||||
Simply separate out your specific modifications to the `${jetty.base}`, and in the future, just upgrade your `${jetty.home}` directory with a new Jetty distribution.
|
||||
|
||||
* Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as
|
||||
command line arguments.
|
||||
[[executing-startjar]]
|
||||
|
||||
==== Executing start.jar
|
||||
|
||||
When executed `start.jar` performs the following actions:
|
||||
|
||||
* Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as command line arguments.
|
||||
* Loads and parses `${jetty.base}/start.ini` as command line arguments.
|
||||
* Parses actual command line arguments used to execute `start.jar`
|
||||
itself.
|
||||
* Resolves any XML configuration files, modules, and libraries using
|
||||
base vs. home resolution steps:
|
||||
* Parses actual command line arguments used to execute `start.jar` itself.
|
||||
* Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:
|
||||
1. Checks whether file exists as relative reference to `${jetty.base}.`
|
||||
2. Checks whether file exists as relative reference to `${jetty.home}.`
|
||||
3. Uses default behavior of `java.io.File.`
|
||||
+
|
||||
(Relative to `System.getProperty` ("user.dir") and then as absolute file
|
||||
system path)
|
||||
* Loads any dependent modules (merges XXNK, library, and properties
|
||||
results with active command line).
|
||||
3. Uses default behavior of `java.io.File` (Relative to `System.getProperty` ("user.dir") and then as absolute file system path).
|
||||
* Loads any dependent modules (merges XXNK, library, and properties results with active command line).
|
||||
* Builds out server classpath.
|
||||
* Determines run mode:
|
||||
** Shows informational command line options and exit.
|
||||
** Executes Jetty normally, waits for Jetty to stop.
|
||||
** Executes a forked JVM to run Jetty in, waits for forked JVM to exit.
|
||||
* If you want to start Jetty:
|
||||
** Load each XML configuration (in the order determined by the INIs and
|
||||
module system).
|
||||
** Let XML configuration start Jetty.
|
||||
|
||||
==== start.jar Command Line Options
|
||||
|
||||
--help::
|
||||
Obtains the current list of command line options and some basic usage
|
||||
help.
|
||||
Obtains the current list of command line options and some basic usage help.
|
||||
--version::
|
||||
Shows the list of server classpath entries, and prints version
|
||||
information found for each entry.
|
||||
Shows the list of server classpath entries, and prints version information found for each entry.
|
||||
--list-classpath::
|
||||
Similar to --version, shows the server classpath.
|
||||
Similar to --version, shows the server classpath.
|
||||
--list-config::
|
||||
Lists the resolved configuration that will start Jetty.
|
||||
+
|
||||
* Java environment
|
||||
* Jetty environment
|
||||
* JVM arguments
|
||||
* Properties
|
||||
* Server classpath
|
||||
* Server XML configuration files
|
||||
--dry-run::
|
||||
Prints the resolved command line that `start.jar` should use to start
|
||||
a forked instance of Jetty.
|
||||
--exec::
|
||||
Starts a forked instance of Jetty.
|
||||
Lists the resolved configuration that will start Jetty.
|
||||
|
||||
+
|
||||
* Java environment
|
||||
* Jetty environment
|
||||
* JVM arguments
|
||||
* Properties
|
||||
* Server classpath
|
||||
* Server XML configuration files
|
||||
--dry-run::
|
||||
Prints the resolved command line that `start.jar` should use to start a forked instance of Jetty.
|
||||
--exec::
|
||||
Starts a forked instance of Jetty.
|
||||
--debug::
|
||||
Enables debugging output of the startup procedure.
|
||||
+
|
||||
Note: This does not set up debug logging for Jetty itself.
|
||||
Enables debugging output of the startup procedure.
|
||||
+
|
||||
*Note*: This does not set up debug logging for Jetty itself.
|
||||
For information on logging, please see the section on <<configuring-jetty-logging, Configuring Jetty Logging.>>
|
||||
--start-log-file=<filename>::
|
||||
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.
|
||||
|
||||
+
|
||||
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.
|
||||
--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.
|
||||
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.
|
||||
--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.`
|
||||
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.`
|
||||
--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.
|
||||
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.
|
||||
--add-to-startd=<name>,(<name>)*::
|
||||
Enables a module via creation of a module-specific INI file in the
|
||||
`${jetty.base}/start.d/` directory.
|
||||
+
|
||||
The content of the new INI is provided by the module-defined ini
|
||||
templates.
|
||||
+
|
||||
Note: Transitive modules are also created in the same directory as
|
||||
their own INI files.
|
||||
Enables a module via creation of a module-specific INI file in the `${jetty.base}/start.d/` directory.
|
||||
+
|
||||
The content of the new INI is provided by the module-defined ini templates.
|
||||
+
|
||||
Note: Transitive modules are also created in the same directory as their own INI files.
|
||||
|
||||
[NOTE]
|
||||
--
|
||||
With respect to `start.ini` and `start.d/*.ini` files, only *one* of these methods should be implemented.
|
||||
Mixing a `start.ini` with module specific ini files in the `{$jetty.base}/start.d` directory can lead to server issues unless great care is taken.
|
||||
--
|
||||
|
||||
--write-module-graph=<filename>::
|
||||
Advanced feature: Creates a graphviz
|
||||
http://graphviz.org/content/dot-language[dot file] of the module graph
|
||||
as it exists for the active `${jetty.base}`.
|
||||
+
|
||||
Advanced feature: Creates a graphviz http://graphviz.org/content/dot-language[dot file] of the module graph as it exists for the active `${jetty.base}`.
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
# generate module.dot
|
||||
|
|
@ -183,33 +142,26 @@ $ java -jar start.jar --module=websocket --write-module-graph=modules.dot
|
|||
# post process to a PNG file
|
||||
$ 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.
|
||||
+
|
||||
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.
|
||||
|
||||
--stop::
|
||||
Sends a stop signal to the running Jetty instance.
|
||||
+
|
||||
Note: The server must have been started with various stop properties
|
||||
for this to work.
|
||||
+
|
||||
STOP.PORT=<number>;;
|
||||
The port to use to stop the running Jetty server. This is an
|
||||
internal port, opened on localhost, used solely for stopping the
|
||||
running Jetty server. Choose a port that you do not use to serve web
|
||||
traffic.
|
||||
+
|
||||
Required for --stop to function.
|
||||
STOP.KEY=<alphanumeric>;;
|
||||
The passphrase defined to stop the server.
|
||||
+
|
||||
Required for --stop to function.
|
||||
STOP.WAIT=<number>;;
|
||||
The time (in seconds) to wait for confirmation that the running
|
||||
Jetty server has stopped. If not specified, the stopper waits
|
||||
indefinitely for the server to stop.
|
||||
+
|
||||
If the time specified elapses, without a confirmation of server
|
||||
stop, then the --stop command exits with a non-zero return code.
|
||||
Sends a stop signal to the running Jetty instance.
|
||||
+
|
||||
Note: The server must have been started with various stop properties for this to work.
|
||||
|
||||
STOP.PORT=<number>;;
|
||||
The port to use to stop the running Jetty server.
|
||||
This is an internal port, opened on localhost, used solely for stopping the running Jetty server.
|
||||
Choose a port that you do not use to serve web traffic.
|
||||
+
|
||||
Required for --stop to function.
|
||||
STOP.KEY=<alphanumeric>;;
|
||||
The passphrase defined to stop the server.
|
||||
+
|
||||
Required for --stop to function.
|
||||
STOP.WAIT=<number>;;
|
||||
The time (in seconds) to wait for confirmation that the running Jetty server has stopped.
|
||||
If not specified, the stopper waits indefinitely for the server to stop.
|
||||
+
|
||||
If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code.
|
||||
|
|
|
|||
|
|
@ -17,53 +17,40 @@
|
|||
[[startup-base-and-home]]
|
||||
=== Managing Jetty Base and Jetty Home
|
||||
|
||||
Starting with Jetty 9.1, it is now possible to maintain a separation
|
||||
between the binary installation of the standalone Jetty (known as
|
||||
`${jetty.home}`), and the customizations for your specific environment
|
||||
(known as `${jetty.base}`).
|
||||
Starting with Jetty 9.1, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment (known as `${jetty.base}`).
|
||||
|
||||
Jetty Base::
|
||||
Also known as the `${jetty.base}` property
|
||||
+
|
||||
This is the location for your configurations and customizations to the
|
||||
Jetty distribution.
|
||||
* Also known as the `${jetty.base}` property.
|
||||
* This is the location for your configurations and customizations to the Jetty distribution.
|
||||
Jetty Home::
|
||||
Also known as the `${jetty.home}` property.
|
||||
+
|
||||
This is the location for the Jetty distribution binaries, default XML
|
||||
IoC configurations, and default module definitions.
|
||||
* Also known as the `${jetty.home}` property.
|
||||
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
|
||||
|
||||
Potential configuration is resolved from these 2 directory locations.
|
||||
|
||||
Check Jetty Base::
|
||||
If the referenced configuration exists, relative to the defined Jetty
|
||||
Base, use it.
|
||||
If the referenced configuration exists, relative to the defined Jetty base, use it.
|
||||
Check Jetty Home::
|
||||
If the referenced configuration exists, relative to the defined Jetty
|
||||
Home, use it.
|
||||
If the referenced configuration exists, relative to the defined Jetty home, use it.
|
||||
Use java.io.File(String pathname) Logic::
|
||||
Lastly, use the reference as a `java.io.File(String
|
||||
pathname)` reference, following the default resolution rules
|
||||
outlined by that constructor.
|
||||
+
|
||||
In brief, the reference will be used as-is, be it relative (to current
|
||||
working directory, aka $\{user.dir}) or absolute path, or even network
|
||||
reference (such as on Windows and use of UNC paths).
|
||||
Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.
|
||||
|
||||
For more details on how startup with start.jar works, see
|
||||
link:#execute-start-jar[Using start.jar: Executing]
|
||||
+
|
||||
In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).
|
||||
|
||||
For more details on how startup with start.jar works, see link:#execute-start-jar[Using start.jar: Executing]
|
||||
|
||||
[[demo-base]]
|
||||
==== Demo-Base in the Jetty Distribution
|
||||
|
||||
The Jetty Distribution comes with an example $\{jetty.base} which
|
||||
enables the various demonstration webapps and server configurations.
|
||||
The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
|
||||
|
||||
How to use the demo-base directory as a Jetty Base directory.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[jetty-distribution-{VERSION}]$ ls -la
|
||||
|
||||
total 496
|
||||
drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./
|
||||
drwxr-xr-x 14 user group 4096 Oct 8 13:04 ../
|
||||
|
|
@ -82,8 +69,10 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 start.d/
|
|||
-rw-rw-r-- 1 user group 71921 Sep 30 19:55 start.jar
|
||||
-rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt
|
||||
drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
|
||||
|
||||
[jetty-distribution-{VERSION}]$ cd demo-base
|
||||
[demo-base]$ java -jar $JETTY_HOME/start.jar
|
||||
|
||||
2013-10-16 09:08:47.800:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
|
||||
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
|
||||
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-{VERSION}/demo-base/webapps/] at interval 1
|
||||
|
|
@ -91,11 +80,9 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
|
|||
...
|
||||
....
|
||||
|
||||
As you can see above, you are executing the demo-base configuration
|
||||
using the Jetty Base concepts.
|
||||
As you can see above, you are executing the demo-base configuration using the Jetty base concepts.
|
||||
|
||||
If you want to see what the Jetty Base looks like without executing
|
||||
Jetty, you can simply list the configuration
|
||||
If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -210,22 +197,17 @@ Jetty Active XMLs:
|
|||
${jetty.base}/etc/test-realm.xml
|
||||
....
|
||||
|
||||
This demonstrates the powerful `--list-config` command line option and
|
||||
how you can use it to see what the configuration will look like when
|
||||
starting Jetty. From the Java environment, to the system properties, to
|
||||
the classpath, and finally the Active Jetty IoC XML used to build up
|
||||
your Jetty server configuration.
|
||||
This demonstrates the powerful `--list-config` command line option and how you can use it to see what the configuration will look like when starting Jetty.
|
||||
From the Java environment, to the system properties, to the classpath, and finally the Active Jetty IoC XML used to build up the Jetty server configuration.
|
||||
|
||||
Of note, is that the output will make it known where the configuration
|
||||
elements came from, be it in either in `${jetty.home}` or
|
||||
`${jetty.base}`.
|
||||
Of note, is that the output will make it known where the configuration elements came from, be it in either in `${jetty.home}` or `${jetty.base}`.
|
||||
|
||||
If you look at the $\{jetty.base}/start.ini you will see something like
|
||||
the following.
|
||||
If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[my-base]$ cat start.ini
|
||||
|
||||
# Enable security via jaas, and configure it
|
||||
--module=jaas
|
||||
jaas.login.conf=etc/login.conf
|
||||
|
|
@ -259,71 +241,64 @@ jetty.dump.stop=false
|
|||
--module=annotations
|
||||
....
|
||||
|
||||
The $\{jetty.base}/start.ini is the main startup configuration entry
|
||||
point for Jetty. In this example you will see that we are enabling a few
|
||||
modules for Jetty, specifying some properties, and also referencing some
|
||||
Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and
|
||||
`etc/test-realm.xml` files)
|
||||
The `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
|
||||
In this example you will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
|
||||
|
||||
When Jetty's `start.jar` resolves the entries in the start.ini, it will
|
||||
follow the link:#base-vs-home-resolution[resolution rules above].
|
||||
When Jetty's `start.jar` resolves the entries in the `start.ini`, it will follow the link:#base-vs-home-resolution[resolution rules above].
|
||||
|
||||
For example, the reference to `etc/demo-rewrite-rules.xml` was found in
|
||||
`${jetty.base}/etc/demo-rewrite-rules.xml`.
|
||||
For example, the reference to `etc/demo-rewrite-rules.xml` was found in `${jetty.base}/etc/demo-rewrite-rules.xml`.
|
||||
|
||||
==== Declaring Jetty Base
|
||||
|
||||
The Jetty Distribution's start.jar is the component that manages the
|
||||
behavior of this separation.
|
||||
The Jetty distribution's `start.jar` is the component that manages the behavior of this separation.
|
||||
|
||||
The Jetty start.jar and XML files always assume that both
|
||||
`${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
|
||||
The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
|
||||
|
||||
You can opt to manually define the `${jetty.home}` and `${jetty.base}`
|
||||
directories, such as this:
|
||||
You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[jetty-distribution-{VERSION}]$ pwd
|
||||
/home/user/jetty-distribution-{VERSION}
|
||||
|
||||
[jetty-distribution-{VERSION}]$ java -jar start.jar \
|
||||
jetty.home=/home/user/jetty-distribution-{VERSION} \
|
||||
jetty.base=/home/user/my-base
|
||||
|
||||
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
|
||||
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
|
||||
...
|
||||
....
|
||||
|
||||
Or you can declare one directory and let the other one be discovered.
|
||||
Alternately, you can declare one directory and let the other one be discovered.
|
||||
|
||||
The following example uses default discovery of `${jetty.home}` by using
|
||||
the parent directory of wherever start.jar itself is, and a manual
|
||||
declaration of `${jetty.base}`.
|
||||
The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[jetty-distribution-{VERSION}]$ pwd
|
||||
/home/user/jetty-distribution-{VERSION}
|
||||
|
||||
[jetty-distribution-{VERSION}]$ java -jar start.jar jetty.base=/home/user/my-base
|
||||
|
||||
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
|
||||
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
|
||||
...
|
||||
....
|
||||
|
||||
But Jetty recommends that you always start Jetty by sitting in the
|
||||
directory that is your $\{jetty.base} and starting Jetty by referencing
|
||||
the start.jar remotely.
|
||||
But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
|
||||
the `start.jar` in your `{$jetty.home}` remotely.
|
||||
|
||||
The following demonstrates this by allowing default discovery of
|
||||
`${jetty.home}` via locating the `start.jar`, and using the `user.dir`
|
||||
System Property for `${jetty.base}`.
|
||||
The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[jetty-distribution-{VERSION}]$ pwd
|
||||
/home/user/jetty-distribution-{VERSION}
|
||||
|
||||
[jetty-distribution-{VERSION}]$ cd /home/user/my-base
|
||||
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
|
||||
|
||||
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
|
||||
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
|
||||
...
|
||||
|
|
@ -331,7 +306,6 @@ System Property for `${jetty.base}`.
|
|||
|
||||
____
|
||||
[IMPORTANT]
|
||||
Be aware of the `user.dir` system property, it can only be safely set when the JVM starts, and many 3rd party libraries (especially logging) use this system property.
|
||||
+
|
||||
Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
|
||||
It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.
|
||||
____
|
||||
|
|
|
|||
|
|
@ -20,36 +20,25 @@
|
|||
Jetty Server Classpath is determined by a combination of factors.
|
||||
|
||||
The java.class.path System Property::
|
||||
If you start Jetty with a JVM specified classpath, then Jetty will use
|
||||
the java.class.path System Property to populate the initial classpath.
|
||||
If you start Jetty with a JVM specified classpath, then Jetty will use the java.class.path System Property to populate the initial classpath.
|
||||
Module specified Libraries::
|
||||
With Jetty 9.1+ the module system declares various libraries that are
|
||||
required for that module to operate, these module defined libraries
|
||||
are added to the Jetty Server classpath when any module is activated
|
||||
with library declarations.
|
||||
The module system declares various libraries that are required for that module to operate.
|
||||
These module defined libraries are added to the Jetty Server classpath when any module is activated with library declarations.
|
||||
Command Line Libraries::
|
||||
The command line option `--lib=<path>`can be used as a final means to
|
||||
add arbitrary entries to the Jetty Server classpath.
|
||||
The command line option `--lib=<path>` can be used as a final means to add arbitrary entries to the Jetty Server classpath.
|
||||
|
||||
Of special note, there are 2 structural modules defined to ease some of
|
||||
this for you.
|
||||
Of special note, there are 2 structural modules defined to ease some of this for you.
|
||||
|
||||
--module=ext::
|
||||
The `ext` module will enable the `lib/ext/*.jar` logic.
|
||||
+
|
||||
If this module is activated, then all jar files found in the lib/ext/
|
||||
paths will be automatically added to the Jetty Server Classpath.
|
||||
If this module is activated, then all jar files found in the lib/ext/ paths will be automatically added to the Jetty Server Classpath.
|
||||
--module=resources::
|
||||
The `resources` module will add the `resources/` directory the
|
||||
classpath.
|
||||
The `resources` module will add the `resources/` directory the classpath.
|
||||
+
|
||||
If you have 3rd party libraries that lookup resources from the
|
||||
classpath, put your files in here.
|
||||
If you have 3rd party libraries that lookup resources from the classpath, put your files in here.
|
||||
+
|
||||
Logging libraries often have classpath lookup of their configuration
|
||||
files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and
|
||||
`logback.xml`), so this would be the ideal setup for this sort of
|
||||
configuration demand.
|
||||
Logging libraries often have classpath lookup of their configuration files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so this would be the ideal setup for this sort of configuration demand.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
|
|
@ -58,14 +47,11 @@ ____
|
|||
|
||||
==== Interrogating the Server Classpath
|
||||
|
||||
The Jetty start.jar has the ability to resolve the classpath from the
|
||||
command line + modules + configuration, and list the classpath entries
|
||||
it will use to start jetty.
|
||||
The Jetty `start.jar` has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.
|
||||
|
||||
The `--list-classpath` command line option is used as such.
|
||||
|
||||
(Demonstrated with the link:#demo-base[demo-base from the Jetty
|
||||
Distribution])
|
||||
(Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -120,6 +106,4 @@ Note: order presented here is how they would appear on the classpath.
|
|||
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
|
||||
....
|
||||
|
||||
Of note is that an attempt is made to list the internally declared
|
||||
version of each artifact on the Server Classpath, of potential help when
|
||||
diagnosing classpath issues.
|
||||
Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.
|
||||
|
|
|
|||
|
|
@ -17,152 +17,94 @@
|
|||
[[startup-modules]]
|
||||
=== Managing Startup Modules
|
||||
|
||||
Starting with Jetty 9.1, a new Module system was introduced. (It
|
||||
replaced the old `start.config` + `OPTIONS` techniques from past Jetty
|
||||
Distributions).
|
||||
Starting with Jetty 9.1, a new Module system was introduced, replacing the previous `start.config` + `OPTIONS` techniques from past Jetty Distributions.
|
||||
|
||||
The standard Jetty Distribution ships with several modules defined in
|
||||
`${jetty.home}/modules/`
|
||||
The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
|
||||
|
||||
What a Jetty Startup Module Defines:
|
||||
|
||||
A Module Name::
|
||||
The name of the module is the keyword used by the `--module=<name>`
|
||||
command line argument to activate/enable modules, and also find
|
||||
dependant modules.
|
||||
+
|
||||
The filename of the module defines its name. (eg: server.mod becomes
|
||||
the module named "server")
|
||||
The name of the module is the keyword used by the `--module=<name>` command line argument to activate/enable modules, and also find dependent modules.
|
||||
The filename of the module defines its name (eg: server.mod becomes the module named "server").
|
||||
List of Dependant Modules::
|
||||
All modules can declare that they depend on other modules with the
|
||||
`[depend]` section.
|
||||
+
|
||||
The list of dependencies is used to transitively resolve other modules
|
||||
that are deemed to be required based on the modules that you activate.
|
||||
+
|
||||
The order of modules defined in the graph of active modules is used to
|
||||
determine various execution order for configuration, such as Jetty IoC
|
||||
XML configurations, and to resolve conflicting property declarations.
|
||||
+
|
||||
Of note: there is a special section `[optional]` used to describe
|
||||
structurally dependant modules that are not technically required, but
|
||||
might be of use to your specific configuration.
|
||||
All modules can declare that they depend on other modules with the `[depend]` section.
|
||||
The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.
|
||||
The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.
|
||||
Of note: there is a special section `[optional]` used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration.
|
||||
List of Libraries::
|
||||
Module can optionally declare that they have libraries that they need
|
||||
to function properly.
|
||||
+
|
||||
The `[lib]` section declares a set of pathnames that follow the
|
||||
link:#base-vs-home-resolution[Jetty Base and Jetty Home path
|
||||
resolution rules].
|
||||
Module can optionally declare that they have libraries that they need to function properly.
|
||||
The `[lib]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
|
||||
List of Jetty IoC XML Configurations::
|
||||
A Module can optionally declare a list of Jetty IoC XML configurations
|
||||
used to wire up the functionality that this module defines.
|
||||
+
|
||||
The `[xml]` section declares a set of pathnames that follow the
|
||||
link:#base-vs-home-resolution[Jetty Base and Jetty Home path
|
||||
resolution rules].
|
||||
+
|
||||
Ideally, all XML files are parameterized to accept properties to
|
||||
configure the various elements of the standard configuration. Allowing
|
||||
for a simplified configuration of Jetty for the vast majority of
|
||||
deployments.
|
||||
+
|
||||
The execution order of the Jetty IoC XML configurations is determined
|
||||
by the graph of active module dependencies resolved via the `[depend]`
|
||||
sections.
|
||||
+
|
||||
If the default XML is not sufficient to satisfy your needs, you can
|
||||
override this XML by making your own in the $\{jetty.base}/etc/
|
||||
directory, with the same name. The resolution steps for Jetty Base and
|
||||
Jetty Home will ensure that your copy from $\{jetty.base} will be
|
||||
picked up over the default one in $\{jetty.home}.
|
||||
A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines.
|
||||
The `[xml]` section declares a set of pathnames that follow the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
|
||||
Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration.
|
||||
Allowing for a simplified configuration of Jetty for the vast majority of deployments.
|
||||
The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the `[depend]` sections.
|
||||
If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the `${jetty.base}/etc/` directory, with the same name.
|
||||
The resolution steps for Jetty Base and Jetty Home will ensure that your copy from `${jetty.base}` will be picked up over the default one in `${jetty.home}`.
|
||||
Jetty INI Template::
|
||||
Each module can optionally declare a startup ini template that is used
|
||||
to insert/append/inject sample configuration elements into the
|
||||
`start.ini` or `start.d/*.ini` files when using the
|
||||
`--add-to-start=<name>` or `--add-to-startd=<name>` command line
|
||||
arguments in `start.jar`.
|
||||
+
|
||||
Commonly used to present some of the parameterized property options
|
||||
from the Jetty IoC XML configuration files also referenced in the same
|
||||
module.
|
||||
+
|
||||
The `[ini-template]` section declares this section of sample
|
||||
configuration.
|
||||
Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the `start.ini` or `start.d/*.ini` files when using the `--add-to-start=<name>` or `--add-to-startd=<name>` command line arguments in `start.jar`.
|
||||
Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.
|
||||
The `[ini-template]` section declares this section of sample configuration.
|
||||
Required Files and Directories::
|
||||
If the activation of a module requires some paths to exist, the
|
||||
`[files]` section defines them.
|
||||
+
|
||||
If the activation of a module requires some paths to exist, the `[files]` section defines them.
|
||||
There are 2 modes of operation of the entries in this section.
|
||||
+
|
||||
Ensure Directory Exists;;
|
||||
If you add a pathname that ends in `"/"` (slash), such as
|
||||
`"webapps/"`, then that directory will be created if it does not yet
|
||||
exist in `${jetty.base}/<pathname>` (eg: `"webapps/"` will result in
|
||||
`${jetty.base}/webapps/` being created)
|
||||
Download File;;
|
||||
There is a special syntax to allow you to download a file into a
|
||||
specific location if it doesn't exist yet.
|
||||
+
|
||||
`<url>:<pathname>`
|
||||
+
|
||||
Currently, the `<url>` must be a `http://` scheme URL
|
||||
(link:#bugs[file a bug] if you want more schemes supported). The
|
||||
`<pathname>` portion follows the link:#base-vs-home-resolution[Jetty
|
||||
Base and Jetty Home path resolution rules].
|
||||
+
|
||||
Example:
|
||||
+
|
||||
`http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar`
|
||||
+
|
||||
This will check for the existence of `lib/corp-security-policy.jar`,
|
||||
and if it doesn't exist, it will download the jar file from
|
||||
Ensure Directory Exists;;
|
||||
If you add a pathname that ends in `"/"` (slash), such as `"webapps/"`, then that directory will be created if it does not yet exist in `${jetty.base}/<pathname>` (eg: `"webapps/"` will result in `${jetty.base}/webapps/` being created).
|
||||
Download File;;
|
||||
There is a special syntax to allow you to download a file into a specific location if it doesn't exist yet: `<url>:<pathname>`.
|
||||
Currently, the `<url>` must be a `http://` scheme URL (please link:#bugs[let us know] if you need more schemes supported).
|
||||
The `<pathname>` portion follows the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
|
||||
Example: `http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar`
|
||||
This will check for the existence of `lib/corp-security-policy.jar`, and if it doesn't exist, it will download the jar file from
|
||||
`http://repo.corp.com/maven/corp-security-policy-1.0.jar`
|
||||
|
||||
[[enabling-modules]]
|
||||
==== Enabling Modules
|
||||
|
||||
Jetty ships with many modules defined, and a small subset predefined in
|
||||
the `start.ini` found in the jetty distribution.
|
||||
Jetty ships with many modules defined, and a small subset predefined in the `start.ini` found in the jetty distribution.
|
||||
|
||||
____
|
||||
[TIP]
|
||||
The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}`. Where the directories for `${jetty.home}` and `${jetty.base}` point to the same location.
|
||||
+
|
||||
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
|
||||
____
|
||||
|
||||
When you want enable a module, you can use the `--module=<modulename>`
|
||||
syntax on the command line (or start.ini) to enable that module and all
|
||||
of its dependant modules.
|
||||
When you want enable a module, you can use the `--module=<modulename>` syntax on the command line to enable that module and all of its dependent modules.
|
||||
|
||||
An example of this, with a new, empty, base directory.
|
||||
We can see from this output, that the directory is new.
|
||||
|
||||
We can see from this output, that the directory is new (it is empty
|
||||
after all).
|
||||
include::screen-empty-base.adoc[]
|
||||
|
||||
Lets see what the configuration looks like so far
|
||||
Lets see what the configuration looks like so far:
|
||||
|
||||
Lets try adding some basic support for webapps, with automatic deploy
|
||||
(hot deploy), and a single basic HTTP/1.1 connector.
|
||||
include::screen-empty-base-listconfig.adoc[]
|
||||
|
||||
That just created what we need in the `${jetty.base}` directory. Lets
|
||||
see what it looks like configuration wise.
|
||||
Lets try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.
|
||||
|
||||
You now have a configured and functional server, albiet with no webapps
|
||||
deployed. At this point you can toss a webapp (war file) into
|
||||
`mybase/webapps/` directory and and start Jetty
|
||||
include::screen-http-webapp-deploy.adoc[]
|
||||
|
||||
This created the webapps directory in our `mybase` directory and appended the `start.ini` file with the ini template arguments from the associated module files.
|
||||
Additionally, where needed, Jetty enabled any module dependencies and added their module ini template properties.
|
||||
|
||||
Lets see what it looks like configuration wise.
|
||||
|
||||
include::screen-http-webapp-deploy-listconfig.adoc[]
|
||||
|
||||
You now have a configured and functional server, albeit with no webapps deployed.
|
||||
At this point you can place a webapp (war file) in the `mybase/webapps/` directory and and start Jetty.
|
||||
|
||||
[[startup-listing-modules]]
|
||||
==== Listing Available and Active Modules
|
||||
|
||||
To see which modules are __available__, use the `--list-modules` command
|
||||
line argument. This command will also show you which modules are
|
||||
__enabled__. Here's an example
|
||||
To see which modules are __available__, use the `--list-modules` command line argument.
|
||||
This command will also show you which modules are __enabled__.
|
||||
Here's an example:
|
||||
|
||||
Wow, are there really that many modules available?
|
||||
include::screen-list-modules.adoc[]
|
||||
|
||||
Yes, the module system has grown a fair bit since it was introduced in
|
||||
Jetty 9
|
||||
Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
|
||||
Below is a graphical representation of the standard modules and their dependencies.
|
||||
|
||||
image:images/modules-9.3-simplified.png[image,width=768]
|
||||
|
|
|
|||
|
|
@ -17,75 +17,57 @@
|
|||
[[startup-overview]]
|
||||
=== Startup Overview
|
||||
|
||||
The `start.jar` bootstrap manages the startup of standalone Jetty. It is
|
||||
responsible for:
|
||||
The `start.jar` bootstrap manages the startup of standalone Jetty.
|
||||
It is responsible for:
|
||||
|
||||
Building the classpath::
|
||||
The `start.jar` bootstrap builds a classpath for all the required
|
||||
Jetty features and their dependencies. It builds the classpath using
|
||||
either the `--lib` option to `start.jar` to add an individual
|
||||
classpath entry, or with the `--module` option that includes all the
|
||||
libs and their dependencies for a module (a named Jetty feature).
|
||||
The `start.jar` bootstrap builds a classpath for all the required Jetty features and their dependencies.
|
||||
It builds the classpath using either the `--lib` option to `start.jar` to add an individual classpath entry, or with the `--module` option that includes all the libs and their dependencies for a module (a named Jetty feature).
|
||||
Instantiating the Server Components::
|
||||
The server and its components are instantiated using either Jetty IoC
|
||||
XML or spring. The Jetty server is just a collection of java POJOs for
|
||||
the server, connectors, session managers and others. These are
|
||||
instantiated, injected, and wired up together in XML files, commonly
|
||||
one per module/feature, that are passed as arguments to `start.jar`.
|
||||
The server and its components are instantiated using either Jetty IoC XML or Spring.
|
||||
The Jetty server is a collection of POJOs for the server, connectors, session managers and others.
|
||||
These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to `start.jar`.
|
||||
Resolving Server Filesystem Locations::
|
||||
The `start.jar` mechanism resolves canonical locations for the
|
||||
`${jetty.home}` and the `${jetty.base}` directories.
|
||||
The `start.jar` mechanism resolves canonical locations for the `${jetty.home}` and the `${jetty.base}` directories.
|
||||
The `${jetty.home}` directory is the location of the standard distribution of Jetty.
|
||||
The `${jetty.base}` directory is the location of the local server customization and configurations.
|
||||
+
|
||||
The `${jetty.home}` directory is the location of the standard
|
||||
distribution of Jetty.
|
||||
+
|
||||
The `${jetty.base}` directory is the location of the local server
|
||||
customization and configurations.
|
||||
+
|
||||
If you want to modify the Jetty distribution, base and home can be the
|
||||
same directory. Separating the base and home directories allows the
|
||||
distribution to remain unmodified, with all customizations in the base
|
||||
directory, and thus simplifies subsequent server version upgrades.
|
||||
If you want to modify the Jetty distribution, base and home can be the same directory.
|
||||
Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the base directory, and thus simplifies subsequent server version upgrades.
|
||||
Parameterizing the Server Configuration::
|
||||
XML files primarily determine the server configuration. Many of these
|
||||
files are parameterized to allow simple injection of host names,
|
||||
ports, passwords and more. The `start.jar` mechanism allows you to set
|
||||
parameters on the command line or in properties files.
|
||||
XML files primarily determine the server configuration.
|
||||
Many of these files are parameterized to allow simple injection of host names, ports, passwords and more.
|
||||
The `start.jar` mechanism allows you to set parameters on the command line or in properties files.
|
||||
|
||||
To achieve these start up mechanisms, the `start.jar` uses:
|
||||
|
||||
Command line arguments::
|
||||
You can configure the entire server with command line arguments that
|
||||
specify libraries, properties and XML files. However in practice the
|
||||
INI and modules mechanisms (below) reduce the verbosity of the command
|
||||
line.
|
||||
You can configure the entire server with command line arguments that specify libraries, properties and XML files.
|
||||
However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
|
||||
INI files::
|
||||
The `start.jar` mechanism uses the contents of the
|
||||
`${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with
|
||||
each line equivalent to a `start.jar` command line argument. This
|
||||
means that either a global `start.ini` file or multiple
|
||||
`start.d/feature.ini` files control the configuration of the server.
|
||||
The `start.jar` mechanism uses the contents of the `${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with each line equivalent to a `start.jar` command line argument.
|
||||
This means that either a global `start.ini` file or multiple `start.d/feature.ini` files control the configuration of the server.
|
||||
[NOTE]
|
||||
--
|
||||
It is important to chose *either* `${jetty.base}/start.ini` or `${jetty.base}/start.d/*.ini` to manage configuration.
|
||||
Using both is not recommended and can lead to issues with your server.
|
||||
--
|
||||
Modules::
|
||||
Instead of explicitly listing all the libraries, properties and XML
|
||||
files for a feature, the `start.jar` mechanism allows you to create
|
||||
modules. You define a module in a `modules/*.mod` file, including the
|
||||
libraries, dependencies, XML, and template INI files for a Jetty
|
||||
feature. Thus you can use a single `--module=name` command line option
|
||||
as the equivalent of specifying many `--lib=location`, feature.xml,
|
||||
name=value arguments for a feature and all its dependencies. Modules
|
||||
also use their dependencies to control the ordering of libraries and
|
||||
XML files.
|
||||
Instead of explicitly listing all the libraries, properties and XML files for a feature, the `start.jar` mechanism allows you to create modules.
|
||||
A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
|
||||
Thus you can use a single `--module=name` command line option as the equivalent of specifying `--lib=location`, `feature.xml` or `name=value` arguments for a feature and all its dependencies.
|
||||
Modules also use their dependencies to control the ordering of libraries and XML files.
|
||||
There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations...etc.
|
||||
These module files should *only* be edited if you are making structural changes to the way the feature will perform.
|
||||
For more information, refer to the section on <<startup-modules,managing startup modules>> later in this chapter.
|
||||
XML Files::
|
||||
XML files in either Jetty IoC or Spring format instantiate the actual
|
||||
POJO components of the server. This includes all major components such
|
||||
as connectors, keystores, session managers, and data sources.
|
||||
Typically there are one or more XML files per module, and these are
|
||||
defined and activated in the corresponding module.
|
||||
XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server.
|
||||
This includes all major components such as connectors, keystores, session managers, and data sources.
|
||||
Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.
|
||||
|
||||
==== Startup Example
|
||||
|
||||
The simplest way to start Jetty is via the `start.jar` mechanism using
|
||||
the following Java command line:
|
||||
The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -93,10 +75,8 @@ the following Java command line:
|
|||
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
|
||||
....
|
||||
|
||||
This command uses the `start.jar` mechanism to bootstrap the classpath,
|
||||
properties, and XML files with the metadata obtained from the `http`
|
||||
module. Specifically the `http` module is defined in the
|
||||
`${jetty.home}/modules/http.mod` file, and includes the following:
|
||||
This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
|
||||
Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -112,14 +92,10 @@ jetty.http.port=8080
|
|||
http.timeout=30000
|
||||
....
|
||||
|
||||
The `http` module declares that `http` depends on the server module,
|
||||
uses the `jetty-http.xml` file, and can be parameterized with
|
||||
`jetty.http.port` and `http.timeout` parameters. The INI-template
|
||||
section is not actually used by the command above, so the
|
||||
`jetty.http.port` must still be defined on the command line.
|
||||
The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters.
|
||||
The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.
|
||||
|
||||
Following the server dependency, the `${jetty.home}/modules/server.mod`
|
||||
file includes:
|
||||
Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -140,13 +116,10 @@ threads.min=10
|
|||
threads.max=200
|
||||
....
|
||||
|
||||
The `server` module declares the libraries the server needs and t0 use
|
||||
`jetty.xml` file. The combined metadata of the `http` and `server`
|
||||
modules results in `start.jar` generating the effective Java command
|
||||
line required to start Jetty.
|
||||
The `server` module declares the libraries the server needs and to use `jetty.xml` file.
|
||||
The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
|
||||
|
||||
Another way to see this is by asking Jetty what its configuration looks
|
||||
like:
|
||||
Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -201,14 +174,11 @@ Jetty Active XMLs:
|
|||
${jetty.home}/etc/jetty-http.xml
|
||||
....
|
||||
|
||||
This represents the entirety of the configuration that is applied to
|
||||
start Jetty.
|
||||
This represents the entirety of the configuration that is applied to start Jetty.
|
||||
|
||||
If you don't want to use the `start.jar` bootstrap, you can start Jetty
|
||||
using a traditional Java command line.
|
||||
If you don't want to use the `start.jar` bootstrap, you can start Jetty using a traditional Java command line.
|
||||
|
||||
The following is the equivalent `java` command line for what the
|
||||
`start.jar` bootstrap above performs.
|
||||
The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -233,14 +203,9 @@ $JETTY_HOME/etc/jetty.xml \
|
|||
$JETTY_HOME/etc/jetty-http.xml
|
||||
....
|
||||
|
||||
The java command line sets up the classpath with the core Jetty jars and
|
||||
the servlet API, executes the XmlConfiguration class, and passes it some
|
||||
XML files that define the server and an HTTP connector running on the
|
||||
port defined in the `jetty.properties` file.
|
||||
The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.
|
||||
|
||||
You can further simplify the startup of this server by using the INI
|
||||
template defined by the modules to create a `start.ini` file with the
|
||||
command:
|
||||
You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
@ -251,11 +216,14 @@ command:
|
|||
total 8
|
||||
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
|
||||
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
|
||||
|
||||
[example-base]$ java -jar $JETTY_HOME/start.jar --add-to-start=http
|
||||
|
||||
WARNING: http initialised in ${jetty.base}/start.ini (appended)
|
||||
WARNING: http enabled in ${jetty.base}/start.ini
|
||||
WARNING: server initialised in ${jetty.base}/start.ini (appended)
|
||||
WARNING: server enabled in ${jetty.base}/start.ini
|
||||
|
||||
[example-base]$ ls -la
|
||||
total 12
|
||||
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
|
||||
|
|
@ -263,8 +231,7 @@ drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
|
|||
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
|
||||
....
|
||||
|
||||
Once complete, you can edit the `start.ini` file to modify any
|
||||
parameters and you can run the server with the simple command:
|
||||
Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
|
|
|||
|
|
@ -17,16 +17,9 @@
|
|||
[[startup-xml-config]]
|
||||
=== Managing XML Based Startup Configuration
|
||||
|
||||
When you see XML files on the command line for startup of Jetty, they
|
||||
are always part of the Jetty IoC Configuration mechanism.
|
||||
When you see XML files on the command line for startup of Jetty, they are always part of the Jetty IoC Configuration mechanism.
|
||||
|
||||
Internally, Jetty uses these XML files to build up Jetty with the
|
||||
features that you wan to use.
|
||||
Internally, Jetty uses these XML files to build up Jetty with the features that you wan to use.
|
||||
|
||||
The module mechanism present in Jetty determines the load order of the
|
||||
XML files.
|
||||
|
||||
The Jetty Base and Jetty Home resolution logic also applies, which
|
||||
allows you to override a XML file declared by a module with your XML by
|
||||
simply having the same named XML in your `${jetty.base}` directory
|
||||
location.
|
||||
The module mechanism present in Jetty determines the load order of the XML files.
|
||||
The Jetty Base and Jetty Home resolution logic also applies, which allows you to override a XML file declared by a module with your XML by simply having the same named XML in your `${jetty.base}/etc` directory location.
|
||||
|
|
|
|||
Loading…
Reference in New Issue