zookeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From f..@apache.org
Subject zookeeper git commit: ZOOKEEPER-2635: Regenerate documentation (fpj)
Date Sun, 11 Dec 2016 21:33:34 GMT
Repository: zookeeper
Updated Branches:
  refs/heads/branch-3.5 3119a194a -> e99c68316

ZOOKEEPER-2635: Regenerate documentation (fpj)

Project: http://git-wip-us.apache.org/repos/asf/zookeeper/repo
Commit: http://git-wip-us.apache.org/repos/asf/zookeeper/commit/e99c6831
Tree: http://git-wip-us.apache.org/repos/asf/zookeeper/tree/e99c6831
Diff: http://git-wip-us.apache.org/repos/asf/zookeeper/diff/e99c6831

Branch: refs/heads/branch-3.5
Commit: e99c68316ecf19a1941fbf1290f11c4a65c1e268
Parents: 3119a19
Author: fpj <fpj@apache.org>
Authored: Sun Dec 11 21:33:15 2016 +0000
Committer: fpj <fpj@apache.org>
Committed: Sun Dec 11 21:33:15 2016 +0000

 docs/index.pdf                        | Bin 12668 -> 12643 bytes
 docs/javaExample.pdf                  | Bin 33901 -> 33876 bytes
 docs/linkmap.pdf                      | Bin 10833 -> 10808 bytes
 docs/recipes.pdf                      | Bin 33907 -> 33882 bytes
 docs/zookeeperAdmin.html              |  37 ++++++++
 docs/zookeeperAdmin.pdf               | Bin 92294 -> 93572 bytes
 docs/zookeeperHierarchicalQuorums.pdf | Bin 6660 -> 6635 bytes
 docs/zookeeperInternals.pdf           | Bin 48873 -> 48848 bytes
 docs/zookeeperJMX.pdf                 | Bin 16498 -> 16473 bytes
 docs/zookeeperObservers.pdf           | Bin 12885 -> 12860 bytes
 docs/zookeeperOver.pdf                | Bin 302520 -> 302506 bytes
 docs/zookeeperProgrammers.pdf         | Bin 142179 -> 142154 bytes
 docs/zookeeperQuotas.pdf              | Bin 11195 -> 11170 bytes
 docs/zookeeperReconfig.html           | 144 +++++++++++++++++++++++++++++
 docs/zookeeperReconfig.pdf            | Bin 53703 -> 62104 bytes
 docs/zookeeperStarted.pdf             | Bin 28124 -> 28099 bytes
 docs/zookeeperTutorial.pdf            | Bin 30558 -> 30533 bytes
 17 files changed, 181 insertions(+)

diff --git a/docs/index.pdf b/docs/index.pdf
index 7e7aeac..6e6cf50 100644
Binary files a/docs/index.pdf and b/docs/index.pdf differ

diff --git a/docs/javaExample.pdf b/docs/javaExample.pdf
index dd4a94d..3803a92 100644
Binary files a/docs/javaExample.pdf and b/docs/javaExample.pdf differ

diff --git a/docs/linkmap.pdf b/docs/linkmap.pdf
index 76182d5..137714a 100644
Binary files a/docs/linkmap.pdf and b/docs/linkmap.pdf differ

diff --git a/docs/recipes.pdf b/docs/recipes.pdf
index f97c6d3..1c6a66e 100644
Binary files a/docs/recipes.pdf and b/docs/recipes.pdf differ

diff --git a/docs/zookeeperAdmin.html b/docs/zookeeperAdmin.html
index 4ca7c3b..673c64a 100644
--- a/docs/zookeeperAdmin.html
+++ b/docs/zookeeperAdmin.html
@@ -1317,6 +1317,7 @@ server.3=zoo3:2888:3888</pre>
               of the observers on restart. Set to "false" to disable this
               feature. Default is "true"</p>
 <a name="sc_clusterOptions"></a>
@@ -1488,6 +1489,42 @@ server.3=zoo3:2888:3888</pre>
               to a server's config file.
+<p>(No Java system property)</p>
+<strong>New in 3.5.3:</strong>
+                This controls the enabling or disabling of
+                <a href="zookeeperReconfig.html">
+                  Dynamic Reconfiguration</a> feature. When the feature
+                is enabled, users can perform reconfigure operations through
+                the ZooKeeper client API or through ZooKeeper command line tools
+                assuming users are authorized to perform such operations.
+                When the feature is disabled, no user, including the super user,
+                can perform a reconfiguration. Any attempt to reconfigure will return an
+                <strong>"reconfigEnabled"</strong> option can be set as
+                <strong>"reconfigEnabled=false"</strong> or
+                <strong>"reconfigEnabled=true"</strong>
+                to a server's config file, or using QuorumPeerConfig's
+                setReconfigEnabled method. The default value is false.
+                If present, the value should be consistent across every server in
+                the entire ensemble. Setting the value as true on some servers and false
+                on other servers will cause inconsistent behavior depending on which server
+                is elected as leader. If the leader has a setting of
+                <strong>"reconfigEnabled=true"</strong>, then the ensemble
+                will have reconfig feature enabled. If the leader has a setting of
+                <strong>"reconfigEnabled=false"</strong>, then the ensemble
+                will have reconfig feature disabled. It is thus recommended to have a consistent
+                value for <strong>"reconfigEnabled"</strong> across servers
+                in the ensemble.
+              </p>

diff --git a/docs/zookeeperAdmin.pdf b/docs/zookeeperAdmin.pdf
index dbfa426..5a12299 100644
Binary files a/docs/zookeeperAdmin.pdf and b/docs/zookeeperAdmin.pdf differ

diff --git a/docs/zookeeperHierarchicalQuorums.pdf b/docs/zookeeperHierarchicalQuorums.pdf
index 2180e00..69bed0e 100644
Binary files a/docs/zookeeperHierarchicalQuorums.pdf and b/docs/zookeeperHierarchicalQuorums.pdf

diff --git a/docs/zookeeperInternals.pdf b/docs/zookeeperInternals.pdf
index f71daef..a3d72c3 100644
Binary files a/docs/zookeeperInternals.pdf and b/docs/zookeeperInternals.pdf differ

diff --git a/docs/zookeeperJMX.pdf b/docs/zookeeperJMX.pdf
index f5c1763..73d3223 100644
Binary files a/docs/zookeeperJMX.pdf and b/docs/zookeeperJMX.pdf differ

diff --git a/docs/zookeeperObservers.pdf b/docs/zookeeperObservers.pdf
index a9f22d7..250cccd 100644
Binary files a/docs/zookeeperObservers.pdf and b/docs/zookeeperObservers.pdf differ

diff --git a/docs/zookeeperOver.pdf b/docs/zookeeperOver.pdf
index a2cfd99..8607664 100644
Binary files a/docs/zookeeperOver.pdf and b/docs/zookeeperOver.pdf differ

diff --git a/docs/zookeeperProgrammers.pdf b/docs/zookeeperProgrammers.pdf
index 5c80669..4ac5203 100644
Binary files a/docs/zookeeperProgrammers.pdf and b/docs/zookeeperProgrammers.pdf differ

diff --git a/docs/zookeeperQuotas.pdf b/docs/zookeeperQuotas.pdf
index 18a0feb..6af0654 100644
Binary files a/docs/zookeeperQuotas.pdf and b/docs/zookeeperQuotas.pdf differ

diff --git a/docs/zookeeperReconfig.html b/docs/zookeeperReconfig.html
index d7bee03..8d2c730 100644
--- a/docs/zookeeperReconfig.html
+++ b/docs/zookeeperReconfig.html
@@ -207,6 +207,9 @@ document.write("Last Published: " + document.lastModified);
 <a href="#sc_reconfig_standaloneEnabled">The standaloneEnabled flag</a>
+<a href="#sc_reconfig_reconfigEnabled">The reconfigEnabled flag</a>
 <a href="#sc_reconfig_file">Dynamic configuration file</a>
@@ -221,6 +224,12 @@ document.write("Last Published: " + document.lastModified);
 <a href="#ch_reconfig_dyn">Dynamic Reconfiguration of the ZooKeeper Ensemble</a>
 <ul class="minitoc">
+<a href="#ch_reconfig_api">API</a>
+<a href="#sc_reconfig_access_control">Security</a>
 <a href="#sc_reconfig_retrieving">Retrieving the current dynamic configuration</a>
@@ -299,6 +308,12 @@ document.write("Last Published: " + document.lastModified);
+<strong>Note:</strong> Starting with 3.5.3, the dynamic reconfiguration
+      feature is disabled by default, and has to be explicitly turned on via
+      <a href="zookeeperAdmin.html#sc_advancedConfiguration">
+        reconfigEnabled </a> configuration option.
+    </p>
 <a name="ch_reconfig_format"></a>
@@ -388,6 +403,26 @@ document.write("Last Published: " + document.lastModified);
 <p>Since running the Distributed mode allows more flexibility, we
         recommend setting the flag to <em>false</em>. We expect that
         the legacy Standalone mode will be deprecated in the future.</p>
+<a name="sc_reconfig_reconfigEnabled"></a>
+<h3 class="h4">The reconfigEnabled flag</h3>
+<p>Starting with 3.5.0 and prior to 3.5.3, there is no way to disable
+        dynamic reconfiguration feature. We would like to offer the option of
+        disabling reconfiguration feature because with reconfiguration enabled,
+        we have a security concern that a malicious actor can make arbitrary changes
+        to the configuration of a ZooKeeper ensemble, including adding a compromised
+        server to the ensemble. We prefer to leave to the discretion of the user to
+        decide whether to enable it or not and make sure that the appropriate security
+        measure are in place. So in 3.5.3 the <a href="zookeeperAdmin.html#sc_advancedConfiguration">
+          reconfigEnabled </a> configuration option is introduced
+        such that the reconfiguration feature can be completely disabled and any attempts
+        to reconfigure a cluster through reconfig API with or without authentication
+        will fail by default, unless <strong>reconfigEnabled</strong> is set
+        <strong>true</strong>.
+      </p>
+<p>To set the option to true, the configuration file (zoo.cfg) should contain:</p>
+<span class="codefrag computeroutput">reconfigEnabled=true</span>
 <a name="sc_reconfig_file"></a>
 <h3 class="h4">Dynamic configuration file</h3>
 <p>Starting with 3.5.0 we're distinguishing between dynamic
@@ -526,6 +561,7 @@ server.3=</pre>
       clientPort/clientPortAddress statements (although if you specify client
       ports in the new format, these statements are now redundant).</p>
 <a name="ch_reconfig_dyn"></a>
 <h2 class="h3">Dynamic Reconfiguration of the ZooKeeper Ensemble</h2>
@@ -536,6 +572,114 @@ server.3=</pre>
       here using the Java CLI, but note that you can similarly use the C CLI or
       invoke the commands directly from a program just like any other ZooKeeper
+<a name="ch_reconfig_api"></a>
+<h3 class="h4">API</h3>
+<p>There are two sets of APIs for both Java and C client.
+      </p>
+<strong>Reconfiguration API</strong>
+<p>Reconfiguration API is used to reconfigure the ZooKeeper cluster.
+              Starting with 3.5.3, reconfiguration Java APIs are moved into ZooKeeperAdmin
+              from ZooKeeper class, and use of this API requires ACL setup and user
+              authentication (see <a href="#sc_reconfig_access_control">Security</a>
for more information.).
+            </p>
+<strong>Get Configuration API</strong>
+<p>Get configuration APIs are used to retrieve ZooKeeper cluster configuration information
+              stored in /zookeeper/config znode. Use of this API does not require specific
setup or authentication,
+            because /zookeeper/config is readable to any users.</p>
+<a name="sc_reconfig_access_control"></a>
+<h3 class="h4">Security</h3>
+<p>Prior to <strong>3.5.3</strong>, there is no enforced security mechanism
+        over reconfig so any ZooKeeper clients that can connect to ZooKeeper server ensemble
+        will have the ability to change the state of a ZooKeeper cluster via reconfig.
+        It is thus possible for a malicious client to add compromised server to an ensemble,
+        e.g., add a compromised server, or remove legitimate servers.
+        Cases like these could be security vulnerabilities on a case by case basis.
+      </p>
+<p>To address this security concern, we introduced access control over reconfig
+        starting from <strong>3.5.3</strong> such that only a specific set of
+        can use reconfig commands or APIs, and these users need be configured explicitly.
In addition,
+        the setup of ZooKeeper cluster must enable authentication so ZooKeeper clients can
be authenticated.
+      </p>
+        We also provides an escape hatch for users who operate and interact with a ZooKeeper
ensemble in a secured
+        environment (i.e. behind company firewall). For those users who want to use reconfiguration
feature but
+        don't want the overhead of configuring an explicit list of authorized user for reconfig
access checks,
+        they can set <a href="zookeeperAdmin.html#sc_authOptions">"skipACL"</a>
to "yes" which will
+        skip ACL check and allow any user to reconfigure cluster.
+      </p>
+        Overall, ZooKeeper provides flexible configuration options for the reconfigure feature
+        that allow a user to choose based on user's security requirement.
+        We leave to the discretion of the user to decide appropriate security measure are
in place.
+      </p>
+<strong>Access Control</strong>
+<p>The dynamic configuration is stored in a special znode
+              ZooDefs.CONFIG_NODE = /zookeeper/config. This node by default is read only
+              for all users, except super user and users that's explicitly configured for
+              access.
+            </p>
+<p>Clients that need to use reconfig commands or reconfig API should be configured
as users
+              that have write access to CONFIG_NODE. By default, only the super user has
full control including
+              write access to CONFIG_NODE. Additional users can be granted write access through
+              by setting an ACL that has write permission associated with specified user.
+            </p>
+<p>A few examples of how to setup ACLs and use reconfiguration API with authentication
can be found in
+              ReconfigExceptionTest.java and TestReconfigServer.cc.</p>
+<p>Authentication of users is orthogonal to the access control and is delegated to
+              existing authentication mechanism supported by ZooKeeper's pluggable authentication
+              See <a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/Zookeeper+and+SASL">ZooKeeper
and SASL</a> for more details on this topic.
+            </p>
+<strong>Disable ACL check</strong>
+              ZooKeeper supports <a href="zookeeperAdmin.html#sc_authOptions">"skipACL"</a>
option such that ACL
+              check will be completely skipped, if skipACL is set to "yes". In such cases
any unauthenticated
+              users can use reconfig API.
+            </p>
 <a name="sc_reconfig_retrieving"></a>
 <h3 class="h4">Retrieving the current dynamic configuration</h3>
 <p>The dynamic configuration is stored in a special znode

diff --git a/docs/zookeeperReconfig.pdf b/docs/zookeeperReconfig.pdf
index 359f47e..7dbcb4f 100644
Binary files a/docs/zookeeperReconfig.pdf and b/docs/zookeeperReconfig.pdf differ

diff --git a/docs/zookeeperStarted.pdf b/docs/zookeeperStarted.pdf
index 7e9baff..8bcdf80 100644
Binary files a/docs/zookeeperStarted.pdf and b/docs/zookeeperStarted.pdf differ

diff --git a/docs/zookeeperTutorial.pdf b/docs/zookeeperTutorial.pdf
index 44ddeb0..2f246d0 100644
Binary files a/docs/zookeeperTutorial.pdf and b/docs/zookeeperTutorial.pdf differ

View raw message