documentation/9.3.0.v20150612/startup.html - www.eclipse.org/jetty - Git at Google

 <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-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="administration.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="prev" href="administration.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="next" href="startup-xml-config.html" title="Managing XML Based Startup Configuration"><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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.3.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript">  (function() {
             var cx = '016459005284625897022:obd4lsai2ds';
             var gcse = document.createElement('script');
             gcse.type = 'text/javascript';
             gcse.async = true;
             gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
             '//www.google.com/cse/cse.js?cx=' + cx;
             var s = document.getElementsByTagName('script')[0];
             s.parentNode.insertBefore(gcse, s);
             })();
           </script><gcse:search></gcse:search></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="administration.html"><i class="icon-chevron-left"></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="icon-home"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="startup-xml-config.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
       </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><dt><span class="section"><a href="startup.html#startup-overview">Startup Overview</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="startup-base-and-home.html">Managing Jetty Base and Jetty Home</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-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></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><dt><span class="section"><a href="startup.html#d0e7555">Startup Example</a></span></dt></dl></div><p>The <code class="filename">start.jar</code> bootstrap manages the startup of standalone Jetty. It is responsible for:</p><div class="variablelist"><dl><dt><span class="term">Building the classpath</span></dt><dd><p>The <code class="filename">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="filename">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).</p></dd><dt><span class="term">Instantiating the Server Components</span></dt><dd><p>The server and its components are instantiated using either
         Jetty IoC XML or spring. The Jetty server is just a collection of java
         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="filename">start.jar</code>.</p></dd><dt><span class="term">Resolving Server Filesystem Locations</span></dt><dd><p>The <code class="filename">start.jar</code> mechanism resolves
         canonical locations for the <code class="literal">${jetty.home}</code> and the
         <code class="literal">${jetty.base}</code> directories.</p><p>The <code class="literal">${jetty.home}</code> directory is the location of the standard
         distribution of Jetty.</p><p>The <code class="literal">${jetty.base}</code> directory is the location of the local server
         customization and configurations.</p><p>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 the home directory, and thus
         simplifies subsequent server version upgrades.</p></dd><dt><span class="term">Parameterizing the Server Configuration</span></dt><dd><p>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="filename">start.jar</code> mechanism allows you to set parameters
         on the command line or in properties files.</p></dd></dl></div><p>To achieve these start up mechanisms, the <code class="filename">start.jar</code>
   uses:</p><div class="variablelist"><dl><dt><span class="term">Command line arguments</span></dt><dd><p>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.</p></dd><dt><span class="term">INI files</span></dt><dd><p>The
         <code class="filename">start.jar</code> mechanism uses the contents of the <code class="filename">${jetty.base}/start.ini</code>
         and <code class="filename">${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="filename">start.ini</code> file or multiple <code class="filename">start.d/feature.ini</code> files control the configuration of the server.</p></dd><dt><span class="term">Modules</span></dt><dd><p>Instead of explicitly listing all the libraries, properties and
         XML files for a feature, the <code class="filename">start.jar</code> mechanism
         allows you to create modules. You define a module in a
         <code class="filename">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 many
         <code class="literal">--lib=location</code>, feature.xml, name=value arguments
         for a feature and all its dependencies. Modules also use their
         dependencies to control the ordering of libraries and XML
         files.</p></dd><dt><span class="term">XML Files</span></dt><dd><p>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.</p></dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e7555"></a>Startup Example</h3></div></div></div><p>The simplest way to start Jetty is via the
     <code class="filename">start.jar</code> mechanism using the following Java command
     line:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
 [jetty-distribution-9.3.0.v20150612]$ java -jar start.jar --module=http jetty.http.port=8080</pre></div><p>This command uses the <code class="filename">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="filename">${jetty.home}/modules/http.mod</code> file, and includes the
     following:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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="filename">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="filename">${jetty.home}/modules/server.mod</code> file
     includes:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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 t0 use <code class="filename">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="filename">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:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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.3.0.v20150612
  jetty.base=/opt/jetty/jetty-distribution-9.3.0.v20150612
  jetty.version=9.3.0.v20150612

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

 System Properties:
 ------------------
  jetty.home = /opt/jetty/jetty-distribution-9.3.0.v20150612
  jetty.base = /opt/jetty/jetty-distribution-9.3.0.v20150612

 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.3.0.v20150612 | ${jetty.home}/lib/jetty-http-9.3.0.v20150612.jar
  3:               9.3.0.v20150612 | ${jetty.home}/lib/jetty-server-9.3.0.v20150612.jar
  4:               9.3.0.v20150612 | ${jetty.home}/lib/jetty-xml-9.3.0.v20150612.jar
  5:               9.3.0.v20150612 | ${jetty.home}/lib/jetty-util-9.3.0.v20150612.jar
  6:               9.3.0.v20150612 | ${jetty.home}/lib/jetty-io-9.3.0.v20150612.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't want to use the <code class="filename">start.jar</code>
     bootstrap, you can start Jetty using a traditional Java command
     line.</p><p>The following is the equivalent <code class="filename">java</code> command
     line for what the <code class="filename">start.jar</code> bootstrap above
     performs.</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
 [jetty-distribution-9.3.0.v20150612]$ echo jetty.http.port=8080 &gt; /tmp/jetty.properties
 [jetty-distribution-9.3.0.v20150612]$ export JETTY_HOME=`pwd`
 [jetty-distribution-9.3.0.v20150612]$ export JETTY_BASE=`pwd`
 [jetty-distribution-9.3.0.v20150612]$ export JETTY_VERSION="${project.version}"
 [jetty-distribution-9.3.0.v20150612]$ 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="filename">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="filename">start.ini</code> file with the command:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
 [jetty-distribution-9.3.0.v20150612]$ 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="filename">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="administration.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="administration.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="startup-xml-config.html">Next <i class="icon-chevron-right"></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="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Managing XML Based Startup Configuration</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/jetty-project/jetty-documentation">Contribute to this documentation at
                 <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:18-05:00)</i></span></div></p><script 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" type="text/javascript">
   var _gaq = _gaq || [];
   _gaq.push(['_setAccount', 'UA-1149868-7']);
   _gaq.push(['_trackPageview']);

   (function() {
     var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
     ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
     var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
   })();
     </script></body></html>
	<html><head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Chapter 9. Starting Jetty</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="administration.html" title="Part III. Jetty Administration Guide"><link rel="prev" href="administration.html" title="Part III. Jetty Administration Guide"><link rel="next" href="startup-xml-config.html" title="Managing XML Based Startup Configuration"><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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.3.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript"> (function() {
	var cx = '016459005284625897022:obd4lsai2ds';
	var gcse = document.createElement('script');
	gcse.type = 'text/javascript';
	gcse.async = true;
	gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
	'//www.google.com/cse/cse.js?cx=' + cx;
	var s = document.getElementsByTagName('script')[0];
	s.parentNode.insertBefore(gcse, s);
	})();
	</script><gcse:search></gcse:search></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 9. Starting Jetty</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="administration.html"><i class="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Part III. Jetty Administration Guide<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="startup-xml-config.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
	</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="startup"></a>Chapter 9. Starting Jetty</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="startup.html#startup-overview">Startup Overview</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="startup-base-and-home.html">Managing Jetty Base and Jetty Home</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-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></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><dt><span class="section"><a href="startup.html#d0e7555">Startup Example</a></span></dt></dl></div><p>The <code class="filename">start.jar</code> bootstrap manages the startup of standalone Jetty. It is responsible for:</p><div class="variablelist"><dl><dt><span class="term">Building the classpath</span></dt><dd><p>The <code class="filename">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="filename">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).</p></dd><dt><span class="term">Instantiating the Server Components</span></dt><dd><p>The server and its components are instantiated using either
	Jetty IoC XML or spring. The Jetty server is just a collection of java
	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="filename">start.jar</code>.</p></dd><dt><span class="term">Resolving Server Filesystem Locations</span></dt><dd><p>The <code class="filename">start.jar</code> mechanism resolves
	canonical locations for the <code class="literal">${jetty.home}</code> and the
	<code class="literal">${jetty.base}</code> directories.</p><p>The <code class="literal">${jetty.home}</code> directory is the location of the standard
	distribution of Jetty.</p><p>The <code class="literal">${jetty.base}</code> directory is the location of the local server
	customization and configurations.</p><p>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 the home directory, and thus
	simplifies subsequent server version upgrades.</p></dd><dt><span class="term">Parameterizing the Server Configuration</span></dt><dd><p>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="filename">start.jar</code> mechanism allows you to set parameters
	on the command line or in properties files.</p></dd></dl></div><p>To achieve these start up mechanisms, the <code class="filename">start.jar</code>
	uses:</p><div class="variablelist"><dl><dt><span class="term">Command line arguments</span></dt><dd><p>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.</p></dd><dt><span class="term">INI files</span></dt><dd><p>The
	<code class="filename">start.jar</code> mechanism uses the contents of the <code class="filename">${jetty.base}/start.ini</code>
	and <code class="filename">${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="filename">start.ini</code> file or multiple <code class="filename">start.d/feature.ini</code> files control the configuration of the server.</p></dd><dt><span class="term">Modules</span></dt><dd><p>Instead of explicitly listing all the libraries, properties and
	XML files for a feature, the <code class="filename">start.jar</code> mechanism
	allows you to create modules. You define a module in a
	<code class="filename">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 many
	<code class="literal">--lib=location</code>, feature.xml, name=value arguments
	for a feature and all its dependencies. Modules also use their
	dependencies to control the ordering of libraries and XML
	files.</p></dd><dt><span class="term">XML Files</span></dt><dd><p>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.</p></dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e7555"></a>Startup Example</h3></div></div></div><p>The simplest way to start Jetty is via the
	<code class="filename">start.jar</code> mechanism using the following Java command
	line:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
	[jetty-distribution-9.3.0.v20150612]$ java -jar start.jar --module=http jetty.http.port=8080</pre></div><p>This command uses the <code class="filename">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="filename">${jetty.home}/modules/http.mod</code> file, and includes the
	following:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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="filename">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="filename">${jetty.home}/modules/server.mod</code> file
	includes:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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 t0 use <code class="filename">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="filename">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:</p><div class="screenexample"><pre class="screen">[jetty-distribution-9.3.0.v20150612]$ 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.3.0.v20150612
	jetty.base=/opt/jetty/jetty-distribution-9.3.0.v20150612
	jetty.version=9.3.0.v20150612

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

	System Properties:
	------------------
	jetty.home = /opt/jetty/jetty-distribution-9.3.0.v20150612
	jetty.base = /opt/jetty/jetty-distribution-9.3.0.v20150612

	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.3.0.v20150612 \| ${jetty.home}/lib/jetty-http-9.3.0.v20150612.jar
	3: 9.3.0.v20150612 \| ${jetty.home}/lib/jetty-server-9.3.0.v20150612.jar
	4: 9.3.0.v20150612 \| ${jetty.home}/lib/jetty-xml-9.3.0.v20150612.jar
	5: 9.3.0.v20150612 \| ${jetty.home}/lib/jetty-util-9.3.0.v20150612.jar
	6: 9.3.0.v20150612 \| ${jetty.home}/lib/jetty-io-9.3.0.v20150612.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't want to use the <code class="filename">start.jar</code>
	bootstrap, you can start Jetty using a traditional Java command
	line.</p><p>The following is the equivalent <code class="filename">java</code> command
	line for what the <code class="filename">start.jar</code> bootstrap above
	performs.</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
	[jetty-distribution-9.3.0.v20150612]$ echo jetty.http.port=8080 > /tmp/jetty.properties
	[jetty-distribution-9.3.0.v20150612]$ export JETTY_HOME=`pwd`
	[jetty-distribution-9.3.0.v20150612]$ export JETTY_BASE=`pwd`
	[jetty-distribution-9.3.0.v20150612]$ export JETTY_VERSION="${project.version}"
	[jetty-distribution-9.3.0.v20150612]$ 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="filename">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="filename">start.ini</code> file with the command:</p><div class="screenexample"><pre class="screen">[user]$ cd jetty-distribution-9.3.0.v20150612
	[jetty-distribution-9.3.0.v20150612]$ 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="filename">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="administration.html"><i class="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="administration.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="startup-xml-config.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Part III. Jetty Administration Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top"> Managing XML Based Startup Configuration</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/jetty-project/jetty-documentation">Contribute to this documentation at
	<span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:18-05:00)</i></span></div></p><script 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" type="text/javascript">
	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-1149868-7']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();
	</script></body></html>