PageRenderTime 21ms CodeModel.GetById 13ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/tags/release-0.2.0-rc0/src/docs/src/documentation/content/xdocs/install.xml

#
XML | 236 lines | 181 code | 39 blank | 16 comment | 0 complexity | 61f251992469f731262fbb60d598f96a MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<!--
  3  Licensed to the Apache Software Foundation (ASF) under one or more
  4  contributor license agreements.  See the NOTICE file distributed with
  5  this work for additional information regarding copyright ownership.
  6  The ASF licenses this file to You under the Apache License, Version 2.0
  7  (the "License"); you may not use this file except in compliance with
  8  the License.  You may obtain a copy of the License at
  9
 10      http://www.apache.org/licenses/LICENSE-2.0
 11
 12  Unless required by applicable law or agreed to in writing, software
 13  distributed under the License is distributed on an "AS IS" BASIS,
 14  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 15  See the License for the specific language governing permissions and
 16  limitations under the License.
 17-->
 18<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 19
 20<document>
 21  <header>
 22    <title>Installing HCatalog</title>
 23  </header>
 24  <body>
 25
 26  <section>
 27    <title>Server Installation</title>
 28
 29    <p><strong>Prerequisites</strong></p>
 30    <ul>
 31        <li>Machine on which the server can be installed - this should have
 32        access to the hadoop cluster in question, and be accessible from
 33        the machines you launch jobs from</li>
 34        <li>MySQL db</li>
 35        <li>Hadoop cluster</li>
 36        <li>Unix user that the server will run as, and an associated kerberos
 37        service principal and keytabs.</li>
 38    </ul>
 39
 40    <p>Throughout these instructions when you see a word in <em>italics</em> it
 41    indicates a place where you should replace the word with a locally 
 42    appropriate value such as a hostname or password.</p>
 43
 44    <p><strong>Database Setup</strong></p>
 45
 46    <p>Select a machine to install the database on.  This need not be the same
 47    machine as the Thrift server, which we will set up later.  For large
 48    clusters we recommend that they not be the same machine.  For the 
 49    purposes of these instructions we will refer to this machine as
 50    <em>hcatdb.acme.com</em></p>
 51
 52    <p>Install MySQL server on <em>hcatdb.acme.com</em>.  You can obtain
 53    packages for MySQL from <a href="http://www.mysql.com/downloads/">MySQL's
 54    download site</a>.  We have developed and tested with versions 5.1.46
 55    and 5.1.48.  We suggest you use these versions or later.
 56    Once you have MySQL up and running, use the <code>mysql</code> command line
 57    tool to add the <code>hive</code> user and <code>hivemetastoredb</code>
 58    database.  You will need to pick a password for your <code>hive</code>
 59    user, and replace <em>dbpassword</em> in the following commands with it.</p>
 60
 61    <p><code>mysql -u root</code></p>
 62    <p><code>mysql> CREATE USER 'hive'@'</code><em>hcatdb.acme.com</em><code>' IDENTIFIED BY '</code><em>dbpassword</em><code>';</code></p>
 63    <p><code>mysql> CREATE DATABASE hivemetastoredb DEFAULT CHARACTER SET latin1 DEFAULT COLLATE latin1_swedish_ci;</code></p>
 64    <p><code>mysql> GRANT ALL PRIVILEGES ON hivemetastoredb.* TO 'hive'@'</code><em>hcatdb.acme.com</em><code>' WITH GRANT OPTION;</code></p>
 65    <p><code>mysql> flush privileges;</code></p>
 66    <p><code>mysql> quit;</code></p>
 67
 68    <p>In a temporary directory, untar the HCatalog artifact</p>
 69
 70    <p><code>tar xzf hcatalog-</code><em>version</em><code>.tar.gz</code></p>
 71
 72    <p>Use the database installation script found in the package to create the
 73    database</p>
 74    <p><code>mysql -u hive -D hivemetastoredb -h</code><em>hcatdb.acme.com</em><code> -p &lt; scripts/hive-schema-0.7.0.mysql.sql</code></p>
 75
 76    <p><strong>Thrift Server Setup</strong></p>
 77
 78    <p>Select a machine to install your Thrift server on.  For smaller and test
 79    installations this can be the same machine as the database.  For the
 80    purposes of these instructions we will refer to this machine as
 81    <em>hcatsvr.acme.com</em>.</p>
 82
 83    <p>Install the MySQL Java connector libraries on <em>hcatsvr.acme.com</em>.
 84    You can obtain these from
 85    <a href="http://www.mysql.com/downloads/connector/j/5.1.html">MySQL's
 86    download site</a>.</p>
 87
 88    <p>Select a user to run the Thrift server as.  This user should not be a
 89    human user, and must be able to act as a proxy for other users.  We suggest
 90    the name "hcat" for the user.  Throughout the rest of this documentation 
 91    we will refer to this user as "hcat".  If necessary, add the user to 
 92    <em>hcatsvr.acme.com</em>.</p>
 93
 94    <p>Select a <em>root</em> directory for your installation of HCatalog.  This 
 95    directory must be owned by the hcat user.  We recommend
 96    <code>/usr/local/hcat</code>.  If necessary, create the directory.</p>
 97
 98    <p>Download the HCatalog release into a temporary directory, and untar
 99    it.  Then change directories into the new distribution and run the HCatalog
100    server installation script.  You will need to know the directory you chose
101    as <em>root</em> and the
102    directory you installed the MySQL Java connector libraries into (referred
103    to in the command below as <em>dbroot</em>).</p>
104
105    <p><code>tar zxf hcatalog-</code><em>version</em><code>.tar.gz
106    cd hcatalog-</code><em>version</em></p>
107    <p><code>scripts/hcat_server_install.sh -r </code><em>root</em><code> -d </code><em>dbroot</em></p>
108
109    <p>Now you need to edit your <em>root</em><code>/conf/hive-site.xml</code> file.
110    Open this file in your favorite text editor.  The following table shows the
111    values you need to configure.</p>
112
113    <table>
114        <tr>
115            <th>Parameter</th>
116            <th>Value to Set it to</th>
117        </tr>
118        <tr>
119            <td>javax.jdo.option.ConnectionURL</td>
120            <td>In the JDBC connection string, change DBHOSTNAME to the name 
121            of the machine you put the MySQL server on.</td>
122        </tr>
123        <tr>
124            <td>javax.jdo.option.ConnectionPassword</td>
125            <td><em>dbpassword</em> value you used in setting up the MySQL server
126            above</td>
127        </tr>
128        <tr>
129            <td>hive.metastore.warehouse.dir</td>
130            <td>The directory you want to use for the default database in your
131            installation</td>
132        </tr>
133        <tr>
134            <td>hive.metastore.uris</td>
135            <td>You need to set the hostname to your Thrift
136            server.  Replace <em>SVRHOST</em> with the name of the
137            machine you are installing the Thrift server on.  You can also
138            change the port the Thrift server runs on by changing the default
139            value of 3306.</td>
140        </tr>
141        <tr>
142            <td>hive.metastore.sasl.enabled</td>
143            <td>Set to true by default.  Set to false if you do not wish to
144            secure the thrift interface.  This can be convenient for testing.
145            We do not recommend turning this off in production.</td>
146        </tr>
147        <tr>
148            <td>hive.metastore.kerberos.keytab.file</td>
149            <td>The path to the Kerberos keytab file containg the metastore
150            thrift server's service principal.</td>
151        </tr>
152        <tr>
153            <td>hive.metastore.kerberos.principal</td>
154            <td>The service principal for the metastore thrift server.  You can
155            reference your host as _HOST and it will be replaced with your
156            actual hostname</td>
157        </tr>
158    </table>
159
160    <p>You can now procede to starting the server.</p>
161  </section>
162
163  <section>
164    <title>Starting the Server</title>
165            
166    <p>Start the HCatalog server by switching directories to
167    <em>root</em> and invoking the start script
168    <code>bin/hcat_server_start.sh</code></p>
169
170  </section>
171
172  <section>
173    <title>Logging</title>
174
175    <p>Server activity logs and gc logs are located in
176    <em>root</em><code>/var/log/hcat_server</code>.  Logging configuration is located at
177    <em>root</em><code>/conf/log4j.properties</code>.  Server logging uses
178    <code>DailyRollingFileAppender</code> by default. It will generate a new
179    file per day and does not expire old log files automatically.</p>
180
181  </section>
182
183  <section>
184    <title>Stopping the Server</title>
185
186    <p>To stop the HCatalog server, change directories to the <em>root</em>
187    directory and invoke the stop script
188    <code>bin/hcat_server_stop.sh</code></p>
189
190  </section>
191
192  <section>
193    <title>Client Install</title>
194
195    <p>Select a <em>root</em> directory for your installation of HCatalog client.
196    We recommend <code>/usr/local/hcat</code>.  If necessary, create the directory.</p>
197
198    <p>Download the HCatalog release into a temporary directory, and untar
199    it.</p>
200
201    <p><code>tar zxf hcatalog-</code><em>version</em><code>.tar.gz</code></p>
202
203    <p>Now you need to edit your <em>root</em><code>/conf/hive-site.xml</code> file.
204    Open this file in your favorite text editor.  The following table shows the
205    values you need to configure.   These values should match the values set on
206    the HCatalog server.  Do <strong>NOT</strong> copy the configuration file
207    from your server installation as that contains the password to your
208    database, which you should not distribute to your clients.</p>
209
210    <table>
211        <tr>
212            <th>Parameter</th>
213            <th>Value to Set it to</th>
214        </tr>
215        <tr>
216            <td>hive.metastore.warehouse.dir</td>
217            <td>The directory you want to use for the default database in your
218            installation</td>
219        </tr>
220        <tr>
221            <td>hive.metastore.uris</td>
222            <td>You need to set the hostname wish your Thrift
223            server to use by replacing <em>SVRHOST</em> with the name of the
224            machine you are installing the Thrift server on.  You can also
225            change the port the Thrift server runs on by changing the default
226            value of 3306.</td>
227        </tr>
228    </table>
229
230    <p>The HCatalog command line interface (CLI) can now be invoked as
231    <em>root</em><code>/bin/hcat.sh</code>.</p>
232
233  </section>
234
235  </body>
236</document>