You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@zookeeper.apache.org by "anmolnar (via GitHub)" <gi...@apache.org> on 2026/05/19 16:45:46 UTC
[PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
anmolnar opened a new pull request, #2389:
URL: https://github.com/apache/zookeeper/pull/2389
(no comment)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar merged PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3455493756
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
+
+#### Default Security Posture
+
+The default AdminServer configuration is intended for ease of use in trusted environments, but it is **not secure for
Review Comment:
what do you mean by that?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4492565883
fwiw claude says:
----
Documentation Files
┌────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ File │ Change Needed │
├────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ │ Required Software (line ~128): Update "release 1.8 or greater (JDK 8 LTS, JDK 11 LTS, JDK 12 - Java 9 │
│ zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md │ and 10 are not supported)" → state JDK 17 as the new minimum/default. Also review TLS cipher suites │
│ │ section (~line 1742/1899) which documents Java 8 vs Java 9+ behavior differences — some of that │
│ │ context may become irrelevant. │
├────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ README.md │ Line ~42-45: Remove/update the "If you are going to compile with Java 1.8, you should use a recent │
│ │ release at u211 or above" caveat — no longer applicable. │
├────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ zookeeper-docs/src/main/resources/markdown/zookeeperStarted.md │ No direct version text, but it delegates to zookeeperAdmin.md — verify the link/reference still makes │
│ │ sense after the above change. │
└────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────┘
Build/CI Files (not prose docs, but tightly coupled)
┌────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ File │ Change Needed │
├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ pom.xml │ maven.compiler.source, maven.compiler.target (currently 1.8), and maven.compiler.release (currently 8) → update to 17. │
├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ .github/workflows/ci.yaml │ Remove/replace full-build-jdk8 matrix profile; make JDK 17 the primary matrix entry. │
├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ .github/workflows/e2e.yaml │ jdk: [8, 11] → replace 8 with 17 (or [17, 21]). │
└────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
---
The single most impactful documentation edit is zookeeperAdmin.md line ~128 — that's the canonical "required software" statement users and operators reference. The pom.xml
and CI workflow changes are mechanical but required to make the claim true.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4773170546
Thank you guys for the reviews. If I got it right, we should not make Admin Server disabled by default on branches other than the `master`. Which means I need to carefully backport this patch with the text "reversed" and referring to the enabled behavior.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3269778628
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
+
+#### Default Security Posture
+
+The default AdminServer configuration is intended for ease of use in trusted environments, but it is **not secure for
Review Comment:
shouldn't we err on the side of security instead? (see prev line comment)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4751711996
Thanks @eolivelli !
I think we can leave the default setting enabled on other branches and backport this patch without the code change.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3455490827
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
+
+#### Default Security Posture
+
+The default AdminServer configuration is intended for ease of use in trusted environments, but it is **not secure for
+exposure to untrusted networks**.
+
+Default settings include:
+
+* `admin.enableServer=true`
+* `admin.serverAddress=0.0.0.0`
+* `admin.serverPort=8080`
+* `admin.forceHttps=false`
+* `admin.needClientAuth=false`
+
+With these defaults:
+
+* All traffic is transmitted in clear text over HTTP.
+* Administrative data, including configuration and runtime details, can be viewed by anyone with network access.
+* Many commands (such as `stat`, `srvr`, `conf`, and `cons`) do not require authentication.
+* Sensitive operational information may be disclosed.
+* In some environments, unrestricted administrative access can increase the impact of vulnerabilities or misconfiguration.
+
+#### Recommended Deployment Practices
+
+Administrators should ensure that the AdminServer is accessible only to authorized users.
+
+##### Option 1: Restrict Access with Firewall Rules (Minimum Recommendation)
+
+Limit access to the AdminServer port to trusted hosts or management networks only.
+
+Examples:
+
+* Bind the server to localhost:
+
+ ```properties
+ admin.serverAddress=127.0.0.1
+ ```
+* Use host-based firewall rules (such as `iptables`, `firewalld`, or cloud security groups) to allow access only from
+* administrative systems.
+
+This is the minimum recommended protection when HTTPS and client authentication are not enabled.
+
+##### Option 2: Enable HTTPS
+
+To encrypt all communication, configure SSL/TLS and force HTTPS:
+
+```properties
+admin.forceHttps=true
+```
+
+This prevents credentials and administrative data from being transmitted in clear text. ZooKeeper supports configuring
+the AdminServer with TLS certificates and trust stores.
+
+##### Option 3: Require Client Authentication
+
+To restrict access to trusted clients using X.509 certificates:
+
+```properties
+admin.needClientAuth=true
+```
+
+When enabled, only clients presenting valid certificates trusted by the server will be allowed to connect.
+
+#### Recommended Secure Configuration
+
+For production environments, the following configuration is strongly recommended:
+
+```properties
+admin.forceHttps=true
+admin.needClientAuth=true
+admin.serverAddress=<management-network-ip>
+```
+
+In addition, restrict access to the AdminServer port using firewall rules.
+
+#### Disable the AdminServer If Not Needed
Review Comment:
I think this is also done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3455487070
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
Review Comment:
it's done
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3269776158
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
Review Comment:
given these issues why wouldn't this be disabled by default?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4492251098
It's not clear to me (and I don't see here nor in the references JIRA) why we wouldn't just flip this and disable by default, include the excellent new docs you've added, and put the burden on the user to ensure the requisite security enforcement prior to enabling/overriding? I think this would be fine and "backward compatible" given the user can make a change via config at runtime - we could include such details in the release notes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4493411243
@eolivelli PTAL.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Enhance documentation of AdminServer to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on code in PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#discussion_r3269783098
##########
zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md:
##########
@@ -2719,7 +2719,106 @@ The AdminServer is enabled by default, but can be disabled by either:
Note that the TCP four-letter word interface is still available if
the AdminServer is disabled.
-##### Configuring AdminServer for SSL/TLS
+#### Security Considerations
+
+> **Important:** The AdminServer is enabled by default and listens on all network interfaces (`0.0.0.0`) on port `8080`
+> unless explicitly configured otherwise. By default, communication is **unencrypted (HTTP)** and **client authentication
+> is disabled**. Most administrative commands can be executed by any client that can connect to the AdminServer.
+
+#### Default Security Posture
+
+The default AdminServer configuration is intended for ease of use in trusted environments, but it is **not secure for
+exposure to untrusted networks**.
+
+Default settings include:
+
+* `admin.enableServer=true`
+* `admin.serverAddress=0.0.0.0`
+* `admin.serverPort=8080`
+* `admin.forceHttps=false`
+* `admin.needClientAuth=false`
+
+With these defaults:
+
+* All traffic is transmitted in clear text over HTTP.
+* Administrative data, including configuration and runtime details, can be viewed by anyone with network access.
+* Many commands (such as `stat`, `srvr`, `conf`, and `cons`) do not require authentication.
+* Sensitive operational information may be disclosed.
+* In some environments, unrestricted administrative access can increase the impact of vulnerabilities or misconfiguration.
+
+#### Recommended Deployment Practices
+
+Administrators should ensure that the AdminServer is accessible only to authorized users.
+
+##### Option 1: Restrict Access with Firewall Rules (Minimum Recommendation)
+
+Limit access to the AdminServer port to trusted hosts or management networks only.
+
+Examples:
+
+* Bind the server to localhost:
+
+ ```properties
+ admin.serverAddress=127.0.0.1
+ ```
+* Use host-based firewall rules (such as `iptables`, `firewalld`, or cloud security groups) to allow access only from
+* administrative systems.
+
+This is the minimum recommended protection when HTTPS and client authentication are not enabled.
+
+##### Option 2: Enable HTTPS
+
+To encrypt all communication, configure SSL/TLS and force HTTPS:
+
+```properties
+admin.forceHttps=true
+```
+
+This prevents credentials and administrative data from being transmitted in clear text. ZooKeeper supports configuring
+the AdminServer with TLS certificates and trust stores.
+
+##### Option 3: Require Client Authentication
+
+To restrict access to trusted clients using X.509 certificates:
+
+```properties
+admin.needClientAuth=true
+```
+
+When enabled, only clients presenting valid certificates trusted by the server will be allowed to connect.
+
+#### Recommended Secure Configuration
+
+For production environments, the following configuration is strongly recommended:
+
+```properties
+admin.forceHttps=true
+admin.needClientAuth=true
+admin.serverAddress=<management-network-ip>
+```
+
+In addition, restrict access to the AdminServer port using firewall rules.
+
+#### Disable the AdminServer If Not Needed
Review Comment:
we could flip this (see prev comments) and say to enable if needed?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "anmolnar (via GitHub)" <gi...@apache.org>.
anmolnar commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4744862966
@phunt @eolivelli I've updated the ticket and the patch to disable Admin Server in the default configuration. Also modified the docs accordingly. PTAL.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] ZOOKEEPER-5050. Disable AdminServer and enhance documentation to highlight security considerations [zookeeper]
Posted by "phunt (via GitHub)" <gi...@apache.org>.
phunt commented on PR #2389:
URL: https://github.com/apache/zookeeper/pull/2389#issuecomment-4773147912
lgtm - +1. Having this off by default with clear documentation on how to enable safely is great to see. Thanks Andor.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@zookeeper.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org