activemq-artemis/docs/user-manual/web-server.adoc

220 lines
7.9 KiB
Plaintext
Raw Normal View History

ARTEMIS-4383 migrate user docs to AsciiDoc Markdown, which is currently used for user-facing documentation, is good for a lot of things. However, it's not great for the kind of complex documentation we have and our need to produce both multi-page HTML and single-page PDF output via Maven. Markdown lacks features which would make the documentation easier to read, easier to navigate, and just look better overall. The current tool-chain uses honkit and a tool called Calibre. Honkit is written in TypeScript and is installed via NPM. Calibre is a native tool so it must be installed via an OS-specific package manager. All this complexity makes building, releasing, uploading, etc. a pain. AsciiDoc is relatively simple like Markdown, but it has more features for presentation and navigation not to mention Java-based Maven tooling to generate both HTML and PDF. Migrating will improve both the appearance of the documentation as well as the processes to generate and upload it. This commit contains the following changes: - Convert all the Markdown for the User Manual, Migration Guide, and Hacking guide to AsciiDoc via kramdown [1]. - Update the `artemis-website` build to use AsciiDoctor Maven tooling. - Update `RELEASING.md` with simplified instructions. - Update Hacking Guide with simplified instructions. - Use AsciiDoc link syntax in Artemis Maven doc plugin. - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking Guide. All docs will be HTML only except for the User Manual which will have PDF. - Move all docs up out of their respective "en" directory. This was a hold-over from when we had docs in different languages. - Migration & Hacking Guides are now single-page HTML since they are relatively short. - Refactor README.md to simplify and remove redundant content. Benefits of the change: - Much simplified tooling. No more NPM packages or native tools. - Auto-generated table of contents for every chapter. - Auto-generated anchor links for every sub-section. - Overall more appealing presentation. - All docs will use the ActiveMQ favicon. - No more manual line-wrapping! AsciiDoc recommends one sentence per line and paragraphs are separated by a blank line. - AsciiDoctor plugins for IDEA are quite good. - Resulting HTML is less than *half* of the previous size. All previous links/bookmarks should continue to work. [1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
= Embedded Web Server
:idprefix:
:idseparator: -
Apache ActiveMQ Artemis embeds the https://www.eclipse.org/jetty/[Jetty web server].
Its main purpose is to host the xref:management-console.adoc#management-console[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.:
[,xml]
----
<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>
----
=== 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`.
=== Binding
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 xref:masking-passwords.adoc#masking-passwords[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 xref:masking-passwords.adoc#masking-passwords[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`.
=== App
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.
== Request Log
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 https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[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 https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[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 https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[`org.eclipse.jetty.server.CustomRequestLog`] and https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/RequestLogWriter.html[`org.eclipse.jetty.server.RequestLogWriter`] instances.
Default values are based on these implementations.
Here is an example configuration:
[,xml]
----
<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.
[,xml]
----
<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 https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] customizer to handle `X-Forwarded` headers.
Set the `customizer` attribute via the `web` element to enable the https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] customizer, ie:
[,xml]
----
<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.