ZOOKEEPER-245. update readme/quickstart to be release tar, rather than source, based (patrick hunt via mahadev)

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

CHANGES.txt

@@ -50,17 +50,19 @@ BUGFIXES:
   ZOOKEEPER-241. Build of a distro fails after clean target is run.
   (patrick hunt via mahadev)
 
+  ZOOKEEPER-245. update readme/quickstart to be release tar, rather than
+source, based (patrick hunt via mahadev)
+  
 IMPROVEMENTS:
    
-  ZOOKEEPER-161. Content needed: "Designing a ZooKeeper Deployment"
-  (breed via phunt)
-
   ZOOKEEPER-64. Log system env information when initializing server and
   client (pat via mahadev)
 
   ZOOKEEPER-243. add SEQUENCE flag documentation to the programming guide.
   (patrick hunt via mahadev)
-
+  
+   ZOOKEEPER-161. Content needed: "Designing a ZooKeeper Deployment"
+  (breed via phunt)
 
 Release 3.0.0 - 2008-10-21
 

README.txt

@@ -1,37 +1,9 @@
-Welcome to ZooKeeper!
+For the latest information about ZooKeeper, please visit our website at:
 
--------------------
-Documentation
+   http://hadoop.apache.org/zookeeper/
 
-See docs/index.html
+and our wiki, at:
 
-New Users -- see the overview, getting started, and programmer guides
-Existing Users -- if you are upgrading to 3.0 review the releasenotes and upgrade guide
+   http://wiki.apache.org/hadoop/ZooKeeper
 
--------------------
-Quick Start
-
-Run "ant" command in this directory to build the server/client. "zookeeper-dev.jar" will be output to this directory on a successful build.
-
--------------------
-Starting the server:
-
-1) in the conf directory make a copy of zoo_sample.cfg (ie zoo.cfg) and edit as necessary. Default values will support a "standalone" instance.
-
-2) start the server with the following comand line:
-
-java -cp conf:zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar org.apache.zookeeper.server.quorum.QuorumPeerMain conf/zoo.cfg
-
-Notice that the server is picking up the log4j.properties file from the conf directory (default).
-
-
------------------------
-Starting a client shell
-
-1) run the following command
-
-java -cp conf:zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar org.apache.zookeeper.ZooKeeperMain <server>:<port>
-
-where server and port correspond to the ZooKeeper configuration.
-
-Notice that the client is picking up the log4j.properties file from the conf directory (default).
+Full documentation for this release can also be found in docs/index.html

docs/zookeeperAdmin.html

@@ -187,6 +187,14 @@ document.write("Last Published: " + document.lastModified);
 <ul class="minitoc">
 <li>
 <a href="#sc_systemReq">System Requirements</a>
+<ul class="minitoc">
+<li>
+<a href="#sc_supportedPlatforms">Supported Platforms</a>
+</li>
+<li>
+<a href="#sc_requiredSoftware">Required Software </a>
+</li>
+</ul>
 </li>
 <li>
 <a href="#sc_zkMulitServerSetup">Clustered (Multi-Server) Setup</a>
@@ -320,13 +328,57 @@ document.write("Last Published: " + document.lastModified);
     production environment.</p>
 <a name="N10032"></a><a name="sc_systemReq"></a>
 <h3 class="h4">System Requirements</h3>
-<p>ZooKeeper runs in Java, release 1.5 or greater (JDK 5 or greater).
-      It runs as an <em>ensemble</em> of ZooKeeper servers. Three ZooKeeper
-      servers is the minimum recommended size for an ensemble, and we also recommend that
-      they run on separate machines. At Yahoo!, ZooKeeper is usually deployed on 
-      dedicated RHEL boxes, with dual-core processors, 2GB of RAM, and 80GB IDE hard 
-      drives.</p>
-<a name="N1003F"></a><a name="sc_zkMulitServerSetup"></a>
+<a name="N10038"></a><a name="sc_supportedPlatforms"></a>
+<h4>Supported Platforms</h4>
+<ul>
+          
+<li>
+            
+<p>GNU/Linux is supported as a development and production
+              platform for both server and client.</p>
+          
+</li>
+          
+<li>
+            
+<p>Sun Solaris is supported as a development and production
+              platform for both server and client.</p>
+          
+</li>
+          
+<li>
+            
+<p>FreeBSD is supported as a development and production
+              platform for clients only. Java NIO selector support in
+              the FreeBSD JVM is broken.</p>
+          
+</li>
+          
+<li>
+            
+<p>Win32 is supported as a <em>development
+            platform</em> only for both server and client.</p>
+          
+</li>
+          
+<li>
+            
+<p>MacOSX is supported as a <em>development
+            platform</em> only for both server and client.</p>
+          
+</li>
+        
+</ul>
+<a name="N10066"></a><a name="sc_requiredSoftware"></a>
+<h4>Required Software </h4>
+<p>ZooKeeper runs in Java, release 1.5 or greater (JDK 5 or
+          greater).  It runs as an <em>ensemble</em> of
+          ZooKeeper servers. Three ZooKeeper servers is the minimum
+          recommended size for an ensemble, and we also recommend that
+          they run on separate machines. At Yahoo!, ZooKeeper is
+          usually deployed on dedicated RHEL boxes, with dual-core
+          processors, 2GB of RAM, and 80GB IDE hard drives.</p>
+<a name="N10074"></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
       cluster known as an <em>ensemble</em>. As long as a majority
@@ -494,7 +546,7 @@ server.3=zoo3:2888:3888</span>
 </li>
       
 </ol>
-<a name="N100D3"></a><a name="sc_singleAndDevSetup"></a>
+<a name="N10108"></a><a name="sc_singleAndDevSetup"></a>
 <h3 class="h4">Single Server and Developer Setup</h3>
 <p>If you want to setup ZooKeeper for development purposes, you will
       probably want to setup a single server instance of ZooKeeper, and then
@@ -512,7 +564,7 @@ server.3=zoo3:2888:3888</span>
 </div>
 
   
-<a name="N100F4"></a><a name="ch_administration"></a>
+<a name="N10129"></a><a name="ch_administration"></a>
 <h2 class="h3">Administration</h2>
 <div class="section">
 <p>This section contains information about running and maintaining
@@ -627,7 +679,7 @@ server.3=zoo3:2888:3888</span>
 </li>
       
 </ul>
-<a name="N10160"></a><a name="sc_designing"></a>
+<a name="N10195"></a><a name="sc_designing"></a>
 <h3 class="h4">Designing a ZooKeeper Deployment</h3>
 <p>The reliablity of ZooKeeper rests on two basic assumptions.</p>
 <ol>
@@ -654,7 +706,7 @@ server.3=zoo3:2888:3888</span>
       to hold true. Some of these are cross-machines considerations,
       and others are things you should consider for each and every
       machine in your deployment.</p>
-<a name="N1017C"></a><a name="sc_CrossMachineRequirements"></a>
+<a name="N101B1"></a><a name="sc_CrossMachineRequirements"></a>
 <h4>Cross Machine Requirements</h4>
 <p>For the ZooKeeper service to be active, there must be a
         majority of non-failing machines that can communicate with
@@ -672,7 +724,7 @@ server.3=zoo3:2888:3888</span>
         failure of that switch could cause a correlated failure and
         bring down the service. The same holds true of shared power
         circuits, cooling systems, etc.</p>
-<a name="N10189"></a><a name="Single+Machine+Requirements"></a>
+<a name="N101BE"></a><a name="Single+Machine+Requirements"></a>
 <h4>Single Machine Requirements</h4>
 <p>If ZooKeeper has to contend with other applications for
         access to resourses like storage media, CPU, network, or
@@ -713,19 +765,19 @@ server.3=zoo3:2888:3888</span>
 </li>
       
 </ul>
-<a name="N101A7"></a><a name="sc_provisioning"></a>
+<a name="N101DC"></a><a name="sc_provisioning"></a>
 <h3 class="h4">Provisioning</h3>
 <p></p>
-<a name="N101B0"></a><a name="sc_strengthsAndLimitations"></a>
+<a name="N101E5"></a><a name="sc_strengthsAndLimitations"></a>
 <h3 class="h4">Things to Consider: ZooKeeper Strengths and Limitations</h3>
 <p></p>
-<a name="N101B9"></a><a name="sc_administering"></a>
+<a name="N101EE"></a><a name="sc_administering"></a>
 <h3 class="h4">Administering</h3>
 <p></p>
-<a name="N101C2"></a><a name="sc_monitoring"></a>
+<a name="N101F7"></a><a name="sc_monitoring"></a>
 <h3 class="h4">Monitoring</h3>
 <p></p>
-<a name="N101CB"></a><a name="sc_logging"></a>
+<a name="N10200"></a><a name="sc_logging"></a>
 <h3 class="h4">Logging</h3>
 <p>ZooKeeper uses <strong>log4j</strong> version 1.2 as 
       its logging infrastructure. The  ZooKeeper default <span class="codefrag filename">log4j.properties</span> 
@@ -735,10 +787,10 @@ server.3=zoo3:2888:3888</span>
 <p>For more information, see 
       <a href="http://logging.apache.org/log4j/1.2/manual.html#defaultInit">Log4j Default Initialization Procedure</a> 
       of the log4j manual.</p>
-<a name="N101EB"></a><a name="sc_troubleshooting"></a>
+<a name="N10220"></a><a name="sc_troubleshooting"></a>
 <h3 class="h4">Troubleshooting</h3>
 <p></p>
-<a name="N101F4"></a><a name="sc_configuration"></a>
+<a name="N10229"></a><a name="sc_configuration"></a>
 <h3 class="h4">Configuration Parameters</h3>
 <p>ZooKeeper's behavior is governed by the ZooKeeper configuration
       file. This file is designed so that the exact same file can be used by
@@ -746,7 +798,7 @@ server.3=zoo3:2888:3888</span>
       layouts are the same. If servers use different configuration files, care
       must be taken to ensure that the list of servers in all of the different
       configuration files match.</p>
-<a name="N101FD"></a><a name="sc_minimumConfiguration"></a>
+<a name="N10232"></a><a name="sc_minimumConfiguration"></a>
 <h4>Minimum Configuration</h4>
 <p>Here are the minimum configuration keywords that must be defined
         in the configuration file:</p>
@@ -793,7 +845,7 @@ server.3=zoo3:2888:3888</span>
 </dd>
         
 </dl>
-<a name="N10224"></a><a name="sc_advancedConfiguration"></a>
+<a name="N10259"></a><a name="sc_advancedConfiguration"></a>
 <h4>Advanced Configuration</h4>
 <p>The configuration settings in the section are optional. You can
         use them to further fine tune the behaviour of your ZooKeeper servers.
@@ -884,7 +936,7 @@ server.3=zoo3:2888:3888</span>
 </dd>
         
 </dl>
-<a name="N10284"></a><a name="sc_clusterOptions"></a>
+<a name="N102B9"></a><a name="sc_clusterOptions"></a>
 <h4>Cluster Options</h4>
 <p>The options in this section are designed for use with an ensemble
         of servers -- that is, when deploying clusters of servers.</p>
@@ -974,7 +1026,7 @@ server.3=zoo3:2888:3888</span>
         
 </dl>
 <p></p>
-<a name="N102E1"></a><a name="Unsafe+Options"></a>
+<a name="N10316"></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
@@ -1019,7 +1071,7 @@ server.3=zoo3:2888:3888</span>
 </dd>
         
 </dl>
-<a name="N10313"></a><a name="sc_zkCommands"></a>
+<a name="N10348"></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
@@ -1084,7 +1136,7 @@ server.3=zoo3:2888:3888</span>
 <pre class="code">$ echo ruok | nc 127.0.0.1 5111
 imok
 </pre>
-<a name="N10353"></a><a name="sc_dataFileManagement"></a>
+<a name="N10388"></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
@@ -1092,7 +1144,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="N1035C"></a><a name="The+Data+Directory"></a>
+<a name="N10391"></a><a name="The+Data+Directory"></a>
 <h4>The Data Directory</h4>
 <p>This directory has two files in it:</p>
 <ul>
@@ -1138,14 +1190,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="N10398"></a><a name="The+Log+Directory"></a>
+<a name="N103CD"></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="N103A2"></a><a name="File+Management"></a>
+<a name="N103D7"></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
@@ -1162,7 +1214,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="N103B3"></a><a name="sc_commonProblems"></a>
+<a name="N103E8"></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>
@@ -1216,7 +1268,7 @@ imok
 </dd>
       
 </dl>
-<a name="N103D7"></a><a name="sc_bestPractices"></a>
+<a name="N1040C"></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/zookeeperStarted.html

@@ -186,7 +186,13 @@ document.write("Last Published: " + document.lastModified);
       ZooKeeper</a>
 <ul class="minitoc">
 <li>
-<a href="#sc_InstallingSingleMode">Installing and Running ZooKeeper in Single Server Mode</a>
+<a href="#sc_Prerequisites">Pre-requisites</a>
+</li>
+<li>
+<a href="#sc_Download">Download</a>
+</li>
+<li>
+<a href="#sc_InstallingSingleMode">Standalone Operation</a>
 </li>
 <li>
 <a href="#sc_ConnectingToZooKeeper">Connecting to ZooKeeper</a>
@@ -214,46 +220,44 @@ document.write("Last Published: " + document.lastModified);
       ZooKeeper</h2>
 <div class="section">
 <p>This document contains information to get you started quickly with
-    Zookeeper. It is aimed primarily at developers hoping to try it out, and
+    ZooKeeper. It is aimed primarily at developers hoping to try it out, and
     contains simple installation instructions for a single ZooKeeper server, a
     few commands to verify that it is running, and a simple programming
     example. Finally, as a convenience, there are a few sections regarding
     more complicated installations, for example running replicated
     deployments, and optimizing the transaction log. However for the complete
-    instructions for commercial deployments, please refer to the <a href="zookeeperAdmin.html">Zookeeper
+    instructions for commercial deployments, please refer to the <a href="zookeeperAdmin.html">ZooKeeper
     Administrator's Guide</a>.</p>
-<a name="N10016"></a><a name="sc_InstallingSingleMode"></a>
-<h3 class="h4">Installing and Running ZooKeeper in Single Server Mode</h3>
+<a name="N10016"></a><a name="sc_Prerequisites"></a>
+<h3 class="h4">Pre-requisites</h3>
+<p>See <a href="zookeeperAdmin.html#sc_systemReq">
+          System Requirements</a> in the Admin guide.</p>
+<a name="N10024"></a><a name="sc_Download"></a>
+<h3 class="h4">Download</h3>
+<p>To get a ZooKeeper distribution, download a recent
+        <a href="http://hadoop.apache.org/zookeeper/releases.html">
+          stable</a> release from one of the Apache Download
+        Mirrors.</p>
+<a name="N10032"></a><a name="sc_InstallingSingleMode"></a>
+<h3 class="h4">Standalone Operation</h3>
 <p>Setting up a ZooKeeper server in standalone mode is
-      straightforward. The server is contained in a single JAR file, so
-      installation consists of copying a JAR file and creating a
-      configuration.</p>
-<div class="note">
-<div class="label">Note</div>
-<div class="content">
-        
-<p>Zookeeper requires Java 1.5 or more recent.</p>
-      
-</div>
-</div>
-<p>Once you have downloaded the ZooKeeper source, cd to the root of
-      your ZooKeeper source, and run "ant jar". For example:</p>
-<pre class="code">
-$ cd ~/dev/zookeeper
-$ ~/dev/zookeeper/: ant jar
-</pre>
-<p>This should generate a JAR file called zookeeper.jar. To start
-      Zookeeper, compile and run zookeeper.jar.</p>
-<p>To start ZooKeeper you need a configuration file. Here is a sample
-      file:</p>
+      straightforward. The server is contained in a single JAR file,
+      so installation consists of creating a configuration.</p>
+<p>Once you've downloaded a stable ZooKeeper release unpack
+      it and cd to the root</p>
+<p>To start ZooKeeper you need a configuration file. Here is a sample,
+      create it in <strong>conf/zoo.cfg</strong>:</p>
 <pre class="code">
 tickTime=2000
 dataDir=/var/zookeeper
 clientPort=2181
 </pre>
 <p>This file can be called anything, but for the sake of this
-      discussion, call it <strong>zoo.cfg</strong>. Here are
-      the meanings for each of the fields:</p>
+      discussion call
+      it <strong>conf/zoo.cfg</strong>. Change the
+      value of <strong>dataDir</strong> to specify an
+      existing (empty to start with) directory.  Here are the meanings
+      for each of the fields:</p>
 <dl>
         
 <dt>
@@ -294,20 +298,19 @@ clientPort=2181
 </dl>
 <p>Now that you created the configuration file, you can start
       ZooKeeper:</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>
+<pre class="code">bin/zkServer.sh start</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>
+      coming to the console (default) 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
+      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="N1006F"></a><a name="sc_ConnectingToZooKeeper"></a>
+      ZooKeeper</a>.</p>
+<a name="N10083"></a><a name="sc_ConnectingToZooKeeper"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
 <p>Once ZooKeeper is running, you have several options for connection
       to it:</p>
@@ -316,12 +319,10 @@ clientPort=2181
 <li>
           
 <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>
+<strong>Java</strong>: Use</p>
+
+          
+<pre class="code">bin/zkCli.sh 127.0.0.1:2181</pre>
 
           
 <p>This lets you perform simple, file-like operations.</p>
@@ -334,27 +335,40 @@ clientPort=2181
 <p>
 <strong>C</strong>: compile cli_mt
           (multi-threaded) or cli_st (single-threaded) by running
-          <span class="codefrag command">make cli_mt</span> or <span class="codefrag command">make cli_st</span>
-          in the c subdirectory in the ZooKeeper sources.</p>
+          <span class="codefrag command">make cli_mt</span> or <span class="codefrag command">make
+          cli_st</span> in
+          the <strong>src/c</strong> subdirectory in
+          the ZooKeeper sources. See the README contained within
+          <strong>src/c</strong> for full details.</p>
+
+          
+<p>You can run the program
+          from <strong>src/c</strong> using:</p>
 
           
-<p>You can run the program using <em>LD_LIBRARY_PATH=.
-          cli_mt 127.0.0.1:2181</em> or <em>LD_LIBRARY_PATH=.
-          cli_st 127.0.0.1:2181</em>. This will give you a simple shell
-          to execute file system like operations on ZooKeeper.</p>
+<pre class="code">LD_LIBRARY_PATH=. cli_mt 127.0.0.1:2181</pre>
+
+          
+<p>or</p>
+
+          
+<pre class="code">LD_LIBRARY_PATH=. cli_st 127.0.0.1:2181</pre>
+          
+<p>This will give you a simple shell to execute file
+          system like operations on ZooKeeper.</p>
         
 </li>
       
 </ul>
-<a name="N100A3"></a><a name="sc_ProgrammingToZooKeeper"></a>
+<a name="N100C6"></a><a name="sc_ProgrammingToZooKeeper"></a>
 <h3 class="h4">Programming to ZooKeeper</h3>
 <p>ZooKeeper has a Java bindings and C bindings. They are
       functionally equivalent. The C bindings exist in two variants: single
       threaded and multi-threaded. These differ only in how the messaging loop
       is done. For more information, see the <a href="zookeeperProgrammers.html#ch_programStructureWithExample.html">Programming
-      Examples in the Zookeeper Programmer's Guide</a> for
+      Examples in the ZooKeeper Programmer's Guide</a> for
       sample code using of the different APIs.</p>
-<a name="N100B1"></a><a name="sc_RunningReplicatedZooKeeper"></a>
+<a name="N100D4"></a><a name="sc_RunningReplicatedZooKeeper"></a>
 <h3 class="h4">Running Replicated ZooKeeper</h3>
 <p>Running ZooKeeper in standalone mode is convenient for evaluation,
       some development, and testing. But in production, you should run
@@ -374,7 +388,7 @@ 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
+      timeouts ZooKeeper uses to limit the length of time the ZooKeeper
       servers in quorum have to connect to a leader. The entry <strong>syncLimit</strong> limits how far out of date a server can
       be from a leader.</p>
 <p>With both of these timeouts, you specify the unit of time using
@@ -414,7 +428,7 @@ server.3=zoo3:2888:3888
       
 </div>
 </div>
-<a name="N100EE"></a><a name="Other+Optimizations"></a>
+<a name="N10111"></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>

src/c/README

@@ -1,9 +1,14 @@
                      Zookeeper C client library 
 
 
-This package provides a C client interface to Zookeeper server. For general
-information about Zookeeper please see http://zookeeper.wiki.sourceforge.net/.
-The homepage for this project is http://sourceforge.net/projects/zookeeper/.
+This package provides a C client interface to Zookeeper server.
+
+For the latest information about ZooKeeper, please visit our website at:
+   http://hadoop.apache.org/zookeeper/
+and our wiki, at:
+   http://wiki.apache.org/hadoop/ZooKeeper
+
+Full documentation for this release can also be found in ../../docs/index.html
 
 
 OVERVIEW
@@ -13,62 +18,70 @@ The client supports two types of APIs -- synchronous and asynchronous.
 Asynchronous API provides non-blocking operations with completion callbacks and 
 relies on the application to implement event multiplexing on its behalf.
 
-On the other hand, Synchronous API provides a blocking flavor of zookeeper operations 
-and runs its own event loop in a separate thread.
+On the other hand, Synchronous API provides a blocking flavor of
+zookeeper operations and runs its own event loop in a separate thread.
 
 Sync and Async APIs can be mixed and matched within the same application.
 
-The package includes two shared libraries: zookeeper_st and zookeeper_mt. The former
-only provides the Async API and is not thread-safe. The only reason this library
-exists is to support the platforms were pthread library is not available or unstable 
-(i.e. FreeBSD 4.x). In all other cases the application developers are advised to link
-against zookeeper_mt as it includes support for both Sync and Async API.
+The package includes two shared libraries: zookeeper_st and
+zookeeper_mt. The former only provides the Async API and is not
+thread-safe. The only reason this library exists is to support the
+platforms were pthread library is not available or unstable
+(i.e. FreeBSD 4.x). In all other cases the application developers are
+advised to link against zookeeper_mt as it includes support for both
+Sync and Async API.
 
 
 INSTALLATION
 
-If you're building the client from a check-out from Source Forge repository, you
-need to follow the steps outlined below. If you're building from a project source package 
-downloaded from Source Forge please skip to step 3.
-1) do a "ant compile_jute" from the zookeeper top level directory (.../trunk/zookeeper).
-   This will create a directory named "generated" under zookeeper/c. 
-2) change directory to the zookeeper/c and do a "autoreconf -i" to bootstrap 
-   autoconf, automake and libtool. Please make sure you have autoconf version 2.59
-   or greater installed. Skip to step 4.
-3) unzip/untar the source tarball and cd to the zookeeper-x.x.x/ directory
-4) do a "./configure [OPTIONS]" to generate the makefile. See INSTALL for general 
-   information about running configure. Additionally, the configure supports 
-   the following options:
-   --enable-debug     enables optimization and enables debug info compiler options,
-                      disabled by default
-   --without-syncapi  disables Sync API support; zookeeper_mt library won't be built,
-                      enabled by default
+If you're building the client from a source checkout you need to
+follow the steps outlined below. If you're building from a release
+tar downloaded from Apache please skip to step 2.
+
+1) do a "ant compile_jute" from the zookeeper top level directory (.../trunk).
+   This will create a directory named "generated" under src/c.  Skip to step 3.
+2) unzip/untar the source tarball and cd to the zookeeper-x.x.x/src/c directory
+3) change directory to src/c and do a "autoreconf -if" to bootstrap
+   autoconf, automake and libtool. Please make sure you have autoconf
+   version 2.59 or greater installed.
+4) do a "./configure [OPTIONS]" to generate the makefile. See INSTALL
+   for general information about running configure. Additionally, the
+   configure supports the following options:
+   --enable-debug     enables optimization and enables debug info compiler
+                      options, disabled by default
+   --without-syncapi  disables Sync API support; zookeeper_mt library won't
+                      be built, enabled by default
    --disable-static   do not build static libraries, enabled by default
    --disable-shared   do not build shared libraries, enabled by default
 5) do a "make" or "make install" to build the libraries and install them. 
-   Alternatively, you can also build and run a unit test suite (and you probably should). 
-   Please make sure you have cppunit-1.10.x or higher installed before you execute step 4. 
-   Once ./configure has finished, do a "make run-check". It will build the libraries, 
-   build the tests and run them.
-6) to generate doxygen documentation do a "make doxygen-doc". All documentations will be 
-   placed to a new subfolder named docs. By default only HTML documentation is generated.
-   For information on other document formats please use "./configure --help"
-   
+   Alternatively, you can also build and run a unit test suite (and
+   you probably should).  Please make sure you have cppunit-1.10.x or
+   higher installed before you execute step 4.  Once ./configure has
+   finished, do a "make run-check". It will build the libraries, build
+   the tests and run them.
+6) to generate doxygen documentation do a "make doxygen-doc". All
+   documentations will be placed to a new subfolder named docs. By
+   default only HTML documentation is generated.  For information on
+   other document formats please use "./configure --help"
 
 
 USING THE CLIENT
 
-You can test your client by running a zookeeper server (see instructions on 
-the project wiki page on how to run it) and connecting to it using the zookeeper shell
-application cli that is built as part of the installation procedure.
+You can test your client by running a zookeeper server (see
+instructions on the project wiki page on how to run it) and connecting
+to it using the zookeeper shell application cli that is built as part
+of the installation procedure.
 
-cli_mt (multithreaded, built against zookeeper_mt library) is shown in this example, 
-but you could also use cli_st (singlethreaded, built against zookeeper_st library):
+cli_mt (multithreaded, built against zookeeper_mt library) is shown in
+this example, but you could also use cli_st (singlethreaded, built
+against zookeeper_st library):
 
 $ cli_mt zookeeper_host:9876
 
-This is a client application that gives you a shell for executing simple zookeeper
-commands. Once succesully started and connected to the server it displays a shell prompt. 
+This is a client application that gives you a shell for executing
+simple zookeeper commands. Once successfully started and connected to
+the server it displays a shell prompt.
+
 You can now enter zookeeper commands. For example, to create a node:
 
 > create /my_new_node
@@ -81,8 +94,8 @@ You should see a list of nodes who are the children of the root node "/".
 
 Here's a list of command supported by the cli shell:
 
-ls <path>             -- list children of a znode identified by <path>. The command
-                         set a children watch on the znode.
+ls <path>             -- list children of a znode identified by <path>. The
+                         command set a children watch on the znode.
 get <path>            -- get the value of a znode at <path>
 set <path> <value>    -- set the value of a znode at <path> to <value>
 create [+e|+s] <path> -- create a znode as a child of znode <path>; 
@@ -107,8 +120,3 @@ In order to be able to use the zookeeper API in your application you have to
 
 Please take a look at cli.c to understand how to use the two API types. 
 (TODO: some kind of short tutorial would be helpful, I guess)
-
-
-SUPPORT
-
-For questions, please email <zookeeper-user@lists.sourceforge.net>

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

@@ -71,12 +71,46 @@
     <section id="sc_systemReq">
       <title>System Requirements</title>
 
-      <para>ZooKeeper runs in Java, release 1.5 or greater (JDK 5 or greater).
-      It runs as an <emphasis>ensemble</emphasis> of ZooKeeper servers. Three ZooKeeper
-      servers is the minimum recommended size for an ensemble, and we also recommend that
-      they run on separate machines. At Yahoo!, ZooKeeper is usually deployed on 
-      dedicated RHEL boxes, with dual-core processors, 2GB of RAM, and 80GB IDE hard 
-      drives.</para>
+      <section id="sc_supportedPlatforms">
+        <title>Supported Platforms</title>
+
+        <itemizedlist>
+          <listitem>
+            <para>GNU/Linux is supported as a development and production
+              platform for both server and client.</para>
+          </listitem>
+          <listitem>
+            <para>Sun Solaris is supported as a development and production
+              platform for both server and client.</para>
+          </listitem>
+          <listitem>
+            <para>FreeBSD is supported as a development and production
+              platform for clients only. Java NIO selector support in
+              the FreeBSD JVM is broken.</para>
+          </listitem>
+          <listitem>
+            <para>Win32 is supported as a <emphasis>development
+            platform</emphasis> only for both server and client.</para>
+          </listitem>
+          <listitem>
+            <para>MacOSX is supported as a <emphasis>development
+            platform</emphasis> only for both server and client.</para>
+          </listitem>
+        </itemizedlist>
+      </section>
+
+      <section id="sc_requiredSoftware">
+        <title>Required Software </title>
+
+        <para>ZooKeeper runs in Java, release 1.5 or greater (JDK 5 or
+          greater).  It runs as an <emphasis>ensemble</emphasis> of
+          ZooKeeper servers. Three ZooKeeper servers is the minimum
+          recommended size for an ensemble, and we also recommend that
+          they run on separate machines. At Yahoo!, ZooKeeper is
+          usually deployed on dedicated RHEL boxes, with dual-core
+          processors, 2GB of RAM, and 80GB IDE hard drives.</para>
+      </section>
+
     </section>
 
     <section id="sc_zkMulitServerSetup">

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

@@ -37,7 +37,7 @@
     <abstract>
       <para>This guide contains detailed information about creating
       distributed applications that use ZooKeeper. It discusses the basic
-      operations Zookeeper supports, and how these can be used to build
+      operations ZooKeeper supports, and how these can be used to build
       higher-level abstractions. It contains solutions to common tasks, a
       troubleshooting guide, and links to other information.</para>
     </abstract>
@@ -48,40 +48,44 @@
       ZooKeeper</title>
 
     <para>This document contains information to get you started quickly with
-    Zookeeper. It is aimed primarily at developers hoping to try it out, and
+    ZooKeeper. It is aimed primarily at developers hoping to try it out, and
     contains simple installation instructions for a single ZooKeeper server, a
     few commands to verify that it is running, and a simple programming
     example. Finally, as a convenience, there are a few sections regarding
     more complicated installations, for example running replicated
     deployments, and optimizing the transaction log. However for the complete
     instructions for commercial deployments, please refer to the <ulink
-    url="zookeeperAdmin.html">Zookeeper
+    url="zookeeperAdmin.html">ZooKeeper
     Administrator's Guide</ulink>.</para>
 
-    <section id="sc_InstallingSingleMode">
-      <title>Installing and Running ZooKeeper in Single Server Mode</title>
+    <section id="sc_Prerequisites">
+      <title>Pre-requisites</title>
 
-      <para>Setting up a ZooKeeper server in standalone mode is
-      straightforward. The server is contained in a single JAR file, so
-      installation consists of copying a JAR file and creating a
-      configuration.</para>
+      <para>See <ulink url="zookeeperAdmin.html#sc_systemReq">
+          System Requirements</ulink> in the Admin guide.</para>
+    </section>
 
-      <note>
-        <para>Zookeeper requires Java 1.5 or more recent.</para>
-      </note>
+    <section id="sc_Download">
+      <title>Download</title>
 
-      <para>Once you have downloaded the ZooKeeper source, cd to the root of
-      your ZooKeeper source, and run "ant jar". For example:</para>
-<programlisting>
-$ cd ~/dev/zookeeper
-$ ~/dev/zookeeper/: ant jar
-</programlisting>
+      <para>To get a ZooKeeper distribution, download a recent
+        <ulink url="http://hadoop.apache.org/zookeeper/releases.html">
+          stable</ulink> release from one of the Apache Download
+        Mirrors.</para>
+    </section>
 
-      <para>This should generate a JAR file called zookeeper.jar. To start
-      Zookeeper, compile and run zookeeper.jar.</para>
+    <section id="sc_InstallingSingleMode">
+      <title>Standalone Operation</title>
 
-      <para>To start ZooKeeper you need a configuration file. Here is a sample
-      file:</para>
+      <para>Setting up a ZooKeeper server in standalone mode is
+      straightforward. The server is contained in a single JAR file,
+      so installation consists of creating a configuration.</para>
+
+      <para>Once you've downloaded a stable ZooKeeper release unpack
+      it and cd to the root</para>
+
+      <para>To start ZooKeeper you need a configuration file. Here is a sample,
+      create it in <emphasis role="bold">conf/zoo.cfg</emphasis>:</para>
 
 <programlisting>
 tickTime=2000
@@ -90,8 +94,11 @@ clientPort=2181
 </programlisting>
 
       <para>This file can be called anything, but for the sake of this
-      discussion, call it <emphasis role="bold">zoo.cfg</emphasis>. Here are
-      the meanings for each of the fields:</para>
+      discussion call
+      it <emphasis role="bold">conf/zoo.cfg</emphasis>. Change the
+      value of <emphasis role="bold">dataDir</emphasis> to specify an
+      existing (empty to start with) directory.  Here are the meanings
+      for each of the fields:</para>
 
       <variablelist>
         <varlistentry>
@@ -128,23 +135,21 @@ clientPort=2181
       <para>Now that you created the configuration file, you can start
       ZooKeeper:</para>
 
-      <programlisting>java -cp zookeeper-dev.jar:src/java/lib/log4j-1.2.15.jar:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.cfg</programlisting>
+      <programlisting>bin/zkServer.sh start</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. You will see log messages
-      coming to the console and/or a log file depending on the log4j
-      configuration.</para>
+      coming to the console (default) 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.
-      This is fine for most development situations, but to run Zookeeper in
+      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 <ulink
       url="#sc_RunningReplicatedZooKeeper">Running Replicated
-      Zookeeper</ulink>.</para>
-
-      <para></para>
+      ZooKeeper</ulink>.</para>
     </section>
 
     <section id="sc_ConnectingToZooKeeper">
@@ -155,11 +160,9 @@ clientPort=2181
 
       <itemizedlist>
         <listitem>
-          <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><emphasis role="bold">Java</emphasis>: Use</para>
+
+          <programlisting>bin/zkCli.sh 127.0.0.1:2181</programlisting>
 
           <para>This lets you perform simple, file-like operations.</para>
         </listitem>
@@ -167,13 +170,22 @@ clientPort=2181
         <listitem>
           <para><emphasis role="bold">C</emphasis>: compile cli_mt
           (multi-threaded) or cli_st (single-threaded) by running
-          <command>make cli_mt</command> or <command>make cli_st</command>
-          in the c subdirectory in the ZooKeeper sources.</para>
+          <command>make cli_mt</command> or <command>make
+          cli_st</command> in
+          the <emphasis role="bold">src/c</emphasis> subdirectory in
+          the ZooKeeper sources. See the README contained within
+          <emphasis role="bold">src/c</emphasis> for full details.</para>
+
+          <para>You can run the program
+          from <emphasis role="bold">src/c</emphasis> using:</para>
+
+          <programlisting>LD_LIBRARY_PATH=. cli_mt 127.0.0.1:2181</programlisting>
+
+          <para>or</para>
 
-          <para>You can run the program using <emphasis>LD_LIBRARY_PATH=.
-          cli_mt 127.0.0.1:2181</emphasis> or <emphasis>LD_LIBRARY_PATH=.
-          cli_st 127.0.0.1:2181</emphasis>. This will give you a simple shell
-          to execute file system like operations on ZooKeeper.</para>
+          <programlisting>LD_LIBRARY_PATH=. cli_st 127.0.0.1:2181</programlisting>
+          <para>This will give you a simple shell to execute file
+          system like operations on ZooKeeper.</para>
         </listitem>
       </itemizedlist>
     </section>
@@ -186,7 +198,7 @@ clientPort=2181
       threaded and multi-threaded. These differ only in how the messaging loop
       is done. For more information, see the <ulink
       url="zookeeperProgrammers.html#ch_programStructureWithExample.html">Programming
-      Examples in the Zookeeper Programmer's Guide</ulink> for
+      Examples in the ZooKeeper Programmer's Guide</ulink> for
       sample code using of the different APIs.</para>
     </section>
 
@@ -213,7 +225,7 @@ server.3=zoo3:2888:3888
 </programlisting>
 
       <para>The new entry, <emphasis role="bold">initLimit</emphasis> is
-      timeouts ZooKeeper uses to limit the length of time the Zookeeper
+      timeouts ZooKeeper uses to limit the length of time the ZooKeeper
       servers in quorum have to connect to a leader. The entry <emphasis
       role="bold">syncLimit</emphasis> limits how far out of date a server can
       be from a leader.</para>