Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
activemq-artemis/docs/user-manual/en/web-server.md

7.8 KiB
Raw Blame History

Embedded Web Server

Apache ActiveMQ Artemis embeds the Jetty web server. Its main purpose is to host the Management Console. However, it can also host other web applications.

Configuration

The embedded Jetty instance is configured in etc/bootstrap.xml via the web element, e.g.:

<web path="web">
   <binding uri="http://localhost:8161">
      <app url="activemq-branding" war="activemq-branding.war"/>
      <app url="artemis-plugin" war="artemis-plugin.war"/>
      <app url="console" war="console.war"/>
   </binding>
</web>

The web element has the following attributes:

  • path 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.
  • customizer The name of customizer class to load.
  • rootRedirectLocation The location to redirect the requests with the root target.
  • webContentEnabled Whether or not the content included in the web folder of the home and the instance directories is accessible. Default is false.

The web element should contain at least one binding element to configure how clients can connect to the web-server. A binding element has the following attributes:

  • uri The protocol to use (i.e. http or https) as well as the host and port on which to listen. This attribute is required.
  • clientAuth Whether or not clients should present an SSL certificate when they connect. Only applicable when using https.
  • passwordCodec The custom coded to use for unmasking the keystorePassword and trustStorePassword.
  • keyStorePath The location on disk of the keystore. Only applicable when using https.
  • keyStorePassword The password to the keystore. Only applicable when using https. Can be masked using ENC() syntax or by defining passwordCodec. See more in the password masking chapter.
  • trustStorePath The location on disk for the truststore. Only applicable when using https.
  • trustStorePassword The password to the truststore. Only applicable when using https. Can be masked using ENC() syntax or by defining passwordCodec. See more in the password masking chapter.
  • includedTLSProtocols A comma seperated list of included TLS protocols, ie "TLSv1,TLSv1.1,TLSv1.2". Only applicable when using https.
  • excludedTLSProtocols A comma seperated list of excluded TLS protocols, ie "TLSv1,TLSv1.1,TLSv1.2". Only applicable when using https.
  • includedCipherSuites A comma seperated list of included cipher suites. Only applicable when using https.
  • excludedCipherSuites A comma seperated list of excluded cipher suites. Only applicable when using https.
  • sniHostCheck 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 true. Only applicable when using https.
  • sniRequired Whether or not the client request must include an SNI Host name. Default is false. Only applicable when using https.

Each web application should be defined in an app element inside an binding element. The app element has the following attributes:

  • url The context to use for the web application.
  • war The name of the web application archive on disk.

It's also possible to configure HTTP/S request logging via the request-log element which has the following attributes:

  • filename The full path of the request log. This attribute is required.
  • append Whether or not to append to the existing log or truncate it. Boolean flag.
  • extended Whether or not to use the extended request log format. Boolean flag. If true will use the format %{client}a - %u %t "%r" %s %O "%{Referer}i" "%{User-Agent}i". If false will use the format %{client}a - %u %t "%r" %s %O. Default is false. See the format specification for more details.
  • filenameDateFormat The log file name date format.
  • retainDays The number of days before rotated log files are deleted.
  • ignorePaths Request paths that will not be logged. Comma delimited list.
  • format Custom format to use. If set this will override extended. See the format specification for more details.

The following options were previously supported, but they were replaced by the format: logCookie, logTimeZone, logDateFormat, logLocale, logLatency, logServer, preferProxiedForAddress. All these options are now deprecated and ignored.

These attributes are essentially passed straight through to the underlying org.eclipse.jetty.server.CustomRequestLog and org.eclipse.jetty.server.RequestLogWriter instances. Default values are based on these implementations.

Here is an example configuration:

<web path="web">
   <binding uri="http://localhost:8161">
      <app url="activemq-branding" war="activemq-branding.war"/>
      <app url="artemis-plugin" war="artemis-plugin.war"/>
      <app url="console" war="console.war"/>
   </binding>
   <request-log filename="${artemis.instance}/log/http-access-yyyy_MM_dd.log" append="true" extended="true"/>
</web>

System properties

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.

To enable the client authentication for an existing binding with the name artemis, set the system property webconfig.bindings.artemis.clientAuth to true, i.e.

java -Dwebconfig.bindings.artemis.clientAuth=true

To add a new binding or app set the new binding or app attributes using their new names, i.e.

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

To update a binding without a name use its uri and to update an app without a name use its url , i.e.

<web path="web">
  <binding uri="http://localhost:8161">
    <app url="activemq-branding" war="activemq-branding.war"/>
...

java -Dwebconfig.bindings."http://localhost:8161".clientAuth=true

java -Dwebconfig.bindings."http://localhost:8161".apps."activemq-branding".war=my-branding.war

Proxy Forwarding

The proxies and load balancers usually support X-Forwarded headers to send information altered or lost when a proxy is involved in the path of the request. Jetty supports the ForwardedRequestCustomizer customizer to handle X-Forwarded headers. Set the customizer attribute via the web element to enable the ForwardedRequestCustomizer customizer, ie:

<web path="web" customizer="org.eclipse.jetty.server.ForwardedRequestCustomizer">
   <binding uri="http://localhost:8161">
      <app url="activemq-branding" war="activemq-branding.war"/>
      <app url="artemis-plugin" war="artemis-plugin.war"/>
      <app url="console" war="console.war"/>
   </binding>
</web>

Management

The embedded web server can be stopped, started, or restarted via any available management interface via the stopEmbeddedWebServer, starteEmbeddedWebServer, and restartEmbeddedWebServer operations on the ActiveMQServerControl respectively.