| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" |
| "http://forrest.apache.org/dtd/document-v20.dtd"> |
| <document> |
| <header> |
| <title> |
| Hadoop On Demand用户指南 |
| </title> |
| </header> |
| |
| <body> |
| <section> |
| <title>简介</title><anchor id="Introduction"></anchor> |
| <p>Hadoop On Demand (HOD)是一个能在大规模物理集群上供应虚拟Hadoop集群的系统。它使用Torque资源管理器进行节点分配。在所分配的节点上，它能启动Hadoop Map/Reduce以及HDFS守护进程。它能自动为Hadoop守护进程及客户端生成合适的配置文件(Hadoop-site.xml)。HOD还能够将Hadoop分发到它分配的虚拟集群节点上。总之，HOD方便管理者和用户快速安装与使用Hadoop。它也是需要在同一物理集群上测试各自版本的Hadoop开发者和测试者的实用工具。</p> |
| <p>HOD支持Hadoop 0.15及其后续版本。</p> |
| <p>后面的文档包括一个快速入门指南能让你快速上手HOD，一个所有HOD特性的详细手册，命令行选项，一些已知问题和故障排除的信息。</p> |
| </section> |
| <section> |
| <title>HOD使用入门</title><anchor id="Getting_Started_Using_HOD_0_4"></anchor> |
| |
| <p>在这部分，我们将会逐步骤地介绍使用HOD涉及到的最基本的操作。在开始遵循这些步骤之前，我们假定HOD及其依赖的软硬件均已被正确安装和配置。这步通常由集群的系统管理员负责。</p> |
| <p>HOD的用户界面是一个命令行工具，叫做<code>hod</code>。它被一个通常由系统管理员为用户设置好的配置文件所驱动。用户在使用<code>hod</code>的时候可以覆盖这个配置，文档的后面会由介绍。使用<code>hod</code>时有如下两种方式可以指定配置文件：</p> |
| <ul> |
| <li>在命令行中指定，使用 -c 选项。例如<code>hod <operation> <required-args> -c path-to-the-configuration-file [ohter-options]</code></li> |
| <li>在运行<code>hod</code>的地方设置环境变量<em>HOD_CONF_DIR</em>。这个变量应指向指向一个本地目录，其中有名为<em>hodrc</em>的文件。这与Hadoop中的<em>HADOOP_CONF_DIR</em>与<em>hadoop-site.xml</em>文件是类似的。如果命令行中未指定配置文件，<code>hod</code>会查找<em>HOD_CONF_DIR</em>环境变量指定目录下的<em>hodrc</em>文件。</li> |
| </ul> |
| <p>下面的例子中，我们将不会明确指出这个配置选项，假定其已正确指定。</p> |
| <section><title>一个典型HOD会话</title><anchor id="HOD_Session"></anchor> |
| <p>一个典型HOD会话至少包括三个步骤：分配，执行Hadoop作业，回收。为此，执行如下步骤。</p> |
| <p><strong>创建一个集群目录</strong></p><anchor id="Create_a_Cluster_Directory"></anchor> |
| <p><em>集群目录</em>是本地文件系统上的一个目录，<code>hod</code>会为它分配的集群产生对应的Hadoop配置<em>hadoop-site.xml</em>，放在这个目录下。这个目录可以按下文所述方式传递给<code>hod</code>操作。如果这个目录不存在，HOD会自动创建这个目录。一但分配好了集群，用户可通过Hadoop --config选项指定集群目录，在之上运行Hadoop作业。</p> |
| |
| <p><strong><em>allocate</em>操作</strong></p><anchor id="Operation_allocate"></anchor> |
| <p><em>allocate</em>操作用来分配一组节点并在之上安装和提供Hadoop。它的语法如下。注意它要求指定参数集群目录（-d, --hod.clusterdir）和节点个数（-n, --hod.nodecount）：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes [OPTIONS]</code></td> |
| </tr> |
| |
| </table> |
| <p>如果命令成功执行，<code>cluster_dir/hadoop-site.xml</code>会被生成，文件中包含了分配出的集群的信息。它也会打印出关于Hadoop的web UI的信息。</p> |
| <p>试运行这个命令会产生如下输出。注意在这个例子中集群目录是<code>~/hod-clusters/test</code>，我们要分配5个节点：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d ~/hod-clusters/test -n 5</code><br/> |
| <code>INFO - HDFS UI on http://foo1.bar.com:53422</code><br/> |
| <code>INFO - Mapred UI on http://foo2.bar.com:55380</code><br/></td> |
| </tr> |
| </table> |
| |
| <p><strong>在分配的集群上执行Hadoop作业</strong></p><anchor id="Running_Hadoop_jobs_using_the_al"></anchor> |
| <p>现在，可以用一般的方式在分配的集群上执行Hadoop作业了。这是假定像<em>JAVA_HOME</em>，指向Hadoop安装的路径已被正确地设置了：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hadoop --config cluster_dir hadoop_command hadoop_command_args</code></td> |
| </tr> |
| |
| </table> |
| <p>或者</p> |
| <table> |
| |
| <tr> |
| <td><code>$ export HADOOP_CONF_DIR=cluster_dir</code> <br /> |
| <code>$ hadoop hadoop_command hadoop_command_args</code></td> |
| </tr> |
| |
| </table> |
| <p>继续我们的例子，下面的命令会在分配的集群上运行wordcount的例子：</p> |
| <table><tr><td><code>$ hadoop --config ~/hod-clusters/test jar /path/to/hadoop/hadoop-examples.jar wordcount /path/to/input /path/to/output</code></td></tr></table> |
| <p>或者</p> |
| <table><tr> |
| <td><code>$ export HADOOP_CONF_DIR=~/hod-clusters/test</code><br /> |
| <code>$ hadoop jar /path/to/hadoop/hadoop-examples.jar wordcount /path/to/input /path/to/output</code></td> |
| </tr> |
| </table> |
| <p><strong> <em>deallocate</em>操作</strong></p><anchor id="Operation_deallocate"></anchor> |
| <p><em>deallocate</em>操作用来回收分配到的集群。当完成集群使用之后，必须执行回收操作使这些节点可以为其他用户所用。<em>deallocate</em>操作的语法如下。注意它需要集群目录（-d, --hod.clusterdir）作为参数：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hod deallocate -d cluster_dir</code></td> |
| </tr> |
| |
| </table> |
| <p>继续我们的例子，如下命令会回收集群：</p> |
| <table><tr><td><code>$ hod deallocate -d ~/hod-clusters/test</code></td></tr></table> |
| <p>如你所见，HOD允许用户分配一个集群，随意的使用它来运行Hadoop作业。例如，通过从多个shell中启动使用同一个配置的hadoop，用户可以做到在同一个集群上并发运行多个作业。</p> |
| </section> |
| <section><title>使用HOD运行Hadoop脚本</title><anchor id="HOD_Script_Mode"></anchor> |
| <p>HOD的<em>script操作</em>能将集群的分配，使用和回收组织在一起。这对那些想运行Hadoop作业脚本，期望HOD能在脚本结束后自动完成清理操作的用户特别管用。用<code>hod</code>执行Hadoop脚本，需要这么做：</p> |
| <p><strong>创建脚本文件</strong></p><anchor id="Create_a_script_file"></anchor> |
| <p>这是一个普通的shell脚本，通常里面会包含hadoop命令，如：</p> |
| <table><tr><td><code>$ hadoop jar jar_file options</code></td> |
| </tr></table> |
| <p>当然，用户可以向脚本中添加任何有效的命令。HOD会在执行这个脚本时自动地设置<em>HADOOP_CONF_DIR</em>指向分配的集群。用户不必对此担心。不过，像分配操作时一样，用户需要指定一个集群目录。</p> |
| <p><strong>运行脚本</strong></p><anchor id="Running_the_script"></anchor> |
| <p><em>脚本操作</em>的语法如下。注意它需要集群目录（-d, --hod.clusterdir），节点个数（-n, --hod.nodecount）以及脚本文件（-s, --hod.script）作为参数：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hod script -d cluster_directory -n number_of_nodes -s script_file</code></td> |
| </tr> |
| |
| </table> |
| <p>注意一但脚本执行完毕，HOD就会回收集群，这意味着脚本必须要做到等hadoop作业完成后脚本才结束。用户写脚本时必须注意这点。</p> |
| </section> |
| </section> |
| <section> |
| <title>HOD的功能</title><anchor id="HOD_0_4_Features"></anchor> |
| <section><title>供应与管理Hadoop集群</title><anchor id="Provisioning_and_Managing_Hadoop"></anchor> |
| <p>HOD主要功能是供应Hadoop的Map/Reduce和HDFS集群。这些在见入门一节已经做过描述。 此外，要是还有节点可用，并且组织上也批准，一个用户可以在同一时间内使用HOD分配多个Map/Reduce集群。对于分配到的不同集群，用户需要为上面提到的<code>cluster_dir</code>参数指定不同的路径。HOD提供<em>list</em>和<em>info</em>操作可以管理多个集群。</p> |
| <p><strong><em>list</em>操作</strong></p><anchor id="Operation_list"></anchor> |
| <p>list操作能列举到目前为止用户所创建的所有集群。存放hadoop-site.xml的集群目录，与JobTracker和／或HDFS的连接及状态也会被显示出来。list操作的使用语法如下：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hod list</code></td> |
| </tr> |
| |
| </table> |
| <p><strong><em>info</em>操作</strong></p><anchor id="Operation_info"></anchor> |
| <p>info操作会显示指定集群相关的信息。这些信息包括Torque作业id，HOD Ringmaster进程，Hadoop的JobTracker和NameNode守护进程等重要守护进程的位置。info操作的语法如下。注意它需要集群目录（-d, --hod.clusterdir）作为参数：</p> |
| <table> |
| |
| <tr> |
| <td><code>$ hod info -d cluster_dir</code></td> |
| </tr> |
| |
| </table> |
| <p><code>cluster_dir</code>应为前面<em>allocate</em>操作中指定的有效集群目录。</p> |
| </section> |
| <section><title>使用tarball分发Hadoop</title><anchor id="Using_a_tarball_to_distribute_Ha"></anchor> |
| <p>供应Hadoop时，HOD可以使用集群节点上已经安装好的Hadoop，也可以将hadoop的tarball作为供应操作的一部分在节点上进行分发和安装。如果使用tarball选项，就不必非得使用预装的Hadoop了，也不要求集群节点上必须有一个预装的版本。这对开发／QE环境下在一个共享集群上测试不同版本hadoop的开发者尤其有用。</p> |
| <p>要使用预装的Hadoop，你必须在hodrc中的<code>gridservice-hdfs</code>部分和<code>gridservice-mapred</code>部分指定<code>pkgs</code>选项。它必须指向集群中所有节点上Hadoop的安装路径。</p> |
| <p>指定Tarball的语法如下：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -t hadoop_tarball_location</code></td> |
| </tr> |
| </table> |
| <p>例如，下面的命令根据tarball<code>~/share/hadoop.tar.gz</code>分配Hadoop：</p> |
| <table><tr><td><code>$ hod allocate -d ~/hadoop-cluster -n 10 -t ~/share/hadoop.tar.gz</code></td></tr></table> |
| <p>类似地，使用hod脚本的语法如下：</p> |
| <table> |
| <tr> |
| <td><code>$ hod script -d cluster_directory -s scritp_file -n number_of_nodes -t hadoop_tarball_location</code></td> |
| </tr> |
| </table> |
| <p>上面语法中指定的hadoop_tarball_location应指向从所有计算节点都可以访问的共享文件系统的路径。当前，HOD只支持挂载的NFS。</p> |
| <p><em>注意：</em></p> |
| <ul> |
| <li>为了获得更好分发性能，建议Hadoop tarball只包含库与二进制文件，不包含源代码或文档。</li> |
| <li>当你希望在用tarball方式分配的集群上执行作业，你必须使用兼容的Hadoop版本提交你的作业。最好的方式是解压，使用Tarball中的版本。</li> |
| <li>你需要确保在tar分发包的conf目录下没有Hadoop配置文件hadoop-env.sh和hadoop-site.xml。如果这些文件存在并包含错误的值，集群分配可能会失败。 |
| </li> |
| </ul> |
| </section> |
| <section><title>使用外部HDFS</title><anchor id="Using_an_external_HDFS"></anchor> |
| <p>在典型的由HOD提供的Hadoop集群中，HDFS已经被静态地（未使用HOD）设置好。这能使数据在HOD提供的集群被回收后还可以持久保存在HDFS中。为使用静态配置的HDFS，你的hodrc必须指向一个外部HDFS。具体就是，在hodrc的<code>gridservice-hdfs</code>部分将下面选项设置为正确的值：</p> |
| <table><tr><td>external = true</td></tr><tr><td>host = HDFS NameNode主机名</td></tr><tr><td>fs_port = HDFS NameNode端口</td></tr><tr><td>info_port = HDFS NameNode web UI的端口</td></tr></table> |
| <p><em>注意：</em>你也可以从命令行开启这个选项。即，你这样去使用一个静态HDFS：<br /> |
| </p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes --gridservice-hdfs.external</code></td> |
| </tr> |
| </table> |
| <p>如果需要，HOD即可以供应HDFS集群也可以供应Map/Reduce的集群HOD。这需要设置hodrc中的<code>gridservice-hdfs</code>部分的下列选项：</p> |
| <table><tr><td>external = false</td></tr></table> |
| </section> |
| <section><title>配置Hadoop的选项</title><anchor id="Options_for_Configuring_Hadoop"></anchor> |
| <p>HOD提供一个非常方便的机制能配置它提供的Hadoop守护进程和它在客户端生成的hadoop-site.xml。通过在HOD配置文件中指定配置参数，或在分配集群时在命令行指定都可做到这点。</p> |
| <p><strong>配置Hadoop守护进程</strong></p><anchor id="Configuring_Hadoop_Daemons"></anchor> |
| <p>要配置Hadoop守护进程，你可以这么做：</p> |
| <p>对于Map/Reduce，指定<code>gridservice-mapred</code>部分的<code>server-params</code>项的指为一个以逗号分割的key-value对列表。同配置动态HDFS集群一样，设置<code>gridservice-hdfs</code>部分的<code>server-params</code>项。如果这些参数应被标记成<em>final</em>，将这些参数包含到相应部分的<code>final-server-params</code>项中。</p> |
| <p>例如：</p> |
| <table><tr><td><code>server-params = mapred.reduce.parallel.copies=20,io.sort.factor=100,io.sort.mb=128,io.file.buffer.size=131072</code></td></tr><tr><td><code>final-server-params = mapred.child.java.opts=-Xmx512m,dfs.block.size=134217728,fs.inmemory.size.mb=128</code></td> |
| </tr></table> |
| <p>要从命令行指定选项，你可以用如下语法：</p> |
| <p>配置Map/Reduce守护进程：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -Mmapred.reduce.parallel.copies=20 -Mio.sort.factor=100</code></td> |
| </tr> |
| </table> |
| <p>在上述例子中，<em>mapred.reduce.parallel.copies</em>参数和<em>io.sort.factor</em>参数将会被添加到<code>server-params</code>中，如果已经在<code>server-params</code>中存在，则它们会被覆盖。要将这些参数指定成<em>final</em>类型，你可以：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -Fmapred.reduce.parallel.copies=20 -Fio.sort.factor=100</code></td> |
| </tr> |
| </table> |
| <p>不过，应注意final参数无法被命令行改写的，只有在未指定的情形才能追加。</p> |
| <p>配置动态供应的HDFS守护进程的选项与此相似。用-H替换-M以，用-S替换-F即可。</p> |
| <p><strong>配置Hadoop的作业提交（客户端）程序</strong></p><anchor id="Configuring_Hadoop_Job_Submissio"></anchor> |
| <p>如上所述，当allocate操作成功后，<code>cluster_dir/hadoop-site.xml</code>将会生成，其中会包含分配的集群的JobTracker和NameNode的信息。这个配置用于向集群提交作业。HOD提供选项可将其它的hadoop配置参数添加到该文件，其语法如下：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -Cmapred.userlog.limit.kb=200 -Cmapred.child.java.opts=-Xmx512m</code></td> |
| </tr> |
| </table> |
| <p>上例中，<em>mapred.userlog.limit.kb</em>和<em>mapred.child.java.opts</em>会被添加到hod产生的hadoop-site.xml中。</p> |
| </section> |
| <section><title>查看Hadoop的Web-UI</title><anchor id="Viewing_Hadoop_Web_UIs"></anchor> |
| <p>HOD的allocate操作会打印出JobTracker和NameNode的Web UI的URL。例如：</p> |
| <table><tr><td><code>$ hod allocate -d ~/hadoop-cluster -n 10 -c ~/hod-conf-dir/hodrc</code><br/> |
| <code>INFO - HDFS UI on http://host242.foo.com:55391</code><br/> |
| <code>INFO - Mapred UI on http://host521.foo.com:54874</code> |
| </td></tr></table> |
| <p>上面提到的<em>info</em>操作可以给你同样的信息。</p> |
| </section> |
| <section><title>收集和查看Hadoop日志</title><anchor id="Collecting_and_Viewing_Hadoop_Lo"></anchor> |
| <p>要获取在某些分配节点上运行的守护进程的Hadoop日志：</p> |
| <ul> |
| <li>登录感兴趣的节点。如果你想查看JobTracker或者NameNode的日志，<em>list</em>和<em>info</em>操作能告诉你这些进程在那些节点上运行。</li> |
| <li>获取感兴趣的守护进程的进程信息（例如，<code>ps ux | grep TaskTracker</code>）</li> |
| <li>在这些进程信息中，查找变量<code>-Dhadoop.log.dir</code>的值。通常是hod配置文件里<code>hodring.temp-dir</code>目录的一个子目录 。</li> |
| <li>切换到<code>hadoop.log.dir</code>目录以查看守护进程日志和用户日志。</li> |
| </ul> |
| <p>HOD也提供了一个机制，能让你在集群回收后将日志收集存放到文件系统，或者一个在外部配置的HDFS中。这样的话，在作业完成，节点回收后你还可以看这些日志。要做到这点，像下面一样为log-destination-uri指定一个URI：</p> |
| <table><tr><td><code>log-destination-uri= hdfs://host123:45678/user/hod/logs</code>或者</td></tr> |
| <tr><td><code>log-destination-uri= file://path/to/store/log/files</code></td></tr> |
| </table> |
| <p>在上面指定的的根目录中，HOD会创建路径user_name/torque_jobid，把作业涉及到的每个节点上的日志文件gzip压缩，存放在里面。</p> |
| <p>注意要在HDFS上存储这些文件，你得将<code>hodring.pkgs</code>项配置为和刚才提到的HDFS兼容的版本。否则，HOD会尝试使用它供应Hadoop集群时用到的Hadoop版本。</p> |
| </section> |
| <section><title>闲置集群的自动回收</title><anchor id="Auto_deallocation_of_Idle_Cluste"></anchor> |
| <p>HOD会自动回收在一段时间内没有运行Hadoop作业的集群。每次的HOD分配会带有一个监控设施不停地检查Hadoop作业的执行。如果侦测到在一定时间内没Hadoop作业在执行，它就回收这个集群，释放那些未被有效利用的节点。</p> |
| <p><em>注意：</em>当集群被回收时，<em>集群目录</em>没有被自动清空。用户须通过一个正式的<em>deallcocate</em>操作清理它。</p> |
| </section> |
| <section><title>指定额外的作业属性</title><anchor id="Specifying_Additional_Job_Attrib"></anchor> |
| <p>HOD允许用户为一个Torque作业指定一个时钟时间和一个名称（或者标题）。 </p> |
| <p>时钟时间是对Torque作业有效时间的一个估计。这个时间过期后，Torque将自动删除这个作业，释放其节点。指定这个时钟时间还能帮助作业调度程序更好的安排作业，提高对集群资源的使用率。</p> |
| <p>指定时钟时间的语法如下：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -l time_in_seconds</code></td> |
| </tr> |
| </table> |
| <p>Torque作业的名称或标题能给用户以友好的作业标识。每次展示Torque作业的属性的时候，这个字符串就会出现，包括<code>qstat</code>命令。</p> |
| <p>指定名称或标题的语法如下：</p> |
| <table> |
| <tr> |
| <td><code>$ hod allocate -d cluster_dir -n number_of_nodes -N name_of_job</code></td> |
| </tr> |
| </table> |
| <p><em>注意：</em>由于底层Torque资源管理器的限制，不以字母开头或者包含空格的名字将导致作业失败。失败信息会表明问题存在于指定的作业名称中。</p> |
| </section> |
| <section><title>捕获HOD在Torque中的退出码</title><anchor id="Capturing_HOD_exit_codes_in_Torq"></anchor> |
| <p>HOD退出码出现在Torque的exit_status字段中。这有助于使用者和系统管理员区分成功的HOD执行和失败的HOD执行。如果分配成功且所有Hadoop作业在所分配的集群上正确的执行，退出码为0。如果分配失败或者部分hadoop作业在分配集群上运行失败，退出码非0。下表列出了可能出现的退出码。<em>注意：只有所使用的Hadoop版本是0.16或以上时，Hadoop作业状态才可以被捕获。</em></p> |
| <table> |
| |
| <tr> |
| <td>退出码</td> |
| <td>含义</td> |
| </tr> |
| <tr> |
| <td> 6 </td> |
| <td>Ringmaster故障</td> |
| </tr> |
| <tr> |
| <td> 7 </td> |
| <td> DFS故障</td> |
| </tr> |
| <tr> |
| <td> 8 </td> |
| <td> Job tracker故障</td> |
| </tr> |
| <tr> |
| <td> 10 </td> |
| <td> 集群死亡</td> |
| </tr> |
| <tr> |
| <td> 12 </td> |
| <td> 集群已分配 </td> |
| </tr> |
| <tr> |
| <td> 13 </td> |
| <td> HDFS死亡</td> |
| </tr> |
| <tr> |
| <td> 14 </td> |
| <td> Mapred死亡</td> |
| </tr> |
| <tr> |
| <td> 16 </td> |
| <td>集群中所有的Map/Reduce作业失败。查看hadoop日志了解更多细节。</td> |
| </tr> |
| <tr> |
| <td> 17 </td> |
| <td>集群中部分的Map/Reduce作业失败。查看hadoop日志了解更多细节。</td> |
| </tr> |
| </table> |
| </section> |
| <section> |
| <title>命令行</title><anchor id="Command_Line"></anchor> |
| <p>HOD命令行的通用的语法如下：<br/> |
| <em>hod <operation> [ARGS] [OPTIONS]<br/></em> |
| 允许的操作有‘allocate’，‘deallocate’，‘info’，‘list’，‘script’以及‘help’。要获取某特定操作的帮助你可以执行：<code>hod help <operation></code>。要查看可能的操作你可以执行<code>hod help options</code>。</p> |
| <p><em>allocate</em><br /> |
| <em>用法：hod allocate -d cluster_dir -n number_of_nodes [OPTIONS]</em><br /> |
| 分配一个指定节点数目的集群，把分配信息存放在cluster_dir方便后续<code>hadoop</code>命令使用。注意<code>cluster_dir</code>必须在运行该命令前已经存在。</p> |
| <p><em>list</em><br/> |
| <em>用法：hod list [OPTIONS]</em><br /> |
| 列举出用户分配的所有集群。提供的信息包括集群对应的的Torque作业标识，存储分配信息的集群目录，Map/Reduce守护进程是否存活。</p> |
| <p><em>info</em><br/> |
| <em>用法：hod info -d cluster_dir [OPTIONS]</em><br /> |
| 列举集群分配信息存放于某指定集群目录的集群信息。</p> |
| <p><em>deallocate</em><br/> |
| <em>用法：hod deallocate -d cluster_dir [OPTIONS]</em><br /> |
| 回收集群分配信息存放于某指定集群目录的集群。</p> |
| <p><em>script</em><br/> |
| <em>用法：hod script -s script_file -d cluster_directory -n number_of_node [OPTIONS]</em><br /> |
| 用HOD<em>script</em>操作执行一个hadoop脚本。在给定数目的节点上提供Hadoop，在提交的节点执行这个脚本，并在脚本执行结束后回收集群。</p> |
| <p><em>help</em><br/> |
| <em>用法：hod help [operation | 'options']</em><br/> |
| 未指定参数时，<code>hod help</code>给出用法以及基本选项，等同于<code>hod --help</code> （见下文）。当指定参数‘options’时，显示hod的基本选项。当指定operation时，它会显示出该特定operation的用法和相应的描述。例如，希望了解allocate操作，你可以执行<code>hod help allocate</code></p> |
| <p>除上面的操作外，HOD还能接受下列命令行选项。</p> |
| <p><em>--help</em><br /> |
| 打印出用法和基本选项的帮助信息。</p> |
| <p><em>--verbose-help</em><br /> |
| hodrc文件中所有的配置项均可通过命令行传递，使用语法<code>--section_name.option_name[=vlaue]</code>。这种方式下，命令行传递的参数会覆盖hodrc中的配置项。verbose-help命令会列出hodrc文件中全部可用项。这也是一个了解配置选项含义的好方法。</p> |
| <p><a href="#Options_Configuring_HOD">下一部分</a>有多数重要的hod配置项的描述。对于基本选项，你可以通过<code>hod help options</code>了解，对于所有的hod配置中的可能选项，你可以参看<code>hod --verbose-help</code>的输出。了解所有选项的描述，请参看<a href="hod_config_guide.html">配置指南</a>。</p> |
| </section> |
| <section><title> HOD配置选项</title><anchor id="Options_Configuring_HOD"></anchor> |
| <p> 如上所述，HOD的配置是通过系统管理员设置配置文件完成。这是一个INI风格的配置文件，文件分成多个段，每个段包含一些配置项。这些段分别和HOD的进程：client，ringmaster，hodring，mapreduce或hdfs相关。每一个配置项有选项名和值构成。</p> |
| <p>有两种方式可让用户覆盖默认配置文件里的设定：</p> |
| <ul> |
| <li>在每条命令前，用户可以向HOD提供自己的配置文件，使用<code>-c</code>选项。</li> |
| <li>用户可以在命令行指定HOD的配置选项覆盖正使用的配置文件中提供的值。</li> |
| </ul> |
| <p>这一节介绍一些最常用的配置项。为了指定方便，这些常用选项通常会有一个<em>短</em>选项名。所有其它选项可能用随后介绍的<em>长</em>选项指定。</p> |
| <p><em>-c config_file</em><br /> |
| 提供要使用的配置文件。可与其他任何的HOD选项一起使用。此外，可定义<code>HOD_CONF_DIR</code>环境变量为一个包含<code>hodrc</code>文件的目录，避免每条HOD命令都要指定配置文件。</p> |
| <p><em>-d cluster_dir</em><br /> |
| 大多数hod操作都要求这个选项。如<a href="#Create_a_Cluster_Directory">此处</a>描述的，<em>集群目录</em>是在本地文件系统上的一个目录，<code>hod</code>将它分配集群的相应Hadoop配置产生在这个目录里，即<em>hadoop-site.xml</em>。使用-d或者--hod.clusterdir将这个参数传递给<code>hod</code>操作，如果目录不存在，HOD会自动创建该目录。集群分配好后，用户可在这个集群上，通过指定hadoop--config为集群目录来执行Hadoop作业。</p> |
| <p><em>-n number_of_nodes</em><br /> |
| hod allocation操作和script操作要求这个选项。表示要分配的节点数。</p> |
| <p><em>-s script-file</em><br/> |
| 脚本操作时需要，用于指定要执行的脚本文件。</p> |
| <p><em>-b 1|2|3|4</em><br /> |
| 启用给定的调试级别。能与其他HOD选项一起使用。级别4最为详尽。</p> |
| <p><em>-t hadoop_tarball</em><br /> |
| 从指定tar.gz文件提供Hadoop分发。此选项值只适用于<em>allocate</em>操作。为获得更好的分发性能，强烈推荐创建Hadoop tarball<em>前</em>删除其中的源代码或文档。</p> |
| <p><em>-N job-name</em><br /> |
| 内部使用的资源管理作业名。比如，对于Torque作为资源管理器的情况，会被解释成<code>qsub -N</code>选项，使用<code>qstat</code>命令时可以看到这个作业名。</p> |
| <p><em>-l wall-clock-time</em><br /> |
| 用户希望在分配的集群作业的时间总量。它被传递给HOD底层的资源管理器，用于更有效地调度和利用集群。注意对于Torque的情形，这个时间到期后，集群会在被自动回收。</p> |
| <p><em>-j java-home</em><br /> |
| JAVA_HOME环境变量里指定的路径。在<em>script</em>操作中使用。HOD将JAVA_HOME环境变量设置为这个值，并在此环境下启动用户脚本。</p> |
| <p><em>-A account-string</em><br /> |
| 传递给后台资源管理器的核计信息。</p> |
| <p><em>-Q queue-name</em><br /> |
| 接受作业提交的后台资源管理器中队列的名称。</p> |
| <p><em>-Mkey1=value1 -Mkey2=value2</em><br/> |
| 为供应的Map/Reduce守护进程（JobTracker以及TaskTracker）提供配置参数。在集群节点上，会根据这些值产生一个hadoop-site.xml。 <br /> |
| <em>注意：</em>值中的下列字符：空格，逗号，等号，分号需要使用‘\’转义， 且放置在引号中。你也可以使用‘\’来转义‘\’。</p> |
| <p><em>-Hkey1=value1 -Hkey2=value2</em><br /> |
| 为供应的HDFS守护进程（NameNode以及DataNode）提供配置参数。在集群节点上，会根据这些值产生一个hadoop-site.xml。 <br /> |
| <em>注意：</em>值中的下列字符：空格，逗号，等号，分号需要使用‘\’转义， 且放置在引号中。你也可以使用‘\’来转义‘\’。</p> |
| <p><em>-Ckey1=value1 -Ckey2=value2</em><br /> |
| 为提交作业的客户端提供配置参数。在提交节点上，会根据这些值产生一个hadoop-site.xml。<br /> |
| <em>注意：</em>参数值可以使用以下符号：空格，逗号，等号，需要‘\’做转义符的分号，上述符号要用引号进行分割。你也可以使用‘\’转义‘\’。 </p> |
| <p><em>--section-name.option-name=value</em><br /> |
| 这是用<em>长</em>格式提供配置选项的方法。比如，你可以<em>--hod.script-wait-time=20</em></p> |
| </section> |
| </section> |
| <section> |
| <title>故障排除</title><anchor id="Troubleshooting"></anchor> |
| <p>下节列出了一些用户使用HOD时可能碰到的多发错误的条件以及解决问题的方法</p> |
| <section><title>分配操作时<code>hod</code>挂起</title><anchor id="_hod_Hangs_During_Allocation"></anchor><anchor id="hod_Hangs_During_Allocation"></anchor> |
| <p><em>可能原因：</em>HOD或Hadoop的一个组件启动失败。这种情况下，<code>hod</code>命令会在一段时间（通常是2-3分钟）后返回，退出码是错误代码部分定义的错误码7或8。参考该部分以获得更多细节。 </p> |
| <p><em>可能原因：</em>使用tarball模式申请了大规模的集群。有时由于网络负载，或者是分配节点上的负载，tarball分发过程可能会慢的比较明显，需要几分钟才能响应。等待命令完成。还可以检查一下tarball，看是否不含Hadoop源码或文档。</p> |
| <p><em>可能原因：</em>Torque相关的问题。如果原因与Torque相关，<code>hod</code>命令5分钟内是不会返回的。在调试模式下运行<code>hod</code>你会发现<code>qstat</code>命令被重复执行。在另一个shell中执行<code>qstat</code>命令你会发现作业处于<code>Q</code>（排队）状态。这通常说明Torque出现了问题。可能原因有个别节点宕机，或者增加了新节点但Torque不知。通常，需要系统管理员帮助解决此问题。</p> |
| </section> |
| <section><title>回收操作时<code>hod</code>挂起</title><anchor id="_hod_Hangs_During_Deallocation"></anchor><anchor id="hod_Hangs_During_Deallocation"></anchor> |
| <p><em>可能原因：</em>Torque相关的问题，通常是Torque server上的负载较大，或者是分配的集群非常大。一般来说，你唯一能做的是等待命令执行完成。</p> |
| </section> |
| <section><title><code>hod</code>失败时的错误代码和错误信息</title><anchor id="hod_Fails_With_an_error_code_and"></anchor><anchor id="_hod_Fails_With_an_error_code_an"></anchor> |
| <p>如果<code>hod</code>命令的退出码不是<code>0</code>，参考下面的退出代码表确定此情况发生的原因和相应的调试方法。</p> |
| <p><strong>错误代码</strong></p><anchor id="Error_Codes"></anchor> |
| <table> |
| |
| <tr> |
| <th>错误代码</th> |
| <th>含义</th> |
| <th>可能原因及补救方法</th> |
| </tr> |
| <tr> |
| <td> 1 </td> |
| <td>配置错误 </td> |
| <td>hodrc中的参数错误，或者其他与HOD配置相关的错误。此类情况下，错误信息已经足够帮你发现和解决问题。</td> |
| </tr> |
| <tr> |
| <td> 2 </td> |
| <td>无效操作</td> |
| <td>执行<code>hod help</code>查看有效的操作列表。</td> |
| </tr> |
| <tr> |
| <td> 3 </td> |
| <td>无效操作参数</td> |
| <td>执行<code>hod help operation</code>查看特定操作的用法。</td> |
| </tr> |
| <tr> |
| <td> 4 </td> |
| <td>调度失败</td> |
| <td> 1. 请求分配了过多的资源。执行<code>checknodes cluster_name</code>查看是否有足够多的可用节点。<br /> |
| 2. 请求的资源超出了资源管理器的限制。<br /> |
| 3. Torque配置错误，Torque可执行文件路径配置错误，或者其它Torque相关问题。联系系统管理员。</td> |
| </tr> |
| <tr> |
| <td> 5 </td> |
| <td>执行作业失败</td> |
| <td> 1. Torque作业被外部删除。执行Torque <code>qstat</code>命令查看是否有作业处于<code>R</code>（运行）状态。如果没有，尝试重新运行HOD。<br/> |
| 2. Torque的问题诸如服务器暂时性宕机，或者无响应。联系系统管理员。 <br/> |
| 3. 系统管理员可能配置了帐号核实，并且一个非法的帐号被指定。请联系系统管理员。 </td> |
| </tr> |
| <tr> |
| <td> 6 </td> |
| <td>Ringmaster故障</td> |
| <td> HOD会打印信息"Cluster could not be allocated because of the following errors on the ringmaster host <hostname>"。实际的错误信息可能指示下列情形中的一种：<br/> |
| 1. 运行ringmaster的节点配置不合法，错误信息中的hostname会指明具体的机器。<br/> |
| 2. <code>ringmaster</code>段的配置无效，<br /> |
| 3. <code>gridservice-mapred或者gridservice-hdfs</code>段中<code>pkgs</code>项的配置无效，<br /> |
| 4. 无效的hadoop tarball，或者tarball中conf目录下存在无效的配置文件，<br /> |
| 5. Hadoop中的MapReduce与外部HDFS版本不匹配。<br /> |
| Torque <code>qstat</code>命令很可能会显示一个出于<code>C</code>(Completed，已完成)状态的作业。<br/> |
| 你可以登录到HOD失败信息中给出的ringmaster主机，根据错误信息的提示解决问题。如果错误信息没有给出完整的信息，ringmaster日志也可能帮助找到问题的根源。参考下面<em>定位Ringmaster日志</em>一节了解更多信息。</td> |
| </tr> |
| <tr> |
| <td> 7 </td> |
| <td> DFS故障</td> |
| <td> 当HOD由于DFS故障（或者Job tracker失败，错误码8，下文有介绍）分配失败时，它会打印错误信息 "Hodring at <hostname> failed with following errors:"，并给出真正的错误信息，这个信息可能表明下列情形中的一种：<br/> |
| 1. 启动Hadoop集群时出现问题。通常错误信息会表明之前提到的主机出现错误的真正原因。你也要检查HOD配置中文件中Hadoop相关的配置。按上面<em>收集和查看Hadoop日志</em>一节中介绍的方法查看Hadoop的日志。<br /> |
| 2. 运行hodring的节点上的配置无效，错误信息中的hostname会指明机器<br/> |
| 3. hodrc中<code>hodring</code>段的配置无效。<code>ssh</code>到错误信息中提到的节点，在hdring日志中grep<code>ERROR</code>或<code>CRITICAL</code>。参考下面<em>定位Hodring日志</em>部分获取更多信息。<br /> |
| 4. 指定了无效的tarball，可能未正确打包。<br /> |
| 5. 无法与外部配置的HDFS通信。<br /> |
| 当DFS或Job tracker出现故障时，你可以登录到HOD失败信息中提到的主机上，进行debug。解决问题的时候，你也应通过查看ringmaster日志中的其它日志信息，来检查其他机器是否在启动jobtracker/namenode时也出现了问题，而不只是检查错误信息中提到的主机。其他机器也可能发生问题是因为HOD会按照配置项<a href="hod_config_guide.html#3.4+ringmaster的配置项">ringmaster.max-master-failures</a>的设置在多个机器上连续尝试和启动hadoop守护进程。更多关于ringmaster日志的信息请参考下文<em>定位Ringmaster日志</em>。 |
| </td> |
| </tr> |
| <tr> |
| <td> 8 </td> |
| <td>Job tracker故障</td> |
| <td>与<em>DFS故障</em>情形中的原因类似。</td> |
| </tr> |
| <tr> |
| <td> 10 </td> |
| <td>集群死亡</td> |
| <td>1. 集群因为较长时间空闲被自动回收。<br /> |
| 2. 集群因系统管理员或者用户指定的时钟时间到期被自动回收。<br /> |
| 3. 无法与成功分配的JobTracker以及HDFS的NameNode通信。回收集群，重新分配。</td> |
| </tr> |
| <tr> |
| <td> 12 </td> |
| <td>集群已分配</td> |
| <td>指定的集群目录是已被用于先前的分配操作,且尚未回收。指定另外一个目录，或者先回收先前分配的。</td> |
| </tr> |
| <tr> |
| <td> 13 </td> |
| <td>HDFS死亡</td> |
| <td>无法与HDFS的NameNode通信。HDFS的NameNode停掉了。</td> |
| </tr> |
| <tr> |
| <td> 14 </td> |
| <td>Mapred死亡</td> |
| <td> 1. 集群因为长时间闲置被自动回收。 <br /> |
| 2. 集群因系统管理员或用户指定的时钟时间到期被自动回收。<br /> |
| 3. 无法与Map/Reduce的JobTracker通信。JobTracker节点宕机。 <br /> |
| </td> |
| </tr> |
| <tr> |
| <td> 15 </td> |
| <td>集群未分配</td> |
| <td>一个需要已分配集群的操作被指以一个没有状态信息的集群目录。</td> |
| </tr> |
| |
| <tr> |
| <td>任意非0退出代码</td> |
| <td>HOD脚本错误</td> |
| <td>如果使用了hod的脚本选项，很可能这个退出代码是脚本的退出吗。不幸的是，这可能会与hod自己的退出码冲突。为帮助用户区分两者，如果脚本返回了一个退出码，hod将此退出码写到了集群目录下的script.exitcode文件。你可以cat这个文件以确定脚本的退出码。如果文件不存在，则退出代码是hod命令的退出码。</td> |
| </tr> |
| </table> |
| </section> |
| |
| <section><title>Hadoop DFSClient警告NotReplicatedYetException信息</title> |
| <p>有时，当你申请到一个HOD集群后马上尝试上传文件到HDFS时，DFSClient会警告NotReplicatedYetException。通常会有一个这样的信息 - </p><table><tr><td><code>WARN |
| hdfs.DFSClient: NotReplicatedYetException sleeping <filename> retries |
| left 3</code></td></tr><tr><td><code>08/01/25 16:31:40 INFO hdfs.DFSClient: |
| org.apache.hadoop.ipc.RemoteException: java.io.IOException: File |
| <filename> could only be replicated to 0 nodes, instead of |
| 1</code></td></tr></table><p> 当你向一个DataNodes正在和NameNode联络的集群上传文件的时候，这种现象就会发生。在上传新文件到HDFS之前多等待一段时间就可以解决这个问题，因为这使得足够多的DataNode启动并且联络上了NameNode。</p> |
| </section> |
| |
| |
| <section><title>成功分配的集群上无法运行Hadoop作业</title><anchor id="Hadoop_Jobs_Not_Running_on_a_Suc"></anchor> |
| <p>这一情景通常发生在这种情形：一个集群已经分配，并且一段时间内处于不活跃状态，之后hadoop作业试图在这个集群上运行。Hadoop作业会失败，产生如下异常信息：</p> |
| <table><tr><td><code>08/01/25 16:31:40 INFO ipc.Client: Retrying connect to server: foo.bar.com/1.1.1.1:53567. Already tried 1 time(s).</code></td></tr></table> |
| <p><em>可能原因：</em>相当长的时间内无hadoop作业运行，集群会如<em>闲置集群的自动回收</em>一节介绍的那样被自动回收。回收该集群，然后重新分配。</p> |
| <p><em>可能原因：</em>从分配开始算起，Torque管理员指定的或<em>指定额外的作业属性</em>一节中定义的<code>-l</code>选项指定的时间上限过期。这种情况下集群可能已被释放。回收集群，然后重新分配。</p> |
| <p><em>可能原因：</em>提交作业使用的hadoop版本和供应集群的Hadoop版本（通常通过tarball选项）不匹配。确保使用的兼容的版本。</p> |
| <p><em>可能原因：</em> 提交job的hadoop客户端与提供的hadoop(通常通过tarball选项)版本不兼容。 确保所使用hadoop软件版本兼容。</p> |
| <p><em>可能原因：</em> 你使用了<code>-M or -H</code>中的一个指定Hadoop配置，其中有未正确转义的字符比如空格或逗号。参考<em>HOD配置选项</em>一节以了解如何正确指定这些选项。</p> |
| </section> |
| <section><title>我的Hadoop作业被中止了</title><anchor id="My_Hadoop_Job_Got_Killed"></anchor> |
| <p><em>可能原因：</em>从分配开始算起，Torque管理员指定的或<em>指定额外的作业属性</em>一节中定义的<code>-l</code>选项指定的时间上限过期。这种情况下集群可能已被释放。回收集群，然后重新分配，这次要制定一个大点儿的时钟时间。</p> |
| <p><em>可能原因：</em> JobTracker节点出现问题。参考<em>收集和查看Hadoop日志</em>一节以获取更多信息。</p> |
| </section> |
| <section><title>Hadoop作业失败并返回消息：‘Job tracker still initializing’</title><anchor id="Hadoop_Job_Fails_with_Message_Jo"></anchor> |
| <p><em>可能原因：</em>hadoop作业是作为HOD脚本的一部分运行的，它在JobTracker完全就绪前开始了执行。分配集群时为配置选<code>--hod.script-wait-time</code>设定一个大点儿的值。通常取120是可以工作的，尽管通常没必要这么大。</p> |
| </section> |
| <section><title>Torque的退出代码没有包含HOD的</title><anchor id="The_Exit_Codes_For_HOD_Are_Not_G"></anchor> |
| <p><em>可能原因：</em>此功能需要Hadoop 0.16。所用的Hadoop版本不满足这个条件。请使用合适的Hadoop版本。</p> |
| <p><em>可能原因：</em>没有使用<code>hod</code>命令回收集群；例如直接使用<code>qdel</code>。当使用这种方式回收集群时，HOD进程被信号中止。这会导致退出码是基于signal number的，而不是程序的退出码。</p> |
| </section> |
| <section><title>Hadoop日志未被上传到DFS</title><anchor id="The_Hadoop_Logs_are_Not_Uploaded"></anchor> |
| <p><em>可能原因：</em>上传日志的使用的hadoop与外部的HDFS版本不兼容。确保<code>hodring.pkgs</code>选项指定了正确的版本。</p> |
| </section> |
| <section><title>定位Ringmaster日志</title><anchor id="Locating_Ringmaster_Logs"></anchor> |
| <p>遵循以下步骤定位ringmaster日志：</p> |
| <ul> |
| <li>用-b选项在调试模式执行hod。这会打印出当前运行的Torque作业的标识。</li> |
| <li>执行<code>qstat -f torque_job_id</code>，在输出中查找<code>exec_host</code>参数的值。列表中的第一个主机就是ringmaster节点。</li> |
| <li>登陆该节点。</li> |
| <li>ringmaster日志的位置由hodrc中的<code>ringmaster.log-dir</code>项指定。日志文件的名字会是<code>username.torque_job_id/ringmaster-main.log</code>。</li> |
| <li>如果你没有获取到足够的信息，你可以将ringmaster的调试级别设为4。这可通过向hod命令行传递<code>--ringmaster.debug 4</code>做到。</li> |
| </ul> |
| </section> |
| <section><title>定位Hodring日志</title><anchor id="Locating_Hodring_Logs"></anchor> |
| <p>遵循以下步骤定位hodring日志：</p> |
| <ul> |
| <li>用-b选项在调试模式下运行hod。这将打印当前运行的Torque作业的标识。</li> |
| <li>执行<code>qstat -f torque_job_id</code>，查看输出中<code>exec_host</code>参数的值。列表中的的所有节点上都有一个hodring。</li> |
| <li>登陆到任何一个节点。</li> |
| <li>hodring日志的位置由hodrc中的<code>hodring.log-dir</code>项指定。日志文件的名字会是<code>username.torque_job_id/hodring-main.log</code>。</li> |
| <li>如果你没有获得足够的信息，你或许想将hodring的调试等级更改为4。这可以向hod命令行传递<code>--hodring.debug 4</code> 来做到。</li> |
| </ul> |
| </section> |
| </section> |
| </body> |
| </document> |
