ZOOKEEPER-151. Document change to server configuration

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

CHANGES.txt

@@ -35,6 +35,9 @@ Backward compatibile changes:
 
   BUGFIXES: 
 
+  ZOOKEEPER-151. Document change to server configuration
+  (Flavio Paiva Junqueira)
+
   ZOOKEEPER-193. update java example doc to compile with latest zookeeper
   (phunt)
 

docs/zookeeperAdmin.html

@@ -319,7 +319,7 @@ document.write("Last Published: " + document.lastModified);
       It runs as group of hosts called a quorum. Three ZooKeeper hosts per
       quorum is the minimum recommended quorum size. At Yahoo!, ZooKeeper is
       usually deployed on dedicated RHEL boxes, with dual-core processors, 2GB
-      of RAM, and 80GB IDE harddrives.</p>
+      of RAM, and 80GB IDE hard drives.</p>
 <a name="N1003C"></a><a name="sc_zkMulitServerSetup"></a>
 <h3 class="h4">Clustered (Multi-Server) Setup</h3>
 <p>For reliable ZooKeeper service, you should deploy ZooKeeper in a
@@ -390,9 +390,9 @@ dataDir=/var/zookeeper/
 clientPort=2181
 initLimit=5
 syncLimit=2
-server.1=zoo1:2888
-server.2=zoo2:2888
-server.3=zoo3:2888</span>
+server.1=zoo1:2888:3888
+server.2=zoo2:2888:3888
+server.3=zoo3:2888:3888</span>
 </p>
 
           
@@ -403,7 +403,7 @@ server.3=zoo3:2888</span>
           
 <p>Every machine that is part of the ZooKeeper quorum should know
           about every other machine in the quorum. You accomplish this with
-          the series of lines of the form <strong>server.id=host:port</strong>. The integers <strong>host</strong> and <strong>port</strong> are straightforward. You attribute the
+          the series of lines of the form <strong>server.id=host:port:port</strong>. The parameters <strong>host</strong> and <strong>port</strong> are straightforward. You attribute the
           server id to each machine by creating a file named
           <span class="codefrag filename">myid</span>, one for each server, which resides in
           that server's data directory, as specified by the configuration file
@@ -423,7 +423,7 @@ server.3=zoo3:2888</span>
 
           
 <p>
-<span class="codefrag computeroutput">$ java -cp zookeeper-dev.jar:java/lib/log4j-1.2.15.jar:conf \
+<span class="codefrag computeroutput">$ java -cp zookeeper.jar:src/java/lib/log4j-1.2.15.jar:conf \
         org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</span>
 </p>
         
@@ -444,7 +444,7 @@ server.3=zoo3:2888</span>
 
               
 <p>
-<span class="codefrag computeroutput">$ java -cp zookeeper.jar:java/lib/log4j-1.2.15.jar:conf \
+<span class="codefrag computeroutput">$ java -cp zookeeper.jar:src/java/lib/log4j-1.2.15.jar:conf \
       org.apache.zookeeper.ZooKeeperMain 127.0.0.1:2181</span>
 </p>
             
@@ -460,7 +460,7 @@ server.3=zoo3:2888</span>
 
               
 <p>
-<span class="codefrag computeroutput">$ _make cli_st_</span>
+<span class="codefrag computeroutput">$ make cli_st</span>
 </p>
 
               
@@ -468,7 +468,7 @@ server.3=zoo3:2888</span>
 
               
 <p>
-<span class="codefrag computeroutput">$ _make cli_mt_</span>
+<span class="codefrag computeroutput">$ make cli_mt</span>
 </p>
             
 </li>
@@ -811,20 +811,8 @@ server.3=zoo3:2888</span>
               non-authenticated UDP-based version of fast leader election, "2"
               corresponds to the authenticated UDP-based version of fast
               leader election, and "3" corresponds to TCP-based version of
-              fast leader election</p>
-</dd>
-
-          
-<dt>
-<term>electionPort</term>
-</dt>
-<dd>
-<p>(No Java system property)</p>
-<p>Port used for leader election. It is only used when the
-              election algorithm is not "0". When the election algorithm is
-              "0" a UDP port with the same port number as the port listed in
-              the <strong>server.num</strong> option will be
-              used.</p>
+              fast leader election. Currently, only 0 and 3 are supported, 3 
+              being the default</p>
 </dd>
 
           
@@ -863,7 +851,7 @@ server.3=zoo3:2888</span>
 
           
 <dt>
-<term>server.x=[hostname]:nnnn, etc</term>
+<term>server.x=[hostname]:nnnnn[:nnnnn], etc</term>
 </dt>
 <dd>
 <p>(No Java system property)</p>
@@ -876,13 +864,12 @@ server.3=zoo3:2888</span>
 <p>The list of servers that make up ZooKeeper servers that is
               used by the clients must match the list of ZooKeeper servers
               that each ZooKeeper server has.</p>
-<p>The port numbers <strong>nnnn</strong> in
-              this setting are the <em>electionPort</em> numbers
-              of the servers (as opposed to clientPorts). If you want to test
-              multiple servers on a single machine, the individual choices of
-              electionPort for each server can be defined in each server's
-              config files using the line electionPort=xxxx to avoid
-              clashes.</p>
+<p>There are two port numbers <strong>nnnnn</strong>. 
+              The first followers use to connect to the leader, and the second is for 
+              leader election. The leader election port is only necessary if electionAlg 
+              is 1, 2, or 3 (default). If electionAlg is 0, then the second port is not 
+              necessary. If you want to test multiple servers on a single machine, then 
+              different ports can be used for each server.</p>
 </dd>
 
           
@@ -898,7 +885,7 @@ server.3=zoo3:2888</span>
         
 </dl>
 <p></p>
-<a name="N102AF"></a><a name="Unsafe+Options"></a>
+<a name="N102A0"></a><a name="Unsafe+Options"></a>
 <h4>Unsafe Options</h4>
 <p>The following options can be useful, but be careful when you use
         them. The risk of each is explained along with the explanation of what
@@ -943,7 +930,7 @@ server.3=zoo3:2888</span>
 </dd>
         
 </dl>
-<a name="N102E1"></a><a name="sc_zkCommands"></a>
+<a name="N102D2"></a><a name="sc_zkCommands"></a>
 <h3 class="h4">ZooKeeper Commands: The Four Letter Words</h3>
 <p>ZooKeeper responds to a small set of commands. Each command is
       composed of four letters. You issue the commands to ZooKeeper via telnet
@@ -992,7 +979,7 @@ server.3=zoo3:2888</span>
 <pre class="code">$ echo ruok | nc 127.0.0.1 5111
 imok
 </pre>
-<a name="N10313"></a><a name="sc_dataFileManagement"></a>
+<a name="N10304"></a><a name="sc_dataFileManagement"></a>
 <h3 class="h4">Data File Management</h3>
 <p>ZooKeeper stores its data in a data directory and its transaction
       log in a transaction log directory. By default these two directories are
@@ -1000,7 +987,7 @@ imok
       transaction log files in a separate directory than the data files.
       Throughput increases and latency decreases when transaction logs reside
       on a dedicated log devices.</p>
-<a name="N1031C"></a><a name="The+Data+Directory"></a>
+<a name="N1030D"></a><a name="The+Data+Directory"></a>
 <h4>The Data Directory</h4>
 <p>This directory has two files in it:</p>
 <ul>
@@ -1046,14 +1033,14 @@ imok
         idempotent nature of its updates. By replaying the transaction log
         against fuzzy snapshots ZooKeeper gets the state of the system at the
         end of the log.</p>
-<a name="N10358"></a><a name="The+Log+Directory"></a>
+<a name="N10349"></a><a name="The+Log+Directory"></a>
 <h4>The Log Directory</h4>
 <p>The Log Directory contains the ZooKeeper transaction logs.
         Before any update takes place, ZooKeeper ensures that the transaction
         that represents the update is written to non-volatile storage. A new
         log file is started each time a snapshot is begun. The log file's
         suffix is the first zxid written to that log.</p>
-<a name="N10362"></a><a name="File+Management"></a>
+<a name="N10353"></a><a name="File+Management"></a>
 <h4>File Management</h4>
 <p>The format of snapshot and log files does not change between
         standalone ZooKeeper servers and different configurations of
@@ -1070,7 +1057,7 @@ imok
         needs the latest complete fuzzy snapshot and the log files from the
         start of that snapshot. The PurgeTxnLog utility implements a simple
         retention policy that administrators can use.</p>
-<a name="N10373"></a><a name="sc_commonProblems"></a>
+<a name="N10364"></a><a name="sc_commonProblems"></a>
 <h3 class="h4">Things to Avoid</h3>
 <p>Here are some common problems you can avoid by configuring
       ZooKeeper correctly:</p>
@@ -1124,7 +1111,7 @@ imok
 </dd>
       
 </dl>
-<a name="N10397"></a><a name="sc_bestPractices"></a>
+<a name="N10388"></a><a name="sc_bestPractices"></a>
 <h3 class="h4">Best Practices</h3>
 <p>For best results, take note of the following list of good
       Zookeeper practices. <em>[tbd...]</em>

docs/zookeeperInternals.html

@@ -453,7 +453,8 @@ Below, we make clear why.)
 <p>
 Leader activation includes leader election. We currently have two leader election 
 algorithms in ZooKeeper: LeaderElection and FastLeaderElection (AuthFastLeaderElection 
-is a variant of FastLeaderElection). ZooKeeper messaging doesn't care about the 
+is a variant of FastLeaderElection that uses UDP and allows servers to perform a simple
+form of authentication to avoid IP spoofing). ZooKeeper messaging doesn't care about the 
 exact method of electing a leader has long as the following holds:
 </p>
 <ul>
@@ -484,8 +485,8 @@ are missing, or if a follower is missing too many proposals, it will send a full
 snapshot of the state to the follower.
 </p>
 <p>
-There is a corner cases that a follower arrives that has proposals, U, not seen 
-by a leader. Proposals are seen in order, so the proposals of U will have a zxids 
+There is a corner case in which a follower that has proposals, U, not seen 
+by a leader arrives. Proposals are seen in order, so the proposals of U will have a zxids 
 higher than zxids seen by the leader. The follower must have arrived after the 
 leader election, otherwise the follower would have been elected leader given that 
 it has seen a higher zxid. Since committed proposals must be seen by a quorum of 

docs/zookeeperStarted.html

@@ -251,7 +251,7 @@ $ ~/dev/zookeeper/: ant jar
       file:</p>
 <pre class="code">
 tickTime=2000
-dataDir=/var/zookeeper/ 
+dataDir=/var/zookeeper
 clientPort=2181
 </pre>
 <p>This file can be called anything, but for the sake of this
@@ -297,30 +297,34 @@ clientPort=2181
 </dl>
 <p>Now that you created the configuration file, you can start
       ZooKeeper:</p>
-<pre class="code">java -cp zookeeper-dev.jar:java/lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</pre>
-<p>ZooKeeper logs messages using log4j -- more detail available in
-      the <a href="zookeeperProgrammers.html#Logging">Logging</a>
-      section of the Programmer's Guide.<em>[tbd:
-      real reference needed]</em> You will see log messages coming to the
-      console and/or a log file depending on the log4j configuration.</p>
+<pre class="code">java -cp zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</pre>
+<p>ZooKeeper logs messages using log4j -- more detail
+      available in the
+      <a href="zookeeperProgrammers.html#Logging">Logging</a>
+      section of the Programmer's Guide. You will see log messages
+      coming to the console and/or a log file depending on the log4j
+      configuration.</p>
 <p>The steps outlined here run ZooKeeper in standalone mode. There is
       no replication, so if Zookeeper process fails, the service will go down.
       This is fine for most development situations, but to run Zookeeper in
       replicated mode, please see <a href="#sc_RunningReplicatedZooKeeper">Running Replicated
       Zookeeper</a>.</p>
 <p></p>
-<a name="N10072"></a><a name="sc_ConnectingToZooKeeper"></a>
+<a name="N1006F"></a><a name="sc_ConnectingToZooKeeper"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
-<p>Once ZooKeeper is running, you have several option for connection
+<p>Once ZooKeeper is running, you have several options for connection
       to it:</p>
 <ul>
         
 <li>
           
 <p>
-<strong>Java</strong>: Use java -cp
-          zookeeper.jar:java/lib/log4j-1.2.15.jar:conf
-          org.apache.zookeeper.ZooKeeperMain 127.0.0.1:2181</p>
+<strong>Java</strong>:
+          Use <span class="codefrag computeroutput">java -cp
+          zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar:conf
+          org.apache.zookeeper.ZooKeeperMain
+          127.0.0.1:2181</span>
+</p>
 
           
 <p>This lets you perform simple, file-like operations.</p>
@@ -363,14 +367,14 @@ clientPort=2181
       file. The file 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/zookeeper/ 
-clientPort=2181 
-initLimit=5 
-syncLimit=2 
-server.1=zoo1:2888
-server.2=zoo2:2888 
-server.3=zoo3:2888 
+tickTime=2000
+dataDir=/var/zookeeper
+clientPort=2181
+initLimit=5
+syncLimit=2
+server.1=zoo1:2888:3888
+server.2=zoo2:2888:3888
+server.3=zoo3:2888:3888
 </pre>
 <p>The new entry, <strong>initLimit</strong> is
       timeouts ZooKeeper uses to limit the length of time the Zookeeper
@@ -382,24 +386,38 @@ server.3=zoo3:2888
       seconds.</p>
 <p>The entries of the form <em>server.X</em> list the
       servers that make up the ZooKeeper service. When the server starts up,
-      it knows which server it is by looking for the file *myid* in the data
-      directory. That file has the contains the server number, in
-      ASCII.</p>
-<p>Finally, note the "2888" port numbers after each server name.
-      These are the "electionPort" numbers of the servers (as opposed to
-      clientPorts), that is ports for <em>[tbd]</em>.</p>
+      it knows which server it is by looking for the file
+      <em>myid</em> in the data directory. That file has the 
+      contains the server number, in ASCII.</p>
+<p>Finally, note the two port numbers after each server
+       name: " 2888" and "3888". Peers use the former port to connect
+       to other peers. Such a connection is necessary so that peers
+       can communicate, for example, to agree upon the order of
+       updates. More specifically, a ZooKeeper server uses this port
+       to connect followers to the leader. When a new leader arises, a
+       follower opens a TCP connection to the leader using this
+       port. Because the default leader election also uses TCP, we
+       currently require another port for leader election. This is the
+       second port in the server entry.
+       </p>
 <div class="note">
 <div class="label">Note</div>
 <div class="content">
         
-<p>If you want to test multiple servers on a single machine, define
-        the electionPort for each server in that server's config file, using
-        the line <span class="codefrag command">electionPort=xxxx</span> as means of avoiding
-        clashes.</p>
+<p>If you want to test multiple servers on a single
+        machine, specify the servername
+        as <em>localhost</em> with unique quorum &amp;
+        leader election ports (i.e. 2888:3888, 2889:3889, 2890:3890 in
+        the example above) for each server.X in that server's config
+        file. Of course separate <em>dataDir</em>s and
+        distinct <em>clientPort</em>s are also necessary
+        (in the above replicated example, running on a
+        single <em>localhost</em>, you would still have
+        three config files).</p>
       
 </div>
 </div>
-<a name="N100E6"></a><a name="Other+Optimizations"></a>
+<a name="N100EE"></a><a name="Other+Optimizations"></a>
 <h3 class="h4">Other Optimizations</h3>
 <p>There are a couple of other configuration parameters that can
       greatly increase performance:</p>
@@ -407,10 +425,11 @@ server.3=zoo3:2888
         
 <li>
           
-<p>To get low latencies on updates it is important to have a
-          dedicated transaction log directory. By default transaction logs are
-          put in the same directory as the data snapshots and *myid* file. The
-          dataLogDir parameters indicates a different directory to use for the
+<p>To get low latencies on updates it is important to
+          have a dedicated transaction log directory. By default
+          transaction logs are put in the same directory as the data
+          snapshots and <em>myid</em> file. The dataLogDir
+          parameters indicates a different directory to use for the
           transaction logs.</p>
         
 </li>

src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml

@@ -75,7 +75,7 @@
       It runs as group of hosts called a quorum. Three ZooKeeper hosts per
       quorum is the minimum recommended quorum size. At Yahoo!, ZooKeeper is
       usually deployed on dedicated RHEL boxes, with dual-core processors, 2GB
-      of RAM, and 80GB IDE harddrives.</para>
+      of RAM, and 80GB IDE hard drives.</para>
     </section>
 
     <section id="sc_zkMulitServerSetup">
@@ -133,9 +133,9 @@ dataDir=/var/zookeeper/
 clientPort=2181
 initLimit=5
 syncLimit=2
-server.1=zoo1:2888
-server.2=zoo2:2888
-server.3=zoo3:2888</computeroutput></para>
+server.1=zoo1:2888:3888
+server.2=zoo2:2888:3888
+server.3=zoo3:2888:3888</computeroutput></para>
 
           <para>You can find the meanings of these and other configuration
           settings in the section <xref linkend="sc_configuration" />. A word
@@ -144,7 +144,7 @@ server.3=zoo3:2888</computeroutput></para>
           <para>Every machine that is part of the ZooKeeper quorum should know
           about every other machine in the quorum. You accomplish this with
           the series of lines of the form <emphasis
-          role="bold">server.id=host:port</emphasis>. The integers <emphasis
+          role="bold">server.id=host:port:port</emphasis>. The parameters <emphasis
           role="bold">host</emphasis> and <emphasis
           role="bold">port</emphasis> are straightforward. You attribute the
           server id to each machine by creating a file named
@@ -161,7 +161,7 @@ server.3=zoo3:2888</computeroutput></para>
           <para>If your configuration file is set up, you can start
           ZooKeeper:</para>
 
-          <para><computeroutput>$ java -cp zookeeper-dev.jar:java/lib/log4j-1.2.15.jar:conf \
+          <para><computeroutput>$ java -cp zookeeper.jar:src/java/lib/log4j-1.2.15.jar:conf \
         org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</computeroutput></para>
         </listitem>
 
@@ -173,7 +173,7 @@ server.3=zoo3:2888</computeroutput></para>
               <para>In Java, you can run the following command to execute
               simple operations:</para>
 
-              <para><computeroutput>$ java -cp zookeeper.jar:java/lib/log4j-1.2.15.jar:conf \
+              <para><computeroutput>$ java -cp zookeeper.jar:src/java/lib/log4j-1.2.15.jar:conf \
       org.apache.zookeeper.ZooKeeperMain 127.0.0.1:2181</computeroutput></para>
             </listitem>
 
@@ -183,11 +183,11 @@ server.3=zoo3:2888</computeroutput></para>
               ZooKeeper sources. This compiles the single threaded
               client:</para>
 
-              <para><computeroutput>$ _make cli_st_</computeroutput></para>
+              <para><computeroutput>$ make cli_st</computeroutput></para>
 
               <para>And this compiles the mulithreaded client:</para>
 
-              <para><computeroutput>$ _make cli_mt_</computeroutput></para>
+              <para><computeroutput>$ make cli_mt</computeroutput></para>
             </listitem>
           </itemizedlist>
 
@@ -507,21 +507,8 @@ server.3=zoo3:2888</computeroutput></para>
               non-authenticated UDP-based version of fast leader election, "2"
               corresponds to the authenticated UDP-based version of fast
               leader election, and "3" corresponds to TCP-based version of
-              fast leader election</para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>electionPort</term>
-
-            <listitem>
-              <para>(No Java system property)</para>
-
-              <para>Port used for leader election. It is only used when the
-              election algorithm is not "0". When the election algorithm is
-              "0" a UDP port with the same port number as the port listed in
-              the <emphasis role="bold">server.num</emphasis> option will be
-              used.</para>
+              fast leader election. Currently, only 0 and 3 are supported, 3 
+              being the default</para>
             </listitem>
           </varlistentry>
 
@@ -560,7 +547,7 @@ server.3=zoo3:2888</computeroutput></para>
           </varlistentry>
 
           <varlistentry>
-            <term>server.x=[hostname]:nnnn, etc</term>
+            <term>server.x=[hostname]:nnnnn[:nnnnn], etc</term>
 
             <listitem>
               <para>(No Java system property)</para>
@@ -577,13 +564,12 @@ server.3=zoo3:2888</computeroutput></para>
               used by the clients must match the list of ZooKeeper servers
               that each ZooKeeper server has.</para>
 
-              <para>The port numbers <emphasis role="bold">nnnn</emphasis> in
-              this setting are the <emphasis>electionPort</emphasis> numbers
-              of the servers (as opposed to clientPorts). If you want to test
-              multiple servers on a single machine, the individual choices of
-              electionPort for each server can be defined in each server's
-              config files using the line electionPort=xxxx to avoid
-              clashes.</para>
+              <para>There are two port numbers <emphasis role="bold">nnnnn</emphasis>. 
+              The first followers use to connect to the leader, and the second is for 
+              leader election. The leader election port is only necessary if electionAlg 
+              is 1, 2, or 3 (default). If electionAlg is 0, then the second port is not 
+              necessary. If you want to test multiple servers on a single machine, then 
+              different ports can be used for each server.</para>
             </listitem>
           </varlistentry>
 

src/docs/src/documentation/content/xdocs/zookeeperInternals.xml

@@ -205,7 +205,8 @@ Below, we make clear why.)
 <para>
 Leader activation includes leader election. We currently have two leader election 
 algorithms in ZooKeeper: LeaderElection and FastLeaderElection (AuthFastLeaderElection 
-is a variant of FastLeaderElection). ZooKeeper messaging doesn't care about the 
+is a variant of FastLeaderElection that uses UDP and allows servers to perform a simple
+form of authentication to avoid IP spoofing). ZooKeeper messaging doesn't care about the 
 exact method of electing a leader has long as the following holds:
 </para>
 
@@ -233,8 +234,8 @@ snapshot of the state to the follower.
 </para>
 
 <para>
-There is a corner cases that a follower arrives that has proposals, U, not seen 
-by a leader. Proposals are seen in order, so the proposals of U will have a zxids 
+There is a corner case in which a follower that has proposals, U, not seen 
+by a leader arrives. Proposals are seen in order, so the proposals of U will have a zxids 
 higher than zxids seen by the leader. The follower must have arrived after the 
 leader election, otherwise the follower would have been elected leader given that 
 it has seen a higher zxid. Since committed proposals must be seen by a quorum of 

src/docs/src/documentation/content/xdocs/zookeeperStarted.xml

@@ -85,7 +85,7 @@ $ ~/dev/zookeeper/: ant jar
 
 <programlisting>
 tickTime=2000
-dataDir=/var/zookeeper/ 
+dataDir=/var/zookeeper
 clientPort=2181
 </programlisting>
 
@@ -128,13 +128,14 @@ clientPort=2181
       <para>Now that you created the configuration file, you can start
       ZooKeeper:</para>
 
-      <programlisting>java -cp zookeeper-dev.jar:java/lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</programlisting>
+      <programlisting>java -cp zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</programlisting>
 
-      <para>ZooKeeper logs messages using log4j -- more detail available in
-      the <ulink url="zookeeperProgrammers.html#Logging">Logging</ulink>
-      section of the Programmer's Guide.<emphasis>[tbd:
-      real reference needed]</emphasis> You will see log messages coming to the
-      console and/or a log file depending on the log4j configuration.</para>
+      <para>ZooKeeper logs messages using log4j -- more detail
+      available in the
+      <ulink url="zookeeperProgrammers.html#Logging">Logging</ulink>
+      section of the Programmer's Guide. You will see log messages
+      coming to the console and/or a log file depending on the log4j
+      configuration.</para>
 
       <para>The steps outlined here run ZooKeeper in standalone mode. There is
       no replication, so if Zookeeper process fails, the service will go down.
@@ -149,14 +150,16 @@ clientPort=2181
     <section id="sc_ConnectingToZooKeeper">
       <title>Connecting to ZooKeeper</title>
 
-      <para>Once ZooKeeper is running, you have several option for connection
+      <para>Once ZooKeeper is running, you have several options for connection
       to it:</para>
 
       <itemizedlist>
         <listitem>
-          <para><emphasis role="bold">Java</emphasis>: Use java -cp
-          zookeeper.jar:java/lib/log4j-1.2.15.jar:conf
-          org.apache.zookeeper.ZooKeeperMain 127.0.0.1:2181</para>
+          <para><emphasis role="bold">Java</emphasis>:
+          Use <computeroutput>java -cp
+          zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar:conf
+          org.apache.zookeeper.ZooKeeperMain
+          127.0.0.1:2181</computeroutput></para>
 
           <para>This lets you perform simple, file-like operations.</para>
         </listitem>
@@ -199,14 +202,14 @@ clientPort=2181
       few differences. Here is an example:</para>
 
 <programlisting>
-tickTime=2000 
-dataDir=/var/zookeeper/ 
-clientPort=2181 
-initLimit=5 
-syncLimit=2 
-server.1=zoo1:2888
-server.2=zoo2:2888 
-server.3=zoo3:2888 
+tickTime=2000
+dataDir=/var/zookeeper
+clientPort=2181
+initLimit=5
+syncLimit=2
+server.1=zoo1:2888:3888
+server.2=zoo2:2888:3888
+server.3=zoo3:2888:3888
 </programlisting>
 
       <para>The new entry, <emphasis role="bold">initLimit</emphasis> is
@@ -222,19 +225,33 @@ server.3=zoo3:2888
 
       <para>The entries of the form <emphasis>server.X</emphasis> list the
       servers that make up the ZooKeeper service. When the server starts up,
-      it knows which server it is by looking for the file *myid* in the data
-      directory. That file has the contains the server number, in
-      ASCII.</para>
-
-      <para>Finally, note the "2888" port numbers after each server name.
-      These are the "electionPort" numbers of the servers (as opposed to
-      clientPorts), that is ports for <emphasis>[tbd]</emphasis>.</para>
+      it knows which server it is by looking for the file
+      <emphasis>myid</emphasis> in the data directory. That file has the 
+      contains the server number, in ASCII.</para>
+
+       <para>Finally, note the two port numbers after each server
+       name: " 2888" and "3888". Peers use the former port to connect
+       to other peers. Such a connection is necessary so that peers
+       can communicate, for example, to agree upon the order of
+       updates. More specifically, a ZooKeeper server uses this port
+       to connect followers to the leader. When a new leader arises, a
+       follower opens a TCP connection to the leader using this
+       port. Because the default leader election also uses TCP, we
+       currently require another port for leader election. This is the
+       second port in the server entry.
+       </para>
 
       <note>
-        <para>If you want to test multiple servers on a single machine, define
-        the electionPort for each server in that server's config file, using
-        the line <command>electionPort=xxxx</command> as means of avoiding
-        clashes.</para>
+        <para>If you want to test multiple servers on a single
+        machine, specify the servername
+        as <emphasis>localhost</emphasis> with unique quorum &amp;
+        leader election ports (i.e. 2888:3888, 2889:3889, 2890:3890 in
+        the example above) for each server.X in that server's config
+        file. Of course separate <emphasis>dataDir</emphasis>s and
+        distinct <emphasis>clientPort</emphasis>s are also necessary
+        (in the above replicated example, running on a
+        single <emphasis>localhost</emphasis>, you would still have
+        three config files).</para>
       </note>
     </section>
 
@@ -246,10 +263,11 @@ server.3=zoo3:2888
 
       <itemizedlist>
         <listitem>
-          <para>To get low latencies on updates it is important to have a
-          dedicated transaction log directory. By default transaction logs are
-          put in the same directory as the data snapshots and *myid* file. The
-          dataLogDir parameters indicates a different directory to use for the
+          <para>To get low latencies on updates it is important to
+          have a dedicated transaction log directory. By default
+          transaction logs are put in the same directory as the data
+          snapshots and <emphasis>myid</emphasis> file. The dataLogDir
+          parameters indicates a different directory to use for the
           transaction logs.</para>
         </listitem>