ZOOKEEPER-2240: Make the three-node minimum more explicit in documentation

and on website (Shawn Heisey via rgs)

git-svn-id: https://svn.apache.org/repos/asf/zookeeper/trunk@1713320 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -300,6 +300,9 @@ IMPROVEMENTS:
   ZOOKEEPER-2315: Change client connect zk service timeout log level from Info
   to Warn level (Lin Yiqun via rgs)
 
+  ZOOKEEPER-2240: Make the three-node minimum more explicit in documentation
+  and on website (Shawn Heisey via rgs)
+
 Release 3.5.0 - 8/4/2014
 
 NEW FEATURES:

docs/zookeeperAdmin.html

@@ -449,6 +449,27 @@ document.write("Last Published: " + document.lastModified);
       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 Getting Started guide, 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>

docs/zookeeperStarted.html

@@ -522,8 +522,23 @@ 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,7 +587,15 @@ 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>
 <a name="Other+Optimizations"></a>