<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Chapter&nbsp;9.&nbsp;Starting Jetty</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="jetty-admin-guide.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="prev" href="jetty-admin-guide.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="next" href="start-jar.html" title="Using start.jar"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.4.27.v20200227</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;9.&nbsp;Starting Jetty</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jetty-admin-guide.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;III.&nbsp;Jetty Administration Guide<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="start-jar.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
      </p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="startup"></a>Chapter&nbsp;9.&nbsp;Starting Jetty</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="startup.html#startup-overview">Startup Overview</a></span></dt><dt><span class="section"><a href="start-jar.html">Using start.jar</a></span></dt><dt><span class="section"><a href="startup-base-and-home.html">Managing Jetty Base and Jetty Home</a></span></dt><dt><span class="section"><a href="startup-classpath.html">Managing Server Classpath</a></span></dt><dt><span class="section"><a href="startup-modules.html">Managing Startup Modules</a></span></dt><dt><span class="section"><a href="custom-modules.html">Custom Modules</a></span></dt><dt><span class="section"><a href="startup-xml-config.html">Managing XML Based Startup Configuration</a></span></dt><dt><span class="section"><a href="startup-unix-service.html">Startup a Unix Service using jetty.sh</a></span></dt><dt><span class="section"><a href="startup-windows-service.html">Startup via Windows Service</a></span></dt><dt><span class="section"><a href="startup-jpms.html">Startup using the Java Platform Module System (JPMS)</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="startup-overview"></a>Startup Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="startup.html#_startup_example">Startup Example</a></span></dt></dl></div><p>The <code class="literal">start.jar</code> bootstrap manages the startup of standalone Jetty.
It is responsible for:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Building the classpath</span></dt><dd>The <code class="literal">start.jar</code> bootstrap builds a classpath for all the required Jetty features and their dependencies.
It builds the classpath using  either the <code class="literal">--lib</code> option to <code class="literal">start.jar</code> to add an individual  classpath entry, or with the <code class="literal">--module</code> option that includes all the  libs and their dependencies for a module (a named Jetty feature).</dd><dt><span class="term">Instantiating the Server Components</span></dt><dd>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 <code class="literal">start.jar</code>.</dd><dt><span class="term">Resolving Server Filesystem Locations</span></dt><dd>The <code class="literal">start.jar</code> mechanism resolves canonical locations for the <code class="literal">${jetty.home}</code> and the <code class="literal">${jetty.base}</code> directories.
The <code class="literal">${jetty.home}</code> directory is the location of the standard distribution of Jetty.
The <code class="literal">${jetty.base}</code> 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.</dd><dt><span class="term">Parameterizing the Server Configuration</span></dt><dd>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 <code class="literal">start.jar</code> mechanism allows you to set parameters on the command line or in properties files.</dd></dl></div><p>To achieve these start up mechanisms, the <code class="literal">start.jar</code> uses:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Command line arguments</span></dt><dd>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.</dd><dt><span class="term">INI files</span></dt><dd>The <code class="literal">start.jar</code> mechanism uses the contents of the <code class="literal">${jetty.base}/start.ini</code> and <code class="literal">${jetty.base}/start.d/*.ini</code> files with each line equivalent to a <code class="literal">start.jar</code> command line argument.
This means that either a global <code class="literal">start.ini</code> file or multiple <code class="literal">start.d/feature.ini</code> files control the configuration of the server.</dd></dl></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>It is important to chose <span class="strong"><strong>either</strong></span> <code class="literal">${jetty.base}/start.ini</code> or <code class="literal">${jetty.base}/start.d/*.ini</code> to manage configuration.
Using both is not recommended and can lead to issues with your server.</p></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Modules</span></dt><dd>Instead of explicitly listing all the libraries, properties and XML files for a feature, the <code class="literal">start.jar</code> mechanism allows you to create  modules.
A module is defined in a <code class="literal">modules/*.mod</code> file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
Thus you can use a single <code class="literal">--module=name</code> command line option as the equivalent of specifying  <code class="literal">--lib=location</code>, <code class="literal">feature.xml</code> or <code class="literal">name=value</code> 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&#8230;&#8203;etc.
These module files should <span class="strong"><strong>only</strong></span> be edited if you are making structural changes to the way the feature will perform.
For more information, refer to the section on <a class="link" href="startup-modules.html" title="Managing Startup Modules">managing startup modules</a> later in this chapter.</dd><dt><span class="term">XML Files</span></dt><dd>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.</dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_startup_example"></a>Startup Example</h3></div></div></div><p>The simplest way to start Jetty is via the <code class="literal">start.jar</code> mechanism using the following Java command line:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.4.27.v20200227
[jetty-distribution-9.4.27.v20200227]$ java -jar start.jar --module=http jetty.http.port=8080</pre></div><p>This command uses the <code class="literal">start.jar</code> mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the <code class="literal">http</code> module.
Specifically the <code class="literal">http</code> module is defined in the <code class="literal">${jetty.home}/modules/http.mod</code> file, and includes the following:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.4.27.v20200227]$ cat modules/http.mod
[depend]
server

[xml]
etc/jetty-http.xml

[ini-template]
jetty.http.port=8080
http.timeout=30000</pre></div><p>The <code class="literal">http</code> module declares that <code class="literal">http</code> depends on the server module, uses the <code class="literal">jetty-http.xml</code> file, and can be parameterized with <code class="literal">jetty.http.port</code> and <code class="literal">http.timeout</code> parameters.
The INI-template section is not actually used by the command above, so the <code class="literal">jetty.http.port</code> must still be defined on the command line.</p><p>Following the server dependency, the <code class="literal">${jetty.home}/modules/server.mod</code> file includes:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.4.27.v20200227]$ cat modules/server.mod
[lib]
lib/servlet-api-3.1.jar
lib/jetty-http-${jetty.version}.jar
lib/jetty-server-${jetty.version}.jar
lib/jetty-xml-${jetty.version}.jar
lib/jetty-util-${jetty.version}.jar
lib/jetty-io-${jetty.version}.jar

[xml]
etc/jetty.xml

[ini-template]
threads.min=10
threads.max=200</pre></div><p>The <code class="literal">server</code> module declares the libraries the server needs and to use <code class="literal">jetty.xml</code> file.
The combined metadata of the <code class="literal">http</code> and <code class="literal">server</code> modules results in <code class="literal">start.jar</code> generating the effective Java command line required to start Jetty.</p><p>Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.4.27.v20200227]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config

Java Environment:
-----------------
 java.home=/user/lib/jvm/jdk-7u21-x64/jre
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.25-b01
 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.7.0_25-b15
 java.io.tmpdir=/tmp

Jetty Environment:
-----------------
 jetty.home=/opt/jetty/jetty-distribution-9.4.27.v20200227
 jetty.base=/opt/jetty/jetty-distribution-9.4.27.v20200227
 jetty.version=9.4.27.v20200227

JVM Arguments:
--------------
 (no jvm args specified)

System Properties:
------------------
 jetty.home = /opt/jetty/jetty-distribution-9.4.27.v20200227
 jetty.base = /opt/jetty/jetty-distribution-9.4.27.v20200227

Properties:
-----------
 jetty.http.port = 9099

Jetty Server Classpath:
-----------------------
Version Information on 7 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
      changes to the --module=name command line options will be reflected here.
 0:                    3.1.0 | ${jetty.home}/lib/servlet-api-3.1.jar
 1:                  3.1.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
 2:               9.4.27.v20200227 | ${jetty.home}/lib/jetty-http-9.4.27.v20200227.jar
 3:               9.4.27.v20200227 | ${jetty.home}/lib/jetty-server-9.4.27.v20200227.jar
 4:               9.4.27.v20200227 | ${jetty.home}/lib/jetty-xml-9.4.27.v20200227.jar
 5:               9.4.27.v20200227 | ${jetty.home}/lib/jetty-util-9.4.27.v20200227.jar
 6:               9.4.27.v20200227 | ${jetty.home}/lib/jetty-io-9.4.27.v20200227.jar

Jetty Active XMLs:
------------------
 ${jetty.home}/etc/jetty.xml
 ${jetty.home}/etc/jetty-http.xml</pre></div><p>This represents the entirety of the configuration that is applied to start Jetty.</p><p>If you don&#8217;t want to use the <code class="literal">start.jar</code> bootstrap, you can start Jetty using a traditional Java command line.</p><p>The following is the equivalent Java command line for what the <code class="literal">start.jar</code> bootstrap above performs.</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.4.27.v20200227
[jetty-distribution-9.4.27.v20200227]$ echo jetty.http.port=8080 &gt; /tmp/jetty.properties
[jetty-distribution-9.4.27.v20200227]$ export JETTY_HOME=`pwd`
[jetty-distribution-9.4.27.v20200227]$ export JETTY_BASE=`pwd`
[jetty-distribution-9.4.27.v20200227]$ export JETTY_VERSION="${project.version}"
[jetty-distribution-9.4.27.v20200227]$ java -Djetty.home=$JETTY_HOME \
-Djetty.base=$JETTY_BASE \
-cp \
 $JETTY_HOME/lib/servlet-api-3.1.jar\
:$JETTY_HOME/lib/jetty-schemas-3.1.jar\
:$JETTY_HOME/lib/jetty-http-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-server-$JETTY_VERSION.jar \
:$JETTY_HOME/lib/jetty-xml-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-io-$JETTY_VERSION.jar\
org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml</pre></div><p>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 <code class="literal">jetty.properties</code> file.</p><p>You can further simplify the startup of this server by using the INI template defined by the modules to create a <code class="literal">start.ini</code> file with the command:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.4.27.v20200227
[jetty-distribution-9.4.27.v20200227]$ mkdir example-base
[example-base]$ cd example-base
[example-base]$ ls -la
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 ./
drwxrwxr-x 12 user webgroup 4096 Oct  4 11:49 ../
-rw-rw-r--  1 user webgroup  250 Oct  4 11:55 start.ini</pre></div><p>Once complete, you can edit the <code class="literal">start.ini</code> file to modify any parameters and you can run the server with the simple command:</p><div class="screenexample"><pre class="screen">[example-base]$ java -jar $JETTY_HOME/start.jar</pre></div></div></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jetty-admin-guide.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jetty-admin-guide.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="start-jar.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Part&nbsp;III.&nbsp;Jetty Administration Guide&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Using start.jar</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-02-27)</i></span></div></p></body></html>