Author: phunt
Date: Sun Mar 20 04:28:02 2016
New Revision: 1735837
URL: http://svn.apache.org/viewvc?rev=1735837&view=rev
Log:
ZOOKEEPER-2240 Make the three-node minimum more explicit in documentation and
on website (Shawn Heisey and Arshad Mohammad via phunt)
Modified:
zookeeper/branches/branch-3.5/CHANGES.txt
zookeeper/branches/branch-3.5/docs/index.pdf
zookeeper/branches/branch-3.5/docs/javaExample.pdf
zookeeper/branches/branch-3.5/docs/linkmap.pdf
zookeeper/branches/branch-3.5/docs/recipes.pdf
zookeeper/branches/branch-3.5/docs/zookeeperAdmin.html
zookeeper/branches/branch-3.5/docs/zookeeperAdmin.pdf
zookeeper/branches/branch-3.5/docs/zookeeperHierarchicalQuorums.pdf
zookeeper/branches/branch-3.5/docs/zookeeperInternals.pdf
zookeeper/branches/branch-3.5/docs/zookeeperJMX.pdf
zookeeper/branches/branch-3.5/docs/zookeeperObservers.pdf
zookeeper/branches/branch-3.5/docs/zookeeperOver.pdf
zookeeper/branches/branch-3.5/docs/zookeeperProgrammers.pdf
zookeeper/branches/branch-3.5/docs/zookeeperQuotas.pdf
zookeeper/branches/branch-3.5/docs/zookeeperReconfig.pdf
zookeeper/branches/branch-3.5/docs/zookeeperStarted.html
zookeeper/branches/branch-3.5/docs/zookeeperStarted.pdf
zookeeper/branches/branch-3.5/docs/zookeeperTutorial.pdf
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml
Modified: zookeeper/branches/branch-3.5/CHANGES.txt
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/CHANGES.txt?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
--- zookeeper/branches/branch-3.5/CHANGES.txt (original)
+++ zookeeper/branches/branch-3.5/CHANGES.txt Sun Mar 20 04:28:02 2016
@@ -162,6 +162,9 @@ IMPROVEMENTS:
ZOOKEEPER-2300: Expose SecureClientPort and SecureClientAddress JMX
properties
(Arshad Mohammad via rgs)
+ ZOOKEEPER-2240 Make the three-node minimum more explicit in
+ documentation and on website (Shawn Heisey and Arshad Mohammad via phunt)
+
Release 3.5.1 - 07/27/2015
NEW FEATURES:
Modified: zookeeper/branches/branch-3.5/docs/index.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/index.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/javaExample.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/javaExample.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/linkmap.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/linkmap.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/recipes.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/recipes.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperAdmin.html
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperAdmin.html?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
--- zookeeper/branches/branch-3.5/docs/zookeeperAdmin.html (original)
+++ zookeeper/branches/branch-3.5/docs/zookeeperAdmin.html Sun Mar 20 04:28:02
2016
@@ -519,6 +519,35 @@ document.write("Last Published: " + docu
only handle the failure of a single machine; if two machines fail, the
remaining two machines do not constitute a majority. However, with five
machines ZooKeeper can handle the failure of two machines. </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+
+<p>
+ As mentioned in the
+ <a href="zookeeperStarted.html">ZooKeeper Getting Started Guide</a>
+ , a minimum of three servers are required for a fault tolerant
+ clustered setup, and it is strongly recommended that you have an
+ odd number of servers.
+ </p>
+
+<p>Usually three servers is more than enough for a production
+ install, but for maximum reliability during maintenance, you may
+ wish to install five servers. With three servers, if you perform
+ maintenance on one of them, you are vulnerable to a failure on one
+ of the other two servers during that maintenance. If you have five
+ of them running, you can take one down for maintenance, and know
+ that you're still OK if one of the other four suddenly fails.
+ </p>
+
+<p>Your redundancy considerations should include all aspects of
+ your environment. If you have three ZooKeeper servers, but their
+ network cables are all plugged into the same network switch, then
+ the failure of that switch will take down your entire ensemble.
+ </p>
+
+</div>
+</div>
<p>Here are the steps to setting a server that will be part of an
ensemble. These steps should be performed on every host in the
ensemble:</p>
@@ -615,7 +644,7 @@ server.3=zoo3:2888:3888</pre>
<p>
-<span class="codefrag computeroutput">$ java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.16.jar:conf
\
+<span class="codefrag computeroutput">$ java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf
\
org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg
</span>
</p>
@@ -652,7 +681,7 @@ server.3=zoo3:2888:3888</pre>
<p>
-<span class="codefrag computeroutput">$ java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.16.jar:conf:src/java/lib/jline-2.11.jar
\
+<span class="codefrag computeroutput">$ java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf:src/java/lib/jline-2.11.jar
\
org.apache.zookeeper.ZooKeeperMain -server 127.0.0.1:2181</span>
</p>
@@ -976,7 +1005,7 @@ server.3=zoo3:2888:3888</pre>
in the unlikely event a recent log has become corrupted). This
can be run as a cron job on the ZooKeeper server machines to
clean up the logs daily.</p>
-<pre class="code"> java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.16.jar:conf
org.apache.zookeeper.server.PurgeTxnLog <dataDir> <snapDir> -n
<count></pre>
+<pre class="code"> java -cp
zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf
org.apache.zookeeper.server.PurgeTxnLog <dataDir> <snapDir> -n
<count></pre>
<p>Automatic purging of the snapshots and corresponding
transaction logs was introduced in version 3.4.0 and can be
enabled via the following configuration parameters
<strong>autopurge.snapRetainCount</strong> and
<strong>autopurge.purgeInterval</strong>. For more on
@@ -1028,7 +1057,7 @@ server.3=zoo3:2888:3888</pre>
<h3 class="h4">Logging</h3>
<p>
ZooKeeper uses <strong><a
href="http://www.slf4j.org";>SLF4J</a></strong>
- version 1.7 as its logging infrastructure. For backward compatibility
it is bound to
+ version 1.7.5 as its logging infrastructure. For backward
compatibility it is bound to
<strong>LOG4J</strong> but you can use
<strong><a href="http://logback.qos.ch/";>LOGBack</a></strong>
or any other supported logging framework of your choice.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperAdmin.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperAdmin.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperHierarchicalQuorums.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperHierarchicalQuorums.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files
zookeeper/branches/branch-3.5/docs/zookeeperHierarchicalQuorums.pdf (original)
and zookeeper/branches/branch-3.5/docs/zookeeperHierarchicalQuorums.pdf Sun Mar
20 04:28:02 2016 differ
Modified: zookeeper/branches/branch-3.5/docs/zookeeperInternals.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperInternals.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperJMX.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperJMX.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files zookeeper/branches/branch-3.5/docs/zookeeperJMX.pdf (original) and
zookeeper/branches/branch-3.5/docs/zookeeperJMX.pdf Sun Mar 20 04:28:02 2016
differ
Modified: zookeeper/branches/branch-3.5/docs/zookeeperObservers.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperObservers.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files zookeeper/branches/branch-3.5/docs/zookeeperObservers.pdf
(original) and zookeeper/branches/branch-3.5/docs/zookeeperObservers.pdf Sun
Mar 20 04:28:02 2016 differ
Modified: zookeeper/branches/branch-3.5/docs/zookeeperOver.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperOver.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperProgrammers.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperProgrammers.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperQuotas.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperQuotas.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files zookeeper/branches/branch-3.5/docs/zookeeperQuotas.pdf (original)
and zookeeper/branches/branch-3.5/docs/zookeeperQuotas.pdf Sun Mar 20 04:28:02
2016 differ
Modified: zookeeper/branches/branch-3.5/docs/zookeeperReconfig.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperReconfig.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperStarted.html
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperStarted.html?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
--- zookeeper/branches/branch-3.5/docs/zookeeperStarted.html (original)
+++ zookeeper/branches/branch-3.5/docs/zookeeperStarted.html Sun Mar 20
04:28:02 2016
@@ -522,8 +522,30 @@ numChildren = 0
ZooKeeper in replicated mode. A replicated group of servers in the same
application is called a <em>quorum</em>, and in replicated
mode, all servers in the quorum have copies of the same configuration
- file. The file is similar to the one used in standalone mode, but with a
- few differences. Here is an example:</p>
+ file.</p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+
+<p>
+ For replicated mode, a minimum of three servers are required,
+ and it is strongly recommended that you have an odd number of
+ servers. If you only have two servers, then you are in a
+ situation where if one of them fails, there are not enough
+ machines to form a majority quorum. Two servers is inherently
+ <strong>less</strong>
+ stable than a single server, because there are two single
+ points of failure.
+ </p>
+
+</div>
+</div>
+<p>
+ The required
+ <strong>conf/zoo.cfg</strong>
+ file for replicated mode is similar to the one used in standalone
+ mode, but with a few differences. Here is an example:
+ </p>
<pre class="code">
tickTime=2000
dataDir=/var/lib/zookeeper
@@ -572,6 +594,14 @@ server.3=zoo3:2888:3888
(in the above replicated example, running on a
single <em>localhost</em>, you would still have
three config files).</p>
+
+<p>Please be aware that setting up multiple servers on a single
+ machine will not create any redundancy. If something were to
+ happen which caused the machine to die, all of the zookeeper
+ servers would be offline. Full redundancy requires that each
+ server have its own machine. It must be a completely separate
+ physical server. Multiple virtual machines on the same physical
+ host are still vulnerable to the complete failure of that host.</p>
</div>
</div>
Modified: zookeeper/branches/branch-3.5/docs/zookeeperStarted.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperStarted.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/branches/branch-3.5/docs/zookeeperTutorial.pdf
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/docs/zookeeperTutorial.pdf?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
Binary files - no diff available.
Modified:
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
---
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml
(original)
+++
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml
Sun Mar 20 04:28:02 2016
@@ -186,7 +186,28 @@
only handle the failure of a single machine; if two machines fail, the
remaining two machines do not constitute a majority. However, with five
machines ZooKeeper can handle the failure of two machines. </para>
-
+ <note>
+ <para>
+ As mentioned in the
+ <ulink url="zookeeperStarted.html">ZooKeeper Getting Started
Guide</ulink>
+ , a minimum of three servers are required for a fault tolerant
+ clustered setup, and it is strongly recommended that you have an
+ odd number of servers.
+ </para>
+ <para>Usually three servers is more than enough for a production
+ install, but for maximum reliability during maintenance, you may
+ wish to install five servers. With three servers, if you perform
+ maintenance on one of them, you are vulnerable to a failure on one
+ of the other two servers during that maintenance. If you have five
+ of them running, you can take one down for maintenance, and know
+ that you're still OK if one of the other four suddenly fails.
+ </para>
+ <para>Your redundancy considerations should include all aspects of
+ your environment. If you have three ZooKeeper servers, but their
+ network cables are all plugged into the same network switch, then
+ the failure of that switch will take down your entire ensemble.
+ </para>
+ </note>
<para>Here are the steps to setting a server that will be part of an
ensemble. These steps should be performed on every host in the
ensemble:</para>
Modified:
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml
URL:
http://svn.apache.org/viewvc/zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml?rev=1735837&r1=1735836&r2=1735837&view=diff
==============================================================================
---
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml
(original)
+++
zookeeper/branches/branch-3.5/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml
Sun Mar 20 04:28:02 2016
@@ -342,8 +342,25 @@ numChildren = 0
ZooKeeper in replicated mode. A replicated group of servers in the same
application is called a <emphasis>quorum</emphasis>, and in replicated
mode, all servers in the quorum have copies of the same configuration
- file. The file is similar to the one used in standalone mode, but with a
- few differences. Here is an example:</para>
+ file.</para>
+ <note>
+ <para>
+ For replicated mode, a minimum of three servers are required,
+ and it is strongly recommended that you have an odd number of
+ servers. If you only have two servers, then you are in a
+ situation where if one of them fails, there are not enough
+ machines to form a majority quorum. Two servers is inherently
+ <emphasis role="bold">less</emphasis>
+ stable than a single server, because there are two single
+ points of failure.
+ </para>
+ </note>
+ <para>
+ The required
+ <emphasis role="bold">conf/zoo.cfg</emphasis>
+ file for replicated mode is similar to the one used in standalone
+ mode, but with a few differences. Here is an example:
+ </para>
<programlisting>
tickTime=2000
@@ -396,6 +413,13 @@ server.3=zoo3:2888:3888
(in the above replicated example, running on a
single <emphasis>localhost</emphasis>, you would still have
three config files).</para>
+ <para>Please be aware that setting up multiple servers on a single
+ machine will not create any redundancy. If something were to
+ happen which caused the machine to die, all of the zookeeper
+ servers would be offline. Full redundancy requires that each
+ server have its own machine. It must be a completely separate
+ physical server. Multiple virtual machines on the same physical
+ host are still vulnerable to the complete failure of that
host.</para>
</note>
</section>
