Skip to content

Latest commit

 

History

History
347 lines (245 loc) · 12.9 KB

start-configure.adoc

File metadata and controls

347 lines (245 loc) · 12.9 KB
Raw

Configuring $JETTY_BASE

Within the Jetty start mechanism, the source of configurations is layered in this order, from higher priority to lower priority:

  • The command line options.

  • The $JETTY_BASE directory, and its files.

  • The directory specified with the --include-jetty-dir option, and its files.

  • The $JETTY_HOME directory, and its files.

Enabling Modules

You can enable Jetty modules with the --add-modules command:

$ java -jar $JETTY_HOME/start.jar --add-modules=server,http

The Jetty start mechanism will look for the specified modules following the order specified above. In the common case (without a --include-jetty-dir directory), it will look in $JETTY_BASE/modules/ first and then in $JETTY_HOME/modules/.

Since the server and http modules are standard Jetty modules, they are present in $JETTY_HOME/modules/ and loaded from there.

When you enable a Jetty module, the Jetty start mechanism:

  • Creates the correspondent $JETTY_BASE/start.d/*.ini module configuration file. The content of these *.ini files is copied from the [ini-template] section of the correspondent *.mod file.

  • Executes the directives specified in [files] section (if present) of the *.mod file. This may simply create a file or a directory, or download files from the Internet. This step is performed transitively for all module dependencies.

For example, enabling the server and http modules results in the $JETTY_BASE directory to have the following structure:

$JETTY_BASE
├── resources
│   └── jetty-logging.properties
└── start.d
    ├── http.ini
    └── server.ini

The $JETTY_BASE/resources/jetty-logging.properties is created by the [files] directives of the logging-jetty module, which is a transitive dependency of the server module.

Disabling Modules

A module is enabled because the correspondent $JETTY_BASE/start.d/*.ini file contains a --module=<name> directive.

Commenting out the --module=<name> directive effectively disables the module.

Deleting the correspondent $JETTY_BASE/start.d/*.ini file also disables the module.

Editing *.ini Files

You can now edit the $JETTY_BASE/start.d/*.ini configuration files, typically by uncommenting properties to change their default value.

The $JETTY_BASE/start.d/*.ini configuration file may be missing, if the correspondent module is a transitive dependency. You can easily generate the configuration file by explicitly enabling the module, for example to generate the $JETTY_BASE/start.d/logging-jetty.ini configuration file you would issue the following command (the module order does not matter):

$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,logging-jetty

The $JETTY_BASE directory structure is now:

$JETTY_BASE
├── resources
│   └── jetty-logging.properties
└── start.d
    ├── http.ini
    ├── logging-jetty.ini
    └── server.ini

You want to edit the $JETTY_BASE/start.d/*.ini configuration files so that the configuration is applied every time Jetty is started (or re-started).

For example, $JETTY_BASE/start.d/http.ini contains the following property, commented out:

http.ini
# jetty.http.port=8080

You can change the clear-text HTTP port Jetty listens to by uncommenting that property and changing its value:

http.ini
jetty.http.port=9876

When Jetty is started (or re-started) this configuration is applied and Jetty will listen for clear-text HTTP/1.1 on port 9876.

Adding Your Own Modules
Note
 Refer to the custom module section for the details about how to create your own modules.

You can add your own modules by adding a $JETTY_BASE/modules/*.mod file.

For example, you may want to add a Postgres JDBC driver to the server class-path, to avoid that each deployed web application bring its own version. This allows you to control the exact Postgres JDBC driver version for all web applications.

Create the $JETTY_BASE/modules/postgresql.mod file:

postgresql.mod
link:postgresql.mod[role=include]

Then enable it:

$ java -jar $JETTY_HOME/start.jar --add-modules=postgresql

Enabling the postgresql module will execute the [files] directive (downloading the *.jar file from Maven Central if not already present) and create the $JETTY_BASE/start.d/postgresql.ini with the content of the [ini-template] section.

The [lib] section ensures that the specified file is in the server class-path when Jetty is started.

You can display the Jetty configuration to verify that the server class-path is correct.

Custom Module with JVM Options

Using a custom Jetty module, you can customize the JVM startup options.

This is useful if you need to start Jetty and want to specify JVM options such as:

  • -Xmx, to specify the max heap size

  • -Xlog:gc, to specify the GC log file and options

  • -javaagent, to specify Java agents

  • -XX: options, for example to specify the GC implementation

Start by creating $JETTY_BASE/modules/jvm.mod:

jvm.mod
link:jvm.mod[role=include]

Enable it:

$ java -jar $JETTY_HOME/start.jar --add-modules=jvm

Since the module defines an [exec] section, it will fork another JVM when Jetty is started.

This means that when you start Jetty, there will be two JVMs running: one created by you when you run java -jar $JETTY_HOME/start.jar, and another forked by the Jetty start mechanism with the JVM options you specified (that cannot be applied to an already running JVM).

Again, you can display the JVM command line to verify that it is correct.

Tip

The second JVM forked by the Jetty start mechanism when one of the modules requires forking, for example a module that contains an [exec] section, may not be desirable, and may be avoided as explained in this section.
Displaying the Configuration

Once you have enabled and configured the $JETTY_BASE, you can display the configuration to verify that it is correct.

Using the standard server and http Jetty modules, and the postgresql and jvm custom Jetty module defined above, you obtain:

$ java -jar $JETTY_HOME/start.jar --list-config
link:jetty[role=include]

Note how the configuration displayed above includes:

  • In the list of enabled modules, the postgresql and jvm modules

  • In the list of JVM arguments, those specified by the jvm module

  • In the server class-path, the *.jar file specified by the postgresql module

Displaying the JVM Command Line

The Jetty start mechanism can display a full JVM command line that will start Jetty with the configuration you specified, with the --dry-run option:

$ java -jar $JETTY_HOME/start.jar --dry-run

The full JVM command line generated by --dry-run can be split in various parts that can be used individually, for example in scripts.

Furthermore, Jetty modules may specify the --exec option that will fork a second JVM to start Jetty, which may not be desirable. Some option, such as --jpms, imply --exec, as it won’t be possible to modify the module-path in the already started JVM.

To start Jetty without forking a second JVM, the --dry-run option can be used to generate a command line that is then executed so that starting Jetty only spawns one JVM.

Important
 You can use the --dry-run option as explained below to avoid forking a second JVM when using modules that have the [exec] section, or the --exec option, or when using the --jpms option.

For example, using the --dry-run option with the jvm.mod introduced in this section produces the following command line:

$ java -jar $JETTY_HOME/start.jar --dry-run
link:jetty[role=include]

You can then run the generated command line.

For example, in the Linux bash shell you can run it by wrapping it into $(...):

$ $(java -jar $JETTY_HOME/start.jar --dry-run)

The --dry-run option is quite flexible and below you can find a few examples of how to use it to avoid forking a second JVM, or generating scripts or creating an arguments file that can be passed to (a possibly alternative) java executable.

To display the java executable used to start Jetty:

$ java -jar $JETTY_HOME/start.jar --dry-run=java
link:jetty[role=include]

To display the JVM options:

$ java -jar $JETTY_HOME/start.jar --dry-run=opts
link:jetty[role=include]

To display the JVM class-path:

$ java -jar $JETTY_HOME/start.jar --dry-run=path
link:jetty[role=include]

To display the JVM class-path and module-path, if you want to start Jetty using JPMS with the --jpms option:

$ java -jar $JETTY_HOME/start.jar --jpms --dry-run=path
link:jetty[role=include]

To display the JVM main class:

$ java -jar $JETTY_HOME/start.jar --dry-run=main
link:jetty[role=include]

To display the JVM main class when starting Jetty using JPMS:

$ java -jar $JETTY_HOME/start.jar --jpms --dry-run=main
link:jetty[role=include]

The main class is typically Jetty’s XmlConfiguration class that accepts, as program arguments, a list of properties and a list of Jetty XML files to process. The Jetty XML files compose together the Jetty components that are then configured with the values from the command line properties.

To display the program arguments passed to the main class:

$ java -jar $JETTY_HOME/start.jar --dry-run=args
link:jetty[role=include]

Note how the program arguments are a list of properties in the form <name>=<value> and a list of Jetty XML files.

The various parts of the full JVM command line can be combined to leverage the arguments file feature (that is, specify the JVM options in a file rather than on the command line) that is built-in in the java executable:

$ java -jar $JETTY_HOME/start.jar --dry-run=opts,path,main,args > /tmp/jvm_cmd_line.txt
$ /some/other/java @/tmp/jvm_cmd_line.txt

Using --dry-run=opts,path,main,args can be used to avoid that the Jetty start mechanism forks a second JVM when using modules that require forking:

$ java $(java -jar $JETTY_HOME/start.jar --dry-run=opts,path,main,args)

The output of different --dry-run executions can be creatively combined in a shell script:

$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extraProp=value extra.xml