This is an automated email from the ASF dual-hosted git repository.
markt-asf pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new ebc1b16ae2 Another round of documentation updates for clusters with TLS
ebc1b16ae2 is described below
commit ebc1b16ae2ed34afeb04f3ec6357bbed86dcb952
Author: Mark Thomas <[email protected]>
AuthorDate: Fri Sep 25 16:38:01 2026 +0100
Another round of documentation updates for clusters with TLS
Mainly noting the multicast membership is possible (with significant
caveats). Also expand on the important of the pskKey attribute.
---
webapps/docs/cluster-howto.xml | 6 +++-
webapps/docs/config/cluster-channel.xml | 64 +++++++++++++++++----------------
webapps/docs/config/cluster.xml | 6 +++-
3 files changed, 44 insertions(+), 32 deletions(-)
diff --git a/webapps/docs/cluster-howto.xml b/webapps/docs/cluster-howto.xml
index 92dad0fd46..1125be5734 100644
--- a/webapps/docs/cluster-howto.xml
+++ b/webapps/docs/cluster-howto.xml
@@ -122,7 +122,6 @@
<ul>
<li>OpenSSL-FFM support (Java 22+ and OpenSSL library) or Tomact Native
1.2.17+ must be available to provide the TLS
support.</li>
- <li>The cluster must be configured to use static membership.</li>
<li>The <code>pskKey</code> and <code>pskIdentity</code> attributes of the
<code>Channel</code> must be set to the
same values on each cluster node.</li>
<li>The <code>secure</code> attribute of the <code>Channel</code> must be
set to <code>true</code> on each cluster
@@ -130,6 +129,11 @@
<li>The <code>securePort</code> attribute of the <code>Receiver</code>
must be set.</li>
<li>The <code>securePort</code> attribute of each <code>Member</code> must
be set to match the associated
<code>Receiver</code>.</li>
+ <li>It is recommended that the cluster is configured to use static
membership. It is possible to use TLS in
+ combination with dynamic membership (multicast discovery) but the
network communication that manages the dynamic
+ membership takes place in the clear. If any nodes (including
potentially untrusted nodes) attempt to join a
+ cluster using TLS with dynamic membership without the correct TLS
configuration, it will trigger a significant
+ amount of logging until those nodes stop attempting to join the
cluster.</li>
</ul>
<p>
diff --git a/webapps/docs/config/cluster-channel.xml
b/webapps/docs/config/cluster-channel.xml
index e080a7830d..37e490b413 100644
--- a/webapps/docs/config/cluster-channel.xml
+++ b/webapps/docs/config/cluster-channel.xml
@@ -116,17 +116,32 @@
The default is 5000 (5 seconds).
</attribute>
+ <attribute name="jmxEnabled" required="false">
+ Flag whether the channel components register with JMX or not.
+ The default value is true.
+ </attribute>
+
+ <attribute name="jmxDomain" required="false">
+ if <code>jmxEnabled</code> set to true, specifies the jmx domain which
+ this channel should be registered. The ClusterChannel is used as the
+ default value.
+ </attribute>
+
+ <attribute name="jmxPrefix" required="false">
+ if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
+ will be used with channel ObjectName.
+ </attribute>
+
<attribute name="optionCheck" required="false">
If set to true, the GroupChannel will check the option flags that each
interceptor is using. Reports an error if two interceptor share the
same
flag. The default is false.
</attribute>
- <attribute name="secure" required="false">
- If <code>true</code>, the <code>SEND_OPTIONS_SECURE</code> flag is
added
- to every message. Both <code>pskIdentity</code> and <code>pskKey</code>
- must also be configued for TLS to be enabled. Channel startup fails if
- TLS is unavailable. The default is <code>false</code>.
+ <attribute name="pskDigest" required="false">
+ The message digest algorithm associated with the pre-shared key for
+ TLS 1.3, either <code>SHA256</code> or <code>SHA384</code>. The default
+ is <code>SHA256</code>. This attribute is ignored for TLS 1.2.
</attribute>
<attribute name="pskIdentity" required="false">
@@ -134,18 +149,16 @@
<code>pskKey</code> to enable TLS.
</attribute>
- <attribute name="pskDigest" required="false">
- The message digest algorithm associated with the pre-shared key for
- TLS 1.3, either <code>SHA256</code> or <code>SHA384</code>. The default
- is <code>SHA256</code>. This attribute is ignored for TLS 1.2.
- </attribute>
-
<attribute name="pskKey" required="false">
- The TLS pre-shared key encoded as hexadecimal characters. This must be
- configured together with <code>pskIdentity</code>. The key is not
- exposed through JMX. It should be no longer than 512 bytes for TLS 1.2.
- For TLS 1.3, it must be no longer than 48 bytes. If the value is truely
- random then 32 bytes are sufficient for a 256-bit cipher suite.
+ The TLS pre-shared key encoded as hexadecimal characters. This key is
+ the secret that the security of the TLS cluster communication rests on.
+ If this key is compromised, the security of the cluster is compromised.
+ The key is not exposed through JMX. The key should be no longer than
512
+ bytes for TLS 1.2. For TLS 1.3, it must be no longer than 48 bytes. The
+ key must be sufficiently random for the cipher used (the OpenSSL
default
+ for PSK on the system where Tomcat is running). If the value is truely
+ random then 32 bytes are sufficient for a 256-bit cipher suite. The key
+ must be configured together with <code>pskIdentity</code>.
</attribute>
<attribute name="pskProtocol" required="false">
@@ -154,20 +167,11 @@
<code>TLSv1.3</code>.
</attribute>
- <attribute name="jmxEnabled" required="false">
- Flag whether the channel components register with JMX or not.
- The default value is true.
- </attribute>
-
- <attribute name="jmxDomain" required="false">
- if <code>jmxEnabled</code> set to true, specifies the jmx domain which
- this channel should be registered. The ClusterChannel is used as the
- default value.
- </attribute>
-
- <attribute name="jmxPrefix" required="false">
- if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
- will be used with channel ObjectName.
+ <attribute name="secure" required="false">
+ If <code>true</code>, the <code>SEND_OPTIONS_SECURE</code> flag is
added
+ to every message. Both <code>pskIdentity</code> and <code>pskKey</code>
+ must also be configued for TLS to be enabled. Channel startup fails if
+ TLS is unavailable. The default is <code>false</code>.
</attribute>
</attributes>
diff --git a/webapps/docs/config/cluster.xml b/webapps/docs/config/cluster.xml
index c40aff008e..3e753cb582 100644
--- a/webapps/docs/config/cluster.xml
+++ b/webapps/docs/config/cluster.xml
@@ -52,7 +52,6 @@
<ul>
<li>OpenSSL-FFM support (Java 22+ and OpenSSL library) or Tomact Native
1.2.17+ must be available to provide the TLS
support.</li>
- <li>The cluster must be configured to use static membership.</li>
<li>The <code>pskKey</code> and <code>pskIdentity</code> attributes of the
<code>Channel</code> must be set to the
same values on each cluster node.</li>
<li>The <code>secure</code> attribute of the <code>Channel</code> must be
set to <code>true</code> on each cluster
@@ -60,6 +59,11 @@
<li>The <code>securePort</code> attribute of the <code>Receiver</code>
must be set.</li>
<li>The <code>securePort</code> attribute of each <code>Member</code> must
be set to match the associated
<code>Receiver</code>.</li>
+ <li>It is recommended that the cluster is configured to use static
membership. It is possible to use TLS in
+ combination with dynamic membership (multicast discovery) but the
network communication that manages the dynamic
+ membership takes place in the clear. If any nodes (including
potentially untrusted nodes) attempt to join a
+ cluster using TLS with dynamic membership without the correct TLS
configuration, it will trigger a significant
+ amount of logging until those nodes stop attempting to join the
cluster.</li>
</ul>
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
