<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Common Jetty Configuration</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="quick-start-getting-started.html" title="Chapter&nbsp;2.&nbsp;Using Jetty"><link rel="prev" href="quickstart-running-jetty.html" title="Running Jetty"><link rel="next" href="quickstart-deploying-webapps.html" title="Deploying Web Applications"><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.28-SNAPSHOT</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">Common Jetty Configuration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="quickstart-running-jetty.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;2.&nbsp;Using Jetty<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="quickstart-deploying-webapps.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="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart-common-config"></a>Common Jetty Configuration</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="quickstart-common-config.html#creating-jetty-base">Creating a new Jetty Base</a></span></dt><dt><span class="section"><a href="quickstart-common-config.html#quickstart-changing-jetty-port">Changing the Jetty Port</a></span></dt><dt><span class="section"><a href="quickstart-common-config.html#quickstart-starting-https">Adding SSL for HTTPS &amp; HTTP2</a></span></dt><dt><span class="section"><a href="quickstart-common-config.html#_more_start_jar_options">More start.jar Options</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="creating-jetty-base"></a>Creating a new Jetty Base</h3></div></div></div><p>The <code class="literal">demo-base</code> directory described earlier is an example of the <a class="link" href="startup-base-and-home.html" title="Managing Jetty Base and Jetty Home"><code class="literal">jetty.base</code></a> mechanism.
A Jetty base directory allows the configuration and web applications of a server instance to be stored separately from the Jetty distribution, so that upgrades can be done with minimal disruption.
Jetty&#8217;s default configuration is based on two properties:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">jetty.home</span></dt><dd>The property that defines the location of the Jetty distribution, its libs, default modules and default XML files (typically start.jar, lib, etc).</dd><dt><span class="term">jetty.base</span></dt><dd>The property that defines the location of a specific implementation of a Jetty server, its configuration, logs and web applications (typically start.d/*.ini files, logs and webapps).</dd></dl></div><div class="blockquote"><blockquote class="blockquote"><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="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-plus" aria-hidden="true"></i> Important</h3><p>Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed.
Changes or additions to your configuration should take place in the Jetty Base directory.</p></div></blockquote></div><p>The <code class="literal">jetty.home</code> and <code class="literal">jetty.base</code> properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:</p><div class="screenexample"><pre class="screen">&gt; cd $JETTY_BASE
&gt; java -jar $JETTY_HOME/start.jar</pre></div><p>The following commands create a new base directory, enables both the HTTP connector and the web application deployer modules, and copies a demo webapp to be deployed:</p><div class="screenexample"><pre class="screen">&gt; JETTY_BASE=/tmp/mybase
&gt; mkdir $JETTY_BASE
&gt; cd $JETTY_BASE
&gt; java -jar $JETTY_HOME/start.jar

WARNING: Nothing to start, exiting ...

Usage: java -jar start.jar [options] [properties] [configs]
       java -jar start.jar --help  # for more information

&gt; java -jar $JETTY_HOME/start.jar --create-startd
INFO : Base directory was modified
&gt; java -jar $JETTY_HOME/start.jar --add-to-start=http,deploy

INFO: server          initialised (transitively) in ${jetty.base}/start.d/server.ini
INFO: http            initialised in ${jetty.base}/start.d/http.ini
INFO: security        initialised (transitively) in ${jetty.base}/start.d/security.ini
INFO: servlet         initialised (transitively) in ${jetty.base}/start.d/servlet.ini
INFO: webapp          initialised (transitively) in ${jetty.base}/start.d/webapp.ini
INFO: deploy          initialised in ${jetty.base}/start.d/deploy.ini
MKDIR: ${jetty.base}/webapps
INFO: Base directory was modified

&gt; cp $JETTY_HOME/demo-base/webapps/async-rest.war webapps/ROOT.war
&gt; java -jar $JETTY_HOME/start.jar

2015-06-04 11:10:16.286:INFO::main: Logging initialized @274ms
2015-06-04 11:10:16.440:INFO:oejs.Server:main: jetty-9.3.0.v20150601
2015-06-04 11:10:16.460:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/mybase/webapps/] at interval 1
2015-06-04 11:10:16.581:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2015-06-04 11:10:16.589:INFO:oejw.StandardDescriptorProcessor:main: NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet
2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1a407d53{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.4.28-SNAPSHOT.jar!/META-INF/resources],AVAILABLE}{/ROOT.war}
2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started ServerConnector@3abbfa04{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="quickstart-changing-jetty-port"></a>Changing the Jetty Port</h3></div></div></div><p>You can configure Jetty to run on a different port by setting the <code class="literal">jetty.http.port</code> property on the command line:</p><div class="screenexample"><pre class="screen">&gt; cd $JETTY_BASE
&gt; java -jar $JETTY_HOME/start.jar jetty.http.port=8081
...</pre></div><p>When the server starts, it will now run on port <code class="literal">8081</code>.
It is important to note that setting properties on the command line will only take affect for that instance of the server.
To change the configuration so that the server will always start on the desired port, you will need to edit the <code class="literal">start.d/http.ini</code></p><div class="blockquote"><blockquote class="blockquote"><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>The configuration by properties works via the following chain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">The <code class="literal">start.d/http.ini</code> file is part of the effective command line and contains the <code class="literal">--module=http</code> argument which activates the http module.</li><li class="listitem">The <code class="literal">modules/http.mod</code> file defines the http module which specifies the <code class="literal">etc/jetty-http.xml</code> configuration file and the template ini properties it uses.</li><li class="listitem">The <code class="literal">jetty.http.port</code> property is used by the Property XML element in <code class="literal">etc/jetty.http.xml</code> to inject the <code class="literal">ServerConnector</code> instance with the port.</li></ul></div><p>For more information see the <a class="link" href="quick-start-configure.html" title="Chapter&nbsp;3.&nbsp;An Introduction to Jetty Configuration">Quickstart Configuration Guide</a> and <a class="link" href="configuring-connectors.html" title="Chapter&nbsp;6.&nbsp;Configuring Jetty Connectors">Configuring Connectors</a>.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="quickstart-starting-https"></a>Adding SSL for HTTPS &amp; HTTP2</h3></div></div></div><p>Building on the example above, we can activate additional modules to add support HTTPS and HTTP2 for the server.
To add HTTPS and HTTP2 connectors to a Jetty configuration, the modules can be activated by the following command:</p><div class="screenexample"><pre class="screen">&gt; java -jar $JETTY_HOME/start.jar --add-to-start=https,http2

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  : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
INFO  : alpn            transitively enabled, ini template available with --add-to-start=alpn
INFO  : alpn-impl/alpn-8 dynamic dependency of alpn
INFO  : http2           initialized in ${jetty.base}/start.d/http2.ini
INFO  : https           initialized in ${jetty.base}/start.d/https.ini
INFO  : ssl             transitively enabled, ini template available with --add-to-start=ssl
MKDIR : ${jetty.base}/lib/alpn
DOWNLD: https://repo1.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
MKDIR : ${jetty.base}/etc
COPY  : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO  : Base directory was modified

&gt; java -jar $JETTY_HOME/start.jar
[...]
2017-05-22 12:48:23.271:INFO:oejs.AbstractConnector:main: Started ServerConnector@134d0064{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
[...]</pre></div><p>The <code class="literal">--add-to-start</code> command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">transitively enabled the <code class="literal">ssl</code> module that configures an SSL connector (eg port, keystore etc.) by adding <code class="literal">etc/jetty-ssl.xml</code> and <code class="literal">etc/jetty-ssl-context.xml</code> to the effective command line.</li><li class="listitem">transitively enabled the <code class="literal">alpn</code> module that configures protocol negotiation on the SSL connector by adding <code class="literal">etc/jetty-alpn.xml</code> to the effective command line.</li><li class="listitem">creates <code class="literal">start.d/https.ini</code> that configures the HTTPS protocol on the SSL connector by adding <code class="literal">etc/jetty-https.xml</code> to the effective command line.</li><li class="listitem">creates <code class="literal">start.d/http2.ini</code> that configures the HTTP/2 protocol on the SSL connector by adding <code class="literal">etc/jetty-http2.xml</code> to the effective command line.</li><li class="listitem">checks for the existence of a <code class="literal">etc/keystore</code> file and if not present, downloads a demonstration keystore file.</li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="quickstart-changing-https-port"></a>Changing the Jetty HTTPS Port</h4></div></div></div><p>You can configure the SSL connector to run on a different port by setting the <code class="literal">jetty.ssl.port</code> property on the command line:</p><div class="screenexample"><pre class="screen">&gt; cd $JETTY_BASE
&gt; java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444</pre></div><p>Alternatively, property values can be added to the effective command line built from the <code class="literal">start.ini</code> file or <code class="literal">start.d/*.ini</code> files, depending on your set up.
Please see the section on <a class="link" href="startup-modules.html#start-vs-startd" title="Start.ini vs. Start.d">Start.ini vs. Start.d</a> for more information.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_more_start_jar_options"></a>More start.jar Options</h3></div></div></div><p>The job of the <code class="literal">start.jar</code> is to interpret the command line, <code class="literal">start.ini</code> and <code class="literal">start.d</code> directory (and associated .ini files) to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism.
The <code class="literal">start.jar</code> mechanism has many options which are documented in the <a class="xref" href="startup.html" title="Chapter&nbsp;9.&nbsp;Starting Jetty">Chapter&nbsp;9, <i>Starting Jetty</i></a> administration section and you can see them in summary by using the command:</p><div class="screenexample"><pre class="screen">&gt; java -jar $JETTY_HOME/start.jar --help</pre></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="quickstart-running-jetty.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="quick-start-getting-started.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="quickstart-deploying-webapps.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Running Jetty&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;Deploying Web Applications</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-03-10)</i></span></div></p></body></html>