Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-11199 One-time effort to pretty-print the Docbook XML, to make further patch review easier (Misty Stanley-Jones)

This commit is contained in:
Michael Stack 2014-05-28 07:58:50 -07:00
parent ab896f05d1
commit 63e8304e96
19 changed files with 8289 additions and 7042 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1221
src/main/docbkx/book.xml
View File

File diff suppressed because it is too large Load Diff

232
src/main/docbkx/case_studies.xml
View File

@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="casestudies" <chapter
version="5.0"
xml:id="casestudies"
xmlns="http://docbook.org/ns/docbook" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
@ -27,86 +29,123 @@
*/ */
--> -->
<title>Apache HBase Case Studies</title> <title>Apache HBase Case Studies</title>
<section xml:id="casestudies.overview"> <section
xml:id="casestudies.overview">
<title>Overview</title> <title>Overview</title>
<para>This chapter will describe a variety of performance and troubleshooting case studies that can <para> This chapter will describe a variety of performance and troubleshooting case studies that
provide a useful blueprint on diagnosing Apache HBase cluster issues.</para> can provide a useful blueprint on diagnosing Apache HBase cluster issues. </para>
<para>For more information on Performance and Troubleshooting, see <xref linkend="performance"/> and <xref linkend="trouble"/>. <para> For more information on Performance and Troubleshooting, see <xref
</para> linkend="performance" /> and <xref
linkend="trouble" />. </para>
</section> </section>
<section xml:id="casestudies.schema"> <section
xml:id="casestudies.schema">
<title>Schema Design</title> <title>Schema Design</title>
<para>See the schema design case studies here: <xref linkend="schema.casestudies"/> <para>See the schema design case studies here: <xref
linkend="schema.casestudies" />
</para> </para>
</section> <!-- schema design --> </section>
<!-- schema design -->
<section xml:id="casestudies.perftroub"> <section
xml:id="casestudies.perftroub">
<title>Performance/Troubleshooting</title> <title>Performance/Troubleshooting</title>
<section xml:id="casestudies.slownode"> <section
xml:id="casestudies.slownode">
<title>Case Study #1 (Performance Issue On A Single Node)</title> <title>Case Study #1 (Performance Issue On A Single Node)</title>
<section><title>Scenario</title> <section>
<para>Following a scheduled reboot, one data node began exhibiting unusual behavior. Routine MapReduce <title>Scenario</title>
jobs run against HBase tables which regularly completed in five or six minutes began taking 30 or 40 minutes <para> Following a scheduled reboot, one data node began exhibiting unusual behavior.
to finish. These jobs were consistently found to be waiting on map and reduce tasks assigned to the troubled data node Routine MapReduce jobs run against HBase tables which regularly completed in five or six
(e.g., the slow map tasks all had the same Input Split). minutes began taking 30 or 40 minutes to finish. These jobs were consistently found to be
The situation came to a head during a distributed copy, when the copy was severely prolonged by the lagging node. waiting on map and reduce tasks assigned to the troubled data node (e.g., the slow map
</para> tasks all had the same Input Split). The situation came to a head during a distributed
copy, when the copy was severely prolonged by the lagging node. </para>
</section> </section>
<section><title>Hardware</title> <section>
<para>Datanodes: <title>Hardware</title>
<itemizedlist> <itemizedlist>
<listitem><para>Two 12-core processors</para></listitem> <title>Datanodes:</title>
<listitem><para>Six Enerprise SATA disks</para></listitem> <listitem>
<listitem><para>24GB of RAM</para></listitem> <para>Two 12-core processors</para>
<listitem><para>Two bonded gigabit NICs</para></listitem> </listitem>
<listitem>
<para>Six Enerprise SATA disks</para>
</listitem>
<listitem>
<para>24GB of RAM</para>
</listitem>
<listitem>
<para>Two bonded gigabit NICs</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para>Network:
<itemizedlist> <itemizedlist>
<listitem><para>10 Gigabit top-of-rack switches</para></listitem> <title>Network:</title>
<listitem><para>20 Gigabit bonded interconnects between racks.</para></listitem> <listitem>
<para>10 Gigabit top-of-rack switches</para>
</listitem>
<listitem>
<para>20 Gigabit bonded interconnects between racks.</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
</section> </section>
<section><title>Hypotheses</title> <section>
<section><title>HBase "Hot Spot" Region</title> <title>Hypotheses</title>
<para>We hypothesized that we were experiencing a familiar point of pain: a "hot spot" region in an HBase table, <section>
where uneven key-space distribution can funnel a huge number of requests to a single HBase region, bombarding the RegionServer <title>HBase "Hot Spot" Region</title>
process and cause slow response time. Examination of the HBase Master status page showed that the number of HBase requests to the <para> We hypothesized that we were experiencing a familiar point of pain: a "hot spot"
troubled node was almost zero. Further, examination of the HBase logs showed that there were no region splits, compactions, or other region transitions region in an HBase table, where uneven key-space distribution can funnel a huge number
in progress. This effectively ruled out a "hot spot" as the root cause of the observed slowness. of requests to a single HBase region, bombarding the RegionServer process and cause slow
</para> response time. Examination of the HBase Master status page showed that the number of
HBase requests to the troubled node was almost zero. Further, examination of the HBase
logs showed that there were no region splits, compactions, or other region transitions
in progress. This effectively ruled out a "hot spot" as the root cause of the observed
slowness. </para>
</section> </section>
<section><title>HBase Region With Non-Local Data</title> <section>
<para>Our next hypothesis was that one of the MapReduce tasks was requesting data from HBase that was not local to the datanode, thus <title>HBase Region With Non-Local Data</title>
forcing HDFS to request data blocks from other servers over the network. Examination of the datanode logs showed that there were very <para> Our next hypothesis was that one of the MapReduce tasks was requesting data from
few blocks being requested over the network, indicating that the HBase region was correctly assigned, and that the majority of the necessary HBase that was not local to the datanode, thus forcing HDFS to request data blocks from
data was located on the node. This ruled out the possibility of non-local data causing a slowdown. other servers over the network. Examination of the datanode logs showed that there were
</para> very few blocks being requested over the network, indicating that the HBase region was
correctly assigned, and that the majority of the necessary data was located on the node.
This ruled out the possibility of non-local data causing a slowdown. </para>
</section> </section>
<section><title>Excessive I/O Wait Due To Swapping Or An Over-Worked Or Failing Hard Disk</title> <section>
<para>After concluding that the Hadoop and HBase were not likely to be the culprits, we moved on to troubleshooting the datanode's hardware. <title>Excessive I/O Wait Due To Swapping Or An Over-Worked Or Failing Hard Disk</title>
Java, by design, will periodically scan its entire memory space to do garbage collection. If system memory is heavily overcommitted, the Linux <para> After concluding that the Hadoop and HBase were not likely to be the culprits, we
kernel may enter a vicious cycle, using up all of its resources swapping Java heap back and forth from disk to RAM as Java tries to run garbage moved on to troubleshooting the datanode's hardware. Java, by design, will periodically
collection. Further, a failing hard disk will often retry reads and/or writes many times before giving up and returning an error. This can manifest scan its entire memory space to do garbage collection. If system memory is heavily
as high iowait, as running processes wait for reads and writes to complete. Finally, a disk nearing the upper edge of its performance envelope will overcommitted, the Linux kernel may enter a vicious cycle, using up all of its resources
begin to cause iowait as it informs the kernel that it cannot accept any more data, and the kernel queues incoming data into the dirty write pool in memory. swapping Java heap back and forth from disk to RAM as Java tries to run garbage
However, using <code>vmstat(1)</code> and <code>free(1)</code>, we could see that no swap was being used, and the amount of disk IO was only a few kilobytes per second. collection. Further, a failing hard disk will often retry reads and/or writes many times
</para> before giving up and returning an error. This can manifest as high iowait, as running
processes wait for reads and writes to complete. Finally, a disk nearing the upper edge
of its performance envelope will begin to cause iowait as it informs the kernel that it
cannot accept any more data, and the kernel queues incoming data into the dirty write
pool in memory. However, using <code>vmstat(1)</code> and <code>free(1)</code>, we could
see that no swap was being used, and the amount of disk IO was only a few kilobytes per
second. </para>
</section> </section>
<section><title>Slowness Due To High Processor Usage</title> <section>
<para>Next, we checked to see whether the system was performing slowly simply due to very high computational load. <code>top(1)</code> showed that the system load <title>Slowness Due To High Processor Usage</title>
was higher than normal, but <code>vmstat(1)</code> and <code>mpstat(1)</code> showed that the amount of processor being used for actual computation was low. <para> Next, we checked to see whether the system was performing slowly simply due to very
</para> high computational load. <code>top(1)</code> showed that the system load was higher than
normal, but <code>vmstat(1)</code> and <code>mpstat(1)</code> showed that the amount of
processor being used for actual computation was low. </para>
</section> </section>
<section><title>Network Saturation (The Winner)</title> <section>
<para>Since neither the disks nor the processors were being utilized heavily, we moved on to the performance of the network interfaces. The datanode had two <title>Network Saturation (The Winner)</title>
gigabit ethernet adapters, bonded to form an active-standby interface. <code>ifconfig(8)</code> showed some unusual anomalies, namely interface errors, overruns, framing errors. <para> Since neither the disks nor the processors were being utilized heavily, we moved on
While not unheard of, these kinds of errors are exceedingly rare on modern hardware which is operating as it should: to the performance of the network interfaces. The datanode had two gigabit ethernet
<programlisting> adapters, bonded to form an active-standby interface. <code>ifconfig(8)</code> showed
some unusual anomalies, namely interface errors, overruns, framing errors. While not
unheard of, these kinds of errors are exceedingly rare on modern hardware which is
operating as it should: </para>
<screen>
$ /sbin/ifconfig bond0 $ /sbin/ifconfig bond0
bond0 Link encap:Ethernet HWaddr 00:00:00:00:00:00 bond0 Link encap:Ethernet HWaddr 00:00:00:00:00:00
inet addr:10.x.x.x Bcast:10.x.x.255 Mask:255.255.255.0 inet addr:10.x.x.x Bcast:10.x.x.255 Mask:255.255.255.0
@ -115,12 +154,13 @@ RX packets:2990700159 errors:12 dropped:0 overruns:1 frame:6 &lt;--- Lo
TX packets:3443518196 errors:0 dropped:0 overruns:0 carrier:0 TX packets:3443518196 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0 collisions:0 txqueuelen:0
RX bytes:2416328868676 (2.4 TB) TX bytes:3464991094001 (3.4 TB) RX bytes:2416328868676 (2.4 TB) TX bytes:3464991094001 (3.4 TB)
</programlisting> </screen>
</para> <para> These errors immediately lead us to suspect that one or more of the ethernet
<para>These errors immediately lead us to suspect that one or more of the ethernet interfaces might have negotiated the wrong line speed. This was confirmed both by running an ICMP ping interfaces might have negotiated the wrong line speed. This was confirmed both by
from an external host and observing round-trip-time in excess of 700ms, and by running <code>ethtool(8)</code> on the members of the bond interface and discovering that the active interface running an ICMP ping from an external host and observing round-trip-time in excess of
was operating at 100Mbs/, full duplex. 700ms, and by running <code>ethtool(8)</code> on the members of the bond interface and
<programlisting> discovering that the active interface was operating at 100Mbs/, full duplex. </para>
<screen>
$ sudo ethtool eth0 $ sudo ethtool eth0
Settings for eth0: Settings for eth0:
Supported ports: [ TP ] Supported ports: [ TP ]
@ -147,45 +187,53 @@ Supports Wake-on: umbg
Wake-on: g Wake-on: g
Current message level: 0x00000003 (3) Current message level: 0x00000003 (3)
Link detected: yes Link detected: yes
</programlisting> </screen>
</para> <para> In normal operation, the ICMP ping round trip time should be around 20ms, and the
<para>In normal operation, the ICMP ping round trip time should be around 20ms, and the interface speed and duplex should read, "1000MB/s", and, "Full", respectively. interface speed and duplex should read, "1000MB/s", and, "Full", respectively. </para>
</para>
</section> </section>
</section> </section>
<section><title>Resolution</title> <section>
<para>After determining that the active ethernet adapter was at the incorrect speed, we used the <code>ifenslave(8)</code> command to make the standby interface <title>Resolution</title>
the active interface, which yielded an immediate improvement in MapReduce performance, and a 10 times improvement in network throughput: <para> After determining that the active ethernet adapter was at the incorrect speed, we
</para> used the <code>ifenslave(8)</code> command to make the standby interface the active
<para>On the next trip to the datacenter, we determined that the line speed issue was ultimately caused by a bad network cable, which was replaced. interface, which yielded an immediate improvement in MapReduce performance, and a 10 times
</para> improvement in network throughput: </para>
<para> On the next trip to the datacenter, we determined that the line speed issue was
ultimately caused by a bad network cable, which was replaced. </para>
</section> </section>
</section> <!-- case study --> </section>
<section xml:id="casestudies.perf.1"> <!-- case study -->
<section
xml:id="casestudies.perf.1">
<title>Case Study #2 (Performance Research 2012)</title> <title>Case Study #2 (Performance Research 2012)</title>
<para>Investigation results of a self-described "we're not sure what's wrong, but it seems slow" problem. <para> Investigation results of a self-described "we're not sure what's wrong, but it seems
<link xlink:href="http://gbif.blogspot.com/2012/03/hbase-performance-evaluation-continued.html">http://gbif.blogspot.com/2012/03/hbase-performance-evaluation-continued.html</link> slow" problem. <link
xlink:href="http://gbif.blogspot.com/2012/03/hbase-performance-evaluation-continued.html">http://gbif.blogspot.com/2012/03/hbase-performance-evaluation-continued.html</link>
</para> </para>
</section> </section>
<section xml:id="casestudies.perf.2"> <section
xml:id="casestudies.perf.2">
<title>Case Study #3 (Performance Research 2010))</title> <title>Case Study #3 (Performance Research 2010))</title>
<para> <para> Investigation results of general cluster performance from 2010. Although this research
Investigation results of general cluster performance from 2010. Although this research is on an older version of the codebase, this writeup is on an older version of the codebase, this writeup is still very useful in terms of
is still very useful in terms of approach. approach. <link
<link xlink:href="http://hstack.org/hbase-performance-testing/">http://hstack.org/hbase-performance-testing/</link> xlink:href="http://hstack.org/hbase-performance-testing/">http://hstack.org/hbase-performance-testing/</link>
</para> </para>
</section> </section>
<section xml:id="casestudies.xceivers"> <section
xml:id="casestudies.xceivers">
<title>Case Study #4 (xcievers Config)</title> <title>Case Study #4 (xcievers Config)</title>
<para>Case study of configuring <code>xceivers</code>, and diagnosing errors from mis-configurations. <para> Case study of configuring <code>xceivers</code>, and diagnosing errors from
<link xlink:href="http://www.larsgeorge.com/2012/03/hadoop-hbase-and-xceivers.html">http://www.larsgeorge.com/2012/03/hadoop-hbase-and-xceivers.html</link> mis-configurations. <link
</para> xlink:href="http://www.larsgeorge.com/2012/03/hadoop-hbase-and-xceivers.html">http://www.larsgeorge.com/2012/03/hadoop-hbase-and-xceivers.html</link>
<para>See also <xref linkend="dfs.datanode.max.transfer.threads"/>.
</para> </para>
<para> See also <xref
linkend="dfs.datanode.max.transfer.threads" />. </para>
</section> </section>
</section> <!-- performance/troubleshooting --> </section>
<!-- performance/troubleshooting -->
</chapter> </chapter>

217
src/main/docbkx/community.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<chapter xml:id="community" <chapter
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="community"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -27,131 +29,124 @@
*/ */
--> -->
<title>Community</title> <title>Community</title>
<section xml:id="decisions"> <section
xml:id="decisions">
<title>Decisions</title> <title>Decisions</title>
<section xml:id="feature_branches"> <section
xml:id="feature_branches">
<title>Feature Branches</title> <title>Feature Branches</title>
<para>Feature Branches are easy to make. You do not have to be a committer to make one. Just request the name of your branch be added to JIRA up on the <para>Feature Branches are easy to make. You do not have to be a committer to make one. Just
developer's mailing list and a committer will add it for you. Thereafter you can file issues against your feature branch in Apache HBase JIRA. Your code you request the name of your branch be added to JIRA up on the developer's mailing list and a
keep elsewhere -- it should be public so it can be observed -- and you can update dev mailing list on progress. When the feature is ready for commit, committer will add it for you. Thereafter you can file issues against your feature branch in
3 +1s from committers will get your feature merged<footnote><para>See <link xlink:href="http://search-hadoop.com/m/asM982C5FkS1">HBase, mail # dev - Thoughts about large feature dev branches</link></para></footnote> Apache HBase JIRA. Your code you keep elsewhere -- it should be public so it can be observed
-- and you can update dev mailing list on progress. When the feature is ready for commit, 3
+1s from committers will get your feature merged<footnote>
<para>See <link
xlink:href="http://search-hadoop.com/m/asM982C5FkS1">HBase, mail # dev - Thoughts
about large feature dev branches</link></para>
</footnote>
</para> </para>
</section> </section>
<section xml:id="patchplusonepolicy"> <section
xml:id="patchplusonepolicy">
<title>Patch +1 Policy</title> <title>Patch +1 Policy</title>
<para> <para> The below policy is something we put in place 09/2012. It is a suggested policy rather
The below policy is something we put in place 09/2012. It is a than a hard requirement. We want to try it first to see if it works before we cast it in
suggested policy rather than a hard requirement. We want to try it stone. </para>
first to see if it works before we cast it in stone. <para> Apache HBase is made of <link
</para> xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link>.
<para> Components have one or more <xref
Apache HBase is made of linkend="OWNER" />s. See the 'Description' field on the <link
<link xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link>. xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link>
Components have one or more <xref linkend="OWNER" />s. See the 'Description' field on the JIRA page for who the current owners are by component. </para>
<link xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link> <para> Patches that fit within the scope of a single Apache HBase component require, at least,
JIRA page for who the current owners are by component. a +1 by one of the component's owners before commit. If owners are absent -- busy or
</para> otherwise -- two +1s by non-owners will suffice. </para>
<para> <para> Patches that span components need at least two +1s before they can be committed,
Patches that fit within the scope of a single Apache HBase component require, preferably +1s by owners of components touched by the x-component patch (TODO: This needs
at least, a +1 by one of the component's owners before commit. If tightening up but I think fine for first pass). </para>
owners are absent -- busy or otherwise -- two +1s by non-owners will <para> Any -1 on a patch by anyone vetos a patch; it cannot be committed until the
suffice. justification for the -1 is addressed. </para>
</para>
<para>
Patches that span components need at least two +1s before they can be
committed, preferably +1s by owners of components touched by the
x-component patch (TODO: This needs tightening up but I think fine for
first pass).
</para>
<para>
Any -1 on a patch by anyone vetos a patch; it cannot be committed
until the justification for the -1 is addressed.
</para>
</section> </section>
<section xml:id="hbase.fix.version.in.JIRA"> <section
xml:id="hbase.fix.version.in.JIRA">
<title>How to set fix version in JIRA on issue resolve</title> <title>How to set fix version in JIRA on issue resolve</title>
<para>Here is how <link xlink:href="http://search-hadoop.com/m/azemIi5RCJ1">we agreed</link> to set versions in JIRA when we <para>Here is how <link
resolve an issue. If trunk is going to be 0.98.0 then: xlink:href="http://search-hadoop.com/m/azemIi5RCJ1">we agreed</link> to set versions in
JIRA when we resolve an issue. If trunk is going to be 0.98.0 then: </para>
<itemizedlist> <itemizedlist>
<listitem><para>
Commit only to trunk: Mark with 0.98
</para></listitem>
<listitem><para>
Commit to 0.95 and trunk : Mark with 0.98, and 0.95.x
</para></listitem>
<listitem><para>
Commit to 0.94.x and 0.95, and trunk: Mark with 0.98, 0.95.x, and 0.94.x
</para></listitem>
<listitem><para>
Commit to 89-fb: Mark with 89-fb.
</para></listitem>
<listitem><para>
Commit site fixes: no version
</para></listitem>
</itemizedlist>
</para>
</section>
<section xml:id="hbase.when.to.close.JIRA">
<title>Policy on when to set a RESOLVED JIRA as CLOSED</title>
<para>We <link xlink:href="http://search-hadoop.com/m/4cIKs1iwXMS1">agreed</link>
that for issues that list multiple releases in their <emphasis>Fix Version/s</emphasis> field,
CLOSE the issue on the release of any of the versions listed; subsequent change
to the issue must happen in a new JIRA.
</para>
</section>
<section xml:id="no.permanent.state.in.zk">
<title>Only transient state in ZooKeeper!</title>
<para>
You should be able to kill the data in zookeeper and hbase should ride over it recreating the zk content as it goes.
This is an old adage around these parts. We just made note of it now. We also are currently in violation of this
basic tenet -- replication at least keeps permanent state in zk -- but we are working to undo this breaking of a
golden rule.
</para>
</section>
</section>
<section xml:id="community.roles">
<title>Community Roles</title>
<section xml:id="OWNER">
<title>Component Owner/Lieutenant</title>
<para>
Component owners are listed in the description field on this Apache HBase JIRA <link xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link>
page. The owners are listed in the 'Description' field rather than in the 'Component
Lead' field because the latter only allows us list one individual
whereas it is encouraged that components have multiple owners.
</para>
<para>
Owners or component lieutenants are volunteers who are (usually, but not necessarily) expert in
their component domain and may have an agenda on how they think their
Apache HBase component should evolve.
</para>
<para>
Duties include:
<orderedlist>
<listitem> <listitem>
<para> <para> Commit only to trunk: Mark with 0.98 </para>
Owners will try and review patches that land within their component's scope. </listitem>
<listitem>
<para> Commit to 0.95 and trunk : Mark with 0.98, and 0.95.x </para>
</listitem>
<listitem>
<para> Commit to 0.94.x and 0.95, and trunk: Mark with 0.98, 0.95.x, and 0.94.x </para>
</listitem>
<listitem>
<para> Commit to 89-fb: Mark with 89-fb. </para>
</listitem>
<listitem>
<para> Commit site fixes: no version </para>
</listitem>
</itemizedlist>
</section>
<section
xml:id="hbase.when.to.close.JIRA">
<title>Policy on when to set a RESOLVED JIRA as CLOSED</title>
<para>We <link
xlink:href="http://search-hadoop.com/m/4cIKs1iwXMS1">agreed</link> that for issues that
list multiple releases in their <emphasis>Fix Version/s</emphasis> field, CLOSE the issue on
the release of any of the versions listed; subsequent change to the issue must happen in a
new JIRA. </para>
</section>
<section
xml:id="no.permanent.state.in.zk">
<title>Only transient state in ZooKeeper!</title>
<para> You should be able to kill the data in zookeeper and hbase should ride over it
recreating the zk content as it goes. This is an old adage around these parts. We just made
note of it now. We also are currently in violation of this basic tenet -- replication at
least keeps permanent state in zk -- but we are working to undo this breaking of a golden
rule. </para>
</section>
</section>
<section
xml:id="community.roles">
<title>Community Roles</title>
<section
xml:id="OWNER">
<title>Component Owner/Lieutenant</title>
<para> Component owners are listed in the description field on this Apache HBase JIRA <link
xlink:href="https://issues.apache.org/jira/browse/HBASE#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponents-panel">components</link>
page. The owners are listed in the 'Description' field rather than in the 'Component Lead'
field because the latter only allows us list one individual whereas it is encouraged that
components have multiple owners. </para>
<para> Owners or component lieutenants are volunteers who are (usually, but not necessarily)
expert in their component domain and may have an agenda on how they think their Apache HBase
component should evolve. </para>
<orderedlist>
<title>Component Owner Duties</title>
<listitem>
<para> Owners will try and review patches that land within their component's scope.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para> If applicable, if an owner has an agenda, they will publish their goals or the
If applicable, if an owner has an agenda, they will publish their design toward which they are driving their component </para>
goals or the design toward which they are driving their component
</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> <para> If you would like to be volunteer as a component owner, just write the dev list and
<para> we'll sign you up. Owners do not need to be committers. </para>
If you would like to be volunteer as a component owner, just write the
dev list and we'll sign you up. Owners do not need to be committers.
</para>
</section> </section>
</section> </section>
<section xml:id="hbase.commit.msg.format"> <section
xml:id="hbase.commit.msg.format">
<title>Commit Message format</title> <title>Commit Message format</title>
<para>We <link xlink:href="http://search-hadoop.com/m/Gwxwl10cFHa1">agreed</link> <para>We <link
to the following SVN commit message format: xlink:href="http://search-hadoop.com/m/Gwxwl10cFHa1">agreed</link> to the following SVN
<programlisting>HBASE-xxxxx &lt;title>. (&lt;contributor>)</programlisting> commit message format:
If the person making the commit is the contributor, leave off the '(&lt;contributor>)' element. <programlisting>HBASE-xxxxx &lt;title>. (&lt;contributor>)</programlisting> If the person
</para> making the commit is the contributor, leave off the '(&lt;contributor>)' element. </para>
</section> </section>
</chapter> </chapter>

1828
src/main/docbkx/configuration.xml
View File

File diff suppressed because it is too large Load Diff

12
src/main/docbkx/cp.xml
View File

@ -1,5 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="cp" xmlns="http://docbook.org/ns/docbook" <chapter
version="5.0"
xml:id="cp"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -26,8 +29,9 @@
*/ */
--> -->
<title>Apache HBase Coprocessors</title> <title>Apache HBase Coprocessors</title>
<para>The idea of HBase coprocessors was inspired by Google's BigTable coprocessors. The <link xlink:href="https://blogs.apache.org/hbase/entry/coprocessor_introduction">Apache HBase Blog on Coprocessor</link> is a very good documentation on that. It has detailed information about the coprocessor framework, terminology, management, and so on. <para>The idea of HBase coprocessors was inspired by Google's BigTable coprocessors. The <link
</para> xlink:href="https://blogs.apache.org/hbase/entry/coprocessor_introduction">Apache HBase Blog
on Coprocessor</link> is a very good documentation on that. It has detailed information about
the coprocessor framework, terminology, management, and so on. </para>
</chapter> </chapter>

632
src/main/docbkx/developer.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<chapter xml:id="developer" <chapter
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="developer"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -502,7 +504,7 @@ HBase have a character not usually seen in other projects.</para>
integration with corresponding JUnit <link xlink:href="http://www.junit.org/node/581">categories</link>: integration with corresponding JUnit <link xlink:href="http://www.junit.org/node/581">categories</link>:
<classname>SmallTests</classname>, <classname>MediumTests</classname>, <classname>SmallTests</classname>, <classname>MediumTests</classname>,
<classname>LargeTests</classname>, <classname>IntegrationTests</classname>. <classname>LargeTests</classname>, <classname>IntegrationTests</classname>.
JUnit categories are denoted using java annotations and look like this in your unit test code. JUnit categories are denoted using java annotations and look like this in your unit test code.</para>
<programlisting>... <programlisting>...
@Category(SmallTests.class) @Category(SmallTests.class)
public class TestHRegionInfo { public class TestHRegionInfo {
@ -511,192 +513,212 @@ public class TestHRegionInfo {
// ... // ...
} }
}</programlisting> }</programlisting>
The above example shows how to mark a unit test as belonging to the small category. <para>The above example shows how to mark a unit test as belonging to the small category.
All unit tests in HBase have a categorization. All unit tests in HBase have a categorization. </para>
</para> <para> The first three categories, small, medium, and large are for tests run when you
<para> type <code>$ mvn test</code>; i.e. these three categorizations are for HBase unit
The first three categories, small, medium, and large are for tests run when tests. The integration category is for not for unit tests but for integration tests.
you type <code>$ mvn test</code>; i.e. these three categorizations are for These are run when you invoke <code>$ mvn verify</code>. Integration tests are
HBase unit tests. The integration category is for not for unit tests but for integration described in <xref
tests. These are run when you invoke <code>$ mvn verify</code>. Integration tests linkend="integration.tests" /> and will not be discussed further in this section
are described in <xref linkend="integration.tests"/> and will not be discussed further on HBase unit tests.</para>
in this section on HBase unit tests.</para> <para> Apache HBase uses a patched maven surefire plugin and maven profiles to implement
<para> its unit test characterizations. </para>
Apache HBase uses a patched maven surefire plugin and maven profiles to implement
its unit test characterizations.
</para>
<para>Read the below to figure which annotation of the set small, medium, and large to <para>Read the below to figure which annotation of the set small, medium, and large to
put on your new HBase unit test. put on your new HBase unit test. </para>
</para>
<section xml:id="hbase.unittests.small"> <section
xml:id="hbase.unittests.small">
<title>Small Tests<indexterm><primary>SmallTests</primary></indexterm></title> <title>Small Tests<indexterm><primary>SmallTests</primary></indexterm></title>
<para> <para>
<emphasis>Small</emphasis> tests are executed in a shared JVM. We put in this category all the tests that can <emphasis>Small</emphasis> tests are executed in a shared JVM. We put in this
be executed quickly in a shared JVM. The maximum execution time for a small test is 15 seconds, category all the tests that can be executed quickly in a shared JVM. The maximum
and small tests should not use a (mini)cluster.</para> execution time for a small test is 15 seconds, and small tests should not use a
(mini)cluster.</para>
</section> </section>
<section xml:id="hbase.unittests.medium"> <section
xml:id="hbase.unittests.medium">
<title>Medium Tests<indexterm><primary>MediumTests</primary></indexterm></title> <title>Medium Tests<indexterm><primary>MediumTests</primary></indexterm></title>
<para><emphasis>Medium</emphasis> tests represent tests that must be executed <para><emphasis>Medium</emphasis> tests represent tests that must be executed before
before proposing a patch. They are designed to run in less than 30 minutes altogether, proposing a patch. They are designed to run in less than 30 minutes altogether,
and are quite stable in their results. They are designed to last less than 50 seconds and are quite stable in their results. They are designed to last less than 50
individually. They can use a cluster, and each of them is executed in a separate JVM. seconds individually. They can use a cluster, and each of them is executed in a
</para> separate JVM. </para>
</section> </section>
<section xml:id="hbase.unittests.large"> <section
xml:id="hbase.unittests.large">
<title>Large Tests<indexterm><primary>LargeTests</primary></indexterm></title> <title>Large Tests<indexterm><primary>LargeTests</primary></indexterm></title>
<para><emphasis>Large</emphasis> tests are everything else. They are typically large-scale <para><emphasis>Large</emphasis> tests are everything else. They are typically
tests, regression tests for specific bugs, timeout tests, performance tests. large-scale tests, regression tests for specific bugs, timeout tests,
They are executed before a commit on the pre-integration machines. They can be run on performance tests. They are executed before a commit on the pre-integration
the developer machine as well. machines. They can be run on the developer machine as well. </para>
</para>
</section> </section>
<section xml:id="hbase.unittests.integration"> <section
<title>Integration Tests<indexterm><primary>IntegrationTests</primary></indexterm></title> xml:id="hbase.unittests.integration">
<para><emphasis>Integration</emphasis> tests are system level tests. See <title>Integration
<xref linkend="integration.tests"/> for more info. Tests<indexterm><primary>IntegrationTests</primary></indexterm></title>
</para> <para><emphasis>Integration</emphasis> tests are system level tests. See <xref
linkend="integration.tests" /> for more info. </para>
</section> </section>
</section> </section>
<section xml:id="hbase.unittests.cmds"> <section
xml:id="hbase.unittests.cmds">
<title>Running tests</title> <title>Running tests</title>
<para>Below we describe how to run the Apache HBase junit categories.</para> <para>Below we describe how to run the Apache HBase junit categories.</para>
<section xml:id="hbase.unittests.cmds.test"> <section
<title>Default: small and medium category tests xml:id="hbase.unittests.cmds.test">
</title> <title>Default: small and medium category tests </title>
<para>Running <programlisting>mvn test</programlisting> will execute all small tests in a single JVM <para>Running <programlisting>mvn test</programlisting> will execute all small tests
(no fork) and then medium tests in a separate JVM for each test instance. in a single JVM (no fork) and then medium tests in a separate JVM for each test
Medium tests are NOT executed if there is an error in a small test. instance. Medium tests are NOT executed if there is an error in a small test.
Large tests are NOT executed. There is one report for small tests, and one report for Large tests are NOT executed. There is one report for small tests, and one
medium tests if they are executed. report for medium tests if they are executed. </para>
</para>
</section> </section>
<section xml:id="hbase.unittests.cmds.test.runAllTests"> <section
xml:id="hbase.unittests.cmds.test.runAllTests">
<title>Running all tests</title> <title>Running all tests</title>
<para>Running <programlisting>mvn test -P runAllTests</programlisting> <para>Running <programlisting>mvn test -P runAllTests</programlisting> will execute
will execute small tests in a single JVM then medium and large tests in a separate JVM for each test. small tests in a single JVM then medium and large tests in a separate JVM for
Medium and large tests are NOT executed if there is an error in a small test. each test. Medium and large tests are NOT executed if there is an error in a
Large tests are NOT executed if there is an error in a small or medium test. small test. Large tests are NOT executed if there is an error in a small or
There is one report for small tests, and one report for medium and large tests if they are executed. medium test. There is one report for small tests, and one report for medium and
</para> large tests if they are executed. </para>
</section> </section>
<section xml:id="hbase.unittests.cmds.test.localtests.mytest"> <section
xml:id="hbase.unittests.cmds.test.localtests.mytest">
<title>Running a single test or all tests in a package</title> <title>Running a single test or all tests in a package</title>
<para>To run an individual test, e.g. <classname>MyTest</classname>, do <para>To run an individual test, e.g. <classname>MyTest</classname>, do
<programlisting>mvn test -Dtest=MyTest</programlisting> You can also <programlisting>mvn test -Dtest=MyTest</programlisting> You can also pass
pass multiple, individual tests as a comma-delimited list: multiple, individual tests as a comma-delimited list:
<programlisting>mvn test -Dtest=MyTest1,MyTest2,MyTest3</programlisting> <programlisting>mvn test -Dtest=MyTest1,MyTest2,MyTest3</programlisting> You can
You can also pass a package, which will run all tests under the package: also pass a package, which will run all tests under the package:
<programlisting>mvn test '-Dtest=org.apache.hadoop.hbase.client.*'</programlisting> <programlisting>mvn test '-Dtest=org.apache.hadoop.hbase.client.*'</programlisting>
</para> </para>
<para> <para> When <code>-Dtest</code> is specified, <code>localTests</code> profile will
When <code>-Dtest</code> is specified, <code>localTests</code> profile will be used. It will use the official release be used. It will use the official release of maven surefire, rather than our
of maven surefire, rather than our custom surefire plugin, and the old connector (The HBase build uses a patched custom surefire plugin, and the old connector (The HBase build uses a patched
version of the maven surefire plugin). Each junit tests is executed in a separate JVM (A fork per test class). version of the maven surefire plugin). Each junit tests is executed in a
There is no parallelization when tests are running in this mode. You will see a new message at the end of the separate JVM (A fork per test class). There is no parallelization when tests are
-report: "[INFO] Tests are skipped". It's harmless. While you need to make sure the sum of <code>Tests run:</code> in running in this mode. You will see a new message at the end of the -report:
the <code>Results :</code> section of test reports matching the number of tests you specified because no "[INFO] Tests are skipped". It's harmless. While you need to make sure the sum
error will be reported when a non-existent test case is specified. of <code>Tests run:</code> in the <code>Results :</code> section of test reports
</para> matching the number of tests you specified because no error will be reported
when a non-existent test case is specified. </para>
</section> </section>
<section xml:id="hbase.unittests.cmds.test.profiles"> <section
xml:id="hbase.unittests.cmds.test.profiles">
<title>Other test invocation permutations</title> <title>Other test invocation permutations</title>
<para>Running <programlisting>mvn test -P runSmallTests</programlisting> will execute "small" tests only, using a single JVM. <para>Running <command>mvn test -P runSmallTests</command> will execute "small"
</para> tests only, using a single JVM. </para>
<para>Running <programlisting>mvn test -P runMediumTests</programlisting> will execute "medium" tests only, launching a new JVM for each test-class. <para>Running <command>mvn test -P runMediumTests</command> will execute "medium"
</para> tests only, launching a new JVM for each test-class. </para>
<para>Running <programlisting>mvn test -P runLargeTests</programlisting> will execute "large" tests only, launching a new JVM for each test-class. <para>Running <command>mvn test -P runLargeTests</command> will execute "large"
</para> tests only, launching a new JVM for each test-class. </para>
<para>For convenience, you can run <programlisting>mvn test -P runDevTests</programlisting> to execute both small and medium tests, using a single JVM. <para>For convenience, you can run <command>mvn test -P runDevTests</command> to
</para> execute both small and medium tests, using a single JVM. </para>
</section> </section>
<section xml:id="hbase.unittests.test.faster"> <section
xml:id="hbase.unittests.test.faster">
<title>Running tests faster</title> <title>Running tests faster</title>
<para> By default, <code>$ mvn test -P runAllTests</code> runs 5 tests in parallel. It can be <para> By default, <code>$ mvn test -P runAllTests</code> runs 5 tests in parallel.
increased on a developer's machine. Allowing that you can have 2 tests in It can be increased on a developer's machine. Allowing that you can have 2 tests
parallel per core, and you need about 2Gb of memory per test (at the extreme), in parallel per core, and you need about 2Gb of memory per test (at the
if you have an 8 core, 24Gb box, you can have 16 tests in parallel. but the extreme), if you have an 8 core, 24Gb box, you can have 16 tests in parallel.
memory available limits it to 12 (24/2), To run all tests with 12 tests in but the memory available limits it to 12 (24/2), To run all tests with 12 tests
parallel, do this: <command>mvn test -P runAllTests in parallel, do this: <command>mvn test -P runAllTests
-Dsurefire.secondPartThreadCount=12</command>. To increase the speed, you -Dsurefire.secondPartThreadCount=12</command>. To increase the speed, you
can as well use a ramdisk. You will need 2Gb of memory to run all tests. You can as well use a ramdisk. You will need 2Gb of memory to run all tests. You
will also need to delete the files between two test run. The typical way to will also need to delete the files between two test run. The typical way to
configure a ramdisk on Linux is: configure a ramdisk on Linux is:</para>
<programlisting>$ sudo mkdir /ram2G <screen>$ sudo mkdir /ram2G
sudo mount -t tmpfs -o size=2048M tmpfs /ram2G</programlisting> sudo mount -t tmpfs -o size=2048M tmpfs /ram2G</screen>
You can then use it to run all HBase tests with the command: <command>mvn test <para>You can then use it to run all HBase tests with the command: </para>
<screen>mvn test
-P runAllTests -Dsurefire.secondPartThreadCount=12 -P runAllTests -Dsurefire.secondPartThreadCount=12
-Dtest.build.data.basedirectory=/ram2G</command> -Dtest.build.data.basedirectory=/ram2G</screen>
</para>
</section> </section>
<section xml:id="hbase.unittests.cmds.test.hbasetests"> <section
xml:id="hbase.unittests.cmds.test.hbasetests">
<title><command>hbasetests.sh</command></title> <title><command>hbasetests.sh</command></title>
<para>It's also possible to use the script <command>hbasetests.sh</command>. This script runs the medium and <para>It's also possible to use the script <command>hbasetests.sh</command>. This
large tests in parallel with two maven instances, and provides a single report. This script does not use script runs the medium and large tests in parallel with two maven instances, and
the hbase version of surefire so no parallelization is being done other than the two maven instances the provides a single report. This script does not use the hbase version of surefire
script sets up. so no parallelization is being done other than the two maven instances the
It must be executed from the directory which contains the <filename>pom.xml</filename>.</para> script sets up. It must be executed from the directory which contains the
<para>For example running <filename>pom.xml</filename>.</para>
<programlisting>./dev-support/hbasetests.sh</programlisting> will execute small and medium tests. <para>For example running <command>./dev-support/hbasetests.sh</command> will
Running <programlisting>./dev-support/hbasetests.sh runAllTests</programlisting> will execute all tests. execute small and medium tests. Running <command>./dev-support/hbasetests.sh
Running <programlisting>./dev-support/hbasetests.sh replayFailed</programlisting> will rerun the failed tests a runAllTests</command> will execute all tests. Running
second time, in a separate jvm and without parallelisation. <command>./dev-support/hbasetests.sh replayFailed</command> will rerun the
failed tests a second time, in a separate jvm and without parallelisation.
</para> </para>
</section> </section>
<section xml:id="hbase.unittests.resource.checker"> <section
<title>Test Resource Checker<indexterm><primary>Test Resource Checker</primary></indexterm></title> xml:id="hbase.unittests.resource.checker">
<para> <title>Test Resource Checker<indexterm><primary>Test Resource
A custom Maven SureFire plugin listener checks a number of resources before Checker</primary></indexterm></title>
<para> A custom Maven SureFire plugin listener checks a number of resources before
and after each HBase unit test runs and logs its findings at the end of the test and after each HBase unit test runs and logs its findings at the end of the test
output files which can be found in <filename>target/surefire-reports</filename> output files which can be found in <filename>target/surefire-reports</filename>
per Maven module (Tests write test reports named for the test class into this directory. per Maven module (Tests write test reports named for the test class into this
Check the <filename>*-out.txt</filename> files). The resources counted are the number directory. Check the <filename>*-out.txt</filename> files). The resources
of threads, the number of file descriptors, etc. If the number has increased, it adds counted are the number of threads, the number of file descriptors, etc. If the
a <emphasis>LEAK?</emphasis> comment in the logs. As you can have an HBase instance number has increased, it adds a <emphasis>LEAK?</emphasis> comment in the logs.
running in the background, some threads can be deleted/created without any specific As you can have an HBase instance running in the background, some threads can be
action in the test. However, if the test does not work as expected, or if the test deleted/created without any specific action in the test. However, if the test
should not impact these resources, it's worth checking these log lines does not work as expected, or if the test should not impact these resources,
<computeroutput>...hbase.ResourceChecker(157): before...</computeroutput> and it's worth checking these log lines
<computeroutput>...hbase.ResourceChecker(157): after...</computeroutput>. For example: <computeroutput>...hbase.ResourceChecker(157): before...</computeroutput>
<computeroutput> and <computeroutput>...hbase.ResourceChecker(157): after...</computeroutput>.
2012-09-26 09:22:15,315 INFO [pool-1-thread-1] hbase.ResourceChecker(157): after: regionserver.TestColumnSeeking#testReseeking Thread=65 (was 65), OpenFileDescriptor=107 (was 107), MaxFileDescriptor=10240 (was 10240), ConnectionCount=1 (was 1) For example: </para>
</computeroutput> <screen>2012-09-26 09:22:15,315 INFO [pool-1-thread-1]
</para> hbase.ResourceChecker(157): after:
regionserver.TestColumnSeeking#testReseeking Thread=65 (was 65),
OpenFileDescriptor=107 (was 107), MaxFileDescriptor=10240 (was 10240),
ConnectionCount=1 (was 1) </screen>
</section> </section>
</section> </section>
<section xml:id="hbase.tests.writing"> <section
xml:id="hbase.tests.writing">
<title>Writing Tests</title> <title>Writing Tests</title>
<section xml:id="hbase.tests.rules"> <section
xml:id="hbase.tests.rules">
<title>General rules</title> <title>General rules</title>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>As much as possible, tests should be written as category small tests.</para> <para>As much as possible, tests should be written as category small
tests.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>All tests must be written to support parallel execution on the same machine, hence they should not use shared resources as fixed ports or fixed file names.</para> <para>All tests must be written to support parallel execution on the same
machine, hence they should not use shared resources as fixed ports or
fixed file names.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Tests should not overlog. More than 100 lines/second makes the logs complex to read and use i/o that are hence not available for the other tests.</para> <para>Tests should not overlog. More than 100 lines/second makes the logs
complex to read and use i/o that are hence not available for the other
tests.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Tests can be written with <classname>HBaseTestingUtility</classname>. <para>Tests can be written with <classname>HBaseTestingUtility</classname>.
This class offers helper functions to create a temp directory and do the cleanup, or to start a cluster.</para> This class offers helper functions to create a temp directory and do the
cleanup, or to start a cluster.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
<section xml:id="hbase.tests.categories"> <section
xml:id="hbase.tests.categories">
<title>Categories and execution time</title> <title>Categories and execution time</title>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -706,164 +728,231 @@ This class offers helper functions to create a temp directory and do the cleanup
<para>All tests should be written to be as fast as possible.</para> <para>All tests should be written to be as fast as possible.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Small category tests should last less than 15 seconds, and must not have any side effect.</para> <para>Small category tests should last less than 15 seconds, and must not
have any side effect.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Medium category tests should last less than 50 seconds.</para> <para>Medium category tests should last less than 50 seconds.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Large category tests should last less than 3 minutes. This should ensure a good parallelization for people using it, and ease the analysis when the test fails.</para> <para>Large category tests should last less than 3 minutes. This should
ensure a good parallelization for people using it, and ease the analysis
when the test fails.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
<section xml:id="hbase.tests.sleeps"> <section
xml:id="hbase.tests.sleeps">
<title>Sleeps in tests</title> <title>Sleeps in tests</title>
<para>Whenever possible, tests should not use <methodname>Thread.sleep</methodname>, but rather waiting for the real event they need. This is faster and clearer for the reader. <para>Whenever possible, tests should not use <methodname>Thread.sleep</methodname>,
Tests should not do a <methodname>Thread.sleep</methodname> without testing an ending condition. This allows understanding what the test is waiting for. Moreover, the test will work whatever the machine performance is. but rather waiting for the real event they need. This is faster and clearer for
Sleep should be minimal to be as fast as possible. Waiting for a variable should be done in a 40ms sleep loop. Waiting for a socket operation should be done in a 200 ms sleep loop. the reader. Tests should not do a <methodname>Thread.sleep</methodname> without
</para> testing an ending condition. This allows understanding what the test is waiting
for. Moreover, the test will work whatever the machine performance is. Sleep
should be minimal to be as fast as possible. Waiting for a variable should be
done in a 40ms sleep loop. Waiting for a socket operation should be done in a
200 ms sleep loop. </para>
</section> </section>
<section xml:id="hbase.tests.cluster"> <section
<title>Tests using a cluster xml:id="hbase.tests.cluster">
</title> <title>Tests using a cluster </title>
<para>Tests using a HRegion do not have to start a cluster: A region can use the local file system. <para>Tests using a HRegion do not have to start a cluster: A region can use the
Start/stopping a cluster cost around 10 seconds. They should not be started per test method but per test class. local file system. Start/stopping a cluster cost around 10 seconds. They should
Started cluster must be shutdown using <methodname>HBaseTestingUtility#shutdownMiniCluster</methodname>, which cleans the directories. not be started per test method but per test class. Started cluster must be
As most as possible, tests should use the default settings for the cluster. When they don't, they should document it. This will allow to share the cluster later. shutdown using <methodname>HBaseTestingUtility#shutdownMiniCluster</methodname>,
</para> which cleans the directories. As most as possible, tests should use the default
settings for the cluster. When they don't, they should document it. This will
allow to share the cluster later. </para>
</section> </section>
</section> </section>
<section xml:id="integration.tests"> <section
xml:id="integration.tests">
<title>Integration Tests</title> <title>Integration Tests</title>
<para>HBase integration/system tests are tests that are beyond HBase unit tests. They <para>HBase integration/system tests are tests that are beyond HBase unit tests. They
are generally long-lasting, sizeable (the test can be asked to 1M rows or 1B rows), are generally long-lasting, sizeable (the test can be asked to 1M rows or 1B rows),
targetable (they can take configuration that will point them at the ready-made cluster targetable (they can take configuration that will point them at the ready-made
they are to run against; integration tests do not include cluster start/stop code), cluster they are to run against; integration tests do not include cluster start/stop
and verifying success, integration tests rely on public APIs only; they do not code), and verifying success, integration tests rely on public APIs only; they do
attempt to examine server internals asserting success/fail. Integration tests not attempt to examine server internals asserting success/fail. Integration tests
are what you would run when you need to more elaborate proofing of a release candidate are what you would run when you need to more elaborate proofing of a release
beyond what unit tests can do. They are not generally run on the Apache Continuous Integration candidate beyond what unit tests can do. They are not generally run on the Apache
build server, however, some sites opt to run integration tests as a part of their Continuous Integration build server, however, some sites opt to run integration
continuous testing on an actual cluster. tests as a part of their continuous testing on an actual cluster. </para>
</para> <para> Integration tests currently live under the <filename>src/test</filename>
<para> directory in the hbase-it submodule and will match the regex:
Integration tests currently live under the <filename>src/test</filename> directory <filename>**/IntegrationTest*.java</filename>. All integration tests are also
in the hbase-it submodule and will match the regex: <filename>**/IntegrationTest*.java</filename>. annotated with <code>@Category(IntegrationTests.class)</code>. </para>
All integration tests are also annotated with <code>@Category(IntegrationTests.class)</code>.
</para>
<para> <para> Integration tests can be run in two modes: using a mini cluster, or against an
Integration tests can be run in two modes: using a mini cluster, or against an actual distributed cluster. actual distributed cluster. Maven failsafe is used to run the tests using the mini
Maven failsafe is used to run the tests using the mini cluster. IntegrationTestsDriver class is used for cluster. IntegrationTestsDriver class is used for executing the tests against a
executing the tests against a distributed cluster. Integration tests SHOULD NOT assume that they are running against a distributed cluster. Integration tests SHOULD NOT assume that they are running
mini cluster, and SHOULD NOT use private API's to access cluster state. To interact with the distributed or mini against a mini cluster, and SHOULD NOT use private API's to access cluster state. To
cluster uniformly, <code>IntegrationTestingUtility</code>, and <code>HBaseCluster</code> classes, interact with the distributed or mini cluster uniformly,
and public client API's can be used. <code>IntegrationTestingUtility</code>, and <code>HBaseCluster</code> classes,
</para> and public client API's can be used. </para>
<para> <para> On a distributed cluster, integration tests that use ChaosMonkey or otherwise
On a distributed cluster, integration tests that use ChaosMonkey or otherwise manipulate services thru cluster manager (e.g. restart regionservers) use SSH to do it. manipulate services thru cluster manager (e.g. restart regionservers) use SSH to do
To run these, test process should be able to run commands on remote end, so ssh should be configured accordingly (for example, if HBase runs under hbase it. To run these, test process should be able to run commands on remote end, so ssh
user in your cluster, you can set up passwordless ssh for that user and run the test also under it). To facilitate that, <code>hbase.it.clustermanager.ssh.user</code>, should be configured accordingly (for example, if HBase runs under hbase user in
<code>hbase.it.clustermanager.ssh.opts</code> and <code>hbase.it.clustermanager.ssh.cmd</code> configuration settings can be used. "User" is the remote user that cluster manager should use to perform ssh commands. your cluster, you can set up passwordless ssh for that user and run the test also
"Opts" contains additional options that are passed to SSH (for example, "-i /tmp/my-key"). under it). To facilitate that, <code>hbase.it.clustermanager.ssh.user</code>,
Finally, if you have some custom environment setup, "cmd" is the override format for the entire tunnel (ssh) command. The default string is {<code>/usr/bin/ssh %1$s %2$s%3$s%4$s "%5$s"</code>} and is a good starting point. This is a standard Java format string with 5 arguments that is used to execute the remote command. The argument 1 (%1$s) is SSH options set the via opts setting or via environment variable, 2 is SSH user name, 3 is "@" if username is set or "" otherwise, 4 is the target host name, and 5 is the logical command to execute (that may include single quotes, so don't use them). For example, if you run the tests under non-hbase user and want to ssh as that user and change to hbase on remote machine, you can use {<code>/usr/bin/ssh %1$s %2$s%3$s%4$s "su hbase - -c \"%5$s\""</code>}. That way, to kill RS (for example) integration tests may run {<code>/usr/bin/ssh some-hostname "su hbase - -c \"ps aux | ... | kill ...\""</code>}. <code>hbase.it.clustermanager.ssh.opts</code> and
The command is logged in the test logs, so you can verify it is correct for your environment. <code>hbase.it.clustermanager.ssh.cmd</code> configuration settings can be used.
</para> "User" is the remote user that cluster manager should use to perform ssh commands.
"Opts" contains additional options that are passed to SSH (for example, "-i
/tmp/my-key"). Finally, if you have some custom environment setup, "cmd" is the
override format for the entire tunnel (ssh) command. The default string is
{<code>/usr/bin/ssh %1$s %2$s%3$s%4$s "%5$s"</code>} and is a good starting
point. This is a standard Java format string with 5 arguments that is used to
execute the remote command. The argument 1 (%1$s) is SSH options set the via opts
setting or via environment variable, 2 is SSH user name, 3 is "@" if username is set
or "" otherwise, 4 is the target host name, and 5 is the logical command to execute
(that may include single quotes, so don't use them). For example, if you run the
tests under non-hbase user and want to ssh as that user and change to hbase on
remote machine, you can use {<code>/usr/bin/ssh %1$s %2$s%3$s%4$s "su hbase - -c
\"%5$s\""</code>}. That way, to kill RS (for example) integration tests may run
{<code>/usr/bin/ssh some-hostname "su hbase - -c \"ps aux | ... | kill
...\""</code>}. The command is logged in the test logs, so you can verify it is
correct for your environment. </para>
<section xml:id="maven.build.commands.integration.tests.mini"> <section
xml:id="maven.build.commands.integration.tests.mini">
<title>Running integration tests against mini cluster</title> <title>Running integration tests against mini cluster</title>
<para>HBase 0.92 added a <varname>verify</varname> maven target. <para>HBase 0.92 added a <varname>verify</varname> maven target. Invoking it, for
Invoking it, for example by doing <code>mvn verify</code>, will example by doing <code>mvn verify</code>, will run all the phases up to and
run all the phases up to and including the verify phase via the including the verify phase via the maven <link
maven <link xlink:href="http://maven.apache.org/plugins/maven-failsafe-plugin/">failsafe plugin</link>, xlink:href="http://maven.apache.org/plugins/maven-failsafe-plugin/">failsafe
running all the above mentioned HBase unit tests as well as tests that are in the HBase integration test group. plugin</link>, running all the above mentioned HBase unit tests as well as
After you have completed tests that are in the HBase integration test group. After you have completed
<programlisting>mvn install -DskipTests</programlisting> <command>mvn install -DskipTests</command> You can run just the integration
You can run just the integration tests by invoking: tests by invoking:</para>
<programlisting> <programlisting>
cd hbase-it cd hbase-it
mvn verify</programlisting> mvn verify</programlisting>
<para>If you just want to run the integration tests in top-level, you need to run
two commands. First: <command>mvn failsafe:integration-test</command> This
actually runs ALL the integration tests. </para>
<note>
<para>This command will always output <code>BUILD SUCCESS</code> even if there
are test failures. </para>
</note>
<para>At this point, you could grep the output by hand looking for failed tests.
However, maven will do this for us; just use: <command>mvn
failsafe:verify</command> The above command basically looks at all the test
results (so don't remove the 'target' directory) for test failures and reports
the results.</para>
If you just want to run the integration tests in top-level, you need to run two commands. First: <section
<programlisting>mvn failsafe:integration-test</programlisting> xml:id="maven.build.commands.integration.tests2">
This actually runs ALL the integration tests.
<note><para>This command will always output <code>BUILD SUCCESS</code> even if there are test failures.
</para></note>
At this point, you could grep the output by hand looking for failed tests. However, maven will do this for us; just use:
<programlisting>mvn failsafe:verify</programlisting>
The above command basically looks at all the test results (so don't remove the 'target' directory) for test failures and reports the results.</para>
<section xml:id="maven.build.commands.integration.tests2">
<title>Running a subset of Integration tests</title> <title>Running a subset of Integration tests</title>
<para>This is very similar to how you specify running a subset of unit tests (see above), but use the property <para>This is very similar to how you specify running a subset of unit tests
<code>it.test</code> instead of <code>test</code>. (see above), but use the property <code>it.test</code> instead of
To just run <classname>IntegrationTestClassXYZ.java</classname>, use: <code>test</code>. To just run
<programlisting>mvn failsafe:integration-test -Dit.test=IntegrationTestClassXYZ</programlisting> <classname>IntegrationTestClassXYZ.java</classname>, use: <command>mvn
The next thing you might want to do is run groups of integration tests, say all integration tests that are named IntegrationTestClassX*.java: failsafe:integration-test -Dit.test=IntegrationTestClassXYZ</command>
<programlisting>mvn failsafe:integration-test -Dit.test=*ClassX*</programlisting> The next thing you might want to do is run groups of integration tests, say
This runs everything that is an integration test that matches *ClassX*. This means anything matching: "**/IntegrationTest*ClassX*". all integration tests that are named IntegrationTestClassX*.java:
You can also run multiple groups of integration tests using comma-delimited lists (similar to unit tests). Using a list of matches still supports full regex matching for each of the groups.This would look something like: <command>mvn failsafe:integration-test -Dit.test=*ClassX*</command> This
<programlisting>mvn failsafe:integration-test -Dit.test=*ClassX*, *ClassY</programlisting> runs everything that is an integration test that matches *ClassX*. This
means anything matching: "**/IntegrationTest*ClassX*". You can also run
multiple groups of integration tests using comma-delimited lists (similar to
unit tests). Using a list of matches still supports full regex matching for
each of the groups.This would look something like: <command>mvn
failsafe:integration-test -Dit.test=*ClassX*, *ClassY</command>
</para> </para>
</section> </section>
</section> </section>
<section xml:id="maven.build.commands.integration.tests.distributed"> <section
xml:id="maven.build.commands.integration.tests.distributed">
<title>Running integration tests against distributed cluster</title> <title>Running integration tests against distributed cluster</title>
<para> <para> If you have an already-setup HBase cluster, you can launch the integration
If you have an already-setup HBase cluster, you can launch the integration tests by invoking the class <code>IntegrationTestsDriver</code>. You may have to tests by invoking the class <code>IntegrationTestsDriver</code>. You may have to
run test-compile first. The configuration will be picked by the bin/hbase script. run test-compile first. The configuration will be picked by the bin/hbase
<programlisting>mvn test-compile</programlisting> script. <programlisting>mvn test-compile</programlisting> Then launch the tests
Then launch the tests with: with:</para>
<programlisting>bin/hbase [--config config_dir] org.apache.hadoop.hbase.IntegrationTestsDriver</programlisting> <programlisting>bin/hbase [--config config_dir] org.apache.hadoop.hbase.IntegrationTestsDriver</programlisting>
Pass <code>-h</code> to get usage on this sweet tool. Running the IntegrationTestsDriver without any argument will launch tests found under <code>hbase-it/src/test</code>, having <code>@Category(IntegrationTests.class)</code> annotation, <para>Pass <code>-h</code> to get usage on this sweet tool. Running the
and a name starting with <code>IntegrationTests</code>. See the usage, by passing -h, to see how to filter test classes. IntegrationTestsDriver without any argument will launch tests found under
You can pass a regex which is checked against the full class name; so, part of class name can be used. <code>hbase-it/src/test</code>, having
IntegrationTestsDriver uses Junit to run the tests. Currently there is no support for running integration tests against a distributed cluster using maven (see <link xlink:href="https://issues.apache.org/jira/browse/HBASE-6201">HBASE-6201</link>). <code>@Category(IntegrationTests.class)</code> annotation, and a name
</para> starting with <code>IntegrationTests</code>. See the usage, by passing -h, to
see how to filter test classes. You can pass a regex which is checked against
the full class name; so, part of class name can be used. IntegrationTestsDriver
uses Junit to run the tests. Currently there is no support for running
integration tests against a distributed cluster using maven (see <link
xlink:href="https://issues.apache.org/jira/browse/HBASE-6201">HBASE-6201</link>). </para>
<para> <para> The tests interact with the distributed cluster by using the methods in the
The tests interact with the distributed cluster by using the methods in the <code>DistributedHBaseCluster</code> (implementing <code>HBaseCluster</code>) class, which in turn uses a pluggable <code>ClusterManager</code>. Concrete implementations provide actual functionality for carrying out deployment-specific and environment-dependent tasks (SSH, etc). The default <code>ClusterManager</code> is <code>HBaseClusterManager</code>, which uses SSH to remotely execute start/stop/kill/signal commands, and assumes some posix commands (ps, etc). Also assumes the user running the test has enough "power" to start/stop servers on the remote machines. By default, it picks up <code>HBASE_SSH_OPTS, HBASE_HOME, HBASE_CONF_DIR</code> from the env, and uses <code>bin/hbase-daemon.sh</code> to carry out the actions. Currently tarball deployments, deployments which uses hbase-daemons.sh, and <link xlink:href="http://incubator.apache.org/ambari/">Apache Ambari</link> deployments are supported. /etc/init.d/ scripts are not supported for now, but it can be easily added. For other deployment options, a ClusterManager can be implemented and plugged in. <code>DistributedHBaseCluster</code> (implementing
</para> <code>HBaseCluster</code>) class, which in turn uses a pluggable
<code>ClusterManager</code>. Concrete implementations provide actual
functionality for carrying out deployment-specific and environment-dependent
tasks (SSH, etc). The default <code>ClusterManager</code> is
<code>HBaseClusterManager</code>, which uses SSH to remotely execute
start/stop/kill/signal commands, and assumes some posix commands (ps, etc). Also
assumes the user running the test has enough "power" to start/stop servers on
the remote machines. By default, it picks up <code>HBASE_SSH_OPTS, HBASE_HOME,
HBASE_CONF_DIR</code> from the env, and uses
<code>bin/hbase-daemon.sh</code> to carry out the actions. Currently tarball
deployments, deployments which uses hbase-daemons.sh, and <link
xlink:href="http://incubator.apache.org/ambari/">Apache Ambari</link>
deployments are supported. /etc/init.d/ scripts are not supported for now, but
it can be easily added. For other deployment options, a ClusterManager can be
implemented and plugged in. </para>
</section> </section>
<section xml:id="maven.build.commands.integration.tests.destructive"> <section
xml:id="maven.build.commands.integration.tests.destructive">
<title>Destructive integration / system tests</title> <title>Destructive integration / system tests</title>
<para> <para> In 0.96, a tool named <code>ChaosMonkey</code> has been introduced. It is
In 0.96, a tool named <code>ChaosMonkey</code> has been introduced. It is modeled after the <link xlink:href="http://techblog.netflix.com/2012/07/chaos-monkey-released-into-wild.html">same-named tool by Netflix</link>. modeled after the <link
Some of the tests use ChaosMonkey to simulate faults in the running cluster in the way of killing random servers, xlink:href="http://techblog.netflix.com/2012/07/chaos-monkey-released-into-wild.html">same-named
disconnecting servers, etc. ChaosMonkey can also be used as a stand-alone tool to run a (misbehaving) policy while you tool by Netflix</link>. Some of the tests use ChaosMonkey to simulate faults
are running other tests. in the running cluster in the way of killing random servers, disconnecting
</para> servers, etc. ChaosMonkey can also be used as a stand-alone tool to run a
(misbehaving) policy while you are running other tests. </para>
<para> <para> ChaosMonkey defines Action's and Policy's. Actions are sequences of events.
ChaosMonkey defines Action's and Policy's. Actions are sequences of events. We have at least the following actions:</para> We have at least the following actions:</para>
<itemizedlist> <itemizedlist>
<listitem><para>Restart active master (sleep 5 sec)</para></listitem> <listitem>
<listitem><para>Restart random regionserver (sleep 5 sec)</para></listitem> <para>Restart active master (sleep 5 sec)</para>
<listitem><para>Restart random regionserver (sleep 60 sec)</para></listitem> </listitem>
<listitem><para>Restart META regionserver (sleep 5 sec)</para></listitem> <listitem>
<listitem><para>Restart ROOT regionserver (sleep 5 sec)</para></listitem> <para>Restart random regionserver (sleep 5 sec)</para>
<listitem><para>Batch restart of 50% of regionservers (sleep 5 sec)</para></listitem> </listitem>
<listitem><para>Rolling restart of 100% of regionservers (sleep 5 sec)</para></listitem> <listitem>
<para>Restart random regionserver (sleep 60 sec)</para>
</listitem>
<listitem>
<para>Restart META regionserver (sleep 5 sec)</para>
</listitem>
<listitem>
<para>Restart ROOT regionserver (sleep 5 sec)</para>
</listitem>
<listitem>
<para>Batch restart of 50% of regionservers (sleep 5 sec)</para>
</listitem>
<listitem>
<para>Rolling restart of 100% of regionservers (sleep 5 sec)</para>
</listitem>
</itemizedlist> </itemizedlist>
<para> <para> Policies on the other hand are responsible for executing the actions based on
Policies on the other hand are responsible for executing the actions based on a strategy. a strategy. The default policy is to execute a random action every minute based
The default policy is to execute a random action every minute based on predefined action on predefined action weights. ChaosMonkey executes predefined named policies
weights. ChaosMonkey executes predefined named policies until it is stopped. More than one until it is stopped. More than one policy can be active at any time. </para>
policy can be active at any time.
</para>
<para> <para> To run ChaosMonkey as a standalone tool deploy your HBase cluster as usual.
To run ChaosMonkey as a standalone tool deploy your HBase cluster as usual. ChaosMonkey uses the configuration ChaosMonkey uses the configuration from the bin/hbase script, thus no extra
from the bin/hbase script, thus no extra configuration needs to be done. You can invoke the ChaosMonkey by running:</para> configuration needs to be done. You can invoke the ChaosMonkey by
running:</para>
<programlisting>bin/hbase org.apache.hadoop.hbase.util.ChaosMonkey</programlisting> <programlisting>bin/hbase org.apache.hadoop.hbase.util.ChaosMonkey</programlisting>
<para> <para> This will output smt like: </para>
This will output smt like:
</para>
<screen> <screen>
12/11/19 23:21:57 INFO util.ChaosMonkey: Using ChaosMonkey Policy: class org.apache.hadoop.hbase.util.ChaosMonkey$PeriodicRandomActionPolicy, period:60000 12/11/19 23:21:57 INFO util.ChaosMonkey: Using ChaosMonkey Policy: class org.apache.hadoop.hbase.util.ChaosMonkey$PeriodicRandomActionPolicy, period:60000
12/11/19 23:21:57 INFO util.ChaosMonkey: Sleeping for 26953 to add jitter 12/11/19 23:21:57 INFO util.ChaosMonkey: Sleeping for 26953 to add jitter
@ -1293,7 +1382,8 @@ Bar bar = foo.getBar(); &lt;--- imagine there's an extra space(s) after the
<section xml:id="common.patch.feedback.javadoc.defaults"> <section xml:id="common.patch.feedback.javadoc.defaults">
<title>Javadoc - Useless Defaults</title> <title>Javadoc - Useless Defaults</title>
<para>Don't just leave the @param arguments the way your IDE generated them. Don't do this... <para>Don't just leave the @param arguments the way your IDE generated them. Don't do
this...</para>
<programlisting> <programlisting>
/** /**
* *
@ -1302,31 +1392,32 @@ Bar bar = foo.getBar(); &lt;--- imagine there's an extra space(s) after the
*/ */
public Foo getFoo(Bar bar); public Foo getFoo(Bar bar);
</programlisting> </programlisting>
... either add something descriptive to the @param and @return lines, or just remove them. <para>... either add something descriptive to the @param and @return lines, or just
But the preference is to add something descriptive and useful. remove them. But the preference is to add something descriptive and
</para> useful.</para>
</section> </section>
<section xml:id="common.patch.feedback.onething"> <section
xml:id="common.patch.feedback.onething">
<title>One Thing At A Time, Folks</title> <title>One Thing At A Time, Folks</title>
<para>If you submit a patch for one thing, don't do auto-reformatting or unrelated reformatting of code on a completely <para>If you submit a patch for one thing, don't do auto-reformatting or unrelated
different area of code. reformatting of code on a completely different area of code. </para>
</para> <para>Likewise, don't add unrelated cleanup or refactorings outside the scope of
<para>Likewise, don't add unrelated cleanup or refactorings outside the scope of your Jira. your Jira. </para>
</para>
</section> </section>
<section xml:id="common.patch.feedback.tests"> <section
xml:id="common.patch.feedback.tests">
<title>Ambigious Unit Tests</title> <title>Ambigious Unit Tests</title>
<para>Make sure that you're clear about what you are testing in your unit tests and why. <para>Make sure that you're clear about what you are testing in your unit tests and
</para> why. </para>
</section> </section>
</section> <!-- patch feedback --> </section>
<!-- patch feedback -->
<section> <section>
<title>Submitting a patch again</title> <title>Submitting a patch again</title>
<para> <para> Sometimes committers ask for changes for a patch. After incorporating the
Sometimes committers ask for changes for a patch. After incorporating the suggested/requested changes, follow the following process to submit the patch again. suggested/requested changes, follow the following process to submit the patch again. </para>
</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Do not delete the old patch file</para> <para>Do not delete the old patch file</para>
@ -1341,20 +1432,22 @@ Bar bar = foo.getBar(); &lt;--- imagine there's an extra space(s) after the
<para>'Cancel Patch' on JIRA.. bug status will change back to Open</para> <para>'Cancel Patch' on JIRA.. bug status will change back to Open</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Attach new patch file (e.g. HBASE_XXXX-v2.patch) using 'Files --> Attach'</para> <para>Attach new patch file (e.g. HBASE_XXXX-v2.patch) using 'Files -->
Attach'</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Click on 'Submit Patch'. Now the bug status will say 'Patch Available'.</para> <para>Click on 'Submit Patch'. Now the bug status will say 'Patch
Available'.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Committers will review the patch. Rinse and repeat as many times as needed :-)</para> <para>Committers will review the patch. Rinse and repeat as many times as needed
:-)</para>
</section> </section>
<section> <section>
<title>Submitting incremental patches</title> <title>Submitting incremental patches</title>
<para> <para> At times you may want to break a big change into mulitple patches. Here is a
At times you may want to break a big change into mulitple patches. Here is a sample work-flow using git sample work-flow using git <itemizedlist>
<itemizedlist>
<listitem> <listitem>
<para>patch 1:</para> <para>patch 1:</para>
<itemizedlist> <itemizedlist>
@ -1374,7 +1467,8 @@ Bar bar = foo.getBar(); &lt;--- imagine there's an extra space(s) after the
<para>save your work</para> <para>save your work</para>
<screen>$ git add file1 file2 </screen> <screen>$ git add file1 file2 </screen>
<screen>$ git commit -am 'saved after HBASE_XXXX-1.patch'</screen> <screen>$ git commit -am 'saved after HBASE_XXXX-1.patch'</screen>
<para>now you have your own branch, that is different from remote master branch</para> <para>now you have your own branch, that is different from remote
master branch</para>
</listitem> </listitem>
<listitem> <listitem>
<para>make more changes...</para> <para>make more changes...</para>

4
src/main/docbkx/external_apis.xml
View File

@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="external_apis" <chapter
version="5.0"
xml:id="external_apis"
xmlns="http://docbook.org/ns/docbook" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"

242
src/main/docbkx/getting_started.xml
View File

@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="getting_started" <chapter
version="5.0"
xml:id="getting_started"
xmlns="http://docbook.org/ns/docbook" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
@ -31,46 +33,53 @@
<section> <section>
<title>Introduction</title> <title>Introduction</title>
<para><xref linkend="quickstart" /> will get you up and <para><xref
running on a single-node, standalone instance of HBase. linkend="quickstart" /> will get you up and running on a single-node, standalone instance of
</para> HBase. </para>
</section> </section>
<section xml:id="quickstart"> <section
xml:id="quickstart">
<title>Quick Start</title> <title>Quick Start</title>
<para>This guide describes setup of a standalone HBase instance. It will <para>This guide describes setup of a standalone HBase instance. It will run against the local
run against the local filesystem. In later sections we will take you through filesystem. In later sections we will take you through how to run HBase on Apache Hadoop's
how to run HBase on Apache Hadoop's HDFS, a distributed filesystem. This section HDFS, a distributed filesystem. This section shows you how to create a table in HBase,
shows you how to create a table in HBase, inserting inserting rows into your new HBase table via the HBase <command>shell</command>, and then
rows into your new HBase table via the HBase <command>shell</command>, and then cleaning cleaning up and shutting down your standalone, local filesystem-based HBase instance. The
up and shutting down your standalone, local filesystem-based HBase instance. The below exercise below exercise should take no more than ten minutes (not including download time). </para>
should take no more than ten minutes (not including download time). <note
</para> xml:id="local.fs.durability">
<note xml:id="local.fs.durability"><title>Local Filesystem and Durability</title> <title>Local Filesystem and Durability</title>
<para>Using HBase with a LocalFileSystem does not currently guarantee durability. <para>Using HBase with a LocalFileSystem does not currently guarantee durability. The HDFS
The HDFS local filesystem implementation will lose edits if files are not properly local filesystem implementation will lose edits if files are not properly closed -- which is
closed -- which is very likely to happen when experimenting with a new download. very likely to happen when experimenting with a new download. You need to run HBase on HDFS
You need to run HBase on HDFS to ensure all writes are preserved. Running to ensure all writes are preserved. Running against the local filesystem though will get you
against the local filesystem though will get you off the ground quickly and get you off the ground quickly and get you familiar with how the general system works so lets run
familiar with how the general system works so lets run with it for now. See with it for now. See <link
<link xlink:href="https://issues.apache.org/jira/browse/HBASE-3696"/> and its associated issues for more details.</para></note> xlink:href="https://issues.apache.org/jira/browse/HBASE-3696" /> and its associated issues
<note xml:id="loopback.ip.getting.started"> for more details.</para>
</note>
<note
xml:id="loopback.ip.getting.started">
<title>Loopback IP</title> <title>Loopback IP</title>
<para><emphasis>The below advice is for hbase-0.94.x and older versions only. We believe this fixed in hbase-0.96.0 and beyond <para><emphasis>The below advice is for hbase-0.94.x and older versions only. We believe this
(let us know if we have it wrong).</emphasis> There should be no need of the below modification to <filename>/etc/hosts</filename> in fixed in hbase-0.96.0 and beyond (let us know if we have it wrong).</emphasis> There
later versions of HBase.</para> should be no need of the below modification to <filename>/etc/hosts</filename> in later
versions of HBase.</para>
<para>HBase expects the loopback IP address to be 127.0.0.1. Ubuntu and some other distributions, <para>HBase expects the loopback IP address to be 127.0.0.1. Ubuntu and some other
for example, will default to 127.0.1.1 and this will cause problems for you distributions, for example, will default to 127.0.1.1 and this will cause problems for you <footnote>
<footnote><para>See <link xlink:href="http://blog.devving.com/why-does-hbase-care-about-etchosts/">Why does HBase care about /etc/hosts?</link> for detail.</para></footnote>. <para>See <link
</para> xlink:href="http://blog.devving.com/why-does-hbase-care-about-etchosts/">Why does
<para><filename>/etc/hosts</filename> should look something like this: HBase care about /etc/hosts?</link> for detail.</para>
<programlisting> </footnote>. </para>
<para><filename>/etc/hosts</filename> should look something like this:</para>
<screen>
127.0.0.1 localhost 127.0.0.1 localhost
127.0.0.1 ubuntu.ubuntu-domain ubuntu 127.0.0.1 ubuntu.ubuntu-domain ubuntu
</programlisting> </screen>
</para>
</note> </note>
@ -78,158 +87,155 @@
<title>Download and unpack the latest stable release.</title> <title>Download and unpack the latest stable release.</title>
<para>Choose a download site from this list of <link <para>Choose a download site from this list of <link
xlink:href="http://www.apache.org/dyn/closer.cgi/hbase/">Apache Download xlink:href="http://www.apache.org/dyn/closer.cgi/hbase/">Apache Download Mirrors</link>.
Mirrors</link>. Click on the suggested top link. This will take you to a Click on the suggested top link. This will take you to a mirror of <emphasis>HBase
mirror of <emphasis>HBase Releases</emphasis>. Click on the folder named Releases</emphasis>. Click on the folder named <filename>stable</filename> and then
<filename>stable</filename> and then download the file that ends in download the file that ends in <filename>.tar.gz</filename> to your local filesystem; e.g.
<filename>.tar.gz</filename> to your local filesystem; e.g.
<filename>hbase-0.94.2.tar.gz</filename>.</para> <filename>hbase-0.94.2.tar.gz</filename>.</para>
<para>Decompress and untar your download and then change into the <para>Decompress and untar your download and then change into the unpacked directory.</para>
unpacked directory.</para>
<para><programlisting>$ tar xfz hbase-<?eval ${project.version}?>.tar.gz <screen><![CDATA[$ tar xfz hbase-<?eval ${project.version}?>.tar.gz
$ cd hbase-<?eval ${project.version}?> $ cd hbase-<?eval ${project.version}?>]]>
</programlisting></para> </screen>
<para>At this point, you are ready to start HBase. But before starting <para>At this point, you are ready to start HBase. But before starting it, edit
it, edit <filename>conf/hbase-site.xml</filename>, the file you write <filename>conf/hbase-site.xml</filename>, the file you write your site-specific
your site-specific configurations into. Set configurations into. Set <varname>hbase.rootdir</varname>, the directory HBase writes data
<varname>hbase.rootdir</varname>, the directory HBase writes data to, to, and <varname>hbase.zookeeper.property.dataDir</varname>, the directory ZooKeeper writes
and <varname>hbase.zookeeper.property.dataDir</varname>, the directory its data too:</para>
ZooKeeper writes its data too: <programlisting><![CDATA[<?xml version="1.0"?>
<programlisting>&lt;?xml version="1.0"?&gt; <?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
&lt;?xml-stylesheet type="text/xsl" href="configuration.xsl"?&gt; <configuration>
&lt;configuration&gt; <property>
&lt;property&gt; <name>hbase.rootdir</name>
&lt;name&gt;hbase.rootdir&lt;/name&gt; <value>file:///DIRECTORY/hbase</value>
&lt;value&gt;file:///DIRECTORY/hbase&lt;/value&gt; </property>
&lt;/property&gt; <property>
&lt;property&gt; <name>hbase.zookeeper.property.dataDir</name>
&lt;name&gt;hbase.zookeeper.property.dataDir&lt;/name&gt; <value>/DIRECTORY/zookeeper</value>
&lt;value&gt;/DIRECTORY/zookeeper&lt;/value&gt; </property>
&lt;/property&gt; </configuration>]]></programlisting>
&lt;/configuration&gt;</programlisting> Replace <varname>DIRECTORY</varname> in the above with the <para> Replace <varname>DIRECTORY</varname> in the above with the path to the directory you
path to the directory you would have HBase and ZooKeeper write their data. By default, would have HBase and ZooKeeper write their data. By default,
<varname>hbase.rootdir</varname> is set to <filename>/tmp/hbase-${user.name}</filename> <varname>hbase.rootdir</varname> is set to <filename>/tmp/hbase-${user.name}</filename>
and similarly so for the default ZooKeeper data location which means you'll lose all and similarly so for the default ZooKeeper data location which means you'll lose all your
your data whenever your server reboots unless you change it (Most operating systems clear data whenever your server reboots unless you change it (Most operating systems clear
<filename>/tmp</filename> on restart).</para> <filename>/tmp</filename> on restart).</para>
</section> </section>
<section xml:id="start_hbase"> <section
xml:id="start_hbase">
<title>Start HBase</title> <title>Start HBase</title>
<para>Now start HBase:<programlisting>$ ./bin/start-hbase.sh <para>Now start HBase:</para>
starting Master, logging to logs/hbase-user-master-example.org.out</programlisting></para> <screen>$ ./bin/start-hbase.sh
starting Master, logging to logs/hbase-user-master-example.org.out</screen>
<para>You should now have a running standalone HBase instance. In <para>You should now have a running standalone HBase instance. In standalone mode, HBase runs
standalone mode, HBase runs all daemons in the the one JVM; i.e. both all daemons in the the one JVM; i.e. both the HBase and ZooKeeper daemons. HBase logs can be
the HBase and ZooKeeper daemons. HBase logs can be found in the found in the <filename>logs</filename> subdirectory. Check them out especially if it seems
<filename>logs</filename> subdirectory. Check them out especially if HBase had trouble starting.</para>
it seems HBase had trouble starting.</para>
<note> <note>
<title>Is <application>java</application> installed?</title> <title>Is <application>java</application> installed?</title>
<para>All of the above presumes a 1.6 version of Oracle <para>All of the above presumes a 1.6 version of Oracle <application>java</application> is
<application>java</application> is installed on your machine and installed on your machine and available on your path (See <xref
available on your path (See <xref linkend="java" />); i.e. when you type linkend="java" />); i.e. when you type <application>java</application>, you see output
<application>java</application>, you see output that describes the that describes the options the java program takes (HBase requires java 6). If this is not
options the java program takes (HBase requires java 6). If this is not the case, HBase will not start. Install java, edit <filename>conf/hbase-env.sh</filename>,
the case, HBase will not start. Install java, edit uncommenting the <envar>JAVA_HOME</envar> line pointing it to your java install, then,
<filename>conf/hbase-env.sh</filename>, uncommenting the
<envar>JAVA_HOME</envar> line pointing it to your java install, then,
retry the steps above.</para> retry the steps above.</para>
</note> </note>
</section> </section>
<section xml:id="shell_exercises"> <section
xml:id="shell_exercises">
<title>Shell Exercises</title> <title>Shell Exercises</title>
<para>Connect to your running HBase via the <command>shell</command>.</para> <para>Connect to your running HBase via the <command>shell</command>.</para>
<para><programlisting>$ ./bin/hbase shell <screen><![CDATA[$ ./bin/hbase shell
HBase Shell; enter 'help&lt;RETURN&gt;' for list of supported commands. HBase Shell; enter 'help<RETURN>' for list of supported commands.
Type "exit&lt;RETURN&gt;" to leave the HBase Shell Type "exit<RETURN>" to leave the HBase Shell
Version: 0.90.0, r1001068, Fri Sep 24 13:55:42 PDT 2010 Version: 0.90.0, r1001068, Fri Sep 24 13:55:42 PDT 2010
hbase(main):001:0&gt; </programlisting></para> hbase(main):001:0>]]> </screen>
<para>Type <command>help</command> and then <para>Type <command>help</command> and then <command>&lt;RETURN&gt;</command> to see a listing
<command>&lt;RETURN&gt;</command> to see a listing of shell commands and of shell commands and options. Browse at least the paragraphs at the end of the help
options. Browse at least the paragraphs at the end of the help emission emission for the gist of how variables and command arguments are entered into the HBase
for the gist of how variables and command arguments are entered into the shell; in particular note how table names, rows, and columns, etc., must be quoted.</para>
HBase shell; in particular note how table names, rows, and columns,
etc., must be quoted.</para>
<para>Create a table named <varname>test</varname> with a single column family named <varname>cf</varname>. <para>Create a table named <varname>test</varname> with a single column family named
Verify its creation by listing all tables and then insert some <varname>cf</varname>. Verify its creation by listing all tables and then insert some
values.</para> values.</para>
<para><programlisting>hbase(main):003:0&gt; create 'test', 'cf' <screen><![CDATA[hbase(main):003:0> create 'test', 'cf'
0 row(s) in 1.2200 seconds 0 row(s) in 1.2200 seconds
hbase(main):003:0&gt; list 'test' hbase(main):003:0> list 'test'
.. ..
1 row(s) in 0.0550 seconds 1 row(s) in 0.0550 seconds
hbase(main):004:0&gt; put 'test', 'row1', 'cf:a', 'value1' hbase(main):004:0> put 'test', 'row1', 'cf:a', 'value1'
0 row(s) in 0.0560 seconds 0 row(s) in 0.0560 seconds
hbase(main):005:0&gt; put 'test', 'row2', 'cf:b', 'value2' hbase(main):005:0> put 'test', 'row2', 'cf:b', 'value2'
0 row(s) in 0.0370 seconds 0 row(s) in 0.0370 seconds
hbase(main):006:0&gt; put 'test', 'row3', 'cf:c', 'value3' hbase(main):006:0> put 'test', 'row3', 'cf:c', 'value3'
0 row(s) in 0.0450 seconds</programlisting></para> 0 row(s) in 0.0450 seconds]]></screen>
<para>Above we inserted 3 values, one at a time. The first insert is at <para>Above we inserted 3 values, one at a time. The first insert is at
<varname>row1</varname>, column <varname>cf:a</varname> with a value of <varname>row1</varname>, column <varname>cf:a</varname> with a value of
<varname>value1</varname>. Columns in HBase are comprised of a column family prefix -- <varname>value1</varname>. Columns in HBase are comprised of a column family prefix --
<varname>cf</varname> in this example -- followed by a colon and then a <varname>cf</varname> in this example -- followed by a colon and then a column qualifier
column qualifier suffix (<varname>a</varname> in this case).</para> suffix (<varname>a</varname> in this case).</para>
<para>Verify the data insert by running a scan of the table as follows</para> <para>Verify the data insert by running a scan of the table as follows</para>
<para><programlisting>hbase(main):007:0&gt; scan 'test' <screen><![CDATA[hbase(main):007:0> scan 'test'
ROW COLUMN+CELL ROW COLUMN+CELL
row1 column=cf:a, timestamp=1288380727188, value=value1 row1 column=cf:a, timestamp=1288380727188, value=value1
row2 column=cf:b, timestamp=1288380738440, value=value2 row2 column=cf:b, timestamp=1288380738440, value=value2
row3 column=cf:c, timestamp=1288380747365, value=value3 row3 column=cf:c, timestamp=1288380747365, value=value3
3 row(s) in 0.0590 seconds</programlisting></para> 3 row(s) in 0.0590 seconds]]></screen>
<para>Get a single row</para> <para>Get a single row</para>
<para><programlisting>hbase(main):008:0&gt; get 'test', 'row1' <screen><![CDATA[hbase(main):008:0> get 'test', 'row1'
COLUMN CELL COLUMN CELL
cf:a timestamp=1288380727188, value=value1 cf:a timestamp=1288380727188, value=value1
1 row(s) in 0.0400 seconds</programlisting></para> 1 row(s) in 0.0400 seconds]]></screen>
<para>Now, disable and drop your table. This will clean up all done <para>Now, disable and drop your table. This will clean up all done above.</para>
above.</para>
<para><programlisting>hbase(main):012:0&gt; disable 'test' <screen>h<![CDATA[base(main):012:0> disable 'test'
0 row(s) in 1.0930 seconds 0 row(s) in 1.0930 seconds
hbase(main):013:0&gt; drop 'test' hbase(main):013:0> drop 'test'
0 row(s) in 0.0770 seconds </programlisting></para> 0 row(s) in 0.0770 seconds ]]></screen>
<para>Exit the shell by typing exit.</para> <para>Exit the shell by typing exit.</para>
<para><programlisting>hbase(main):014:0&gt; exit</programlisting></para> <programlisting><![CDATA[hbase(main):014:0> exit]]></programlisting>
</section> </section>
<section xml:id="stopping"> <section
xml:id="stopping">
<title>Stopping HBase</title> <title>Stopping HBase</title>
<para>Stop your hbase instance by running the stop script.</para> <para>Stop your hbase instance by running the stop script.</para>
<para><programlisting>$ ./bin/stop-hbase.sh <screen>$ ./bin/stop-hbase.sh
stopping hbase...............</programlisting></para> stopping hbase...............</screen>
</section> </section>
<section> <section>
<title>Where to go next</title> <title>Where to go next</title>
<para>The above described standalone setup is good for testing and <para>The above described standalone setup is good for testing and experiments only. In the
experiments only. In the next chapter, <xref linkend="configuration" />, next chapter, <xref
we'll go into depth on the different HBase run modes, system requirements linkend="configuration" />, we'll go into depth on the different HBase run modes, system
running HBase, and critical configurations setting up a distributed HBase deploy.</para> requirements running HBase, and critical configurations setting up a distributed HBase
deploy.</para>
</section> </section>
</section> </section>

731
src/main/docbkx/ops_mgt.xml
View File

File diff suppressed because it is too large Load Diff

1084
src/main/docbkx/performance.xml
View File

File diff suppressed because it is too large Load Diff

72
src/main/docbkx/preface.xml
View File

@ -1,5 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<preface version="5.0" xml:id="preface" xmlns="http://docbook.org/ns/docbook" <preface
version="5.0"
xml:id="preface"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -28,44 +31,39 @@
<title>Preface</title> <title>Preface</title>
<para>This is the official reference guide for the <link <para>This is the official reference guide for the <link
xlink:href="http://hbase.apache.org/">HBase</link> version it ships with. xlink:href="http://hbase.apache.org/">HBase</link> version it ships with. Herein you
Herein you will find either the definitive documentation on an HBase topic will find either the definitive documentation on an HBase topic as of its standing when the
as of its standing when the referenced HBase version shipped, or it referenced HBase version shipped, or it will point to the location in <link
will point to the location in <link xlink:href="http://hbase.apache.org/apidocs/index.html">javadoc</link>, <link
xlink:href="http://hbase.apache.org/apidocs/index.html">javadoc</link>, xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link> or <link
<link xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link> xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki</link> where the pertinent
or <link xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki</link> where information can be found.</para>
the pertinent information can be found.</para>
<para>This reference guide is a work in progress. The source for this guide can <para>This reference guide is a work in progress. The source for this guide can be found at
be found at <filename>src/main/docbkx</filename> in a checkout of the hbase <filename>src/main/docbkx</filename> in a checkout of the hbase project. This reference
project. This reference guide is marked up using guide is marked up using <link
<link xlink:href="http://www.docbook.com/">DocBook</link> from which the xlink:href="http://www.docbook.com/">DocBook</link> from which the the finished guide is
the finished guide is generated as part of the 'site' build target. Run generated as part of the 'site' build target. Run <programlisting>mvn site</programlisting>
<programlisting>mvn site</programlisting> to generate this documentation. to generate this documentation. Amendments and improvements to the documentation are
Amendments and improvements to the documentation are welcomed. Add a welcomed. Add a patch to an issue up in the HBase <link
patch to an issue up in the HBase <link
xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link>.</para> xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link>.</para>
<note xml:id="headsup"> <note
<title>Heads-up if this is your first foray into the world of distributed computing...</title> xml:id="headsup">
<para> <title>Heads-up if this is your first foray into the world of distributed
If this is your first foray into the wonderful world of computing...</title>
Distributed Computing, then you are in for <para> If this is your first foray into the wonderful world of Distributed Computing, then
some interesting times. First off, distributed systems are you are in for some interesting times. First off, distributed systems are hard; making a
hard; making a distributed system hum requires a disparate distributed system hum requires a disparate skillset that spans systems (hardware and
skillset that spans systems (hardware and software) and software) and networking. Your cluster' operation can hiccup because of any of a myriad
networking. Your cluster' operation can hiccup because of any set of reasons from bugs in HBase itself through misconfigurations -- misconfiguration
of a myriad set of reasons from bugs in HBase itself through misconfigurations of HBase but also operating system misconfigurations -- through to hardware problems
-- misconfiguration of HBase but also operating system misconfigurations -- whether it be a bug in your network card drivers or an underprovisioned RAM bus (to
through to hardware problems whether it be a bug in your network card mention two recent examples of hardware issues that manifested as "HBase is slow"). You
drivers or an underprovisioned RAM bus (to mention two recent will also need to do a recalibration if up to this your computing has been bound to a
examples of hardware issues that manifested as "HBase is slow"). single box. Here is one good starting point: <link
You will also need to do a recalibration if up to this your xlink:href="http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing">Fallacies
computing has been bound to a single box. Here is one good of Distributed Computing</link>. That said, you are welcome. Its a fun place to be.
starting point: Yours, the HBase Community. </para>
<link xlink:href="http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing">Fallacies of Distributed Computing</link>.
That said, you are welcome. Its a fun place to be. Yours, the HBase Community.
</para>
</note> </note>
</preface> </preface>

326
src/main/docbkx/rpc.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<appendix xml:id="hbase.rpc" <appendix
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="hbase.rpc"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -27,209 +29,271 @@
--> -->
<title>0.95 RPC Specification</title> <title>0.95 RPC Specification</title>
<para>In 0.95, all client/server communication is done with <para>In 0.95, all client/server communication is done with <link
<link xlink:href="https://code.google.com/p/protobuf/">protobuf’ed</link> Messages rather than with xlink:href="https://code.google.com/p/protobuf/">protobuf’ed</link> Messages rather than
<link xlink:href="http://hadoop.apache.org/docs/current/api/org/apache/hadoop/io/Writable.html">Hadoop Writables</link>. with <link
Our RPC wire format therefore changes. xlink:href="http://hadoop.apache.org/docs/current/api/org/apache/hadoop/io/Writable.html">Hadoop
This document describes the client/server request/response protocol and our new RPC wire-format.</para> Writables</link>. Our RPC wire format therefore changes. This document describes the
client/server request/response protocol and our new RPC wire-format.</para>
<para /> <para />
<para>For what RPC is like in 0.94 and previous, <para>For what RPC is like in 0.94 and previous, see Benoît/Tsuna’s <link
see Benoît/Tsuna’s <link xlink:href="https://github.com/OpenTSDB/asynchbase/blob/master/src/HBaseRpc.java#L164">Unofficial Hadoop / HBase RPC protocol documentation</link>. xlink:href="https://github.com/OpenTSDB/asynchbase/blob/master/src/HBaseRpc.java#L164">Unofficial
For more background on how we arrived at this spec., see Hadoop / HBase RPC protocol documentation</link>. For more background on how we arrived
<link xlink:href="https://docs.google.com/document/d/1WCKwgaLDqBw2vpux0jPsAu2WPTRISob7HGCO8YhfDTA/edit#">HBase RPC: WIP</link></para> at this spec., see <link
xlink:href="https://docs.google.com/document/d/1WCKwgaLDqBw2vpux0jPsAu2WPTRISob7HGCO8YhfDTA/edit#">HBase
RPC: WIP</link></para>
<para /> <para />
<section><title>Goals</title> <section>
<title>Goals</title>
<para> <para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>A wire-format we can evolve</para> <para>A wire-format we can evolve</para>
</listitem> </listitem>
<listitem> <listitem>
<para>A format that does not require our rewriting server core or <para>A format that does not require our rewriting server core or radically
radically changing its current architecture (for later).</para> changing its current architecture (for later).</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
</section> </section>
<section><title>TODO</title> <section>
<title>TODO</title>
<para> <para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>List of problems with currently specified format and where <para>List of problems with currently specified format and where we would like
we would like to go in a version2, etc. For example, what would we to go in a version2, etc. For example, what would we have to change if
have to change if anything to move server async or to support anything to move server async or to support streaming/chunking?</para>
streaming/chunking?</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Diagram on how it works</para> <para>Diagram on how it works</para>
</listitem> </listitem>
<listitem> <listitem>
<para>A grammar that succinctly describes the wire-format. Currently <para>A grammar that succinctly describes the wire-format. Currently we have
we have these words and the content of the rpc protobuf idl but these words and the content of the rpc protobuf idl but a grammar for the
a grammar for the back and forth would help with groking rpc. Also, back and forth would help with groking rpc. Also, a little state machine on
a little state machine on client/server interactions would help client/server interactions would help with understanding (and ensuring
with understanding (and ensuring correct implementation).</para> correct implementation).</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
</section> </section>
<section><title>RPC</title> <section>
<para>The client will send setup information on connection establish. <title>RPC</title>
Thereafter, the client invokes methods against the remote server sending a protobuf Message and receiving a protobuf Message in response. <para>The client will send setup information on connection establish. Thereafter, the client
Communication is synchronous. All back and forth is preceded by an int that has the total length of the request/response. invokes methods against the remote server sending a protobuf Message and receiving a
Optionally, Cells(KeyValues) can be passed outside of protobufs in follow-behind Cell blocks (because protobuf Message in response. Communication is synchronous. All back and forth is
<link xlink:href="https://docs.google.com/document/d/1WEtrq-JTIUhlnlnvA0oYRLp0F8MKpEBeBSCFcQiacdw/edit#">we can’t protobuf megabytes of KeyValues</link> or Cells). preceded by an int that has the total length of the request/response. Optionally,
These CellBlocks are encoded and optionally compressed.</para> Cells(KeyValues) can be passed outside of protobufs in follow-behind Cell blocks
(because <link
xlink:href="https://docs.google.com/document/d/1WEtrq-JTIUhlnlnvA0oYRLp0F8MKpEBeBSCFcQiacdw/edit#">we
can’t protobuf megabytes of KeyValues</link> or Cells). These CellBlocks are encoded
and optionally compressed.</para>
<para /> <para />
<para>For more detail on the protobufs involved, see the <para>For more detail on the protobufs involved, see the <link
<link xlink:href="http://svn.apache.org/viewvc/hbase/trunk/hbase-protocol/src/main/protobuf/RPC.proto?view=markup">RPC.proto</link> file in trunk.</para> xlink:href="http://svn.apache.org/viewvc/hbase/trunk/hbase-protocol/src/main/protobuf/RPC.proto?view=markup">RPC.proto</link>
file in trunk.</para>
<section> <section>
<title>Connection Setup</title> <title>Connection Setup</title>
<para>Client initiates connection.</para> <para>Client initiates connection.</para>
<section><title>Client</title> <section>
<para>On connection setup, client sends a preamble followed by a connection header. <title>Client</title>
</para> <para>On connection setup, client sends a preamble followed by a connection header. </para>
<section> <section>
<title>&lt;preamble&gt;</title> <title>&lt;preamble&gt;</title>
<para><programlisting>&lt;MAGIC 4 byte integer&gt; &lt;1 byte RPC Format Version&gt; &lt;1 byte auth type&gt;<footnote><para> We need the auth method spec. here so the connection header is encoded if auth enabled.</para></footnote></programlisting></para> <para><programlisting>&lt;MAGIC 4 byte integer&gt; &lt;1 byte RPC Format Version&gt; &lt;1 byte auth type&gt;<footnote><para> We need the auth method spec. here so the connection header is encoded if auth enabled.</para></footnote></programlisting></para>
<para>E.g.: HBas0x000x50 -- 4 bytes of MAGIC -- ‘HBas’ -- plus one-byte of version, 0 in this case, and one byte, 0x50 (SIMPLE). of an auth type.</para> <para>E.g.: HBas0x000x50 -- 4 bytes of MAGIC -- ‘HBas’ -- plus one-byte of
version, 0 in this case, and one byte, 0x50 (SIMPLE). of an auth
type.</para>
</section> </section>
<section> <section>
<title>&lt;Protobuf ConnectionHeader Message&gt;</title> <title>&lt;Protobuf ConnectionHeader Message&gt;</title>
<para>Has user info, and “protocol”, as well as the encoders and compression the client will use sending CellBlocks. <para>Has user info, and “protocol”, as well as the encoders and compression the
CellBlock encoders and compressors are for the life of the connection. client will use sending CellBlocks. CellBlock encoders and compressors are
CellBlock encoders implement org.apache.hadoop.hbase.codec.Codec. for the life of the connection. CellBlock encoders implement
CellBlocks may then also be compressed. org.apache.hadoop.hbase.codec.Codec. CellBlocks may then also be compressed.
Compressors implement org.apache.hadoop.io.compress.CompressionCodec. Compressors implement org.apache.hadoop.io.compress.CompressionCodec. This
This protobuf is written using writeDelimited so is prefaced by a pb varint protobuf is written using writeDelimited so is prefaced by a pb varint with
with its serialized length</para> its serialized length</para>
</section> </section>
</section><!--Client--> </section>
<!--Client-->
<section><title>Server</title> <section>
<para>After client sends preamble and connection header, <title>Server</title>
server does NOT respond if successful connection setup. <para>After client sends preamble and connection header, server does NOT respond if
No response means server is READY to accept requests and to give out response. successful connection setup. No response means server is READY to accept
If the version or authentication in the preamble is not agreeable or the server has trouble parsing the preamble, requests and to give out response. If the version or authentication in the
it will throw a org.apache.hadoop.hbase.ipc.FatalConnectionException explaining the error and will then disconnect. preamble is not agreeable or the server has trouble parsing the preamble, it
If the client in the connection header -- i.e. the protobuf’d Message that comes after the connection preamble -- asks for for a will throw a org.apache.hadoop.hbase.ipc.FatalConnectionException explaining the
Service the server does not support or a codec the server does not have, again we throw a FatalConnectionException with explanation.</para> error and will then disconnect. If the client in the connection header -- i.e.
the protobuf’d Message that comes after the connection preamble -- asks for for
a Service the server does not support or a codec the server does not have, again
we throw a FatalConnectionException with explanation.</para>
</section> </section>
</section> </section>
<section><title>Request</title> <section>
<title>Request</title>
<para>After a Connection has been set up, client makes requests. Server responds.</para> <para>After a Connection has been set up, client makes requests. Server responds.</para>
<para>A request is made up of a protobuf RequestHeader followed by a protobuf Message parameter. <para>A request is made up of a protobuf RequestHeader followed by a protobuf Message
The header includes the method name and optionally, metadata on the optional CellBlock that may be following. parameter. The header includes the method name and optionally, metadata on the
The parameter type suits the method being invoked: i.e. if we are doing a getRegionInfo request, optional CellBlock that may be following. The parameter type suits the method being
the protobuf Message param will be an instance of GetRegionInfoRequest. invoked: i.e. if we are doing a getRegionInfo request, the protobuf Message param
The response will be a GetRegionInfoResponse. will be an instance of GetRegionInfoRequest. The response will be a
The CellBlock is optionally used ferrying the bulk of the RPC data: i.e Cells/KeyValues.</para> GetRegionInfoResponse. The CellBlock is optionally used ferrying the bulk of the RPC
<para/> data: i.e Cells/KeyValues.</para>
<section><title>Request Parts</title> <section>
<section><title>&lt;Total Length&gt;</title> <title>Request Parts</title>
<para>The request is prefaced by an int that holds the total length of what follows.</para> <section>
<title>&lt;Total Length&gt;</title>
<para>The request is prefaced by an int that holds the total length of what
follows.</para>
</section> </section>
<section><title>&lt;Protobuf RequestHeader Message&gt;</title> <section>
<para>Will have call.id, trace.id, and method name, etc. including optional Metadata on the Cell block IFF one is following. <title>&lt;Protobuf RequestHeader Message&gt;</title>
Data is protobuf’d inline in this pb Message or optionally comes in the following CellBlock</para> <para>Will have call.id, trace.id, and method name, etc. including optional
Metadata on the Cell block IFF one is following. Data is protobuf’d inline
in this pb Message or optionally comes in the following CellBlock</para>
</section> </section>
<section><title>&lt;Protobuf Param Message&gt;</title> <section>
<para>If the method being invoked is getRegionInfo, if you study the Service descriptor for the client to regionserver protocol, <title>&lt;Protobuf Param Message&gt;</title>
you will find that the request sends a GetRegionInfoRequest protobuf Message param in this position.</para> <para>If the method being invoked is getRegionInfo, if you study the Service
descriptor for the client to regionserver protocol, you will find that the
request sends a GetRegionInfoRequest protobuf Message param in this
position.</para>
</section> </section>
<section><title>&lt;CellBlock&gt;</title> <section>
<title>&lt;CellBlock&gt;</title>
<para>An encoded and optionally compressed Cell block.</para> <para>An encoded and optionally compressed Cell block.</para>
</section> </section>
</section><!--Request parts-->
</section><!--Request-->
<section><title>Response</title>
<para>Same as Request, it is a protobuf ResponseHeader followed by a protobuf Message response where the Message response type suits the method invoked.
Bulk of the data may come in a following CellBlock.</para>
<section><title>Response Parts</title>
<section><title>&lt;Total Length&gt;</title>
<para>The response is prefaced by an int that holds the total length of what follows.</para>
</section> </section>
<section><title>&lt;Protobuf ResponseHeader Message&gt;</title> <!--Request parts-->
<para>Will have call.id, etc. Will include exception if failed processing.  Optionally includes metadata on optional, IFF there is a CellBlock following.</para> </section>
<!--Request-->
<section>
<title>Response</title>
<para>Same as Request, it is a protobuf ResponseHeader followed by a protobuf Message
response where the Message response type suits the method invoked. Bulk of the data
may come in a following CellBlock.</para>
<section>
<title>Response Parts</title>
<section>
<title>&lt;Total Length&gt;</title>
<para>The response is prefaced by an int that holds the total length of what
follows.</para>
</section>
<section>
<title>&lt;Protobuf ResponseHeader Message&gt;</title>
<para>Will have call.id, etc. Will include exception if failed processing.
 Optionally includes metadata on optional, IFF there is a CellBlock
following.</para>
</section> </section>
<section><title>&lt;Protobuf Response Message&gt;</title> <section>
<para>Return or may be nothing if exception. If the method being invoked is getRegionInfo, if you study the Service descriptor for the client to regionserver protocol, <title>&lt;Protobuf Response Message&gt;</title>
you will find that the response sends a GetRegionInfoResponse protobuf Message param in this position.</para> <para>Return or may be nothing if exception. If the method being invoked is
getRegionInfo, if you study the Service descriptor for the client to
regionserver protocol, you will find that the response sends a
GetRegionInfoResponse protobuf Message param in this position.</para>
</section> </section>
<section><title>&lt;CellBlock&gt;</title> <section>
<title>&lt;CellBlock&gt;</title>
<para>An encoded and optionally compressed Cell block.</para> <para>An encoded and optionally compressed Cell block.</para>
</section> </section>
</section><!--Parts-->
</section><!--Response-->
<section><title>Exceptions</title>
<para>There are two distinct types.
There is the request failed which is encapsulated inside the response header for the response.
The connection stays open to receive new requests.
The second type, the FatalConnectionException, kills the connection.</para>
<para>Exceptions can carry extra information.
See the ExceptionResponse protobuf type.
It has a flag to indicate do-no-retry as well as other miscellaneous payload to help improve client responsiveness.</para>
</section> </section>
<section><title>CellBlocks</title> <!--Parts-->
<para>These are not versioned. </section>
Server can do the codec or it cannot. <!--Response-->
If new version of a codec with say, tighter encoding, then give it a new class name.
Codecs will live on the server for all time so old clients can connect.</para> <section>
<title>Exceptions</title>
<para>There are two distinct types. There is the request failed which is encapsulated
inside the response header for the response. The connection stays open to receive
new requests. The second type, the FatalConnectionException, kills the
connection.</para>
<para>Exceptions can carry extra information. See the ExceptionResponse protobuf type.
It has a flag to indicate do-no-retry as well as other miscellaneous payload to help
improve client responsiveness.</para>
</section>
<section>
<title>CellBlocks</title>
<para>These are not versioned. Server can do the codec or it cannot. If new version of a
codec with say, tighter encoding, then give it a new class name. Codecs will live on
the server for all time so old clients can connect.</para>
</section> </section>
</section> </section>
<section><title>Notes</title> <section>
<section><title>Constraints</title> <title>Notes</title>
<para>In some part, current wire-format -- i.e. all requests and responses preceeded by a length -- has been dictated by current server non-async architecture.</para> <section>
<title>Constraints</title>
<para>In some part, current wire-format -- i.e. all requests and responses preceeded by
a length -- has been dictated by current server non-async architecture.</para>
</section> </section>
<section><title>One fat pb request or header+param</title> <section>
<para>We went with pb header followed by pb param making a request and a pb header followed by pb response for now. <title>One fat pb request or header+param</title>
Doing header+param rather than a single protobuf Message with both header and param content:</para> <para>We went with pb header followed by pb param making a request and a pb header
followed by pb response for now. Doing header+param rather than a single protobuf
Message with both header and param content:</para>
<para> <para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>Is closer to what we currently have</para> <para>Is closer to what we currently have</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Having a single fat pb requires extra copying putting the already pb’d param into the body of the fat request pb (and same making result)</para> <para>Having a single fat pb requires extra copying putting the already pb’d
param into the body of the fat request pb (and same making
result)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>We can decide whether to accept the request or not before we read the param; for example, the request might be low priority.  As is, we read header+param in one go as server is currently implemented so this is a TODO.</para> <para>We can decide whether to accept the request or not before we read the
param; for example, the request might be low priority.  As is, we read
header+param in one go as server is currently implemented so this is a
TODO.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
<para>The advantages are minor.  If later, fat request has clear advantage, can roll out a v2 later.</para> <para>The advantages are minor.  If later, fat request has clear advantage, can roll out
a v2 later.</para>
</section> </section>
<section xml:id="rpc.configs"><title>RPC Configurations</title> <section
<section><title>CellBlock Codecs</title> xml:id="rpc.configs">
<title>RPC Configurations</title>
<section>
<title>CellBlock Codecs</title>
<para>To enable a codec other than the default <classname>KeyValueCodec</classname>, <para>To enable a codec other than the default <classname>KeyValueCodec</classname>,
set <varname>hbase.client.rpc.codec</varname> set <varname>hbase.client.rpc.codec</varname> to the name of the Codec class to
to the name of the Codec class to use. Codec must implement hbase's <classname>Codec</classname> Interface. After connection setup, use. Codec must implement hbase's <classname>Codec</classname> Interface. After
all passed cellblocks will be sent with this codec. The server will return cellblocks using this same codec as long connection setup, all passed cellblocks will be sent with this codec. The server
as the codec is on the servers' CLASSPATH (else you will get <classname>UnsupportedCellCodecException</classname>).</para> will return cellblocks using this same codec as long as the codec is on the
<para>To change the default codec, set <varname>hbase.client.default.rpc.codec</varname>. servers' CLASSPATH (else you will get
</para> <classname>UnsupportedCellCodecException</classname>).</para>
<para>To disable cellblocks completely and to go pure protobuf, set the default to the <para>To change the default codec, set
empty String and do not specify a codec in your Configuration. So, set <varname>hbase.client.default.rpc.codec</varname> <varname>hbase.client.default.rpc.codec</varname>. </para>
to the empty string and do not set <varname>hbase.client.rpc.codec</varname>. <para>To disable cellblocks completely and to go pure protobuf, set the default to
This will cause the client to connect to the server with no codec specified. the empty String and do not specify a codec in your Configuration. So, set
If a server sees no codec, it will return all responses in pure protobuf. <varname>hbase.client.default.rpc.codec</varname> to the empty string and do
Running pure protobuf all the time will be slower than running with cellblocks. not set <varname>hbase.client.rpc.codec</varname>. This will cause the client to
</para> connect to the server with no codec specified. If a server sees no codec, it
will return all responses in pure protobuf. Running pure protobuf all the time
will be slower than running with cellblocks. </para>
</section> </section>
<section><title>Compression</title> <section>
<para>Uses hadoops compression codecs. To enable compressing of passed CellBlocks, set <varname>hbase.client.rpc.compressor</varname> <title>Compression</title>
to the name of the Compressor to use. Compressor must implement Hadoops' CompressionCodec Interface. After connection setup, <para>Uses hadoops compression codecs. To enable compressing of passed CellBlocks,
all passed cellblocks will be sent compressed. The server will return cellblocks compressed using this same compressor as long set <varname>hbase.client.rpc.compressor</varname> to the name of the Compressor
as the compressor is on its CLASSPATH (else you will get <classname>UnsupportedCompressionCodecException</classname>).</para> to use. Compressor must implement Hadoops' CompressionCodec Interface. After
connection setup, all passed cellblocks will be sent compressed. The server will
return cellblocks compressed using this same compressor as long as the
compressor is on its CLASSPATH (else you will get
<classname>UnsupportedCompressionCodecException</classname>).</para>
</section> </section>
</section> </section>
</section> </section>

1561
src/main/docbkx/schema_design.xml
View File

File diff suppressed because it is too large Load Diff

1072
src/main/docbkx/security.xml
View File

File diff suppressed because it is too large Load Diff

194
src/main/docbkx/shell.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<chapter xml:id="shell" <chapter
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="shell"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -28,54 +30,46 @@
--> -->
<title>The Apache HBase Shell</title> <title>The Apache HBase Shell</title>
<para> <para> The Apache HBase Shell is <link
The Apache HBase Shell is <link xlink:href="http://jruby.org">(J)Ruby</link>'s xlink:href="http://jruby.org">(J)Ruby</link>'s IRB with some HBase particular commands
IRB with some HBase particular commands added. Anything you can do in added. Anything you can do in IRB, you should be able to do in the HBase Shell.</para>
IRB, you should be able to do in the HBase Shell.</para> <para>To run the HBase shell, do as follows:</para>
<para>To run the HBase shell,
do as follows:
<programlisting>$ ./bin/hbase shell</programlisting> <programlisting>$ ./bin/hbase shell</programlisting>
</para> <para>Type <command>help</command> and then <command>&lt;RETURN&gt;</command> to see a listing
<para>Type <command>help</command> and then <command>&lt;RETURN&gt;</command> of shell commands and options. Browse at least the paragraphs at the end of the help
to see a listing of shell emission for the gist of how variables and command arguments are entered into the HBase
commands and options. Browse at least the paragraphs at the end of shell; in particular note how table names, rows, and columns, etc., must be quoted.</para>
the help emission for the gist of how variables and command <para>See <xref
arguments are entered into the linkend="shell_exercises" /> for example basic shell operation. </para>
HBase shell; in particular note how table names, rows, and <para>Here is a nicely formatted listing of <link
columns, etc., must be quoted.</para> xlink:href="http://learnhbase.wordpress.com/2013/03/02/hbase-shell-commands/">all shell
<para>See <xref linkend="shell_exercises" /> commands</link> by Rajeshbabu Chintaguntla. </para>
for example basic shell operation.
</para>
<para>Here is a nicely formatted listing of <link xlink:href="http://learnhbase.wordpress.com/2013/03/02/hbase-shell-commands/">all shell commands</link> by Rajeshbabu Chintaguntla.
</para>
<section xml:id="scripting"><title>Scripting</title> <section
<para>For examples scripting Apache HBase, look in the xml:id="scripting">
HBase <filename>bin</filename> directory. Look at the files <title>Scripting</title>
that end in <filename>*.rb</filename>. To run one of these <para>For examples scripting Apache HBase, look in the HBase <filename>bin</filename>
files, do as follows: directory. Look at the files that end in <filename>*.rb</filename>. To run one of these
files, do as follows:</para>
<programlisting>$ ./bin/hbase org.jruby.Main PATH_TO_SCRIPT</programlisting> <programlisting>$ ./bin/hbase org.jruby.Main PATH_TO_SCRIPT</programlisting>
</para>
</section> </section>
<section xml:id="shell_tricks"><title>Shell Tricks</title> <section
<section xml:id="table_variables"><title>Table variables</title> xml:id="shell_tricks">
<title>Shell Tricks</title>
<section
xml:id="table_variables">
<title>Table variables</title>
<para> <para> HBase 0.95 adds shell commands that provide a jruby-style object-oriented
HBase 0.95 adds shell commands that provide a jruby-style references for tables. Previously all of the shell commands that act upon a table
object-oriented references for tables. Previously all of have a procedural style that always took the name of the table as an argument. HBase
the shell commands that act upon a table have a procedural 0.95 introduces the ability to assign a table to a jruby variable. The table
style that always took the name of the table as an reference can be used to perform data read write operations such as puts, scans, and
argument. HBase 0.95 introduces the ability to assign a gets well as admin functionality such as disabling, dropping, describing tables. </para>
table to a jruby variable. The table reference can be used
to perform data read write operations such as puts, scans,
and gets well as admin functionality such as disabling,
dropping, describing tables.
</para>
<para> <para> For example, previously you would always specify a table name:</para>
For example, previously you would always specify a table name: <screen>
<programlisting>
hbase(main):000:0> create ‘t’, ‘f’ hbase(main):000:0> create ‘t’, ‘f’
0 row(s) in 1.0970 seconds 0 row(s) in 1.0970 seconds
hbase(main):001:0> put 't', 'rold', 'f', 'v' hbase(main):001:0> put 't', 'rold', 'f', 'v'
@ -101,12 +95,11 @@ hbase(main):005:0> drop 't'
0 row(s) in 23.1670 seconds 0 row(s) in 23.1670 seconds
hbase(main):006:0> hbase(main):006:0>
</programlisting> </screen>
</para>
<para> <para> Now you can assign the table to a variable and use the results in jruby shell
Now you can assign the table to a variable and use the results in jruby shell code. code.</para>
<programlisting> <screen>
hbase(main):007 > t = create 't', 'f' hbase(main):007 > t = create 't', 'f'
0 row(s) in 1.0970 seconds 0 row(s) in 1.0970 seconds
@ -128,13 +121,11 @@ hbase(main):038:0> t.disable
0 row(s) in 6.2350 seconds 0 row(s) in 6.2350 seconds
hbase(main):039:0> t.drop hbase(main):039:0> t.drop
0 row(s) in 0.2340 seconds 0 row(s) in 0.2340 seconds
</programlisting> </screen>
</para>
<para> <para> If the table has already been created, you can assign a Table to a variable by
If the table has already been created, you can assign a using the get_table method:</para>
Table to a variable by using the get_table method: <screen>
<programlisting>
hbase(main):011 > create 't','f' hbase(main):011 > create 't','f'
0 row(s) in 1.2500 seconds 0 row(s) in 1.2500 seconds
@ -150,15 +141,12 @@ ROW COLUMN+CELL
r1 column=f:, timestamp=1378473876949, value=v r1 column=f:, timestamp=1378473876949, value=v
1 row(s) in 0.0240 seconds 1 row(s) in 0.0240 seconds
hbase(main):015:0> hbase(main):015:0>
</programlisting> </screen>
</para>
<para> <para> The list functionality has also been extended so that it returns a list of table
The list functionality has also been extended so that it names as strings. You can then use jruby to script table operations based on these
returns a list of table names as strings. You can then use names. The list_snapshots command also acts similarly.</para>
jruby to script table operations based on these names. The <screen>
list_snapshots command also acts similarly.
<programlisting>
hbase(main):016 > tables = list(‘t.*’) hbase(main):016 > tables = list(‘t.*’)
TABLE TABLE
t t
@ -170,64 +158,64 @@ hbase(main):017:0> tables.map { |t| disable t ; drop t}
=> [nil] => [nil]
hbase(main):018:0> hbase(main):018:0>
</programlisting> </screen>
</para>
</section> </section>
<section><title><filename>irbrc</filename></title> <section>
<para>Create an <filename>.irbrc</filename> file for yourself in your home <title><filename>irbrc</filename></title>
directory. Add customizations. A useful one is command history so commands are save <para>Create an <filename>.irbrc</filename> file for yourself in your home directory.
across Shell invocations: Add customizations. A useful one is command history so commands are save across
<programlisting> Shell invocations:</para>
<screen>
$ more .irbrc $ more .irbrc
require 'irb/ext/save-history' require 'irb/ext/save-history'
IRB.conf[:SAVE_HISTORY] = 100 IRB.conf[:SAVE_HISTORY] = 100
IRB.conf[:HISTORY_FILE] = "#{ENV['HOME']}/.irb-save-history"</programlisting> IRB.conf[:HISTORY_FILE] = "#{ENV['HOME']}/.irb-save-history"</screen>
See the <application>ruby</application> documentation of <filename>.irbrc</filename> <para>See the <application>ruby</application> documentation of
to learn about other possible configurations. </para> <filename>.irbrc</filename> to learn about other possible configurations.
</para>
</section> </section>
<section><title>LOG data to timestamp</title> <section>
<para> <title>LOG data to timestamp</title>
To convert the date '08/08/16 20:56:29' from an hbase log into a timestamp, do: <para> To convert the date '08/08/16 20:56:29' from an hbase log into a timestamp,
<programlisting> do:</para>
<screen>
hbase(main):021:0> import java.text.SimpleDateFormat hbase(main):021:0> import java.text.SimpleDateFormat
hbase(main):022:0> import java.text.ParsePosition hbase(main):022:0> import java.text.ParsePosition
hbase(main):023:0> SimpleDateFormat.new("yy/MM/dd HH:mm:ss").parse("08/08/16 20:56:29", ParsePosition.new(0)).getTime() => 1218920189000</programlisting> hbase(main):023:0> SimpleDateFormat.new("yy/MM/dd HH:mm:ss").parse("08/08/16 20:56:29", ParsePosition.new(0)).getTime() => 1218920189000</screen>
</para> <para> To go the other direction:</para>
<para> <screen>
To go the other direction:
<programlisting>
hbase(main):021:0> import java.util.Date hbase(main):021:0> import java.util.Date
hbase(main):022:0> Date.new(1218920189000).toString() => "Sat Aug 16 20:56:29 UTC 2008"</programlisting> hbase(main):022:0> Date.new(1218920189000).toString() => "Sat Aug 16 20:56:29 UTC 2008"</screen>
</para> <para> To output in a format that is exactly like that of the HBase log format will take
<para> a little messing with <link
To output in a format that is exactly like that of the HBase log format will take a little messing with xlink:href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</link>.
<link xlink:href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</link>.
</para> </para>
</section> </section>
<section><title>Debug</title> <section>
<section><title>Shell debug switch</title> <title>Debug</title>
<para>You can set a debug switch in the shell to see more output <section>
-- e.g. more of the stack trace on exception -- <title>Shell debug switch</title>
when you run a command: <para>You can set a debug switch in the shell to see more output -- e.g. more of the
stack trace on exception -- when you run a command:</para>
<programlisting>hbase> debug &lt;RETURN&gt;</programlisting> <programlisting>hbase> debug &lt;RETURN&gt;</programlisting>
</para>
</section> </section>
<section><title>DEBUG log level</title> <section>
<para>To enable DEBUG level logging in the shell, <title>DEBUG log level</title>
launch it with the <command>-d</command> option. <para>To enable DEBUG level logging in the shell, launch it with the
<command>-d</command> option.</para>
<programlisting>$ ./bin/hbase shell -d</programlisting> <programlisting>$ ./bin/hbase shell -d</programlisting>
</para>
</section> </section>
</section> </section>
<section><title>Commands</title> <section>
<section><title>count</title> <title>Commands</title>
<para>Count command returns the number of rows in a table. <section>
It's quite fast when configured with the right CACHE <title>count</title>
<para>Count command returns the number of rows in a table. It's quite fast when
configured with the right CACHE
<programlisting>hbase> count '&lt;tablename&gt;', CACHE => 1000</programlisting> <programlisting>hbase> count '&lt;tablename&gt;', CACHE => 1000</programlisting>
The above count fetches 1000 rows at a time. Set CACHE lower if your rows are big. The above count fetches 1000 rows at a time. Set CACHE lower if your rows are
Default is to fetch one row at a time. big. Default is to fetch one row at a time. </para>
</para>
</section> </section>
</section> </section>

165
src/main/docbkx/tracing.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<appendix xml:id="tracing" <appendix
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="tracing"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -28,45 +30,36 @@
<title>Enabling Dapper-like Tracing in HBase</title> <title>Enabling Dapper-like Tracing in HBase</title>
<para> <para>
<link xlink:href="https://issues.apache.org/jira/browse/HBASE-6449">HBASE-6449</link> <link
added support for tracing requests through HBase, using the open source tracing library, xlink:href="https://issues.apache.org/jira/browse/HBASE-6449">HBASE-6449</link> added support
<link xlink:href="http://github.com/cloudera/htrace">HTrace</link>. for tracing requests through HBase, using the open source tracing library, <link
Setting up tracing is quite simple, xlink:href="http://github.com/cloudera/htrace">HTrace</link>. Setting up tracing is quite
however it currently requires some very minor changes to your client code simple, however it currently requires some very minor changes to your client code (it would not
(it would not be very difficult to remove this requirement). be very difficult to remove this requirement). </para>
</para>
<section xml:id="tracing.spanreceivers"> <section
xml:id="tracing.spanreceivers">
<title>SpanReceivers</title> <title>SpanReceivers</title>
<para> <para> The tracing system works by collecting information in structs called 'Spans'. It is up to
The tracing system works by collecting information in structs called 'Spans'. you to choose how you want to receive this information by implementing the
It is up to you to choose how you want to receive this information <classname>SpanReceiver</classname> interface, which defines one method: </para>
by implementing the <classname>SpanReceiver</classname> interface,
which defines one method:
<programlisting><![CDATA[ <programlisting><![CDATA[
public void receiveSpan(Span span); public void receiveSpan(Span span);
]]></programlisting> ]]></programlisting>
This method serves as a callback whenever a span is completed. <para>This method serves as a callback whenever a span is completed. HTrace allows you to use as
HTrace allows you to use as many SpanReceivers as you want many SpanReceivers as you want so you can easily send trace information to multiple
so you can easily send trace information to multiple destinations. destinations. </para>
</para>
<para> <para> Configure what SpanReceivers you'd like to us by putting a comma separated list of the
Configure what SpanReceivers you'd like to us fully-qualified class name of classes implementing <classname>SpanReceiver</classname> in
by putting a comma separated list of the <filename>hbase-site.xml</filename> property:
fully-qualified class name of classes implementing <varname>hbase.trace.spanreceiver.classes</varname>. </para>
<classname>SpanReceiver</classname> in <filename>hbase-site.xml</filename>
property: <varname>hbase.trace.spanreceiver.classes</varname>.
</para>
<para> <para> HTrace includes a <classname>LocalFileSpanReceiver</classname> that writes all span
HTrace includes a <classname>LocalFileSpanReceiver</classname> information to local files in a JSON-based format. The
that writes all span information to local files in a JSON-based format. <classname>LocalFileSpanReceiver</classname> looks in <filename>hbase-site.xml</filename>
The <classname>LocalFileSpanReceiver</classname> for a <varname>hbase.local-file-span-receiver.path</varname> property with a value describing
looks in <filename>hbase-site.xml</filename> the name of the file to which nodes should write their span information. </para>
for a <varname>hbase.local-file-span-receiver.path</varname>
property with a value describing the name of the file
to which nodes should write their span information.
<programlisting><![CDATA[ <programlisting><![CDATA[
<property> <property>
<name>hbase.trace.spanreceiver.classes</name> <name>hbase.trace.spanreceiver.classes</name>
@ -77,38 +70,28 @@
<value>/var/log/hbase/htrace.out</value> <value>/var/log/hbase/htrace.out</value>
</property> </property>
]]></programlisting> ]]></programlisting>
</para>
<para> HTrace also provides <classname>ZipkinSpanReceiver</classname> which converts spans to <link
xlink:href="http://github.com/twitter/zipkin">Zipkin</link> span format and send them to
Zipkin server. In order to use this span receiver, you need to install the jar of
htrace-zipkin to your HBase's classpath on all of the nodes in your cluster. </para>
<para> <para>
HTrace also provides <classname>ZipkinSpanReceiver</classname> <filename>htrace-zipkin</filename> is published to the maven central repository. You could get
which converts spans to the latest version from there or just build it locally and then copy it out to all nodes,
<link xlink:href="http://github.com/twitter/zipkin">Zipkin</link> change your config to use zipkin receiver, distribute the new configuration and then (rolling)
span format and send them to Zipkin server. restart. </para>
In order to use this span receiver, <para> Here is the example of manual setup procedure. </para>
you need to install the jar of htrace-zipkin to your HBase's classpath <screen><![CDATA[
on all of the nodes in your cluster.
</para>
<para>
<filename>htrace-zipkin</filename> is published to the maven central repository.
You could get the latest version from there or just build it locally and then
copy it out to all nodes, change your config to use zipkin receiver, distribute
the new configuration and then (rolling) restart.
</para>
<para>
Here is the example of manual setup procedure.
<programlisting><![CDATA[
$ git clone https://github.com/cloudera/htrace $ git clone https://github.com/cloudera/htrace
$ cd htrace/htrace-zipkin $ cd htrace/htrace-zipkin
$ mvn compile assembly:single $ mvn compile assembly:single
$ cp target/htrace-zipkin-*-jar-with-dependencies.jar $HBASE_HOME/lib/ $ cp target/htrace-zipkin-*-jar-with-dependencies.jar $HBASE_HOME/lib/
# copy jar to all nodes... # copy jar to all nodes...
]]></programlisting> ]]></screen>
The <classname>ZipkinSpanReceiver</classname> <para>The <classname>ZipkinSpanReceiver</classname> looks in <filename>hbase-site.xml</filename>
looks in <filename>hbase-site.xml</filename> for a <varname>hbase.zipkin.collector-hostname</varname> and
for a <varname>hbase.zipkin.collector-hostname</varname> <varname>hbase.zipkin.collector-port</varname> property with a value describing the Zipkin
and <varname>hbase.zipkin.collector-port</varname> collector server to which span information are sent. </para>
property with a value describing the Zipkin collector server
to which span information are sent.
<programlisting><![CDATA[ <programlisting><![CDATA[
<property> <property>
<name>hbase.trace.spanreceiver.classes</name> <name>hbase.trace.spanreceiver.classes</name>
@ -123,24 +106,18 @@
<value>9410</value> <value>9410</value>
</property> </property>
]]></programlisting> ]]></programlisting>
</para>
<para> <para> If you do not want to use the included span receivers, you are encouraged to write your
If you do not want to use the included span receivers, own receiver (take a look at <classname>LocalFileSpanReceiver</classname> for an example). If
you are encouraged to write your own receiver you think others would benefit from your receiver, file a JIRA or send a pull request to <link
(take a look at <classname>LocalFileSpanReceiver</classname> for an example). xlink:href="http://github.com/cloudera/htrace">HTrace</link>. </para>
If you think others would benefit from your receiver,
file a JIRA or send a pull request to
<link xlink:href="http://github.com/cloudera/htrace">HTrace</link>.
</para>
</section> </section>
<section xml:id="tracing.client.modifications"> <section
xml:id="tracing.client.modifications">
<title>Client Modifications</title> <title>Client Modifications</title>
<para> <para> In order to turn on tracing in your client code, you must initialize the module sending
In order to turn on tracing in your client code, spans to receiver once per client process. </para>
you must initialize the module sending spans to receiver
once per client process.
<programlisting><![CDATA[ <programlisting><![CDATA[
private SpanReceiverHost spanReceiverHost; private SpanReceiverHost spanReceiverHost;
@ -149,16 +126,15 @@
Configuration conf = HBaseConfiguration.create(); Configuration conf = HBaseConfiguration.create();
SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf); SpanReceiverHost spanReceiverHost = SpanReceiverHost.getInstance(conf);
]]></programlisting> ]]></programlisting>
Then you simply start tracing span before requests you think are interesting, <para>Then you simply start tracing span before requests you think are interesting, and close it
and close it when the request is done. when the request is done. For example, if you wanted to trace all of your get operations, you
For example, if you wanted to trace all of your get operations, change this: </para>
you change this:
<programlisting><![CDATA[ <programlisting><![CDATA[
HTable table = new HTable(conf, "t1"); HTable table = new HTable(conf, "t1");
Get get = new Get(Bytes.toBytes("r1")); Get get = new Get(Bytes.toBytes("r1"));
Result res = table.get(get); Result res = table.get(get);
]]></programlisting> ]]></programlisting>
into: <para>into: </para>
<programlisting><![CDATA[ <programlisting><![CDATA[
TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS); TraceScope ts = Trace.startSpan("Gets", Sampler.ALWAYS);
try { try {
@ -169,38 +145,30 @@
ts.close(); ts.close();
} }
]]></programlisting> ]]></programlisting>
If you wanted to trace half of your 'get' operations, you would pass in: <para>If you wanted to trace half of your 'get' operations, you would pass in: </para>
<programlisting><![CDATA[ <programlisting><![CDATA[
new ProbabilitySampler(0.5) new ProbabilitySampler(0.5)
]]></programlisting> ]]></programlisting>
in lieu of <varname>Sampler.ALWAYS</varname> <para>in lieu of <varname>Sampler.ALWAYS</varname> to <classname>Trace.startSpan()</classname>.
to <classname>Trace.startSpan()</classname>. See the HTrace <filename>README</filename> for more information on Samplers. </para>
See the HTrace <filename>README</filename> for more information on Samplers.
</para>
</section> </section>
<section xml:id="tracing.client.shell"> <section
xml:id="tracing.client.shell">
<title>Tracing from HBase Shell</title> <title>Tracing from HBase Shell</title>
<para> <para> You can use <command>trace</command> command for tracing requests from HBase Shell.
You can use <command>trace</command> command <command>trace 'start'</command> command turns on tracing and <command>trace
for tracing requests from HBase Shell. 'stop'</command> command turns off tracing. </para>
<command>trace 'start'</command> command turns on tracing and
<command>trace 'stop'</command> command turns off tracing.
<programlisting><![CDATA[ <programlisting><![CDATA[
hbase(main):001:0> trace 'start' hbase(main):001:0> trace 'start'
hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands hbase(main):002:0> put 'test', 'row1', 'f:', 'val1' # traced commands
hbase(main):003:0> trace 'stop' hbase(main):003:0> trace 'stop'
]]></programlisting> ]]></programlisting>
</para>
<para> <para>
<command>trace 'start'</command> and <command>trace 'start'</command> and <command>trace 'stop'</command> always returns boolean
<command>trace 'stop'</command> always value representing if or not there is ongoing tracing. As a result, <command>trace
returns boolean value representing 'stop'</command> returns false on suceess. <command>trace 'status'</command> just returns if
if or not there is ongoing tracing. or not tracing is turned on. </para>
As a result, <command>trace 'stop'</command>
returns false on suceess.
<command>trace 'status'</command>
just returns if or not tracing is turned on.
<programlisting><![CDATA[ <programlisting><![CDATA[
hbase(main):001:0> trace 'start' hbase(main):001:0> trace 'start'
=> true => true
@ -214,7 +182,6 @@
hbase(main):004:0> trace 'status' hbase(main):004:0> trace 'status'
=> false => false
]]></programlisting> ]]></programlisting>
</para>
</section> </section>
</appendix> </appendix>

1037
src/main/docbkx/troubleshooting.xml
View File

File diff suppressed because it is too large Load Diff

603
src/main/docbkx/upgrading.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<chapter xml:id="upgrading" <chapter
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="upgrading"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -29,114 +31,120 @@
<title>Upgrading</title> <title>Upgrading</title>
<para>You cannot skip major versions upgrading. If you are upgrading from version 0.90.x to <para>You cannot skip major versions upgrading. If you are upgrading from version 0.90.x to
0.94.x, you must first go from 0.90.x to 0.92.x and then go from 0.92.x to 0.94.x.</para> 0.94.x, you must first go from 0.90.x to 0.92.x and then go from 0.92.x to 0.94.x.</para>
<note><para>It may be possible to skip across versions -- for example go from <note>
0.92.2 straight to 0.98.0 just following the 0.96.x upgrade instructions -- <para>It may be possible to skip across versions -- for example go from 0.92.2 straight to
but we have not tried it so cannot say whether it works or not.</para> 0.98.0 just following the 0.96.x upgrade instructions -- but we have not tried it so
cannot say whether it works or not.</para>
</note> </note>
<para> <para> Review <xref
Review <xref linkend="configuration" />, in particular the section on Hadoop version. linkend="configuration" />, in particular the section on Hadoop version. </para>
</para> <section
<section xml:id="hbase.versioning"> xml:id="hbase.versioning">
<title>HBase version numbers</title> <title>HBase version numbers</title>
<para>HBase has not walked a straight line where version numbers are concerned. <para>HBase has not walked a straight line where version numbers are concerned. Since we
Since we came up out of hadoop itself, we originally tracked hadoop versioning. came up out of hadoop itself, we originally tracked hadoop versioning. Later we left
Later we left hadoop versioning behind because we were moving at a different rate hadoop versioning behind because we were moving at a different rate to that of our
to that of our parent. If you are into the arcane, checkout our old wiki page parent. If you are into the arcane, checkout our old wiki page on <link
on <link xlink:href="http://wiki.apache.org/hadoop/Hbase/HBaseVersions">HBase Versioning</link> xlink:href="http://wiki.apache.org/hadoop/Hbase/HBaseVersions">HBase
which tries to connect the HBase version dots.</para> Versioning</link> which tries to connect the HBase version dots.</para>
<section xml:id="hbase.development.series"><title>Odd/Even Versioning or "Development"" Series Releases</title> <section
xml:id="hbase.development.series">
<title>Odd/Even Versioning or "Development"" Series Releases</title>
<para>Ahead of big releases, we have been putting up preview versions to start the <para>Ahead of big releases, we have been putting up preview versions to start the
feedback cycle turning-over earlier. These "Development" Series releases, feedback cycle turning-over earlier. These "Development" Series releases, always
always odd-numbered, come with no guarantees, not even regards being able odd-numbered, come with no guarantees, not even regards being able to upgrade
to upgrade between two sequential releases (we reserve the right to break compatibility across between two sequential releases (we reserve the right to break compatibility across
"Development" Series releases). Needless to say, these releases are not for "Development" Series releases). Needless to say, these releases are not for
production deploys. They are a preview of what is coming in the hope that production deploys. They are a preview of what is coming in the hope that interested
interested parties will take the release for a test drive and flag us early if we parties will take the release for a test drive and flag us early if we there are
there are issues we've missed ahead of our rolling a production-worthy release. issues we've missed ahead of our rolling a production-worthy release. </para>
</para> <para>Our first "Development" Series was the 0.89 set that came out ahead of HBase
<para>Our first "Development" Series was the 0.89 set that came out ahead of 0.90.0. HBase 0.95 is another "Development" Series that portends HBase 0.96.0.
HBase 0.90.0. HBase 0.95 is another "Development" Series that portends
HBase 0.96.0.
</para> </para>
</section> </section>
<section xml:id="hbase.binary.compatibility"> <section
xml:id="hbase.binary.compatibility">
<title>Binary Compatibility</title> <title>Binary Compatibility</title>
<para>When we say two HBase versions are compatible, we mean that the versions <para>When we say two HBase versions are compatible, we mean that the versions are wire
are wire and binary compatible. Compatible HBase versions means that and binary compatible. Compatible HBase versions means that clients can talk to
clients can talk to compatible but differently versioned servers. compatible but differently versioned servers. It means too that you can just swap
It means too that you can just swap out the jars of one version and replace out the jars of one version and replace them with the jars of another, compatible
them with the jars of another, compatible version and all will just work. version and all will just work. Unless otherwise specified, HBase point versions are
Unless otherwise specified, HBase point versions are binary compatible. binary compatible. You can safely do rolling upgrades between binary compatible
You can safely do rolling upgrades between binary compatible versions; i.e. versions; i.e. across point versions: e.g. from 0.94.5 to 0.94.6<footnote>
across point versions: e.g. from 0.94.5 to 0.94.6<footnote><para>See <para>See <link
<link xlink:href="http://search-hadoop.com/m/bOOvwHGW981/Does+compatibility+between+versions+also+mean+binary+compatibility%253F&amp;subj=Re+Does+compatibility+between+versions+also+mean+binary+compatibility+">Does compatibility between versions also mean binary compatibility?</link> xlink:href="http://search-hadoop.com/m/bOOvwHGW981/Does+compatibility+between+versions+also+mean+binary+compatibility%253F&amp;subj=Re+Does+compatibility+between+versions+also+mean+binary+compatibility+">Does
discussion on the hbaes dev mailing list. compatibility between versions also mean binary compatibility?</link>
</para></footnote>. discussion on the hbaes dev mailing list. </para>
</para> </footnote>. </para>
</section> </section>
<section xml:id="hbase.rolling.restart"> <section
xml:id="hbase.rolling.restart">
<title>Rolling Upgrade between versions/Binary compatibility</title> <title>Rolling Upgrade between versions/Binary compatibility</title>
<para>Unless otherwise specified, HBase point versions are binary compatible. <para>Unless otherwise specified, HBase point versions are binary compatible. you can do
you can do a rolling upgrade between hbase point versions; a rolling upgrade between hbase point versions; for example, you can go to 0.94.6
for example, you can go to 0.94.6 from 0.94.5 by doing a rolling upgrade across the cluster from 0.94.5 by doing a rolling upgrade across the cluster replacing the 0.94.5
replacing the 0.94.5 binary with a 0.94.6 binary. binary with a 0.94.6 binary. </para>
</para>
</section> </section>
</section> </section>
<section xml:id="upgrade0.98"> <section
xml:id="upgrade0.98">
<title>Upgrading from 0.96.x to 0.98.x</title> <title>Upgrading from 0.96.x to 0.98.x</title>
<para>A rolling upgrade from 0.96.x to 0.98.x works. The two versions are not binary compatible.</para> <para>A rolling upgrade from 0.96.x to 0.98.x works. The two versions are not binary
<para>Additional steps are required to take advantage of some of the new features of 0.98.x, including cell visibility compatible.</para>
labels, cell ACLs, and transparent server side encryption. See the <para>Additional steps are required to take advantage of some of the new features of 0.98.x,
<xref linkend="security" /> chapter of this guide for more information. Significant performance improvements include a change to the write including cell visibility labels, cell ACLs, and transparent server side encryption. See
ahead log threading model that provides higher transaction throughput under the <xref
high load, reverse scanners, MapReduce over snapshot files, and striped linkend="security" /> chapter of this guide for more information. Significant
compaction.</para> performance improvements include a change to the write ahead log threading model that
<para>Clients and servers can run with 0.98.x and 0.96.x versions. However, applications may need to be recompiled due to changes in the Java API.</para> provides higher transaction throughput under high load, reverse scanners, MapReduce over
snapshot files, and striped compaction.</para>
<para>Clients and servers can run with 0.98.x and 0.96.x versions. However, applications may
need to be recompiled due to changes in the Java API.</para>
</section> </section>
<section> <section>
<title>Upgrading from 0.94.x to 0.98.x</title> <title>Upgrading from 0.94.x to 0.98.x</title>
<para> <para> A rolling upgrade from 0.94.x directly to 0.98.x does not work. The upgrade path
A rolling upgrade from 0.94.x directly to 0.98.x does not work. The upgrade path follows the same procedures as <xref linkend="upgrade0.96" />. Additional steps are required to use some of the new features of 0.98.x. See <xref linkend="upgrade0.98" /> for an abbreviated list of these features. follows the same procedures as <xref
</para> linkend="upgrade0.96" />. Additional steps are required to use some of the new
features of 0.98.x. See <xref
linkend="upgrade0.98" /> for an abbreviated list of these features. </para>
</section> </section>
<section xml:id="upgrade0.96"> <section
xml:id="upgrade0.96">
<title>Upgrading from 0.94.x to 0.96.x</title> <title>Upgrading from 0.94.x to 0.96.x</title>
<subtitle>The Singularity</subtitle> <subtitle>The Singularity</subtitle>
<para>You will have to stop your old 0.94.x cluster completely to upgrade. If you are replicating <para>You will have to stop your old 0.94.x cluster completely to upgrade. If you are
between clusters, both clusters will have to go down to upgrade. Make sure it is a clean shutdown. replicating between clusters, both clusters will have to go down to upgrade. Make sure
The less WAL files around, the faster the upgrade will run (the upgrade will split any log files it it is a clean shutdown. The less WAL files around, the faster the upgrade will run (the
finds in the filesystem as part of the upgrade process). All clients must be upgraded to 0.96 too. upgrade will split any log files it finds in the filesystem as part of the upgrade
</para> process). All clients must be upgraded to 0.96 too. </para>
<para>The API has changed. You will need to recompile your code against 0.96 and you may need to <para>The API has changed. You will need to recompile your code against 0.96 and you may
adjust applications to go against new APIs (TODO: List of changes). need to adjust applications to go against new APIs (TODO: List of changes). </para>
</para>
<section> <section>
<title>Executing the 0.96 Upgrade</title> <title>Executing the 0.96 Upgrade</title>
<note> <note>
<para>HDFS and ZooKeeper should be up and running during the upgrade process.</para> <para>HDFS and ZooKeeper should be up and running during the upgrade process.</para>
</note> </note>
<para>hbase-0.96.0 comes with an upgrade script. Run <para>hbase-0.96.0 comes with an upgrade script. Run
<programlisting>$ bin/hbase upgrade</programlisting> to see its usage. <programlisting>$ bin/hbase upgrade</programlisting> to see its usage. The script
The script has two main modes: -check, and -execute. has two main modes: -check, and -execute. </para>
</para> <section>
<section><title>check</title> <title>check</title>
<para>The <emphasis>check</emphasis> step is run against a running 0.94 cluster. <para>The <emphasis>check</emphasis> step is run against a running 0.94 cluster. Run
Run it from a downloaded 0.96.x binary. The <emphasis>check</emphasis> step it from a downloaded 0.96.x binary. The <emphasis>check</emphasis> step is
is looking for the presence of <filename>HFileV1</filename> files. These are looking for the presence of <filename>HFileV1</filename> files. These are
unsupported in hbase-0.96.0. To purge them -- have them rewritten as HFileV2 -- unsupported in hbase-0.96.0. To purge them -- have them rewritten as HFileV2 --
you must run a compaction. you must run a compaction. </para>
</para> <para>The <emphasis>check</emphasis> step prints stats at the end of its run (grep
<para>The <emphasis>check</emphasis> step prints stats at the end of its run for “Result:” in the log) printing absolute path of the tables it scanned, any
(grep for “Result:” in the log) printing absolute path of the tables it scanned, HFileV1 files found, the regions containing said files (the regions we need to
any HFileV1 files found, the regions containing said files (the regions we major compact to purge the HFileV1s), and any corrupted files if any found. A
need to major compact to purge the HFileV1s), and any corrupted files if corrupt file is unreadable, and so is undefined (neither HFileV1 nor HFileV2). </para>
any found. A corrupt file is unreadable, and so is undefined (neither HFileV1 nor HFileV2). <para>To run the check step, run <command>$ bin/hbase upgrade -check</command>. Here
</para> is sample output:</para>
<para>To run the check step, run <programlisting>$ bin/hbase upgrade -check</programlisting>. <screen>
Here is sample output:
<programlisting>
Tables Processed: Tables Processed:
hdfs://localhost:41020/myHBase/.META. hdfs://localhost:41020/myHBase/.META.
hdfs://localhost:41020/myHBase/usertable hdfs://localhost:41020/myHBase/usertable
@ -157,52 +165,59 @@
hdfs://localhost:41020/myHBase/usertable/ecdd3eaee2d2fcf8184ac025555bb2af hdfs://localhost:41020/myHBase/usertable/ecdd3eaee2d2fcf8184ac025555bb2af
There are some HFileV1, or corrupt files (files with incorrect major version) There are some HFileV1, or corrupt files (files with incorrect major version)
</programlisting> </screen>
In the above sample output, there are two HFileV1 in two regions, and one corrupt file. <para>In the above sample output, there are two HFileV1 in two regions, and one
Corrupt files should probably be removed. The regions that have HFileV1s need to be major corrupt file. Corrupt files should probably be removed. The regions that have
compacted. To major compact, start up the hbase shell and review how to compact an individual HFileV1s need to be major compacted. To major compact, start up the hbase shell
region. After the major compaction is done, rerun the check step and the HFileV1s shoudl be and review how to compact an individual region. After the major compaction is
gone, replaced by HFileV2 instances. done, rerun the check step and the HFileV1s shoudl be gone, replaced by HFileV2
</para> instances. </para>
<para>By default, the check step scans the hbase root directory (defined as hbase.rootdir in the configuration). <para>By default, the check step scans the hbase root directory (defined as
To scan a specific directory only, pass the <emphasis>-dir</emphasis> option. hbase.rootdir in the configuration). To scan a specific directory only, pass the
<programlisting>$ bin/hbase upgrade -check -dir /myHBase/testTable</programlisting> <emphasis>-dir</emphasis> option.</para>
The above command would detect HFileV1s in the /myHBase/testTable directory. <screen>$ bin/hbase upgrade -check -dir /myHBase/testTable</screen>
</para> <para>The above command would detect HFileV1s in the /myHBase/testTable directory. </para>
<para> <para> Once the check step reports all the HFileV1 files have been rewritten, it is
Once the check step reports all the HFileV1 files have been rewritten, it is safe to proceed with the safe to proceed with the upgrade. </para>
upgrade.
</para>
</section> </section>
<section><title>execute</title> <section>
<para>After the check step shows the cluster is free of HFileV1, it is safe to proceed with the upgrade. <title>execute</title>
Next is the <emphasis>execute</emphasis> step. You must <emphasis>SHUTDOWN YOUR 0.94.x CLUSTER</emphasis> <para>After the check step shows the cluster is free of HFileV1, it is safe to
before you can run the <emphasis>execute</emphasis> step. The execute step will not run if it proceed with the upgrade. Next is the <emphasis>execute</emphasis> step. You
detects running HBase masters or regionservers. must <emphasis>SHUTDOWN YOUR 0.94.x CLUSTER</emphasis> before you can run the
<note> <emphasis>execute</emphasis> step. The execute step will not run if it
<para>HDFS and ZooKeeper should be up and running during the upgrade process. detects running HBase masters or regionservers. <note>
If zookeeper is managed by HBase, then you can start zookeeper so it is available to the upgrade <para>HDFS and ZooKeeper should be up and running during the upgrade
by running <programlisting>$ ./hbase/bin/hbase-daemon.sh start zookeeper</programlisting> process. If zookeeper is managed by HBase, then you can start zookeeper
</para></note> so it is available to the upgrade by running <command>$
./hbase/bin/hbase-daemon.sh start zookeeper</command>
</para> </para>
<para> </note>
The <emphasis>execute</emphasis> upgrade step is made of three substeps. </para>
<para> The <emphasis>execute</emphasis> upgrade step is made of three substeps. </para>
<itemizedlist> <itemizedlist>
<listitem> <para>Namespaces: HBase 0.96.0 has support for namespaces. The upgrade needs to reorder directories in the filesystem for namespaces to work.</para> </listitem> <listitem>
<listitem> <para>ZNodes: All znodes are purged so that new ones can be written in their place using a new protobuf'ed format and a few are migrated in place: e.g. replication and table state znodes</para> </listitem> <para>Namespaces: HBase 0.96.0 has support for namespaces. The upgrade needs
<listitem> <para>WAL Log Splitting: If the 0.94.x cluster shutdown was not clean, we'll split WAL logs as part of migration before to reorder directories in the filesystem for namespaces to work.</para>
we startup on 0.96.0. This WAL splitting runs slower than the native distributed WAL splitting because it is all inside the </listitem>
single upgrade process (so try and get a clean shutdown of the 0.94.0 cluster if you can). <listitem>
</para> </listitem> <para>ZNodes: All znodes are purged so that new ones can be written in their
place using a new protobuf'ed format and a few are migrated in place:
e.g. replication and table state znodes</para>
</listitem>
<listitem>
<para>WAL Log Splitting: If the 0.94.x cluster shutdown was not clean, we'll
split WAL logs as part of migration before we startup on 0.96.0. This
WAL splitting runs slower than the native distributed WAL splitting
because it is all inside the single upgrade process (so try and get a
clean shutdown of the 0.94.0 cluster if you can). </para>
</listitem>
</itemizedlist> </itemizedlist>
</para> <para> To run the <emphasis>execute</emphasis> step, make sure that first you have
<para> copied hbase-0.96.0 binaries everywhere under servers and under clients. Make
To run the <emphasis>execute</emphasis> step, make sure that first you have copied hbase-0.96.0 sure the 0.94.0 cluster is down. Then do as follows:</para>
binaries everywhere under servers and under clients. Make sure the 0.94.0 cluster is down. <screen>$ bin/hbase upgrade -execute</screen>
Then do as follows: <para>Here is some sample output.</para>
<programlisting>$ bin/hbase upgrade -execute</programlisting>
Here is some sample output
<programlisting> <programlisting>
Starting Namespace upgrade Starting Namespace upgrade
Created version file at hdfs://localhost:41020/myHBase with version=7 Created version file at hdfs://localhost:41020/myHBase with version=7
@ -218,17 +233,19 @@
… …
Successfully completed Log splitting Successfully completed Log splitting
</programlisting> </programlisting>
</para> <para> If the output from the execute step looks good, stop the zookeeper instance
<para> you started to do the upgrade:
If the output from the execute step looks good, stop the zookeeper instance you started <programlisting>$ ./hbase/bin/hbase-daemon.sh stop zookeeper</programlisting>
to do the upgrade: <programlisting>$ ./hbase/bin/hbase-daemon.sh stop zookeeper</programlisting> Now start up hbase-0.96.0. </para>
Now start up hbase-0.96.0.
</para>
</section> </section>
<section xml:id="s096.migration.troubleshooting"><title>Troubleshooting</title> <section
<section xml:id="s096.migration.troubleshooting.old.client"><title>Old Client connecting to 0.96 cluster</title> xml:id="s096.migration.troubleshooting">
<para>It will fail with an exception like the below. Upgrade. <title>Troubleshooting</title>
<programlisting>17:22:15 Exception in thread "main" java.lang.IllegalArgumentException: Not a host:port pair: PBUF <section
xml:id="s096.migration.troubleshooting.old.client">
<title>Old Client connecting to 0.96 cluster</title>
<para>It will fail with an exception like the below. Upgrade.</para>
<screen>17:22:15 Exception in thread "main" java.lang.IllegalArgumentException: Not a host:port pair: PBUF
17:22:15 * 17:22:15 *
17:22:15 api-compat-8.ent.cloudera.com <20><> <20><><EFBFBD>( 17:22:15 api-compat-8.ent.cloudera.com <20><> <20><><EFBFBD>(
17:22:15 at org.apache.hadoop.hbase.util.Addressing.parseHostname(Addressing.java:60) 17:22:15 at org.apache.hadoop.hbase.util.Addressing.parseHostname(Addressing.java:60)
@ -239,8 +256,7 @@
17:22:15 at org.apache.hadoop.hbase.client.HConnectionManager$HConnectionImplementation.getMaster(HConnectionManager.java:703) 17:22:15 at org.apache.hadoop.hbase.client.HConnectionManager$HConnectionImplementation.getMaster(HConnectionManager.java:703)
17:22:15 at org.apache.hadoop.hbase.client.HBaseAdmin.&amp;init>(HBaseAdmin.java:126) 17:22:15 at org.apache.hadoop.hbase.client.HBaseAdmin.&amp;init>(HBaseAdmin.java:126)
17:22:15 at Client_4_3_0.setup(Client_4_3_0.java:716) 17:22:15 at Client_4_3_0.setup(Client_4_3_0.java:716)
17:22:15 at Client_4_3_0.main(Client_4_3_0.java:63)</programlisting> 17:22:15 at Client_4_3_0.main(Client_4_3_0.java:63)</screen>
</para>
</section> </section>
</section> </section>
</section> </section>
@ -248,183 +264,224 @@
</section> </section>
<section xml:id="upgrade0.94"> <section
xml:id="upgrade0.94">
<title>Upgrading from 0.92.x to 0.94.x</title> <title>Upgrading from 0.92.x to 0.94.x</title>
<para>We used to think that 0.92 and 0.94 were interface compatible and that you can do a <para>We used to think that 0.92 and 0.94 were interface compatible and that you can do a
rolling upgrade between these versions but then we figured that rolling upgrade between these versions but then we figured that <link
<link xlink:href="https://issues.apache.org/jira/browse/HBASE-5357">HBASE-5357 Use builder pattern in HColumnDescriptor</link> xlink:href="https://issues.apache.org/jira/browse/HBASE-5357">HBASE-5357 Use builder
changed method signatures so rather than return void they instead return HColumnDescriptor. This pattern in HColumnDescriptor</link> changed method signatures so rather than return
will throw <programlisting>java.lang.NoSuchMethodError: org.apache.hadoop.hbase.HColumnDescriptor.setMaxVersions(I)V</programlisting> void they instead return HColumnDescriptor. This will throw</para>
.... so 0.92 and 0.94 are NOT compatible. You cannot do a rolling upgrade between them. <screen>java.lang.NoSuchMethodError: org.apache.hadoop.hbase.HColumnDescriptor.setMaxVersions(I)V</screen>
</para> <para>.... so 0.92 and 0.94 are NOT compatible. You cannot do a rolling upgrade between them.</para> </section>
</section> <section
<section xml:id="upgrade0.92"> xml:id="upgrade0.92">
<title>Upgrading from 0.90.x to 0.92.x</title> <title>Upgrading from 0.90.x to 0.92.x</title>
<subtitle>Upgrade Guide</subtitle> <subtitle>Upgrade Guide</subtitle>
<para>You will find that 0.92.0 runs a little differently to 0.90.x releases. Here are a few things to watch out for upgrading from 0.90.x to 0.92.0. <para>You will find that 0.92.0 runs a little differently to 0.90.x releases. Here are a few
<note><title>tl;dr</title> things to watch out for upgrading from 0.90.x to 0.92.0. </para>
<para> <note>
If you've not patience, here are the important things to know upgrading. <title>tl;dr</title>
<orderedlist> <para> If you've not patience, here are the important things to know upgrading. <orderedlist>
<listitem><para>Once you upgrade, you can’t go back.</para> <listitem>
<para>Once you upgrade, you can’t go back.</para>
</listitem> </listitem>
<listitem><para> <listitem>
MSLAB is on by default. Watch that heap usage if you have a lot of regions.</para> <para> MSLAB is on by default. Watch that heap usage if you have a lot of
regions.</para>
</listitem>
<listitem>
<para> Distributed splitting is on by defaul. It should make region server
failover faster. </para>
</listitem>
<listitem>
<para> There’s a separate tarball for security. </para>
</listitem>
<listitem>
<para> If -XX:MaxDirectMemorySize is set in your hbase-env.sh, it’s going to
enable the experimental off-heap cache (You may not want this). </para>
</listitem> </listitem>
<listitem><para>
Distributed splitting is on by defaul. It should make region server failover faster.
</para></listitem>
<listitem><para>
There’s a separate tarball for security.
</para></listitem>
<listitem><para>
If -XX:MaxDirectMemorySize is set in your hbase-env.sh, it’s going to enable the experimental off-heap cache (You may not want this).
</para></listitem>
</orderedlist> </orderedlist>
</para> </para>
</note> </note>
</para>
<section> <section>
<title>You can’t go back! <title>You can’t go back! </title>
</title> <para>To move to 0.92.0, all you need to do is shutdown your cluster, replace your hbase
<para>To move to 0.92.0, all you need to do is shutdown your cluster, replace your hbase 0.90.x with hbase 0.92.0 binaries (be sure you clear out all 0.90.x instances) and restart (You cannot do a rolling restart from 0.90.x to 0.92.x -- you must restart). 0.90.x with hbase 0.92.0 binaries (be sure you clear out all 0.90.x instances) and
On startup, the <varname>.META.</varname> table content is rewritten removing the table schema from the <varname>info:regioninfo</varname> column. restart (You cannot do a rolling restart from 0.90.x to 0.92.x -- you must restart).
Also, any flushes done post first startup will write out data in the new 0.92.0 file format, <link xlink:href="http://hbase.apache.org/book.html#hfilev2">HFile V2</link>. On startup, the <varname>.META.</varname> table content is rewritten removing the
This means you cannot go back to 0.90.x once you’ve started HBase 0.92.0 over your HBase data directory. table schema from the <varname>info:regioninfo</varname> column. Also, any flushes
done post first startup will write out data in the new 0.92.0 file format, <link
xlink:href="http://hbase.apache.org/book.html#hfilev2">HFile V2</link>. This
means you cannot go back to 0.90.x once you’ve started HBase 0.92.0 over your HBase
data directory. </para>
</section>
<section>
<title>MSLAB is ON by default </title>
<para>In 0.92.0, the <link
xlink:href="http://hbase.apache.org/book.html#hbase.hregion.memstore.mslab.enabled">hbase.hregion.memstore.mslab.enabled</link>
flag is set to true (See <xref
linkend="mslab" />). In 0.90.x it was <constant>false</constant>. When it is
enabled, memstores will step allocate memory in MSLAB 2MB chunks even if the
memstore has zero or just a few small elements. This is fine usually but if you had
lots of regions per regionserver in a 0.90.x cluster (and MSLAB was off), you may
find yourself OOME'ing on upgrade because the <code>thousands of regions * number of
column families * 2MB MSLAB (at a minimum)</code> puts your heap over the top.
Set <varname>hbase.hregion.memstore.mslab.enabled</varname> to
<constant>false</constant> or set the MSLAB size down from 2MB by setting
<varname>hbase.hregion.memstore.mslab.chunksize</varname> to something less.
</para> </para>
</section> </section>
<section> <section>
<title>MSLAB is ON by default <title>Distributed splitting is on by default </title>
</title> <para>Previous, WAL logs on crash were split by the Master alone. In 0.92.0, log
<para>In 0.92.0, the <link xlink:href="http://hbase.apache.org/book.html#hbase.hregion.memstore.mslab.enabled">hbase.hregion.memstore.mslab.enabled</link> flag is set to true splitting is done by the cluster (See See “HBASE-1364 [performance] Distributed
(See <xref linkend="mslab" />). In 0.90.x it was <constant>false</constant>. When it is enabled, memstores will step allocate memory in MSLAB 2MB chunks even if the splitting of regionserver commit logs”). This should cut down significantly on the
memstore has zero or just a few small elements. This is fine usually but if you had lots of regions per regionserver in a 0.90.x cluster (and MSLAB was off), amount of time it takes splitting logs and getting regions back online again.
you may find yourself OOME'ing on upgrade because the <code>thousands of regions * number of column families * 2MB MSLAB (at a minimum)</code>
puts your heap over the top. Set <varname>hbase.hregion.memstore.mslab.enabled</varname> to
<constant>false</constant> or set the MSLAB size down from 2MB by setting <varname>hbase.hregion.memstore.mslab.chunksize</varname> to something less.
</para> </para>
</section> </section>
<section><title>Distributed splitting is on by default <section>
</title> <title>Memory accounting is different now </title>
<para>Previous, WAL logs on crash were split by the Master alone. In 0.92.0, log splitting is done by the cluster (See See “HBASE-1364 [performance] Distributed splitting of regionserver commit logs”). This should cut down significantly on the amount of time it takes splitting logs and getting regions back online again. <para>In 0.92.0, <xref
</para> linkend="hfilev2" /> indices and bloom filters take up residence in the same LRU
</section> used caching blocks that come from the filesystem. In 0.90.x, the HFile v1 indices
lived outside of the LRU so they took up space even if the index was on a ‘cold’
<section><title>Memory accounting is different now file, one that wasn’t being actively used. With the indices now in the LRU, you may
</title> find you have less space for block caching. Adjust your block cache accordingly. See
<para>In 0.92.0, <xref linkend="hfilev2" /> indices and bloom filters take up residence in the same LRU used caching blocks that come from the filesystem. the <xref
In 0.90.x, the HFile v1 indices lived outside of the LRU so they took up space even if the index was on a ‘cold’ file, one that wasn’t being actively used. With the indices now in the LRU, you may find you linkend="block.cache" /> for more detail. The block size default size has been
have less space for block caching. Adjust your block cache accordingly. See the <xref linkend="block.cache" /> for more detail. changed in 0.92.0 from 0.2 (20 percent of heap) to 0.25. </para>
The block size default size has been changed in 0.92.0 from 0.2 (20 percent of heap) to 0.25.
</para>
</section> </section>
<section><title>On the Hadoop version to use <section>
</title> <title>On the Hadoop version to use </title>
<para>Run 0.92.0 on Hadoop 1.0.x (or CDH3u3 when it ships). The performance benefits are worth making the move. Otherwise, our Hadoop prescription is as it has been; you need an Hadoop that supports a working sync. See <xref linkend="hadoop" />. <para>Run 0.92.0 on Hadoop 1.0.x (or CDH3u3 when it ships). The performance benefits are
</para> worth making the move. Otherwise, our Hadoop prescription is as it has been; you
need an Hadoop that supports a working sync. See <xref
linkend="hadoop" />. </para>
<para>If running on Hadoop 1.0.x (or CDH3u3), enable local read. See <link xlink:href="http://files.meetup.com/1350427/hug_ebay_jdcryans.pdf">Practical Caching</link> presentation for ruminations on the performance benefits ‘going local’ (and for how to enable local reads). <para>If running on Hadoop 1.0.x (or CDH3u3), enable local read. See <link
</para> xlink:href="http://files.meetup.com/1350427/hug_ebay_jdcryans.pdf">Practical
</section> Caching</link> presentation for ruminations on the performance benefits ‘going
<section><title>HBase 0.92.0 ships with ZooKeeper 3.4.2 local’ (and for how to enable local reads). </para>
</title>
<para>If you can, upgrade your zookeeper. If you can’t, 3.4.2 clients should work against 3.3.X ensembles (HBase makes use of 3.4.2 API).
</para>
</section> </section>
<section> <section>
<title>Online alter is off by default <title>HBase 0.92.0 ships with ZooKeeper 3.4.2 </title>
</title> <para>If you can, upgrade your zookeeper. If you can’t, 3.4.2 clients should work
<para>In 0.92.0, we’ve added an experimental online schema alter facility (See <xref linkend="hbase.online.schema.update.enable" />). Its off by default. Enable it at your own risk. Online alter and splitting tables do not play well together so be sure your cluster quiescent using this feature (for now). against 3.3.X ensembles (HBase makes use of 3.4.2 API). </para>
</para>
</section> </section>
<section> <section>
<title>WebUI <title>Online alter is off by default </title>
</title> <para>In 0.92.0, we’ve added an experimental online schema alter facility (See <xref
<para>The webui has had a few additions made in 0.92.0. It now shows a list of the regions currently transitioning, recent compactions/flushes, and a process list of running processes (usually empty if all is well and requests are being handled promptly). Other additions including requests by region, a debugging servlet dump, etc. linkend="hbase.online.schema.update.enable" />). Its off by default. Enable it
</para> at your own risk. Online alter and splitting tables do not play well together so be
sure your cluster quiescent using this feature (for now). </para>
</section> </section>
<section> <section>
<title>Security tarball <title>WebUI </title>
</title> <para>The webui has had a few additions made in 0.92.0. It now shows a list of the
<para>We now ship with two tarballs; secure and insecure HBase. Documentation on how to setup a secure HBase is on the way. regions currently transitioning, recent compactions/flushes, and a process list of
</para> running processes (usually empty if all is well and requests are being handled
promptly). Other additions including requests by region, a debugging servlet dump,
etc. </para>
</section>
<section>
<title>Security tarball </title>
<para>We now ship with two tarballs; secure and insecure HBase. Documentation on how to
setup a secure HBase is on the way. </para>
</section> </section>
<section xml:id="slabcache"><title>Experimental off-heap cache: SlabCache</title> <section
<para> xml:id="slabcache">
A new cache was contributed to 0.92.0 to act as a solution between using the “on-heap” cache which is the current LRU cache the region servers have and the operating system cache which is out of our control. <title>Experimental off-heap cache: SlabCache</title>
To enable <emphasis>SlabCache</emphasis>, as this feature is being called, set “-XX:MaxDirectMemorySize” in hbase-env.sh to the value for maximum direct memory size and specify <para> A new cache was contributed to 0.92.0 to act as a solution between using the
<property>hbase.offheapcache.percentage</property> in <filename>hbase-site.xml</filename> with the percentage that you want to dedicate to off-heap cache. This should only be set for servers and not for clients. Use at your own risk. “on-heap” cache which is the current LRU cache the region servers have and the
See this blog post, <link xlink:href="http://www.cloudera.com/blog/2012/01/caching-in-hbase-slabcache/">Caching in Apache HBase: SlabCache</link>, for additional information on this new experimental feature. operating system cache which is out of our control. To enable
</para> <emphasis>SlabCache</emphasis>, as this feature is being called, set
<para>This feature has mostly been eclipsed in later HBases. See <link xlink:href="https://issues.apache.org/jira/browse/HBASE-7404 ">HBASE-7404 Bucket Cache:A solution about CMS,Heap Fragment and Big Cache on HBASE</link>, etc.</para> “-XX:MaxDirectMemorySize” in hbase-env.sh to the value for maximum direct memory
size and specify <property>hbase.offheapcache.percentage</property> in
<filename>hbase-site.xml</filename> with the percentage that you want to
dedicate to off-heap cache. This should only be set for servers and not for clients.
Use at your own risk. See this blog post, <link
xlink:href="http://www.cloudera.com/blog/2012/01/caching-in-hbase-slabcache/">Caching
in Apache HBase: SlabCache</link>, for additional information on this new
experimental feature. </para>
<para>This feature has mostly been eclipsed in later HBases. See <link
xlink:href="https://issues.apache.org/jira/browse/HBASE-7404 ">HBASE-7404 Bucket
Cache:A solution about CMS,Heap Fragment and Big Cache on HBASE</link>,
etc.</para>
</section> </section>
<section><title>Changes in HBase replication <section>
</title> <title>Changes in HBase replication </title>
<para>0.92.0 adds two new features: multi-slave and multi-master replication. The way to enable this is the same as adding a new peer, so in order to have multi-master you would just run add_peer for each cluster that acts as a master to the other slave clusters. Collisions are handled at the timestamp level which may or may not be what you want, this needs to be evaluated on a per use case basis. Replication is still experimental in 0.92 and is disabled by default, run it at your own risk. <para>0.92.0 adds two new features: multi-slave and multi-master replication. The way to
</para> enable this is the same as adding a new peer, so in order to have multi-master you
would just run add_peer for each cluster that acts as a master to the other slave
clusters. Collisions are handled at the timestamp level which may or may not be what
you want, this needs to be evaluated on a per use case basis. Replication is still
experimental in 0.92 and is disabled by default, run it at your own risk. </para>
</section> </section>
<section><title>RegionServer now aborts if OOME <section>
</title> <title>RegionServer now aborts if OOME </title>
<para>If an OOME, we now have the JVM kill -9 the regionserver process so it goes down fast. Previous, a RegionServer might stick around after incurring an OOME limping along in some wounded state. To disable this facility, and recommend you leave it in place, you’d need to edit the bin/hbase file. Look for the addition of the -XX:OnOutOfMemoryError="kill -9 %p" arguments (See [HBASE-4769] - ‘Abort RegionServer Immediately on OOME’) <para>If an OOME, we now have the JVM kill -9 the regionserver process so it goes down
</para> fast. Previous, a RegionServer might stick around after incurring an OOME limping
along in some wounded state. To disable this facility, and recommend you leave it in
place, you’d need to edit the bin/hbase file. Look for the addition of the
-XX:OnOutOfMemoryError="kill -9 %p" arguments (See [HBASE-4769] - ‘Abort
RegionServer Immediately on OOME’) </para>
</section> </section>
<section><title>HFile V2 and the “Bigger, Fewer” Tendency <section>
</title> <title>HFile V2 and the “Bigger, Fewer” Tendency </title>
<para>0.92.0 stores data in a new format, <xref linkend="hfilev2" />. As HBase runs, it will move all your data from HFile v1 to HFile v2 format. This auto-migration will run in the background as flushes and compactions run. <para>0.92.0 stores data in a new format, <xref
HFile V2 allows HBase run with larger regions/files. In fact, we encourage that all HBasers going forward tend toward Facebook axiom #1, run with larger, fewer regions. linkend="hfilev2" />. As HBase runs, it will move all your data from HFile v1 to
If you have lots of regions now -- more than 100s per host -- you should look into setting your region size up after you move to 0.92.0 (In 0.92.0, default size is now 1G, up from 256M), and then running online merge tool (See “HBASE-1621 merge tool should work on online cluster, but disabled table”). HFile v2 format. This auto-migration will run in the background as flushes and
compactions run. HFile V2 allows HBase run with larger regions/files. In fact, we
encourage that all HBasers going forward tend toward Facebook axiom #1, run with
larger, fewer regions. If you have lots of regions now -- more than 100s per host --
you should look into setting your region size up after you move to 0.92.0 (In
0.92.0, default size is now 1G, up from 256M), and then running online merge tool
(See “HBASE-1621 merge tool should work on online cluster, but disabled table”).
</para> </para>
</section> </section>
</section> </section>
<section xml:id="upgrade0.90"> <section
xml:id="upgrade0.90">
<title>Upgrading to HBase 0.90.x from 0.20.x or 0.89.x</title> <title>Upgrading to HBase 0.90.x from 0.20.x or 0.89.x</title>
<para>This version of 0.90.x HBase can be started on data written by <para>This version of 0.90.x HBase can be started on data written by HBase 0.20.x or HBase
HBase 0.20.x or HBase 0.89.x. There is no need of a migration step. 0.89.x. There is no need of a migration step. HBase 0.89.x and 0.90.x does write out the
HBase 0.89.x and 0.90.x does write out the name of region directories name of region directories differently -- it names them with a md5 hash of the region
differently -- it names them with a md5 hash of the region name rather name rather than a jenkins hash -- so this means that once started, there is no going
than a jenkins hash -- so this means that once started, there is no back to HBase 0.20.x. </para>
going back to HBase 0.20.x. <para> Be sure to remove the <filename>hbase-default.xml</filename> from your
</para> <filename>conf</filename> directory on upgrade. A 0.20.x version of this file will
<para> have sub-optimal configurations for 0.90.x HBase. The
Be sure to remove the <filename>hbase-default.xml</filename> from <filename>hbase-default.xml</filename> file is now bundled into the HBase jar and
your <filename>conf</filename> read from there. If you would like to review the content of this file, see it in the src
directory on upgrade. A 0.20.x version of this file will have tree at <filename>src/main/resources/hbase-default.xml</filename> or see <xref
sub-optimal configurations for 0.90.x HBase. The linkend="hbase_default_configurations" />. </para>
<filename>hbase-default.xml</filename> file is now bundled into the <para> Finally, if upgrading from 0.20.x, check your <varname>.META.</varname> schema in the
HBase jar and read from there. If you would like to review shell. In the past we would recommend that users run with a 16kb
the content of this file, see it in the src tree at <varname>MEMSTORE_FLUSHSIZE</varname>. Run <code>hbase> scan '-ROOT-'</code> in the
<filename>src/main/resources/hbase-default.xml</filename> or shell. This will output the current <varname>.META.</varname> schema. Check
see <xref linkend="hbase_default_configurations" />. <varname>MEMSTORE_FLUSHSIZE</varname> size. Is it 16kb (16384)? If so, you will need
</para> to change this (The 'normal'/default value is 64MB (67108864)). Run the script
<para> <filename>bin/set_meta_memstore_size.rb</filename>. This will make the necessary
Finally, if upgrading from 0.20.x, check your edit to your <varname>.META.</varname> schema. Failure to run this change will make for
<varname>.META.</varname> schema in the shell. In the past we would a slow cluster <footnote>
recommend that users run with a 16kb <para> See <link
<varname>MEMSTORE_FLUSHSIZE</varname>. xlink:href="https://issues.apache.org/jira/browse/HBASE-3499">HBASE-3499
Run <code>hbase> scan '-ROOT-'</code> in the shell. This will output Users upgrading to 0.90.0 need to have their .META. table updated with the
the current <varname>.META.</varname> schema. Check right MEMSTORE_SIZE</link>
<varname>MEMSTORE_FLUSHSIZE</varname> size. Is it 16kb (16384)? If so, you will
need to change this (The 'normal'/default value is 64MB (67108864)).
Run the script <filename>bin/set_meta_memstore_size.rb</filename>.
This will make the necessary edit to your <varname>.META.</varname> schema.
Failure to run this change will make for a slow cluster <footnote>
<para>
See <link xlink:href="https://issues.apache.org/jira/browse/HBASE-3499">HBASE-3499 Users upgrading to 0.90.0 need to have their .META. table updated with the right MEMSTORE_SIZE</link>
</para>
</footnote>
.
</para> </para>
</footnote> . </para>
</section> </section>
</chapter> </chapter>

532
src/main/docbkx/zookeeper.xml
View File

@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<chapter xml:id="zookeeper" <chapter
version="5.0" xmlns="http://docbook.org/ns/docbook" xml:id="zookeeper"
version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"
@ -31,247 +33,197 @@
<primary>ZooKeeper</primary> <primary>ZooKeeper</primary>
</indexterm></title> </indexterm></title>
<para>A distributed Apache HBase installation depends on a running ZooKeeper cluster. <para>A distributed Apache HBase installation depends on a running ZooKeeper cluster. All
All participating nodes and clients need to be able to access the participating nodes and clients need to be able to access the running ZooKeeper ensemble. Apache
running ZooKeeper ensemble. Apache HBase by default manages a ZooKeeper HBase by default manages a ZooKeeper "cluster" for you. It will start and stop the ZooKeeper
"cluster" for you. It will start and stop the ZooKeeper ensemble ensemble as part of the HBase start/stop process. You can also manage the ZooKeeper ensemble
as part of the HBase start/stop process. You can also manage the independent of HBase and just point HBase at the cluster it should use. To toggle HBase
ZooKeeper ensemble independent of HBase and just point HBase at management of ZooKeeper, use the <varname>HBASE_MANAGES_ZK</varname> variable in
the cluster it should use. To toggle HBase management of <filename>conf/hbase-env.sh</filename>. This variable, which defaults to
ZooKeeper, use the <varname>HBASE_MANAGES_ZK</varname> variable in <varname>true</varname>, tells HBase whether to start/stop the ZooKeeper ensemble servers as
<filename>conf/hbase-env.sh</filename>. This variable, which part of HBase start/stop.</para>
defaults to <varname>true</varname>, tells HBase whether to
start/stop the ZooKeeper ensemble servers as part of HBase
start/stop.</para>
<para>When HBase manages the ZooKeeper ensemble, you can specify <para>When HBase manages the ZooKeeper ensemble, you can specify ZooKeeper configuration using its
ZooKeeper configuration using its native native <filename>zoo.cfg</filename> file, or, the easier option is to just specify ZooKeeper
<filename>zoo.cfg</filename> file, or, the easier option is to options directly in <filename>conf/hbase-site.xml</filename>. A ZooKeeper configuration option
just specify ZooKeeper options directly in can be set as a property in the HBase <filename>hbase-site.xml</filename> XML configuration file
<filename>conf/hbase-site.xml</filename>. A ZooKeeper by prefacing the ZooKeeper option name with <varname>hbase.zookeeper.property</varname>. For
configuration option can be set as a property in the HBase example, the <varname>clientPort</varname> setting in ZooKeeper can be changed by setting the
<filename>hbase-site.xml</filename> XML configuration file by <varname>hbase.zookeeper.property.clientPort</varname> property. For all default values used
prefacing the ZooKeeper option name with by HBase, including ZooKeeper configuration, see <xref
<varname>hbase.zookeeper.property</varname>. For example, the linkend="hbase_default_configurations" />. Look for the
<varname>clientPort</varname> setting in ZooKeeper can be changed
by setting the
<varname>hbase.zookeeper.property.clientPort</varname> property.
For all default values used by HBase, including ZooKeeper
configuration, see <xref linkend="hbase_default_configurations" />. Look for the
<varname>hbase.zookeeper.property</varname> prefix <footnote> <varname>hbase.zookeeper.property</varname> prefix <footnote>
<para>For the full list of ZooKeeper configurations, see <para>For the full list of ZooKeeper configurations, see ZooKeeper's
ZooKeeper's <filename>zoo.cfg</filename>. HBase does not ship <filename>zoo.cfg</filename>. HBase does not ship with a <filename>zoo.cfg</filename> so
with a <filename>zoo.cfg</filename> so you will need to browse you will need to browse the <filename>conf</filename> directory in an appropriate ZooKeeper
the <filename>conf</filename> directory in an appropriate download.</para>
ZooKeeper download.</para>
</footnote></para> </footnote></para>
<para>You must at least list the ensemble servers in <para>You must at least list the ensemble servers in <filename>hbase-site.xml</filename> using the
<filename>hbase-site.xml</filename> using the <varname>hbase.zookeeper.quorum</varname> property. This property defaults to a single
<varname>hbase.zookeeper.quorum</varname> property. This property ensemble member at <varname>localhost</varname> which is not suitable for a fully distributed
defaults to a single ensemble member at HBase. (It binds to the local machine only and remote clients will not be able to connect). </para>
<varname>localhost</varname> which is not suitable for a fully <note
distributed HBase. (It binds to the local machine only and remote xml:id="how_many_zks">
clients will not be able to connect). <note xml:id="how_many_zks">
<title>How many ZooKeepers should I run?</title> <title>How many ZooKeepers should I run?</title>
<para>You can run a ZooKeeper ensemble that comprises 1 node <para>You can run a ZooKeeper ensemble that comprises 1 node only but in production it is
only but in production it is recommended that you run a recommended that you run a ZooKeeper ensemble of 3, 5 or 7 machines; the more members an
ZooKeeper ensemble of 3, 5 or 7 machines; the more members an ensemble has, the more tolerant the ensemble is of host failures. Also, run an odd number of
ensemble has, the more tolerant the ensemble is of host machines. In ZooKeeper, an even number of peers is supported, but it is normally not used
failures. Also, run an odd number of machines. In ZooKeeper, because an even sized ensemble requires, proportionally, more peers to form a quorum than an
an even number of peers is supported, but it is normally not used odd sized ensemble requires. For example, an ensemble with 4 peers requires 3 to form a
because an even sized ensemble requires, proportionally, more peers quorum, while an ensemble with 5 also requires 3 to form a quorum. Thus, an ensemble of 5
to form a quorum than an odd sized ensemble requires. For example, an allows 2 peers to fail, and thus is more fault tolerant than the ensemble of 4, which allows
ensemble with 4 peers requires 3 to form a quorum, while an ensemble with only 1 down peer. </para>
5 also requires 3 to form a quorum. Thus, an ensemble of 5 allows 2 peers to <para>Give each ZooKeeper server around 1GB of RAM, and if possible, its own dedicated disk (A
fail, and thus is more fault tolerant than the ensemble of 4, which allows dedicated disk is the best thing you can do to ensure a performant ZooKeeper ensemble). For
only 1 down peer. very heavily loaded clusters, run ZooKeeper servers on separate machines from RegionServers
</para> (DataNodes and TaskTrackers).</para>
<para>Give each ZooKeeper server around 1GB of RAM, and if possible, its own </note>
dedicated disk (A dedicated disk is the best thing you can do
to ensure a performant ZooKeeper ensemble). For very heavily
loaded clusters, run ZooKeeper servers on separate machines
from RegionServers (DataNodes and TaskTrackers).</para>
</note></para>
<para>For example, to have HBase manage a ZooKeeper quorum on <para>For example, to have HBase manage a ZooKeeper quorum on nodes
nodes <emphasis>rs{1,2,3,4,5}.example.com</emphasis>, bound to <emphasis>rs{1,2,3,4,5}.example.com</emphasis>, bound to port 2222 (the default is 2181)
port 2222 (the default is 2181) ensure ensure <varname>HBASE_MANAGE_ZK</varname> is commented out or set to <varname>true</varname> in
<varname>HBASE_MANAGE_ZK</varname> is commented out or set to <filename>conf/hbase-env.sh</filename> and then edit <filename>conf/hbase-site.xml</filename>
<varname>true</varname> in <filename>conf/hbase-env.sh</filename> and set <varname>hbase.zookeeper.property.clientPort</varname> and
and then edit <filename>conf/hbase-site.xml</filename> and set
<varname>hbase.zookeeper.property.clientPort</varname> and
<varname>hbase.zookeeper.quorum</varname>. You should also set <varname>hbase.zookeeper.quorum</varname>. You should also set
<varname>hbase.zookeeper.property.dataDir</varname> to other than <varname>hbase.zookeeper.property.dataDir</varname> to other than the default as the default
the default as the default has ZooKeeper persist data under has ZooKeeper persist data under <filename>/tmp</filename> which is often cleared on system
<filename>/tmp</filename> which is often cleared on system
restart. In the example below we have ZooKeeper persist to restart. In the example below we have ZooKeeper persist to
<filename>/user/local/zookeeper</filename>. <programlisting> <filename>/user/local/zookeeper</filename>.</para>
&lt;configuration&gt; <programlisting><![CDATA[
<configuration>
... ...
&lt;property&gt; <property>
&lt;name&gt;hbase.zookeeper.property.clientPort&lt;/name&gt; <name>hbase.zookeeper.property.clientPort</name>
&lt;value&gt;2222&lt;/value&gt; <value>2222</value>
&lt;description&gt;Property from ZooKeeper's config zoo.cfg. <description>Property from ZooKeeper's config zoo.cfg.
The port at which the clients will connect. The port at which the clients will connect.
&lt;/description&gt; </description>
&lt;/property&gt; </property>
&lt;property&gt; <property>
&lt;name&gt;hbase.zookeeper.quorum&lt;/name&gt; <name>hbase.zookeeper.quorum</name>
&lt;value&gt;rs1.example.com,rs2.example.com,rs3.example.com,rs4.example.com,rs5.example.com&lt;/value&gt; <value>rs1.example.com,rs2.example.com,rs3.example.com,rs4.example.com,rs5.example.com</value>
&lt;description&gt;Comma separated list of servers in the ZooKeeper Quorum. <description>Comma separated list of servers in the ZooKeeper Quorum.
For example, "host1.mydomain.com,host2.mydomain.com,host3.mydomain.com". For example, "host1.mydomain.com,host2.mydomain.com,host3.mydomain.com".
By default this is set to localhost for local and pseudo-distributed modes By default this is set to localhost for local and pseudo-distributed modes
of operation. For a fully-distributed setup, this should be set to a full of operation. For a fully-distributed setup, this should be set to a full
list of ZooKeeper quorum servers. If HBASE_MANAGES_ZK is set in hbase-env.sh list of ZooKeeper quorum servers. If HBASE_MANAGES_ZK is set in hbase-env.sh
this is the list of servers which we will start/stop ZooKeeper on. this is the list of servers which we will start/stop ZooKeeper on.
&lt;/description&gt; </description>
&lt;/property&gt; </property>
&lt;property&gt; <property>
&lt;name&gt;hbase.zookeeper.property.dataDir&lt;/name&gt; <name>hbase.zookeeper.property.dataDir</name>
&lt;value&gt;/usr/local/zookeeper&lt;/value&gt; <value>/usr/local/zookeeper</value>
&lt;description&gt;Property from ZooKeeper's config zoo.cfg. <description>Property from ZooKeeper's config zoo.cfg.
The directory where the snapshot is stored. The directory where the snapshot is stored.
&lt;/description&gt; </description>
&lt;/property&gt; </property>
... ...
&lt;/configuration&gt;</programlisting></para> </configuration>]]></programlisting>
<caution xml:id="zk.version"> <caution
xml:id="zk.version">
<title>What verion of ZooKeeper should I use?</title> <title>What verion of ZooKeeper should I use?</title>
<para>The newer version, the better. For example, some folks have been bitten by <para>The newer version, the better. For example, some folks have been bitten by <link
<link xlink:href="https://issues.apache.org/jira/browse/ZOOKEEPER-1277">ZOOKEEPER-1277</link>. xlink:href="https://issues.apache.org/jira/browse/ZOOKEEPER-1277">ZOOKEEPER-1277</link>. If
If running zookeeper 3.5+, you can ask hbase to make use of the new multi operation by running zookeeper 3.5+, you can ask hbase to make use of the new multi operation by enabling <xref
enabling <xref linkend="hbase.zookeeper.useMulti"/>" in your <filename>hbase-site.xml</filename>. linkend="hbase.zookeeper.useMulti" />" in your <filename>hbase-site.xml</filename>. </para>
</para>
</caution> </caution>
<caution> <caution>
<title>ZooKeeper Maintenance</title> <title>ZooKeeper Maintenance</title>
<para>Be sure to set up the data dir cleaner described under <para>Be sure to set up the data dir cleaner described under <link
<link xlink:href="http://zookeeper.apache.org/doc/r3.1.2/zookeeperAdmin.html#sc_maintenance">Zookeeper Maintenance</link> else you could xlink:href="http://zookeeper.apache.org/doc/r3.1.2/zookeeperAdmin.html#sc_maintenance">Zookeeper
have 'interesting' problems a couple of months in; i.e. zookeeper could start Maintenance</link> else you could have 'interesting' problems a couple of months in; i.e.
dropping sessions if it has to run through a directory of hundreds of thousands of zookeeper could start dropping sessions if it has to run through a directory of hundreds of
logs which is wont to do around leader reelection time -- a process rare but run on thousands of logs which is wont to do around leader reelection time -- a process rare but run
occasion whether because a machine is dropped or happens to hiccup.</para> on occasion whether because a machine is dropped or happens to hiccup.</para>
</caution> </caution>
<section> <section>
<title>Using existing ZooKeeper ensemble</title> <title>Using existing ZooKeeper ensemble</title>
<para>To point HBase at an existing ZooKeeper cluster, one that <para>To point HBase at an existing ZooKeeper cluster, one that is not managed by HBase, set
is not managed by HBase, set <varname>HBASE_MANAGES_ZK</varname> <varname>HBASE_MANAGES_ZK</varname> in <filename>conf/hbase-env.sh</filename> to
in <filename>conf/hbase-env.sh</filename> to false false</para>
<programlisting> <screen>
... ...
# Tell HBase whether it should manage its own instance of Zookeeper or not. # Tell HBase whether it should manage its own instance of Zookeeper or not.
export HBASE_MANAGES_ZK=false</programlisting> Next set ensemble locations export HBASE_MANAGES_ZK=false</screen>
and client port, if non-standard, in <para>Next set ensemble locations and client port, if non-standard, in
<filename>hbase-site.xml</filename>, or add a suitably <filename>hbase-site.xml</filename>, or add a suitably configured
configured <filename>zoo.cfg</filename> to HBase's <filename>zoo.cfg</filename> to HBase's <filename>CLASSPATH</filename>. HBase will prefer
<filename>CLASSPATH</filename>. HBase will prefer the the configuration found in <filename>zoo.cfg</filename> over any settings in
configuration found in <filename>zoo.cfg</filename> over any <filename>hbase-site.xml</filename>.</para>
settings in <filename>hbase-site.xml</filename>.</para>
<para>When HBase manages ZooKeeper, it will start/stop the <para>When HBase manages ZooKeeper, it will start/stop the ZooKeeper servers as a part of the
ZooKeeper servers as a part of the regular start/stop scripts. regular start/stop scripts. If you would like to run ZooKeeper yourself, independent of HBase
If you would like to run ZooKeeper yourself, independent of start/stop, you would do the following</para>
HBase start/stop, you would do the following</para>
<programlisting> <screen>
${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
</programlisting> </screen>
<para>Note that you can use HBase in this manner to spin up a <para>Note that you can use HBase in this manner to spin up a ZooKeeper cluster, unrelated to
ZooKeeper cluster, unrelated to HBase. Just make sure to set HBase. Just make sure to set <varname>HBASE_MANAGES_ZK</varname> to <varname>false</varname>
<varname>HBASE_MANAGES_ZK</varname> to <varname>false</varname> if you want it to stay up across HBase restarts so that when HBase shuts down, it doesn't take
if you want it to stay up across HBase restarts so that when ZooKeeper down with it.</para>
HBase shuts down, it doesn't take ZooKeeper down with it.</para>
<para>For more information about running a distinct ZooKeeper <para>For more information about running a distinct ZooKeeper cluster, see the ZooKeeper <link
cluster, see the ZooKeeper <link
xlink:href="http://hadoop.apache.org/zookeeper/docs/current/zookeeperStarted.html">Getting xlink:href="http://hadoop.apache.org/zookeeper/docs/current/zookeeperStarted.html">Getting
Started Guide</link>. Additionally, see the <link xlink:href="http://wiki.apache.org/hadoop/ZooKeeper/FAQ#A7">ZooKeeper Wiki</link> or the Started Guide</link>. Additionally, see the <link
<link xlink:href="http://zookeeper.apache.org/doc/r3.3.3/zookeeperAdmin.html#sc_zkMulitServerSetup">ZooKeeper documentation</link> xlink:href="http://wiki.apache.org/hadoop/ZooKeeper/FAQ#A7">ZooKeeper Wiki</link> or the <link
for more information on ZooKeeper sizing. xlink:href="http://zookeeper.apache.org/doc/r3.3.3/zookeeperAdmin.html#sc_zkMulitServerSetup">ZooKeeper
</para> documentation</link> for more information on ZooKeeper sizing. </para>
</section> </section>
<section xml:id="zk.sasl.auth"> <section
xml:id="zk.sasl.auth">
<title>SASL Authentication with ZooKeeper</title> <title>SASL Authentication with ZooKeeper</title>
<para>Newer releases of Apache HBase (&gt;= 0.92) will <para>Newer releases of Apache HBase (&gt;= 0.92) will support connecting to a ZooKeeper Quorum
support connecting to a ZooKeeper Quorum that supports that supports SASL authentication (which is available in Zookeeper versions 3.4.0 or
SASL authentication (which is available in Zookeeper later).</para>
versions 3.4.0 or later).</para>
<para>This describes how to set up HBase to mutually <para>This describes how to set up HBase to mutually authenticate with a ZooKeeper Quorum.
authenticate with a ZooKeeper Quorum. ZooKeeper/HBase ZooKeeper/HBase mutual authentication (<link
mutual authentication (<link xlink:href="https://issues.apache.org/jira/browse/HBASE-2418">HBASE-2418</link>) is required
xlink:href="https://issues.apache.org/jira/browse/HBASE-2418">HBASE-2418</link>) as part of a complete secure HBase configuration (<link
is required as part of a complete secure HBase configuration xlink:href="https://issues.apache.org/jira/browse/HBASE-3025">HBASE-3025</link>). For
(<link simplicity of explication, this section ignores additional configuration required (Secure HDFS
xlink:href="https://issues.apache.org/jira/browse/HBASE-3025">HBASE-3025</link>). and Coprocessor configuration). It's recommended to begin with an HBase-managed Zookeeper
configuration (as opposed to a standalone Zookeeper quorum) for ease of learning. </para>
For simplicity of explication, this section ignores <section>
additional configuration required (Secure HDFS and Coprocessor <title>Operating System Prerequisites</title>
configuration). It's recommended to begin with an
HBase-managed Zookeeper configuration (as opposed to a
standalone Zookeeper quorum) for ease of learning.
</para>
<section><title>Operating System Prerequisites</title> <para> You need to have a working Kerberos KDC setup. For each <code>$HOST</code> that will
run a ZooKeeper server, you should have a principle <code>zookeeper/$HOST</code>. For each
such host, add a service key (using the <code>kadmin</code> or <code>kadmin.local</code>
tool's <code>ktadd</code> command) for <code>zookeeper/$HOST</code> and copy this file to
<code>$HOST</code>, and make it readable only to the user that will run zookeeper on
<code>$HOST</code>. Note the location of this file, which we will use below as
<filename>$PATH_TO_ZOOKEEPER_KEYTAB</filename>. </para>
<para> <para> Similarly, for each <code>$HOST</code> that will run an HBase server (master or
You need to have a working Kerberos KDC setup. For regionserver), you should have a principle: <code>hbase/$HOST</code>. For each host, add a
each <code>$HOST</code> that will run a ZooKeeper keytab file called <filename>hbase.keytab</filename> containing a service key for
server, you should have a principle <code>hbase/$HOST</code>, copy this file to <code>$HOST</code>, and make it readable only
<code>zookeeper/$HOST</code>. For each such host, to the user that will run an HBase service on <code>$HOST</code>. Note the location of this
add a service key (using the <code>kadmin</code> or file, which we will use below as <filename>$PATH_TO_HBASE_KEYTAB</filename>. </para>
<code>kadmin.local</code> tool's <code>ktadd</code>
command) for <code>zookeeper/$HOST</code> and copy
this file to <code>$HOST</code>, and make it
readable only to the user that will run zookeeper on
<code>$HOST</code>. Note the location of this file,
which we will use below as
<filename>$PATH_TO_ZOOKEEPER_KEYTAB</filename>.
</para>
<para> <para> Each user who will be an HBase client should also be given a Kerberos principal. This
Similarly, for each <code>$HOST</code> that will run principal should usually have a password assigned to it (as opposed to, as with the HBase
an HBase server (master or regionserver), you should servers, a keytab file) which only this user knows. The client's principal's
have a principle: <code>hbase/$HOST</code>. For each <code>maxrenewlife</code> should be set so that it can be renewed enough so that the user
host, add a keytab file called can complete their HBase client processes. For example, if a user runs a long-running HBase
<filename>hbase.keytab</filename> containing a service client process that takes at most 3 days, we might create this user's principal within
key for <code>hbase/$HOST</code>, copy this file to <code>kadmin</code> with: <code>addprinc -maxrenewlife 3days</code>. The Zookeeper client
<code>$HOST</code>, and make it readable only to the and server libraries manage their own ticket refreshment by running threads that wake up
user that will run an HBase service on periodically to do the refreshment. </para>
<code>$HOST</code>. Note the location of this file,
which we will use below as
<filename>$PATH_TO_HBASE_KEYTAB</filename>.
</para>
<para> <para>On each host that will run an HBase client (e.g. <code>hbase shell</code>), add the
Each user who will be an HBase client should also be following file to the HBase home directory's <filename>conf</filename> directory:</para>
given a Kerberos principal. This principal should
usually have a password assigned to it (as opposed to,
as with the HBase servers, a keytab file) which only
this user knows. The client's principal's
<code>maxrenewlife</code> should be set so that it can
be renewed enough so that the user can complete their
HBase client processes. For example, if a user runs a
long-running HBase client process that takes at most 3
days, we might create this user's principal within
<code>kadmin</code> with: <code>addprinc -maxrenewlife
3days</code>. The Zookeeper client and server
libraries manage their own ticket refreshment by
running threads that wake up periodically to do the
refreshment.
</para>
<para>On each host that will run an HBase client
(e.g. <code>hbase shell</code>), add the following
file to the HBase home directory's <filename>conf</filename>
directory:</para>
<programlisting> <programlisting>
Client { Client {
@ -281,18 +233,16 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
}; };
</programlisting> </programlisting>
<para>We'll refer to this JAAS configuration file as <para>We'll refer to this JAAS configuration file as <filename>$CLIENT_CONF</filename>
<filename>$CLIENT_CONF</filename> below.</para> below.</para>
</section> </section>
<section> <section>
<title>HBase-managed Zookeeper Configuration</title> <title>HBase-managed Zookeeper Configuration</title>
<para>On each node that will run a zookeeper, a <para>On each node that will run a zookeeper, a master, or a regionserver, create a <link
master, or a regionserver, create a <link
xlink:href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/LoginConfigFile.html">JAAS</link> xlink:href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jgss/tutorials/LoginConfigFile.html">JAAS</link>
configuration file in the conf directory of the node's configuration file in the conf directory of the node's <filename>HBASE_HOME</filename>
<filename>HBASE_HOME</filename> directory that looks like the directory that looks like the following:</para>
following:</para>
<programlisting> <programlisting>
Server { Server {
@ -313,26 +263,18 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
</programlisting> </programlisting>
<para>where the <filename>$PATH_TO_HBASE_KEYTAB</filename> and <para>where the <filename>$PATH_TO_HBASE_KEYTAB</filename> and
<filename>$PATH_TO_ZOOKEEPER_KEYTAB</filename> files are what <filename>$PATH_TO_ZOOKEEPER_KEYTAB</filename> files are what you created above, and
you created above, and <code>$HOST</code> is the hostname for that <code>$HOST</code> is the hostname for that node.</para>
node.</para>
<para>The <code>Server</code> section will be used by <para>The <code>Server</code> section will be used by the Zookeeper quorum server, while the
the Zookeeper quorum server, while the <code>Client</code> section will be used by the HBase master and regionservers. The path
<code>Client</code> section will be used by the HBase to this file should be substituted for the text <filename>$HBASE_SERVER_CONF</filename> in
master and regionservers. The path to this file should the <filename>hbase-env.sh</filename> listing below.</para>
be substituted for the text <filename>$HBASE_SERVER_CONF</filename>
in the <filename>hbase-env.sh</filename>
listing below.</para>
<para> <para> The path to this file should be substituted for the text
The path to this file should be substituted for the <filename>$CLIENT_CONF</filename> in the <filename>hbase-env.sh</filename> listing below. </para>
text <filename>$CLIENT_CONF</filename> in the
<filename>hbase-env.sh</filename> listing below.
</para>
<para>Modify your <filename>hbase-env.sh</filename> to include the <para>Modify your <filename>hbase-env.sh</filename> to include the following:</para>
following:</para>
<programlisting> <programlisting>
export HBASE_OPTS="-Djava.security.auth.login.config=$CLIENT_CONF" export HBASE_OPTS="-Djava.security.auth.login.config=$CLIENT_CONF"
@ -342,12 +284,11 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
export HBASE_REGIONSERVER_OPTS="-Djava.security.auth.login.config=$HBASE_SERVER_CONF" export HBASE_REGIONSERVER_OPTS="-Djava.security.auth.login.config=$HBASE_SERVER_CONF"
</programlisting> </programlisting>
<para>where <filename>$HBASE_SERVER_CONF</filename> and <para>where <filename>$HBASE_SERVER_CONF</filename> and <filename>$CLIENT_CONF</filename> are
<filename>$CLIENT_CONF</filename> are the full paths to the the full paths to the JAAS configuration files created above.</para>
JAAS configuration files created above.</para>
<para>Modify your <filename>hbase-site.xml</filename> on each node <para>Modify your <filename>hbase-site.xml</filename> on each node that will run zookeeper,
that will run zookeeper, master or regionserver to contain:</para> master or regionserver to contain:</para>
<programlisting><![CDATA[ <programlisting><![CDATA[
<configuration> <configuration>
@ -374,26 +315,23 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
</configuration> </configuration>
]]></programlisting> ]]></programlisting>
<para>where <code>$ZK_NODES</code> is the <para>where <code>$ZK_NODES</code> is the comma-separated list of hostnames of the Zookeeper
comma-separated list of hostnames of the Zookeeper
Quorum hosts.</para> Quorum hosts.</para>
<para>Start your hbase cluster by running one or more <para>Start your hbase cluster by running one or more of the following set of commands on the
of the following set of commands on the appropriate appropriate hosts: </para>
hosts:
</para>
<programlisting> <screen>
bin/hbase zookeeper start bin/hbase zookeeper start
bin/hbase master start bin/hbase master start
bin/hbase regionserver start bin/hbase regionserver start
</programlisting> </screen>
</section> </section>
<section><title>External Zookeeper Configuration</title> <section>
<para>Add a JAAS configuration file that looks like: <title>External Zookeeper Configuration</title>
<para>Add a JAAS configuration file that looks like:</para>
<programlisting> <programlisting>
Client { Client {
com.sun.security.auth.module.Krb5LoginModule required com.sun.security.auth.module.Krb5LoginModule required
@ -403,12 +341,10 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
principal="hbase/$HOST"; principal="hbase/$HOST";
}; };
</programlisting> </programlisting>
<para>where the <filename>$PATH_TO_HBASE_KEYTAB</filename> is the keytab created above for
where the <filename>$PATH_TO_HBASE_KEYTAB</filename> is the keytab HBase services to run on this host, and <code>$HOST</code> is the hostname for that node.
created above for HBase services to run on this host, and <code>$HOST</code> is the Put this in the HBase home's configuration directory. We'll refer to this file's full
hostname for that node. Put this in the HBase home's pathname as <filename>$HBASE_SERVER_CONF</filename> below.</para>
configuration directory. We'll refer to this file's
full pathname as <filename>$HBASE_SERVER_CONF</filename> below.</para>
<para>Modify your hbase-env.sh to include the following:</para> <para>Modify your hbase-env.sh to include the following:</para>
@ -420,8 +356,8 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
</programlisting> </programlisting>
<para>Modify your <filename>hbase-site.xml</filename> on each node <para>Modify your <filename>hbase-site.xml</filename> on each node that will run a master or
that will run a master or regionserver to contain:</para> regionserver to contain:</para>
<programlisting><![CDATA[ <programlisting><![CDATA[
<configuration> <configuration>
@ -437,20 +373,16 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
]]> ]]>
</programlisting> </programlisting>
<para>where <code>$ZK_NODES</code> is the <para>where <code>$ZK_NODES</code> is the comma-separated list of hostnames of the Zookeeper
comma-separated list of hostnames of the Zookeeper
Quorum hosts.</para> Quorum hosts.</para>
<para> <para> Add a <filename>zoo.cfg</filename> for each Zookeeper Quorum host containing:</para>
Add a <filename>zoo.cfg</filename> for each Zookeeper Quorum host containing:
<programlisting> <programlisting>
authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
kerberos.removeHostFromPrincipal=true kerberos.removeHostFromPrincipal=true
kerberos.removeRealmFromPrincipal=true kerberos.removeRealmFromPrincipal=true
</programlisting> </programlisting>
<para>Also on each of these hosts, create a JAAS configuration file containing:</para>
Also on each of these hosts, create a JAAS configuration file containing:
<programlisting> <programlisting>
Server { Server {
com.sun.security.auth.module.Krb5LoginModule required com.sun.security.auth.module.Krb5LoginModule required
@ -461,40 +393,30 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
principal="zookeeper/$HOST"; principal="zookeeper/$HOST";
}; };
</programlisting> </programlisting>
<para>where <code>$HOST</code> is the hostname of each Quorum host. We will refer to the full
pathname of this file as <filename>$ZK_SERVER_CONF</filename> below. </para>
where <code>$HOST</code> is the hostname of each <para> Start your Zookeepers on each Zookeeper Quorum host with:</para>
Quorum host. We will refer to the full pathname of
this file as <filename>$ZK_SERVER_CONF</filename> below.
</para>
<para>
Start your Zookeepers on each Zookeeper Quorum host with:
<programlisting> <programlisting>
SERVER_JVMFLAGS="-Djava.security.auth.login.config=$ZK_SERVER_CONF" bin/zkServer start SERVER_JVMFLAGS="-Djava.security.auth.login.config=$ZK_SERVER_CONF" bin/zkServer start
</programlisting> </programlisting>
</para> <para> Start your HBase cluster by running one or more of the following set of commands on the
appropriate nodes: </para>
<para> <screen>
Start your HBase cluster by running one or more of the following set of commands on the appropriate nodes:
</para>
<programlisting>
bin/hbase master start bin/hbase master start
bin/hbase regionserver start bin/hbase regionserver start
</programlisting> </screen>
</section> </section>
<section> <section>
<title>Zookeeper Server Authentication Log Output</title> <title>Zookeeper Server Authentication Log Output</title>
<para>If the configuration above is successful, <para>If the configuration above is successful, you should see something similar to the
you should see something similar to the following in following in your Zookeeper server logs:</para>
your Zookeeper server logs: <screen>
<programlisting>
11/12/05 22:43:39 INFO zookeeper.Login: successfully logged in. 11/12/05 22:43:39 INFO zookeeper.Login: successfully logged in.
11/12/05 22:43:39 INFO server.NIOServerCnxnFactory: binding to port 0.0.0.0/0.0.0.0:2181 11/12/05 22:43:39 INFO server.NIOServerCnxnFactory: binding to port 0.0.0.0/0.0.0.0:2181
11/12/05 22:43:39 INFO zookeeper.Login: TGT refresh thread started. 11/12/05 22:43:39 INFO zookeeper.Login: TGT refresh thread started.
@ -507,18 +429,15 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
authorizationID=hbase/ip-10-166-175-249.us-west-1.compute.internal@HADOOP.LOCALDOMAIN. authorizationID=hbase/ip-10-166-175-249.us-west-1.compute.internal@HADOOP.LOCALDOMAIN.
11/12/05 22:43:59 INFO auth.SaslServerCallbackHandler: Setting authorizedID: hbase 11/12/05 22:43:59 INFO auth.SaslServerCallbackHandler: Setting authorizedID: hbase
11/12/05 22:43:59 INFO server.ZooKeeperServer: adding SASL authorization for authorizationID: hbase 11/12/05 22:43:59 INFO server.ZooKeeperServer: adding SASL authorization for authorizationID: hbase
</programlisting> </screen>
</para>
</section> </section>
<section> <section>
<title>Zookeeper Client Authentication Log Output</title> <title>Zookeeper Client Authentication Log Output</title>
<para>On the Zookeeper client side (HBase master or regionserver), <para>On the Zookeeper client side (HBase master or regionserver), you should see something
you should see something similar to the following: similar to the following:</para>
<screen>
<programlisting>
11/12/05 22:43:59 INFO zookeeper.ZooKeeper: Initiating client connection, connectString=ip-10-166-175-249.us-west-1.compute.internal:2181 sessionTimeout=180000 watcher=master:60000 11/12/05 22:43:59 INFO zookeeper.ZooKeeper: Initiating client connection, connectString=ip-10-166-175-249.us-west-1.compute.internal:2181 sessionTimeout=180000 watcher=master:60000
11/12/05 22:43:59 INFO zookeeper.ClientCnxn: Opening socket connection to server /10.166.175.249:2181 11/12/05 22:43:59 INFO zookeeper.ClientCnxn: Opening socket connection to server /10.166.175.249:2181
11/12/05 22:43:59 INFO zookeeper.RecoverableZooKeeper: The identifier of this process is 14851@ip-10-166-175-249 11/12/05 22:43:59 INFO zookeeper.RecoverableZooKeeper: The identifier of this process is 14851@ip-10-166-175-249
@ -530,66 +449,56 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
11/12/05 22:43:59 INFO zookeeper.Login: TGT expires: Tue Dec 06 22:43:59 UTC 2011 11/12/05 22:43:59 INFO zookeeper.Login: TGT expires: Tue Dec 06 22:43:59 UTC 2011
11/12/05 22:43:59 INFO zookeeper.Login: TGT refresh sleeping until: Tue Dec 06 18:30:37 UTC 2011 11/12/05 22:43:59 INFO zookeeper.Login: TGT refresh sleeping until: Tue Dec 06 18:30:37 UTC 2011
11/12/05 22:43:59 INFO zookeeper.ClientCnxn: Session establishment complete on server ip-10-166-175-249.us-west-1.compute.internal/10.166.175.249:2181, sessionid = 0x134106594320000, negotiated timeout = 180000 11/12/05 22:43:59 INFO zookeeper.ClientCnxn: Session establishment complete on server ip-10-166-175-249.us-west-1.compute.internal/10.166.175.249:2181, sessionid = 0x134106594320000, negotiated timeout = 180000
</programlisting> </screen>
</para>
</section> </section>
<section> <section>
<title>Configuration from Scratch</title> <title>Configuration from Scratch</title>
<para>This has been tested on the current standard Amazon <para>This has been tested on the current standard Amazon Linux AMI. First setup KDC and
Linux AMI. First setup KDC and principals as principals as described above. Next checkout code and run a sanity check.</para>
described above. Next checkout code and run a sanity
check.</para>
<programlisting> <screen>
git clone git://git.apache.org/hbase.git git clone git://git.apache.org/hbase.git
cd hbase cd hbase
mvn clean test -Dtest=TestZooKeeperACL mvn clean test -Dtest=TestZooKeeperACL
</programlisting> </screen>
<para>Then configure HBase as described above. <para>Then configure HBase as described above. Manually edit target/cached_classpath.txt (see
Manually edit target/cached_classpath.txt (see below): below): </para>
</para> <screen>
<programlisting>
bin/hbase zookeeper &amp; bin/hbase zookeeper &amp;
bin/hbase master &amp; bin/hbase master &amp;
bin/hbase regionserver &amp; bin/hbase regionserver &amp;
</programlisting> </screen>
</section> </section>
<section> <section>
<title>Future improvements</title> <title>Future improvements</title>
<section><title>Fix target/cached_classpath.txt</title> <section>
<para> <title>Fix target/cached_classpath.txt</title>
You must override the standard hadoop-core jar file from the <para> You must override the standard hadoop-core jar file from the
<code>target/cached_classpath.txt</code> <code>target/cached_classpath.txt</code> file with the version containing the
file with the version containing the HADOOP-7070 fix. You can use the following script to do this: HADOOP-7070 fix. You can use the following script to do this:</para>
<screen>
<programlisting>
echo `find ~/.m2 -name "*hadoop-core*7070*SNAPSHOT.jar"` ':' `cat target/cached_classpath.txt` | sed 's/ //g' > target/tmp.txt echo `find ~/.m2 -name "*hadoop-core*7070*SNAPSHOT.jar"` ':' `cat target/cached_classpath.txt` | sed 's/ //g' > target/tmp.txt
mv target/tmp.txt target/cached_classpath.txt mv target/tmp.txt target/cached_classpath.txt
</programlisting> </screen>
</para>
</section> </section>
<section> <section>
<title>Set JAAS configuration <title>Set JAAS configuration programmatically</title>
programmatically</title>
<para>This would avoid the need for a separate Hadoop jar <para>This would avoid the need for a separate Hadoop jar that fixes <link
that fixes <link xlink:href="https://issues.apache.org/jira/browse/HADOOP-7070">HADOOP-7070</link>. xlink:href="https://issues.apache.org/jira/browse/HADOOP-7070">HADOOP-7070</link>.
</para> </para>
</section> </section>
<section> <section>
<title>Elimination of <title>Elimination of <code>kerberos.removeHostFromPrincipal</code> and
<code>kerberos.removeHostFromPrincipal</code> and
<code>kerberos.removeRealmFromPrincipal</code></title> <code>kerberos.removeRealmFromPrincipal</code></title>
<para /> <para />
</section> </section>
@ -597,7 +506,8 @@ ${HBASE_HOME}/bin/hbase-daemons.sh {start,stop} zookeeper
</section> </section>
</section> <!-- SASL Authentication with ZooKeeper --> </section>
<!-- SASL Authentication with ZooKeeper -->