Issue #1319 - Documentation
Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch
parent
4a9ae6695e
commit
ee352d0d19
|
|
@ -22,6 +22,7 @@ include::start-jar.adoc[]
|
|||
include::startup-base-vs-home.adoc[]
|
||||
include::startup-classpath.adoc[]
|
||||
include::startup-modules.adoc[]
|
||||
include::custom-modules.adoc[]
|
||||
include::startup-xml-config.adoc[]
|
||||
include::startup-unix-service.adoc[]
|
||||
include::startup-windows-service.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,219 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[custom-modules]]
|
||||
=== Custom Modules
|
||||
|
||||
In addition to the modules that come packaged with the Jetty distribution, users are able to create and define their own custom modules for use with their Jetty implementation.
|
||||
Custom modules can be used for a number of reasons - they can extend features in Jetty, add new features, manage additional libraries available to the server...etc.
|
||||
|
||||
At the heart of a Jetty module is the `{name}.mod` file itself.
|
||||
A jetty `.mod` file defines the following:
|
||||
|
||||
[NOTE]
|
||||
--
|
||||
It is important to note that when creating your own module, none of these sections are required - simply use those which are applicable to your implementation.
|
||||
--
|
||||
|
||||
Module Description - `[description]`::
|
||||
The description of the module.
|
||||
This will be showing when viewing the `.mod` file itself or using the `--list-modules` command.
|
||||
List of Dependent Modules - `[depend]`::
|
||||
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.
|
||||
Optional Modules - `[optional]`;;
|
||||
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 - `[lib]`::
|
||||
Modules 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 - `[xml]`::
|
||||
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}`.
|
||||
List of Module Tags - `[tags]`::
|
||||
For ease of sorting, modules can be assigned tags.
|
||||
When using the `--list-modules` command, modules will be groups by the first tag that exists in this section.
|
||||
Modules can also be listed specifically by these tags using `--list-modules=<tag name>` on the command line.
|
||||
Ini Variables - `[ini]`::
|
||||
The `[ini]` section is used to add or change server parameters at startup.
|
||||
The `[ini]` section can also include a the path of a file or several files which should be made available to the server only.
|
||||
This is helpful when you want to control what jars are available to deployed webapps.
|
||||
Jetty INI Template - `[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>` command line argument 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.
|
||||
Required Files and Directories - `[files]`::
|
||||
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 (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`
|
||||
Licenses - `[license]`::
|
||||
If you are implementing a software/technology that has a license, it's text can be placed here.
|
||||
When a user attempts to activate the module they will be asked if they accept the license agreement.
|
||||
If a user does not accept the license agreement, the module will not be activated.
|
||||
Additional Startup Commands - `[exec]`::
|
||||
The `[exec]` section is used to define additional parameters specific to the module.
|
||||
These commands are added to the server startup.
|
||||
|
||||
[[custom-module-location]]
|
||||
==== Location of Modules
|
||||
Jetty comes with dozens of modules as part of the distribution package.
|
||||
By default these are located in the `${JETTY_HOME}/modules` directory.
|
||||
These modules should not be modified.
|
||||
In the unlikely circumstance you need to make changes to a stock module, copy it to your `${JETTY_BASE}` in a `modules` directory.
|
||||
|
||||
Custom modules should also be maintained separately as part of the `${JETTY_BASE}/modules` directory, though you can optionally place them in `${JETTY_HOME}/modules` for convenience if you have several `{$JETTY_BASE}` locations in your implementation.
|
||||
|
||||
[[custom-module-examples]]
|
||||
==== Creating Custom Modules
|
||||
As shown above, there are several options that can be utilized when creating custom module files.
|
||||
This may seem daunting, but the good news is that creating custom modules is actually quite easy.
|
||||
|
||||
For example, here is a look at the `http.mod` file which defines parameters for enabling HTTP features for the server:
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
include::{SRCDIR}/jetty-server/src/main/config/modules/http.mod[]
|
||||
----
|
||||
|
||||
You'll notice that the `http.mod` file only includes a handful of the possible sections available - `[description]`, `[tags]`, `[depend]`, `[xml]`, and `[ini-template]`.
|
||||
When configuring your own modules, you are free to pick and choose what you include.
|
||||
|
||||
As an example, below is a module file that defines a custom XML and lib, and activates a number of additional modules.
|
||||
A module like this could be used to enable a set of standard modules and resources for a new JETTY_BASE without having to define them all manually.
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
[description]
|
||||
Enables the standard set of modules and resources for ACME Corp servers.
|
||||
|
||||
[tags]
|
||||
core
|
||||
|
||||
[depend]
|
||||
server
|
||||
client
|
||||
http
|
||||
http2
|
||||
jsp
|
||||
console-capture
|
||||
requestlog
|
||||
stats
|
||||
gzip
|
||||
deploy
|
||||
jmx
|
||||
|
||||
[files]
|
||||
basehome:modules/acme/acme.xml|etc/acme.xml
|
||||
|
||||
[lib]
|
||||
lib/acme/ACMECustom.jar
|
||||
----
|
||||
|
||||
Activating this module will activate all the dependent modules, create any required directories and copy in any required files:
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
java -jar ../start.jar --add-to-start=acme
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: alpn-impl/alpn-8
|
||||
+ ALPN is a hosted at github under the GPL v2 with ClassPath Exception.
|
||||
+ ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package.
|
||||
+ http://github.com/jetty-project/jetty-alpn
|
||||
+ http://openjdk.java.net/legal/gplv2+ce.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
|
||||
INFO : server transitively enabled, ini template available with --add-to-start=server
|
||||
INFO : requestlog transitively enabled, ini template available with --add-to-start=requestlog
|
||||
INFO : alpn transitively enabled, ini template available with --add-to-start=alpn
|
||||
INFO : jsp transitively enabled
|
||||
INFO : servlet transitively enabled
|
||||
INFO : alpn-impl/alpn-8 dynamic dependency of alpn
|
||||
INFO : annotations transitively enabled
|
||||
INFO : gzip transitively enabled, ini template available with --add-to-start=gzip
|
||||
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
|
||||
INFO : plus transitively enabled
|
||||
INFO : deploy transitively enabled, ini template available with --add-to-start=deploy
|
||||
INFO : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
|
||||
INFO : security transitively enabled
|
||||
INFO : jmx transitively enabled
|
||||
INFO : apache-jsp transitively enabled
|
||||
INFO : stats transitively enabled, ini template available with --add-to-start=stats
|
||||
INFO : acme initialized in ${jetty.base}/start.d/acme.ini
|
||||
INFO : jndi transitively enabled
|
||||
INFO : console-capture transitively enabled, ini template available with --add-to-start=console-capture
|
||||
INFO : client transitively enabled
|
||||
INFO : http transitively enabled, ini template available with --add-to-start=http
|
||||
INFO : http2 transitively enabled, ini template available with --add-to-start=http2
|
||||
MKDIR : ${jetty.base}/logs
|
||||
MKDIR : ${jetty.base}/lib
|
||||
MKDIR : ${jetty.base}/lib/alpn
|
||||
MKDIR : ${jetty.base}/etc
|
||||
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
|
||||
MKDIR : ${jetty.base}/webapps
|
||||
DOWNLD: http://central.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar
|
||||
COPY : ${jetty.home}/modules/acme/acme.xml to ${jetty.base}/etc/acme.xml
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
==== Dependencies
|
||||
When dependent modules are enabled, they are done so transitively by default.
|
||||
This means that any `ini` files for dependent modules are not created in the `${JETTY_BASE}/start.d` directory (or added to `${JETTY_BASE}/start.ini`) and are as such not configurable.
|
||||
|
||||
For Jetty to create/add the `ini-template` parameters to `start.d` or `start.ini` the associated module must be enabled explicitly.
|
||||
|
||||
For example, if I activate the `http` module, it will be enabled, and the `server` module will be enabled transitively:
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=http
|
||||
INFO : server transitively enabled, ini template available with --add-to-start=server
|
||||
INFO : http initialized in ${jetty.base}/start.d/http.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
You'll notice that Jetty informs you of what modules were enabled, and where there associated ini files are located (when applicable).
|
||||
It also tells the user what command they would need to run to enable any missing or desired ini files for the selected modules, in this case `--add-to-start=server`.
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=server
|
||||
INFO : server initialized in ${jetty.base}/start.d/server.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down.
|
||||
If a dependent module also has dependencies they too will be enabled.
|
||||
____
|
||||
|
|
@ -20,54 +20,8 @@
|
|||
The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
|
||||
These modules allow flexibility for implementations and make configuration a much more plug-and-play set up.
|
||||
|
||||
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 dependent modules.
|
||||
The filename of the module defines its name (eg: server.mod becomes the module named "server").
|
||||
List of Dependent 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 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].
|
||||
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}`.
|
||||
List of Module Tags::
|
||||
For ease of sorting, modules can be assigned tags.
|
||||
When using the `--list-modules` command, modules will be groups by the first tag that exists in this section.
|
||||
Modules can also be listed specifically by these tags using `--list-modules=<tag name>` on the command line.
|
||||
Ini Variables::
|
||||
The `[ini]` section is used to add or change server parameters at startup.
|
||||
The `[ini]` section can also include a the path of a file or several files which should be made available to the server only.
|
||||
This is helpful when you want to control what jars are available to deployed webapps.
|
||||
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>` command line argument 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.
|
||||
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 (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
|
||||
|
||||
____
|
||||
[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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue