Author: phunt Date: Thu Oct 16 14:55:22 2008 New Revision: 705373 URL: http://svn.apache.org/viewvc?rev=705373&view=rev Log: ZOOKEEPER-151. Document change to server configuration
Modified: hadoop/zookeeper/trunk/CHANGES.txt hadoop/zookeeper/trunk/docs/zookeeperAdmin.html hadoop/zookeeper/trunk/docs/zookeeperAdmin.pdf hadoop/zookeeper/trunk/docs/zookeeperInternals.html hadoop/zookeeper/trunk/docs/zookeeperInternals.pdf hadoop/zookeeper/trunk/docs/zookeeperStarted.html hadoop/zookeeper/trunk/docs/zookeeperStarted.pdf hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperInternals.xml hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml Modified: hadoop/zookeeper/trunk/CHANGES.txt URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/CHANGES.txt (original) +++ hadoop/zookeeper/trunk/CHANGES.txt Thu Oct 16 14:55:22 2008 @@ -35,6 +35,9 @@ BUGFIXES: + ZOOKEEPER-151. Document change to server configuration + (Flavio Paiva Junqueira) + ZOOKEEPER-193. update java example doc to compile with latest zookeeper (phunt) Modified: hadoop/zookeeper/trunk/docs/zookeeperAdmin.html URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperAdmin.html?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/docs/zookeeperAdmin.html (original) +++ hadoop/zookeeper/trunk/docs/zookeeperAdmin.html Thu Oct 16 14:55:22 2008 @@ -319,7 +319,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.</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 @@ 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 @@ <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 @@ <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 @@ <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 @@ <p> -<span class="codefrag computeroutput">$ _make cli_st_</span> +<span class="codefrag computeroutput">$ make cli_st</span> </p> @@ -468,7 +468,7 @@ <p> -<span class="codefrag computeroutput">$ _make cli_mt_</span> +<span class="codefrag computeroutput">$ make cli_mt</span> </p> </li> @@ -811,20 +811,8 @@ 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 @@ <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 @@ <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 @@ </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 @@ </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 @@ <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 @@ 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 @@ 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 @@ 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 @@ </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> Modified: hadoop/zookeeper/trunk/docs/zookeeperAdmin.pdf URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperAdmin.pdf?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== Binary files - no diff available. Modified: hadoop/zookeeper/trunk/docs/zookeeperInternals.html URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperInternals.html?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/docs/zookeeperInternals.html (original) +++ hadoop/zookeeper/trunk/docs/zookeeperInternals.html Thu Oct 16 14:55:22 2008 @@ -453,7 +453,8 @@ <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 @@ 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 Modified: hadoop/zookeeper/trunk/docs/zookeeperInternals.pdf URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperInternals.pdf?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== Binary files - no diff available. Modified: hadoop/zookeeper/trunk/docs/zookeeperStarted.html URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperStarted.html?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/docs/zookeeperStarted.html (original) +++ hadoop/zookeeper/trunk/docs/zookeeperStarted.html Thu Oct 16 14:55:22 2008 @@ -251,7 +251,7 @@ 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 @@ </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 @@ 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 @@ 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 & + 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 @@ <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> Modified: hadoop/zookeeper/trunk/docs/zookeeperStarted.pdf URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperStarted.pdf?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== Binary files - no diff available. Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml (original) +++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml Thu Oct 16 14:55:22 2008 @@ -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 @@ 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 @@ <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 @@ <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 @@ <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 @@ 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 @@ 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 @@ </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 @@ 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> Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperInternals.xml URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperInternals.xml?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperInternals.xml (original) +++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperInternals.xml Thu Oct 16 14:55:22 2008 @@ -205,7 +205,8 @@ <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 @@ </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 Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml?rev=705373&r1=705372&r2=705373&view=diff ============================================================================== --- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml (original) +++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperStarted.xml Thu Oct 16 14:55:22 2008 @@ -85,7 +85,7 @@ <programlisting> tickTime=2000 -dataDir=/var/zookeeper/ +dataDir=/var/zookeeper clientPort=2181 </programlisting> @@ -128,13 +128,14 @@ <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 @@ <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 @@ 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 @@ <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 & + 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 @@ <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>