Merge lp:~hrvojem/percona-xtradb-cluster/bug918060 into lp:~percona-dev/percona-xtradb-cluster/5.5.17-22.1

[Hrvoje Matijakovic]

[Vadim Tkachenko (vadim-tk)]

review: Approve

=== modified file 'doc/source/3nodesec2.rst'
--- doc/source/3nodesec2.rst	2011-12-23 07:28:16 +0000
+++ doc/source/3nodesec2.rst	2012-01-18 14:24:25 +0000
@@ -1,39 +1,39 @@
 How to setup 3 node cluster in EC2 enviroment
 ==============================================
 
-This is how-to setup 3-node cluster in EC2 enviroment.
+This is how to setup 3-node cluster in EC2 enviroment.
 
 Assume you are running *m1.xlarge* instances with OS *Red Hat Enterprise Linux 6.1 64-bit*.
 
 Install XtraDB Cluster from RPM:
 
-1. Install Percona's regular and testing repositories ::
+1. Install Percona's regular and testing repositories: ::
 
         rpm -Uhv http://repo.percona.com/testing/centos/6/os/noarch/percona-testing-0.0-1.noarch.rpm
         rpm -Uhv http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
 
-2. Install Percona XtraDB Cluster packages ::
+2. Install Percona XtraDB Cluster packages: ::
 
         yum install Percona-XtraDB-Cluster-server Percona-XtraDB-Cluster-client
 
-3. Create data directories ::
+3. Create data directories: ::
 
         mkdir -p /mnt/data
         mysql_install_db --datadir=/mnt/data
 
-4. Stop firewall. Cluster requires couple TCP ports to operate. Easiest way :: 
+4. Stop firewall. Cluster requires couple TCP ports to operate. Easiest way: :: 
 
         service iptables stop
 
 If you want to open only specific ports, you need to open 3306, 4444, 4567, 4568 ports.
-For example for 4567 port (substitute 192.168.0.1 by your IP) ::
+For example for 4567 port (substitute 192.168.0.1 by your IP): ::
 
         iptables -A INPUT -i eth0 -p tcp -m tcp --source 192.168.0.1/24 --dport 4567 -j ACCEPT
 
 
 5. Create /etc/my.cnf files.
 
-On the first node (assume IP 10.93.46.58) ::
+On the first node (assume IP 10.93.46.58): ::
 
   [mysqld]
   datadir=/mnt/data
@@ -54,7 +54,7 @@
   innodb_autoinc_lock_mode=2
 
 
-On the second node ::
+On the second node: ::
 
   [mysqld]
   datadir=/mnt/data
@@ -74,33 +74,32 @@
   innodb_locks_unsafe_for_binlog=1
   innodb_autoinc_lock_mode=2
 
-On the third (and following nodes) config is similar, with following change ::
+On the third (and following nodes) config is similar, with the following change: ::
 
   wsrep_node_name=node3
 
 6. Start mysqld
 
-On the first node ::
+On the first node: ::
 
    /usr/sbin/mysqld
    or
    mysqld_safe
 
-You should be able to see in console (or in error-log file) ::
+You should be able to see in console (or in error-log file): ::
 
   111216  0:16:42 [Note] /usr/sbin/mysqld: ready for connections.
   Version: '5.5.17'  socket: '/var/lib/mysql/mysql.sock'  port: 3306  Percona XtraDB Cluster (GPL), Release alpha22.1, Revision 3673 wsrep_22.3.r3673
   111216  0:16:42 [Note] WSREP: Assign initial position for certification: 0, protocol version: 1
   111216  0:16:42 [Note] WSREP: Synchronized with group, ready for connections
 
-On the second (and following nodes) ::
-
+On the second (and following nodes): ::
 
    /usr/sbin/mysqld
    or
    mysqld_safe
 
-You should be able to see in console (or in error-log file) ::
+You should be able to see in console (or in error-log file): ::
 
   111216  0:21:39 [Note] WSREP: Flow-control interval: [12, 23]
   111216  0:21:39 [Note] WSREP: Shifting OPEN -> PRIMARY (TO: 0)
@@ -141,7 +140,7 @@
 
 When all nodes are in SYNCED stage your cluster is ready!
 
-7. Connect to database on any node and create database ::
+7. Connect to database on any node and create database: ::
 
         mysql
         > CREATE DATABASE hello_tom;
 
=== added file 'doc/source/_static/cluster-diagram1.png'
 Binary files doc/source/_static/cluster-diagram1.png	1970-01-01 00:00:00 +0000 and doc/source/_static/cluster-diagram1.png	2012-01-18 14:24:25 +0000 differ
=== added file 'doc/source/bugreport.rst'
--- doc/source/bugreport.rst	1970-01-01 00:00:00 +0000
+++ doc/source/bugreport.rst	2012-01-18 14:24:25 +0000
@@ -0,0 +1,4 @@
+How to Report Bugs
+==================
+
+All bugs can be reported on `Launchpad <https://bugs.launchpad.net/percona-xtradb-cluster/+filebug>`_. Please note that error.log files from **all** the nodes need to be submitted. 
 
=== modified file 'doc/source/conf.py'
--- doc/source/conf.py	2011-12-13 16:28:28 +0000
+++ doc/source/conf.py	2012-01-18 14:24:25 +0000
@@ -44,7 +44,7 @@
 
 # General information about the project.
 project = u'Percona XtraDB Cluster'
-copyright = u'2011, Percona Inc'
+copyright = u'2012, Percona Inc'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -96,6 +96,8 @@
 
 .. |XtraDB|  replace:: :term:`XtraDB`
 
+.. |IST|  replace:: :term:`IST`
+
 .. |XtraDB Cluster|  replace:: :term:`XtraDB Cluster`
 
 .. |Percona XtraDB Cluster|  replace:: :term:`Percona XtraDB Cluster`
@@ -104,6 +106,10 @@
 
 .. |MyISAM|  replace:: :term:`MyISAM`
 
+.. |split brain|  replace:: :term:`split brain`
+
+.. |.frm|  replace:: :term:`.frm`
+
 .. |LSN|  replace:: :term:`LSN`
 
 .. |XtraBackup|  replace:: *XtraBackup*
 
=== modified file 'doc/source/faq.rst'
--- doc/source/faq.rst	2012-01-14 17:24:09 +0000
+++ doc/source/faq.rst	2012-01-18 14:24:25 +0000
@@ -6,64 +6,65 @@
 ========================================================
 A: For auto-increment particular, Cluster changes auto_increment_offset
 for each new node.
-In the single node workload, locking handled by usual way how InnoDB handles locks. 
+In the single node workload, locking handled by usual way how |InnoDB| handles locks. 
 In case of write load on several nodes, Cluster uses optimistic locking (http://en.wikipedia.org/wiki/Optimistic_concurrency_control) and application may receive lock error in the response on COMMIT query.
 
 Q: What if one of the nodes crashes and innodb recovery roll back some transactions? 
 =====================================================================================
 A: When the node crashes, after the restart it will copy whole dataset from another node
-(if there were changes to data since crash) 
+(if there were changes to data since crash). 
 
 Q: Is there a chance to have different table structure on the nodes? 
 =====================================================================
-what I mean is like having 4nodes, 4 tables like sessions_a, sessions_b, sessions_c and sessions_d and have each only on one of the nodes? 
+What I mean is like having 4 nodes, 4 tables like sessions_a, sessions_b, sessions_c and sessions_d and have each only on one of the nodes? 
 
 A: Not at the moment for InnoDB tables. But it will work for MEMORY tables.
 
-Q: What if a node fail and/or what if there is a network issue between them 
-============================================================================
+Q: What if a node fail and/or what if there is a network issue between them? 
+=============================================================================
 A: Then Quorum mechanism in XtraDB Cluster will decide what nodes can accept traffic
 and will shutdown nodes that not belong to quorum. Later when the failure is fixed,
 the nodes will need to copy data from working cluster.
 
 Q: How would it handle split brain? 
 ====================================
-A: It would not handle it. The |split brain| is hard stop, XtraDB Cluster can't resolve it.
+A: It would not handle it. The |split brain| is hard stop, |XtraDB Cluster| can't resolve it.
 That's why the minimal recommendation is to have 3 nodes. 
 However there is possibility to allow a node to handle the traffic, option is: ::
   
   wsrep_provider_options="pc.ignore_sb = yes"
 
-Q: I have a two nodes setup. When node1 fails, node2 does not accept commands, why ?
-=====================================================================================
+Q: I have a two nodes setup. When node1 fails, node2 does not accept commands, why?
+====================================================================================
 A: This is expected behaviour, to prevent |split brain|. See previous question.
 
-Q: What tcp ports are used by Percona XtraDB Cluster ?
+Q: What tcp ports are used by Percona XtraDB Cluster?
 ======================================================
 A: You may need to open up to 4 ports if you are using firewall.
 
- * Regular MySQL port, default 3306
- * Port for group communication, default 4567. It can be changed by the option: ::
-
-  wsrep_provider_options = "gmcast.listen_addr=tcp://0.0.0.0:4010; "
-
- * Port for State Transfer, default 4444. It can be changed by the option: ::
-
-  wsrep_sst_receive_address=10.11.12.205:5555
-
- * Port for Incremental State Transfer, default port for group communication + 1 (4568). It can be changed by the option: ::
-
-  wsrep_provider_options = "ist.recv_addr=10.11.12.206:7777; "
-
-Q: Is there "async" mode for Cluster or only "sync" commits are supported ? 
+1. Regular MySQL port, default 3306.
+
+2. Port for group communication, default 4567. It can be changed by the option: ::
+
+     wsrep_provider_options ="gmcast.listen_addr=tcp://0.0.0.0:4010; "
+
+3. Port for State Transfer, default 4444. It can be changed by the option: ::
+
+     wsrep_sst_receive_address=10.11.12.205:5555
+
+4. Port for Incremental State Transfer, default port for group communication + 1 (4568). It can be changed by the option: ::
+
+     wsrep_provider_options = "ist.recv_addr=10.11.12.206:7777; "
+
+Q: Is there "async" mode for Cluster or only "sync" commits are supported? 
 ===========================================================================
-A: There is no "async" mode, all commits are syncronious on all nodes.
-Or, to be fully correct, the commits are "virtually" syncronious. Which
-means that transaction should pass "certification" on nodes, not physicall commit.
+A: There is no "async" mode, all commits are synchronous on all nodes.
+Or, to be fully correct, the commits are "virtually" synchronous. Which
+means that transaction should pass "certification" on nodes, not physical commit.
 "Certification" means a guarantee that transaction does not have conflicts with 
 another transactions on corresponding node.
 
-Q: Does it work with regular MySQL replication ?
+Q: Does it work with regular MySQL replication?
 ================================================
 A: Yes. On the node  you are going to use as master, you should enable log-bin and log-slave-update options.
 
@@ -73,9 +74,3 @@
   
   echo 0 > /selinux/enforce
 
-
-
-
-
-
-
 
=== added directory 'doc/source/features'
=== added file 'doc/source/features/highavailability.rst'
--- doc/source/features/highavailability.rst	1970-01-01 00:00:00 +0000
+++ doc/source/features/highavailability.rst	2012-01-18 14:24:25 +0000
@@ -0,0 +1,28 @@
+High Availability
+=================
+
+Basic setup: you run 3-nodes setup.
+
+The |Percona XtraDB Cluster| will continue to function when you take any of nodes down.
+At any point in time you can shutdown any Node to perform maintenance or make 
+configuration changes. Even in unplanned situations like Node crash or if it 
+becomes network unavailable the Cluster will continue to work, and you'll be able 
+to run queries on working nodes.
+
+The biggest question there, what will happen when the Node joins the cluster back, and 
+there were changes to data while the node was down. Let's focus on this with details.
+
+There is two ways that Node may use when it joins the cluster: State Snapshot Transfer
+ (SST) and Incremental State Transfer (IST).
+
+* SST is the full copy if data from one node to another. It's used when new node joins the cluster, it has to transfer data from existing node. There are three methods of SST available in Percona XtraDB Cluster: :program:`mysqldump`, :program:`rsync` and :program:`xtrabackup` (Percona |XtraBackup| with support of XtraDB Cluster will be released soon, so far you need to use our `source code repository <http://www.percona.com/doc/percona-xtrabackup/installation/compiling_xtrabackup.html>`_). The downside of `mysqldump` and `rsync` is that your cluster becomes READ-ONLY for time that takes to copy data from one node to another (SST applies :command:`FLUSH TABLES WITH READ LOCK` command). Xtrabackup SST does not require :command:`READ LOCK` for full time, only for syncing |.FRM| files (the same as with regular backup).
+
+* Even with that, SST may be intrusive, that’s why there is IST mechanism. If you put your node down for short period of time and then start it, the node is able to fetch only changes made during period it was down.This is done using caching mechanism on nodes. Each node contains a cache, ring-buffer, (the size is configurable) of last N changes, and the node is able to transfer part of this cache. Obviously IST can be done only if amount of changes needed to transfer is less than N. If it exceeds N, then the joining node has to perform SST.
+
+You can monitor current state of Node by using
+
+.. code-block:: mysql
+
+   SHOW STATUS LIKE 'wsrep_local_state_comment';
+
+When it is ‘Synced (6)’, the node is ready to handle traffic.
 
=== modified file 'doc/source/glossary.rst'
--- doc/source/glossary.rst	2012-01-11 17:47:46 +0000
+++ doc/source/glossary.rst	2012-01-18 14:24:25 +0000
@@ -7,30 +7,35 @@
    LSN
      Each InnoDB page (usually 16kb in size) contains a log sequence number, or LSN. The LSN is the system version number for the entire database. Each page's LSN shows how recently it was changed.
 
-
    InnoDB
-      Storage engine which provides ACID-compilant transactions and foreing key support, among others improvements over :term:`MyISAM`. It is the default engine for |MySQL| as of the 5.5 series.
+      Storage engine which provides ACID-compliant transactions and foreign key support, among others improvements over :term:`MyISAM`. It is the default engine for |MySQL| as of the 5.5 series.
 
    MyISAM
      Previous default storage engine for |MySQL| for versions prior to 5.5. It doesn't fully support transactions but in some scenarios may be faster than :term:`InnoDB`. Each table is stored on disk in 3 files: :term:`.frm`, :term:`.MYD`, :term:`.MYI`
+	
+   IST
+     Incremental State Transfer. Functionallity which instead of whole state snapshot can catch up with te group by receiving the missing writesets, but only if the writeset is still in the donor's writeset cache
+
+   XtraBackup
+     *Percona XtraBackup* is an open-source hot backup utility for |MySQL| - based servers that doesn’t lock your database during the backup.
 
    XtraDB
      *Percona XtraDB* is an enhanced version of the InnoDB storage engine, designed to better scale on modern hardware, and including a variety of other features useful in high performance environments. It is fully backwards compatible, and so can be used as a drop-in replacement for standard InnoDB. More information `here <http://www.percona.com/docs/wiki/Percona-XtraDB:start>`_ .
 
    XtraDB Cluster
-     *Percona XtraDB Cluster* is a high availablity solution for MySQL
+     *Percona XtraDB Cluster* is a high availability solution for MySQL
 
    Percona XtraDB Cluster
-     *Percona XtraDB Cluster* is a high availablity solution for MySQL
+     *Percona XtraDB Cluster* is a high availability solution for MySQL
 
    my.cnf
-     This file refers to the database server's main configuration file. Most linux distributions place it as :file:`/etc/mysql/my.cnf`, but the location and name depends on the particular installation. Note that this is not the only way of configuring the server, some systems does not have one even and rely on the command options to start the server and its defaults values.
+     This file refers to the database server's main configuration file. Most Linux distributions place it as :file:`/etc/mysql/my.cnf`, but the location and name depends on the particular installation. Note that this is not the only way of configuring the server, some systems does not have one even and rely on the command options to start the server and its defaults values.
 
    datadir
     The directory in which the database server stores its databases. Most Linux distribution use :file:`/var/lib/mysql` by default.
 
    ibdata
-     Default prefix for tablespace files, e.g. :file:`ibdata1` is a 10MB  autoextensible file that |MySQL| creates for the shared tablespace by default. 
+     Default prefix for tablespace files, e.g. :file:`ibdata1` is a 10MB  autoextendable file that |MySQL| creates for the shared tablespace by default. 
 
    innodb_file_per_table
      InnoDB option to use separate .ibd files for each table.
@@ -54,10 +59,10 @@
      Each table using the :program:`MERGE` storage engine, besides of a :term:`.frm` file, will have :term:`.MRG` file containing the names of the |MyISAM| tables associated with it.
 
    .TRG
-     File containing the TRiGgers associated to a table, e.g. `:file:`mytable.TRG`. With the :term:`.TRN` file, they represent all the Trigger definitions.
+     File containing the triggers associated to a table, e.g. `:file:`mytable.TRG`. With the :term:`.TRN` file, they represent all the trigger definitions.
 
    .TRN
-     File containing the TRiggers' Names associated to a table, e.g. `:file:`mytable.TRN`. With the :term:`.TRG` file, they represent all the Trigger definitions.
+     File containing the triggers' Names associated to a table, e.g. `:file:`mytable.TRN`. With the :term:`.TRG` file, they represent all the trigger definitions.
 
    .ARM
      Each table with the :program:`Archive Storage Engine` has ``.ARM`` file which contains the metadata of it.
 
=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2012-01-11 16:46:28 +0000
+++ doc/source/index.rst	2012-01-18 14:24:25 +0000
@@ -12,13 +12,13 @@
  
  * Synchronous replication. Transaction either commited on all nodes or none.
 
- * Multi-master  replication. You can write to any node.
+ * Multi-master replication. You can write to any node.
 
  * Parallel applying events on slave. Real “parallel replication”.
 
  * Automatic node provisioning.
 
- * Data consistency. No more unsyncronised slaves.
+ * Data consistency. No more unsynchronized slaves.
 
 Percona XtraDB Cluster is fully compatible with MySQL or Percona Server in the following meaning:
 
@@ -35,6 +35,7 @@
    :glob:
 
    intro
+   resources
 
 Installation
 ============
@@ -46,6 +47,15 @@
    installation
    installation/compiling_xtradb_cluster
 
+Features
+========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   features/highavailability
+
 FAQ
 ===
 
@@ -65,7 +75,7 @@
   
    singlebox
    3nodesec2
-
+   bugreport
 
 Percona XtraDB Cluster limitations
 ==================================
 
=== modified file 'doc/source/installation.rst'
--- doc/source/installation.rst	2011-12-14 02:32:00 +0000
+++ doc/source/installation.rst	2012-01-18 14:24:25 +0000
@@ -61,9 +61,9 @@
 Install XtraBackup SST method
 ==============================
 
-To use Percona XtraBackup for State Transfer method (copy snapsot of data between nodes)
-you can use the regular xtrabackup package with the script what supports galera information.
-You can take *innobackupex* script from source code `innobackupex <http://bazaar.launchpad.net/~percona-dev/percona-xtrabackup/galera-info/view/head:/innobackupex>`_
+To use Percona XtraBackup for State Transfer method (copy snapshot of data between nodes)
+you can use the regular xtrabackup package with the script what supports Galera information.
+You can take *innobackupex* script from source code `innobackupex <http://bazaar.launchpad.net/~percona-dev/percona-xtrabackup/galera-info/view/head:/innobackupex>`_.
 
 To inform node to use xtrabackup you need to specify in my.cnf: ::
 
 
=== modified file 'doc/source/installation/bin_distro_specific.rst'
--- doc/source/installation/bin_distro_specific.rst	2011-12-13 06:38:29 +0000
+++ doc/source/installation/bin_distro_specific.rst	2012-01-18 14:24:25 +0000
@@ -19,7 +19,7 @@
     cp ./usr/bin/tar4ibd /usr/bin
     cp ./usr/bin/innobackupex-1.5.1 /usr/bin
 
-* If you use a version prior to 1.6, the stock perl causes an issue with the backup scripts version detection. Edit :file:`/usr/bin/innobackupex-1.5.1`. Comment out the lines below as shown below ::
+* If you use a version prior to 1.6, the stock perl causes an issue with the backup scripts version detection. Edit :file:`/usr/bin/innobackupex-1.5.1`. Comment out the lines below as shown below: ::
 
     $perl_version = chr($required_perl_version[0])
     . chr($required_perl_version[1])
 
=== modified file 'doc/source/installation/compiling_xtradb_cluster.rst'
--- doc/source/installation/compiling_xtradb_cluster.rst	2011-12-13 06:38:29 +0000
+++ doc/source/installation/compiling_xtradb_cluster.rst	2012-01-18 14:24:25 +0000
@@ -30,11 +30,12 @@
 Compiling 
 ------------
 
-The most esiest way to build binaries is to run
-script BUILD/compile-pentium64-wsrep
+The most esiest way to build binaries is to run script: ::
+
+  BUILD/compile-pentium64-wsrep
 
 If you feel confident to use cmake, you make compile with cmake adding
 -DWITH_WSREP=1 to parameters.
 
-Exampes how to build RPM and DEB packages you can find in packaging/percona directory in the source code
+Examples how to build RPM and DEB packages you can find in packaging/percona directory in the source code.
 
 
=== modified file 'doc/source/installation/yum_repo.rst'
--- doc/source/installation/yum_repo.rst	2012-01-10 02:33:47 +0000
+++ doc/source/installation/yum_repo.rst	2012-01-18 14:24:25 +0000
@@ -13,7 +13,7 @@
 
   $ rpm -Uhv http://repo.percona.com/testing/centos/6/os/noarch/percona-testing-0.0-1.noarch.rpm
 
-You may want to install also Percona stable repository, which provides Percona-shared-compat rpm, needed to satisfy dependencies ::
+You may want to install also Percona stable repository, which provides Percona-shared-compat rpm, needed to satisfy dependencies: ::
  
   $ rpm -Uhv http://www.percona.com/downloads/percona-release/percona-release-0.0-1.x86_64.rpm
 
 
=== modified file 'doc/source/intro.rst'
--- doc/source/intro.rst	2011-12-14 00:33:37 +0000
+++ doc/source/intro.rst	2012-01-18 14:24:25 +0000
@@ -4,37 +4,57 @@
 
 *Percona XtraDB Cluster* is open-source, free |MySQL| High Availability software 
 
+General introduction
+====================
+
+1. The Cluster consists of Nodes. Recommended configuration is to have at least 3 nodes, but you can make it running with 2 nodes as well.
+2. Each Node is regular |MySQL| / |Percona Server| setup. The point is that you can convert your existing MySQL / Percona Server into Node and roll Cluster using it as a base. Or otherwise – you can detach Node from Cluster and use it as just a regular server.
+3. Each Node contains the full copy of data. That defines XtraDB Cluster behavior in many ways. And obviously there are benefits and drawbacks.
+
+.. image:: _static/cluster-diagram1.png
+
+Benefits of such approach:
+ * When you execute a query, it is executed locally on the node. All data is available locally, no need for remote access.
+ * No central management. You can loose any node at any point of time, and the cluster will continue to function.
+ * Good solution for scaling a read workload. You can put read queries to any of the nodes.
+
+Drawbacks:
+ * Overhead of joining new node. The new node has to copy full dataset from one of existing nodes. If it is 100GB, it copies 100GB.
+ * This can’t be used as an effective write scaling solution. There might be some improvements in write throughput when you run write traffic to 2 nodes vs all traffic to 1 node, but you can't expect a lot. All writes still have to go on all nodes.
+ * You have several duplicates of data, for 3 nodes – 3 duplicates.
+
 What is core difference Percona XtraDB Cluster from MySQL Replication ?
 =======================================================================
 
-Let's take look into well know CAP theorem for Distributed systems.
+Let's take look into the well known CAP theorem for Distributed systems.
 Characteristics of Distributed systems:
 
- C - Consistency (all your data is consistent on all nodes)
-
- A - Availability  (your system is AVAILABLE to handle requests in case of  failure of one or several nodes )
-
- P - Partitioning  tolerance (in case of inter-node connection failure, each node is still available to handle requests)
+ C - Consistency (all your data is consistent on all nodes),
+
+ A - Availability  (your system is AVAILABLE to handle requests in case of  failure of one or several nodes ),
+
+ P - Partitioning  tolerance (in case of inter-node connection failure, each node is still available to handle requests).
 
 
 CAP theorem says that each Distributed system can have only two out of these three.
 
-MySQL replication has:  Availability and Partitioning  tolerance
-
-Percona XtraDB Cluster has: Consistency and Availability
-
-That is MySQL replication does not guarantee Consistency of your data, while Percona XtraDB Cluster  provides data Consistency. (And, yes, Percona XtraDB Cluster looses Partitioning  tolerance property)
+MySQL replication has: Availability and Partitioning tolerance.
+
+Percona XtraDB Cluster has: Consistency and Availability.
+
+That is MySQL replication does not guarantee Consistency of your data, while Percona XtraDB Cluster provides data Consistency. (And yes, Percona XtraDB Cluster looses Partitioning tolerance property).
 
 Components
 ==========
 
 *Percona XtraDB Cluster* is based on `Percona Server with XtraDB <http://www.percona.com/software/percona-server/>`_
-and includes `Write Set REPlication patches <https://launchpad.net/codership-mysql>`_.
+and includes `Write Set Replication patches <https://launchpad.net/codership-mysql>`_.
 It uses  the  `Galera library <https://launchpad.net/galera>`_, version 2.x, 
 a generic Synchronous Multi-Master replication plugin for transactional applications. 
 
-Galera library is developed by `Codership Oy <http://www.codership.com/>`_
+Galera library is developed by `Codership Oy <http://www.codership.com/>`_.
 
 Galera 2.x supports such new features as:
- * Incremental State Transfer, especially useful for WAN deployments
- * RSU, Rolling Schema Update. Schema change does not block operations against table
+ * Incremental State Transfer (|IST|), especially useful for WAN deployments,
+ * RSU, Rolling Schema Update. Schema change does not block operations against table.
+
 
=== modified file 'doc/source/limitation.rst'
--- doc/source/limitation.rst	2011-12-14 00:33:37 +0000
+++ doc/source/limitation.rst	2012-01-18 14:24:25 +0000
@@ -2,43 +2,29 @@
  Percona XtraDB Cluster Limitations
 ====================================
 
-There are some limitations which we should be aware of. Some of them will be eliminated later as product is improved;  some are design limitations.
-
- - Currently replication works only with InnoDB storage engine. Any writes to
-   tables of other types, including system (mysql.*) tables are not replicated.
-   However, DDL statements are replicated in statement level, and changes
-   to mysql.* tables will get replicated that way.
-   So, you can safely issue: CREATE USER...,
-   but issuing: INSERT INTO mysql.user..., will not be replicated.
-
- - DELETE operation is unsupported on tables without primary key. Also rows in
-   tables without primary key may appear in different order on different nodes.
-   As a result SELECT...LIMIT... may return slightly different sets.
+There are some limitations which you should be aware of. Some of them will be eliminated later as product is improved and some are design limitations.
+
+ - Currently replication works only with |InnoDB| storage engine. Any writes to tables of other types, including system (mysql.*) tables, are not replicated. However, DDL statements are replicated in statement level, and changes to mysql.* tables will get replicated that way. So, you can safely issue: CREATE USER..., but issuing: INSERT INTO mysql.user..., will not be replicated.
+
+ - DELETE operation is unsupported on tables without primary key. Also rows in tables without primary key may appear in different order on different nodes. As a result SELECT...LIMIT... may return slightly different sets.
 
  - Unsupported queries:
     * LOCK/UNLOCK TABLES cannot be supported in multi-master setups.
     * lock functions (GET_LOCK(), RELEASE_LOCK()... )
 
- - Query log cannot be directed to table. If you enable query logging,
-   you must forward the log to a file:
-       log_output = FILE
-   Use general_log and general_log_file to choose query logging and the
-   log file name
-
- - Maximum allowed transaction size is defined by wsrep_max_ws_rows and
-   wsrep_max_ws_size. Anything bigger (e.g. huge LOAD DATA) will be rejected.
-
- - Due to cluster level optimistic concurrency control, transaction issuing
-   COMMIT may still be aborted at that stage. There can be two transactions.
-   writing to same rows and committing in separate XtraDB Cluster nodes, and only one
-   of the them can successfully commit. The failing one will be aborted.
-   For cluster level aborts, XtraDB Cluster gives back deadlock error.
-   code (Error: 1213 SQLSTATE: 40001  (ER_LOCK_DEADLOCK)).
+ - Query log cannot be directed to table. If you enable query logging, you must forward the log to a file: log_output = FILE. Use general_log and general_log_file to choose query logging and the log file name.
+
+ - Maximum allowed transaction size is defined by wsrep_max_ws_rows and wsrep_max_ws_size. Anything bigger (e.g. huge LOAD DATA) will be rejected.
+
+ - Due to cluster level optimistic concurrency control, transaction issuing COMMIT may still be aborted at that stage. There can be two transactions writing to same rows and committing in separate XtraDB Cluster nodes, and only one of the them can successfully commit. The failing one will be aborted. For cluster level aborts, XtraDB Cluster gives back deadlock error code: 
+   (Error: 1213 SQLSTATE: 40001  (ER_LOCK_DEADLOCK)).
 
  - XA transactions can not be supported due to possible rollback on commit.
 
- - The write throughput of the whole cluster is limited by weakest node. If one node becomes slow, whole cluster is slow. If you have requirements for stable high performance, then it should be supported by corresponding hardware (10Gb network, SSD)
+ - The write throughput of the whole cluster is limited by weakest node. If one node becomes slow, whole cluster is slow. If you have requirements for stable high performance, then it should be supported by corresponding hardware (10Gb network, SSD).
 
- - The minimal recommended size of cluster is 3 nodes
+ - The minimal recommended size of cluster is 3 nodes.
 
  - DDL statements are problematic and may stall cluster. Later, the support of DDL will be improved, but will always require special treatment. 
+
+
 
=== modified file 'doc/source/resources.rst'
--- doc/source/resources.rst	2011-12-21 05:51:01 +0000
+++ doc/source/resources.rst	2012-01-18 14:24:25 +0000
@@ -1,3 +1,7 @@
+=========
+Resources
+=========
+
 In general there are 4 resources that need to be different when you want to run several MySQL/Galera nodes on one host:
 
 1) data directory
@@ -5,19 +9,18 @@
 3) galera replication listen port and/or address
 4) receive address for state snapshot transfer
 
-
-and later incremental state transfer receive address will be added to the bunch. (I know, it is kinda a lot, but we don't see how it can be meaningfully reduced yet)
-
-The first two is the usual mysql stuff.
-
-You figured out the third. It is also possible to pass it via
-
-wsrep_provider_options="gmcast.listen_addr=tcp://127.0.0.1:5678"
-
-as most other galera options. This may save you some extra typing.
+and later incremental state transfer receive address will be added to the bunch. (I know, it is kinda a lot, but we don't see how it can be meaningfully reduced yet).
+
+The first two are the usual mysql stuff.
+
+You figured out the third. It is also possible to pass it via: ::
+
+   wsrep_provider_options="gmcast.listen_addr=tcp://127.0.0.1:5678"
+
+as most other Galera options. This may save you some extra typing.
 
 The fourth one is wsrep_sst_receive_address. This is the address at which the node will be listening for and receiving the state. Note that in galera cluster _joining_ nodes are waiting for connections from donors. It goes contrary to tradition and seems to confuse people time and again, but there are good reasons it was made like that.
 
 If you use mysqldump SST it should be the same as this mysql client connection address plus you need to set wsrep_sst_auth variable to hold user:password pair. The user should be privileged enough to read system tables from donor and create system tables on this node. For simplicity that could be just the root user. Note that it also means that you need to properly set up the privileges on the new node before attempting to join the cluster.
 
-If you use rsync or xtrabackup SST, wsrep_sst_auth is not necessary unless your SST script makes use of it. wsrep_sst_address can be anything local (it may even be the same on all nodes provided you'll be starting them one at a time).
+If you use rsync or |xtrabackup| SST, wsrep_sst_auth is not necessary unless your SST script makes use of it. wsrep_sst_address can be anything local (it may even be the same on all nodes provided you'll be starting them one at a time).
 
=== modified file 'doc/source/singlebox.rst'
--- doc/source/singlebox.rst	2011-12-16 03:50:49 +0000
+++ doc/source/singlebox.rst	2012-01-18 14:24:25 +0000
@@ -1,64 +1,64 @@
 How to setup 3 node cluster on single box
 ==========================================
 
-This is how-to setup 3-node cluster on the single physical box.
+This is how to setup 3-node cluster on the single physical box.
 
-Assume you installed Percona XtraDB Cluster from binary .tar.gz into directory
+Assume you installed |Percona XtraDB Cluster| from binary .tar.gz into directory
 
 /usr/local/Percona-XtraDB-Cluster-5.5.17-22.1-3673.Linux.x86_64.rhel6
 
 
-Now we need to create couple my.cnf files and couple data directories.
+Now we need to create couple my.cnf files and couple of data directories.
 
-Assume we created (see the content of files at the end of document)
+Assume we created (see the content of files at the end of document):
 
  * /etc/my.4000.cnf
  * /etc/my.5000.cnf
  * /etc/my.6000.cnf
 
-and data directories
+and data directories:
 
  * /data/bench/d1
  * /data/bench/d2
  * /data/bench/d3
 
-and assume the local IP address is 10.11.12.205
+and assume the local IP address is 10.11.12.205.
 
-then we should be able to start initial node as (from directory /usr/local/Percona-XtraDB-Cluster-5.5.17-22.1-3673.Linux.x86_64.rhel6)::
+Then we should be able to start initial node as (from directory /usr/local/Percona-XtraDB-Cluster-5.5.17-22.1-3673.Linux.x86_64.rhel6): ::
 
         bin/mysqld --defaults-file=/etc/my.4000.cnf
 
-Following output will let out know that node was started succsefully::
+Following output will let out know that node was started successfully: ::
 
         111215 19:01:49 [Note] WSREP: Shifting JOINED -> SYNCED (TO: 0)
         111215 19:01:49 [Note] WSREP: New cluster view: global state: 4c286ccc-2792-11e1-0800-94bd91e32efa:0, view# 1: Primary, number of nodes: 1, my index: 0, protocol version 1
 
 
-And you can check used ports::
+And you can check used ports: ::
         
         netstat -anp | grep mysqld
         tcp        0      0 0.0.0.0:4000                0.0.0.0:*                   LISTEN      8218/mysqld         
         tcp        0      0 0.0.0.0:4010                0.0.0.0:*                   LISTEN      8218/mysqld
 
 
-After first node, we start second and third::
+After first node, we start second and third: ::
 
         bin/mysqld --defaults-file=/etc/my.5000.cnf
         bin/mysqld --defaults-file=/etc/my.6000.cnf
 
-Succesfull start will produce following output::
+Successful start will produce the following output: ::
 
         111215 19:22:26 [Note] WSREP: Shifting JOINER -> JOINED (TO: 2)
         111215 19:22:26 [Note] WSREP: Shifting JOINED -> SYNCED (TO: 2)
         111215 19:22:26 [Note] WSREP: Synchronized with group, ready for connections
 
 
-Now you can connect to any node and create database, which will be automatically propagated to another nodes::
+Now you can connect to any node and create database, which will be automatically propagated to other nodes: ::
         
         mysql -h127.0.0.1 -P5000 -e "CREATE DATABASE hello_peter"
 
 
-Configuration files (/etc/my.4000.cnf)::
+Configuration files (/etc/my.4000.cnf): ::
 
   /etc/my.4000.cnf
 
@@ -90,7 +90,7 @@
   innodb_locks_unsafe_for_binlog=1
   innodb_autoinc_lock_mode=2
 
-Configuration files (/etc/my.5000.cnf). PLEASE see difference in *wsrep_cluster_address* ::
+Configuration files (/etc/my.5000.cnf). PLEASE see the difference in *wsrep_cluster_address*: ::
 
   /etc/my.5000.cnf
   [mysqld]
@@ -122,7 +122,7 @@
   innodb_autoinc_lock_mode=2
 
 
-Configuration files (/etc/my.6000.cnf). PLEASE see difference in *wsrep_cluster_address* ::
+Configuration files (/etc/my.6000.cnf). PLEASE see the difference in *wsrep_cluster_address*: ::
 
   /etc/my.6000.cnf