jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc - jetty - Git at Google

 //  ========================================================================
 //  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.
 //  ========================================================================

 [[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.

 [source, screen, subs="{sub-order}"]
 ....
 [jetty-distribution-{VERSION}]$ java -jar start.jar
 2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION}
 ...
 ....

 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.

 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 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]).

 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.

 [[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:
 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).
 * 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.

 ==== start.jar Command Line Options

 --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.
 --list-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.
 --debug::
 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.
 --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.
 --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.`
 --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.
 --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.

 [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}`.
 +
 [source, screen, subs="{sub-order}"]
 ....
 # generate module.dot
 $ 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.

 --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.
 +
 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.

 ===== Advanced Commands

 --lib=<classpath>::
 Add arbitrary classpath entries to the the server classpath.

 --include-jetty-dir=<path>::
 Include an extra Jetty directory to use as a source for configuration details.
 This directory behaves similarly to `${jetty.base}` but sits at a layer between `${jetty.base}` and `${jetty.home}`.
 This allows for some complex hierarchies of configuration details.

 --download=<http-uri>|<location>::
 If the file does not exist at the given location, download it from the given http URI.
 Note: location is always relative to `${jetty.base}`.
 You might need to escape the slash "\|" to use this on some environments.
	// ========================================================================
	// 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.
	// ========================================================================

	[[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.

	[source, screen, subs="{sub-order}"]
	....
	[jetty-distribution-{VERSION}]$ java -jar start.jar
	2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION}
	...
	....

	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.

	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 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]).

	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.

	[[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:
	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).
	* 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.

	==== start.jar Command Line Options

	--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.
	--list-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.
	--debug::
	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.
	--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.
	--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.`
	--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.
	--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.

	[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}`.
	+
	[source, screen, subs="{sub-order}"]
	....
	# generate module.dot
	$ 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.

	--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.
	+
	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.

	===== Advanced Commands

	--lib=<classpath>::
	Add arbitrary classpath entries to the the server classpath.

	--include-jetty-dir=<path>::
	Include an extra Jetty directory to use as a source for configuration details.
	This directory behaves similarly to `${jetty.base}` but sits at a layer between `${jetty.base}` and `${jetty.home}`.
	This allows for some complex hierarchies of configuration details.

	--download=<http-uri>\|<location>::
	If the file does not exist at the given location, download it from the given http URI.
	Note: location is always relative to `${jetty.base}`.
	You might need to escape the slash "\\|" to use this on some environments.