| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Embedded Web Server</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Embedded Web Server</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.32.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#configuration">1. Configuration</a> |
| <ul class="sectlevel2"> |
| <li><a href="#web">1.1. Web</a></li> |
| <li><a href="#binding">1.2. Binding</a></li> |
| <li><a href="#app">1.3. App</a></li> |
| </ul> |
| </li> |
| <li><a href="#request-log">2. Request Log</a> |
| <ul class="sectlevel2"> |
| <li><a href="#system-properties">2.1. System properties</a></li> |
| </ul> |
| </li> |
| <li><a href="#proxy-forwarding">3. Proxy Forwarding</a></li> |
| <li><a href="#management">4. Management</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache ActiveMQ Artemis embeds the <a href="https://www.eclipse.org/jetty/">Jetty web server</a>. |
| Its main purpose is to host the <a href="management-console.html#management-console">Management Console</a>. |
| However, it can also host other web applications.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">1. Configuration</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The embedded Jetty instance is configured in <code>etc/bootstrap.xml</code> via the <code>web</code> element, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><web</span> <span class="na">path=</span><span class="s">"web"</span><span class="nt">></span> |
| <span class="nt"><binding</span> <span class="na">uri=</span><span class="s">"http://localhost:8161"</span><span class="nt">></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"activemq-branding"</span> <span class="na">war=</span><span class="s">"activemq-branding.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"artemis-plugin"</span> <span class="na">war=</span><span class="s">"artemis-plugin.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"console"</span> <span class="na">war=</span><span class="s">"console.war"</span><span class="nt">/></span> |
| <span class="nt"></binding></span> |
| <span class="nt"></web></span></code></pre> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="web"><a class="anchor" href="#web"></a><a class="link" href="#web">1.1. Web</a></h3> |
| <div class="paragraph"> |
| <p>The <code>web</code> element has the following attributes:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">path</dt> |
| <dd> |
| <p>The name of the subdirectory in which to find the web application archives (i.e. WAR files). |
| This is a subdirectory of the broker’s home or instance directory.</p> |
| </dd> |
| <dt class="hdlist1">customizer</dt> |
| <dd> |
| <p>The name of customizer class to load.</p> |
| </dd> |
| <dt class="hdlist1">rootRedirectLocation</dt> |
| <dd> |
| <p>The location to redirect the requests with the root target.</p> |
| </dd> |
| <dt class="hdlist1">webContentEnabled</dt> |
| <dd> |
| <p>Whether or not the content included in the web folder of the home and the instance directories is accessible. |
| Default is <code>false</code>.</p> |
| </dd> |
| <dt class="hdlist1">maxThreads</dt> |
| <dd> |
| <p>The maximum number of threads the embedded web server can create to service HTTP requests. |
| Default is <code>200</code>.</p> |
| </dd> |
| <dt class="hdlist1">minThreads</dt> |
| <dd> |
| <p>The minimum number of threads the embedded web server will hold to service HTTP requests. |
| Default is <code>8</code> or the value of <code>maxThreads</code> if it is lower.</p> |
| </dd> |
| <dt class="hdlist1">idleThreadTimeout</dt> |
| <dd> |
| <p>The time to wait before terminating an idle thread from the embedded web server. Measured in milliseconds. Default is <code>60000</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="binding"><a class="anchor" href="#binding"></a><a class="link" href="#binding">1.2. Binding</a></h3> |
| <div class="paragraph"> |
| <p>The <code>web</code> element should contain at least one <code>binding</code> element to configure how clients can connect to the web-server. |
| A <code>binding</code> element has the following attributes:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">uri</dt> |
| <dd> |
| <p>The protocol to use (i.e. <code>http</code> or <code>https</code>) as well as the host and port on which to listen. |
| This attribute is required.</p> |
| </dd> |
| <dt class="hdlist1">clientAuth</dt> |
| <dd> |
| <p>Whether or not clients should present an SSL certificate when they connect. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">passwordCodec</dt> |
| <dd> |
| <p>The custom coded to use for unmasking the <code>keystorePassword</code> and <code>trustStorePassword</code>.</p> |
| </dd> |
| <dt class="hdlist1">keyStorePath</dt> |
| <dd> |
| <p>The location on disk of the keystore. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">keyStorePassword</dt> |
| <dd> |
| <p>The password to the keystore. |
| Only applicable when using <code>https</code>. |
| Can be masked using <code>ENC()</code> syntax or by defining <code>passwordCodec</code>. |
| See more in the <a href="masking-passwords.html#masking-passwords">password masking</a> chapter.</p> |
| </dd> |
| <dt class="hdlist1">trustStorePath</dt> |
| <dd> |
| <p>The location on disk for the truststore. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">trustStorePassword</dt> |
| <dd> |
| <p>The password to the truststore. |
| Only applicable when using <code>https</code>. |
| Can be masked using <code>ENC()</code> syntax or by defining <code>passwordCodec</code>. |
| See more in the <a href="masking-passwords.html#masking-passwords">password masking</a> chapter.</p> |
| </dd> |
| <dt class="hdlist1">includedTLSProtocols</dt> |
| <dd> |
| <p>A comma seperated list of included TLS protocols, ie <code>"TLSv1,TLSv1.1,TLSv1.2"</code>. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">excludedTLSProtocols</dt> |
| <dd> |
| <p>A comma seperated list of excluded TLS protocols, ie <code>"TLSv1,TLSv1.1,TLSv1.2"</code>. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">includedCipherSuites</dt> |
| <dd> |
| <p>A comma seperated list of included cipher suites. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">excludedCipherSuites</dt> |
| <dd> |
| <p>A comma seperated list of excluded cipher suites. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">sniHostCheck</dt> |
| <dd> |
| <p>Whether or not the SNI Host name in the client request must match the common name or the subject alternative names in the server certificate. |
| Default is <code>true</code>. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| <dt class="hdlist1">sniRequired</dt> |
| <dd> |
| <p>Whether or not the client request must include an SNI Host name. |
| Default is <code>false</code>. |
| Only applicable when using <code>https</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app"><a class="anchor" href="#app"></a><a class="link" href="#app">1.3. App</a></h3> |
| <div class="paragraph"> |
| <p>Each web application should be defined in an <code>app</code> element inside an <code>binding</code> element. |
| The <code>app</code> element has the following attributes:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">url</dt> |
| <dd> |
| <p>The context to use for the web application.</p> |
| </dd> |
| <dt class="hdlist1">war</dt> |
| <dd> |
| <p>The name of the web application archive on disk.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="request-log"><a class="anchor" href="#request-log"></a><a class="link" href="#request-log">2. Request Log</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>It’s also possible to configure HTTP/S request logging via the <code>request-log</code> element which has the following attributes:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">filename</dt> |
| <dd> |
| <p>The full path of the request log. |
| This attribute is required.</p> |
| </dd> |
| <dt class="hdlist1">append</dt> |
| <dd> |
| <p>Whether or not to append to the existing log or truncate it. |
| Boolean flag.</p> |
| </dd> |
| <dt class="hdlist1">extended</dt> |
| <dd> |
| <p>Whether or not to use the extended request log format. |
| Boolean flag. |
| If <code>true</code> will use the format <code>%{client}a - %u %t "%r" %s %O "%{Referer}i" "%{User-Agent}i"</code>. |
| If <code>false</code> will use the format <code>%{client}a - %u %t "%r" %s %O</code>. |
| Default is <code>false</code>. |
| See the <a href="https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html">format specification</a> for more details.</p> |
| </dd> |
| <dt class="hdlist1">filenameDateFormat</dt> |
| <dd> |
| <p>The log file name date format.</p> |
| </dd> |
| <dt class="hdlist1">retainDays</dt> |
| <dd> |
| <p>The number of days before rotated log files are deleted.</p> |
| </dd> |
| <dt class="hdlist1">ignorePaths</dt> |
| <dd> |
| <p>Request paths that will not be logged. |
| Comma delimited list.</p> |
| </dd> |
| <dt class="hdlist1">format</dt> |
| <dd> |
| <p>Custom format to use. |
| If set this will override <code>extended</code>. |
| See the <a href="https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html">format specification</a> for more details.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>The following options were previously supported, but they were replaced by the <code>format</code>: <code>logCookie</code>, <code>logTimeZone</code>, <code>logDateFormat</code>, <code>logLocale</code>, <code>logLatency</code>, <code>logServer</code>, <code>preferProxiedForAddress</code>. |
| All these options are now deprecated and ignored.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These attributes are essentially passed straight through to the underlying <a href="https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html"><code>org.eclipse.jetty.server.CustomRequestLog</code></a> and <a href="https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/RequestLogWriter.html"><code>org.eclipse.jetty.server.RequestLogWriter</code></a> instances. |
| Default values are based on these implementations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here is an example configuration:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><web</span> <span class="na">path=</span><span class="s">"web"</span><span class="nt">></span> |
| <span class="nt"><binding</span> <span class="na">uri=</span><span class="s">"http://localhost:8161"</span><span class="nt">></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"activemq-branding"</span> <span class="na">war=</span><span class="s">"activemq-branding.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"artemis-plugin"</span> <span class="na">war=</span><span class="s">"artemis-plugin.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"console"</span> <span class="na">war=</span><span class="s">"console.war"</span><span class="nt">/></span> |
| <span class="nt"></binding></span> |
| <span class="nt"><request-log</span> <span class="na">filename=</span><span class="s">"${artemis.instance}/log/http-access-yyyy_MM_dd.log"</span> <span class="na">append=</span><span class="s">"true"</span> <span class="na">extended=</span><span class="s">"true"</span><span class="nt">/></span> |
| <span class="nt"></web></span></code></pre> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="system-properties"><a class="anchor" href="#system-properties"></a><a class="link" href="#system-properties">2.1. System properties</a></h3> |
| <div class="paragraph"> |
| <p>It is possible to use system properties to add or update web configuration items. |
| If you define a system property starting with "webconfig." it will be parsed at the startup to update the web configuration.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To enable the client authentication for an existing binding with the name <code>artemis</code>, set the system property <code>webconfig.bindings.artemis.clientAuth</code> to <code>true</code>, i.e.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">java -Dwebconfig.bindings.artemis.clientAuth=true</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To add a new binding or app set the new binding or app attributes using their new names, i.e.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">java -Dwebconfig.bindings.my-binding.uri=http://localhost:8162 |
| java -Dwebconfig.bindings.my-binding.apps.my-app.uri=my-app |
| java -Dwebconfig.bindings.my-binding.apps.my-app.war=my-app.war</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To update a binding without a name use its uri and to update an app without a name use its url , i.e.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><web</span> <span class="na">path=</span><span class="s">"web"</span><span class="nt">></span> |
| <span class="nt"><binding</span> <span class="na">uri=</span><span class="s">"http://localhost:8161"</span><span class="nt">></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"activemq-branding"</span> <span class="na">war=</span><span class="s">"activemq-branding.war"</span><span class="nt">/></span> |
| ...</code></pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">java -Dwebconfig.bindings."http://localhost:8161".clientAuth=true</pre> |
| </div> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">java -Dwebconfig.bindings."http://localhost:8161".apps."activemq-branding".war=my-branding.war</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="proxy-forwarding"><a class="anchor" href="#proxy-forwarding"></a><a class="link" href="#proxy-forwarding">3. Proxy Forwarding</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The proxies and load balancers usually support <code>X-Forwarded</code> headers to send information altered or lost when a proxy is involved in the path of the request. |
| Jetty supports the <a href="https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html"><code>ForwardedRequestCustomizer</code></a> customizer to handle <code>X-Forwarded</code> headers. |
| Set the <code>customizer</code> attribute via the <code>web</code> element to enable the <a href="https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html"><code>ForwardedRequestCustomizer</code></a> customizer, ie:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><web</span> <span class="na">path=</span><span class="s">"web"</span> <span class="na">customizer=</span><span class="s">"org.eclipse.jetty.server.ForwardedRequestCustomizer"</span><span class="nt">></span> |
| <span class="nt"><binding</span> <span class="na">uri=</span><span class="s">"http://localhost:8161"</span><span class="nt">></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"activemq-branding"</span> <span class="na">war=</span><span class="s">"activemq-branding.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"artemis-plugin"</span> <span class="na">war=</span><span class="s">"artemis-plugin.war"</span><span class="nt">/></span> |
| <span class="nt"><app</span> <span class="na">url=</span><span class="s">"console"</span> <span class="na">war=</span><span class="s">"console.war"</span><span class="nt">/></span> |
| <span class="nt"></binding></span> |
| <span class="nt"></web></span></code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="management"><a class="anchor" href="#management"></a><a class="link" href="#management">4. Management</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The embedded web server can be stopped, started, or restarted via any available management interface via the <code>stopEmbeddedWebServer</code>, <code>starteEmbeddedWebServer</code>, and <code>restartEmbeddedWebServer</code> operations on the <code>ActiveMQServerControl</code> respectively.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
