HDFS 用户手册

HDFS Users Guide

Purpose

本文档是用户使用HDFS的启蒙文档，不管是作为Hadoop集群的一部分，还是独立运行的通用分布式文件系统。虽然HDFS设计的目的是在很多环境工作就好，了解HDFS知识有助于进行配置升级和诊断。

Overview

HDFS是Hadoop应用的主要分布式存储。HDFS集群包含NameNode和DataNodes，NameNode管理文件系统元数据， DataNodes存储实际的数据。HDFS Architecture Guide 详细的阐述了HDFS。本用户手册主要介绍用户和管理员与HDFS集群的交互。HDFS architecture diagram 描述了NameNode，DataNodes，clients 的基本交互。Clients联系NameNode获取文件元数据or文件修改，实际的I/O直接联系DataNodes。

如下是一些用户感兴趣的突出特征：

Hadoop，包括HDFS，是适合于在普通硬件运行的分布式存储和分布式处理程序。它是容错的、可扩展的，并且极易扩展。MapReduce是Hadoop不可获取的一部分，以简单和适用于大量分布式应用而闻名。
HDFS高度可配置，默认配置适用于大多数安装。大多情况下，只需为超大的集群调整配置。
Hadoop以Java语言开发，被所有主流平台支持。
Hadoop支持以类shell的命令行直接与HDFS交互。
NameNode 和 Datanodes 都内置了web servers，可以很方便的查看集群当前状态。
HDFS定期实现新功能和改进。如下是HDFS有用的一些特性：
- 文件权限和身份验证
- 机架感知Rack awareness：在任务调度和分配任务的时候考虑节点的物理位置
- 安全模式Safemode：维护时的管理员模式
- fsck：分析文件系统健康状态的功能，可以发现丢失的文件or数据块
- fetchdt：获取DelegationToken并存储在本地文件系统的文件上
- Balancer：当数据在DataNodes见分配不均衡时，平衡集群的工具
- Upgrade and rollback：在软件升级后，因为一些难以预测的问题，可以回滚至HDFS升级之前的状态
- Secondary NameNode：定期检查namespace的checkpoints，并帮助NameNode保持特定限制的、包含HDFS修改日志的文件大小。
- Checkpoint node: 定期检查namespace的checkpoints，并帮助最小化NameNode存储HDFS变更的日志文件的尺寸。替换先前Secondary NameNode填充的role，虽然还没有经过严格的生产检验。只要没有 Backup nodes 注册到系统，NameNode 就可以允许同时存在多个Checkpoint nodes 。
- Backup node：Checkpoint node的扩展。除了checkpointing ，它还接受来自NameNode的流并维护它自己的namespace在内存中的副本，该副本总是同步active NameNode命名空间的状态。一次只能向NameNode注册一个备份节点。

Prerequisites

如下文档描述了如何安装和设置一个 Hadoop 集群：

Single Node Setup for first-time users.
Cluster Setup for large, distributed clusters.

本文如下部分假设用户有能力在至少在一个DataNode上设置并运行一个HDFS实例。为了本文，NameNode 和DataNode 运行在同一个物理机上。

Web Interface

NameNode 和 DataNode 都内置web server 来提供集群状态的基础信息展示。默认配置，NameNode web接口 http://namenode-name:9870/。它列出了集群的DataNodes和集群的基础统计信息。该web接口还可以用于浏览文件系统（点击 “Browse the file system”）。

Shell Commands

Hadoop包含类shell的命令可以与HDFS以及Hadoop支持的其他文件系统直接交互。命令bin/hdfs dfs -help 列出了Hadoop shell 支持的命令。命令bin/hdfs dfs -help command-name显示某命令更详细的信息。这些命令支持大多数正常的文件系统操作，如复制文件、更改文件权限等。它还支持一些特定于HDFS的操作，如更改文件的副本。更多信息参考File System Shell Guide。

DFSAdmin Command
bin/hdfs dfsadmin命令支持一些HDFS管理相关的操作。bin/hdfs dfsadmin -help命令列出了所有当前支持的命令。比如：
- -report：报告HDFS的基本统计数据。NameNode首页上也提供了一些此类信息。
- -safemode：不常用，管理员可以手动进入、离开安全模式。
- -finalizeUpgrade：删除上次升级时集群的备份。
- -refreshNodes：更新namenode，使用被允许连接到namenode的datanodes集合。默认，Namenodes重新读取文件内dfs.hosts、dfs.hosts.exclude定义的datanode主机名。定义在dfs.hosts的主机是属于集群的datanodes。如果dfs.hosts内有条目，只有在其内的主机被允许注册到namenode。dfs.hosts.exclude 内的条目是需要被停用的datanodes。或者，如果dfs.namenode.hosts.provider.classname被设置为org.apache.hadoop.hdfs.server.blockmanagement.CombinedHostFileManager，所有include和exclude的主机都在JSON文件内被dfs.hosts定义。当所有副本被复制到其他 datanodes，datanode完成停用。停用的nodes不会自动关闭，也不会被写入新副本数据。
- -printTopology：打印集群拓扑。以树状显示racks，和在NameNode上看到的、racks上的datanodes。

命令的用法参考 dfsadmin。

Secondary NameNode

NameNode将文件系统的变更已日志的方式存储到原生文件系统文件edits上。当NameNode启动时，它从image file fsimage读取HDFS状态，然后从edits log文件附加edits。然后，它写入新的HDFS状态到fsimage，并以空edits文件正常启动。既然NameNode仅在启动时合并fsimage和edits文件，那么繁忙集群的edits log文件可能会逐渐变的很大。大edits文件的另外一个影响，就是下次NameNode启动时需要更长时间。

Secondary NameNode定期合并fsimage和edits log文件，并保持edits log在限制尺寸内。它通常与主NameNode在不同服务器上运行，因为它的内存需求跟主NameNode一样。

Secondary NameNode 上检查点进程的启动由两个参数控制。

dfs.namenode.checkpoint.period，默认设置为1 hour，指定连续两个checkpoints之间的最大延迟
dfs.namenode.checkpoint.txns，默认设置为100万，定义强制紧急checkpoint的uncheckpointed事务的数量，即便checkpoint周期尚未到达。

Secondary NameNode在目录内存储最后的checkpoint，目录结构和主NameNode目录相同。所以，如果需要，已经checkpointed 的 image 总是可以被主NameNode读取。

命令使用请参见 secondarynamenode。

Checkpoint Node

NameNode使用两个文件持久化命名空间：命名空间最后一次checkpoint和edits的fsimage，自checkpoint后的命名空间的journal(log)。当NameNode启动时，合并fsimage和edits journal来提供一个最新的文件系统元数据视图。然后 NameNode 以新HDFS状态覆盖fsimage，并开始新的edits journal。

Checkpoint node定期创建命名空间的checkpoints。它从active NameNode下载fsimage和edits，在本地合并，然后回传新image给active NameNode。Checkpoint 通常和NameNode运行于不同的服务器，因为它的内存需求和NameNode相同。Checkpoint node在配置文件指定的node上以bin/hdfs namenode -checkpoint启动。

Checkpoint (or Backup) node 的位置和相随的 web interface 通过dfs.namenode.backup.address 和 dfs.namenode.backup.http-address 变量指定。

Checkpoint node上checkpoint进程的启动由两个配置参数控制：

dfs.namenode.checkpoint.period，默认设置为1 hour，指定连续两个checkpoints之间的最大延迟
dfs.namenode.checkpoint.txns，默认设置为100万，定义强制紧急checkpoint的uncheckpointed事务的数量，即便checkpoint周期尚未到达。

Checkpoint node在目录内存储最后的checkpoint，目录结构和主NameNode目录相同。这允许checkpointed image始终可被NameNode读取。参见导入checkpoint。

多checkpoint nodes可以在集群配置文件指定。

命令使用，参见namenode。

Backup Node

Backup node提供与Checkpoint node一样的checkpointing功能，还维护着一套及时同步active NameNode状态的最近的文件系统命名空间的内存中的副本。除了接受来自NameNode的文件系统的日志流，并持久化到硬盘，Backup node还将这些edits应用到其在内存中的命名空间副本，从而创建命名空间的备份。

Backup node不像Checkpoint node 或 Secondary NameNode那样需要从active NameNode下载fsimage 和 edits 文件，因为它已经在内存内保存了一份实时更新的命名空间状态。Backup node的checkpoint进程效率更高，因为它只需要保存命名空间到本地fsimage文件，然后重置edits。

因为Backup node在内存维护着命名空间的副本，那么它的内存需求也就与NameNode相同了。

NameNode同时只支持一个Backup node。如果使用了Backup node，那么Checkpoint nodes就注册不了了。未来会支持多Backup nodes同时使用。

Backup node 配置方式与 Checkpoint node 相同。以bin/hdfs namenode -backup启动。

Backup (or Checkpoint) node 的位置和相随的 web interface 通过dfs.namenode.backup.address 和 dfs.namenode.backup.http-address 变量指定。

Backup node的使用提供了不依赖固化存储运行NameNode的选项，授权所有的仓库将命名空间的状态持久化到Backup node。为此，需要以 -importCheckpoint 参数启动NameNode，同时指定NameNode配置dfs.namenode.edits.dir没有持久化存储目录。

有关创建Backup node和Checkpoint node动机的讨论，参见HADOOP-4539。
命令使用，参见 namenode。

Import Checkpoint

如果image的其他副本和edits文件全部丢失，最近的checkpoint可以被导入到NameNode。操作如下：

创建一个在dfs.namenode.name.dir变量中指定的空目录
在配置文件变量dfs.namenode.checkpoint.dir指定checkpoint 目录的位置
以 -importCheckpoint 参数启动NameNode

NameNode将从dfs.namenode.checkpoint.dir目录上传checkpoint，然后保存到dfs.namenode.name.dir目录。如果dfs.namenode.name.dir目录已经存在合法Image，则失败。NameNode验证dfs.namenode.checkpoint.dir下image的一致性，但是不会以任何方式修改。

命令使用，参见 namenode.

Balancer

HDFS数据跨DataNode的遍布可能是不一致的。一个常见原因是向现有集群添加新DataNodes。当放置新数据块时，(文件作为一系列块存储)，NameNode在选择哪些DataNodes接受这些数据块前会考虑很多因素。比如：

将块的副本之一放在写入该块的同一台node上
需要将块的副本放置与不同机架上，这样即使整个机架故障也不影响集群
副本之一通常放置于写文件的node的同一机架上，这样可以减少跨机架的网络I/O
将HDFS数据均匀的分布于集群的DataNodes上

基于多种因素，数据可能不会均衡的分布于DataNodes上。HDFS提供了一个工具给管理员用于分析块的散步情况和重新在DataNode间平衡数据。Balancer的主要管理员手册参见HADOOP-1652.

命令行使用，参见balancer.

Rack Awareness

HDFS集群可以识别nodes所在racks的拓扑结构。为了优化数据容量和使用率，配置拓扑是非常重要的。详细信息请参见 rack awareness 。

Safemode

在启动时，NameNode从fsimage和edits log文件加载文件系统状态。然后，等待DataNodes报告它们的块，这样就不会过早的开始复制块虽然集群内已经存在足够的副本。在这期间，NameNode保持在Safemode。NameNode的Safemode基本上就是HDFS集群的只读模式，不允许对文件系统和块进行任何修改。通常，在DataNodes报告大多数文件系统的块可用后，NameNode自动离开Safemode。如果需要，HDFS可以使用bin/hdfs dfsadmin -safemode命令明确指定Safemode。NameNode web接口会显示Safemode是on还是off。更多细节描述和配置维护在setSafeMode()的JavaDoc内。

fsck

HDFS支持fsck命令来检查各种不一致性。它被设计用户报告各种文件的问题，比如，文件缺少块或正在复制块。与原生文件系统的传统fsck功能不同，该命令不会修复检测到的错误。通常，NameNode会自动纠正大多数可恢复的故障。默认fsck忽略打开的文件，但是提供了一个选项可以在报告期间选择所有文件。HDFS fsck 命令不是Hadoop shell命令。可以通过bin/hdfs fsck运行。
命令的使用，参见 fsck。fsck可以在整个文件系统或者文件子集上运行。

fetchdt

HDFS支持fetchdt命令获取Delegation Token，并存储到本地文件系统的文件。这个token可以用于从非安全客户端访问安全服务器 (比如 NameNode)。功能使用RPC or HTTPS (over Kerberos)获取token，因此在运行前需要存在kerberos tickets (运行 kinit 获取 tickets)。 HDFS fetchdt 命令不是Hadoop shell命令。它可以通过 bin/hdfs fetchdt DTfile命令运行。获得token后，你可以无需Kerberos tickets运行HDFS command，通过将HADOOP_TOKEN_FILE_LOCATION环境变量指向授权token文件。
命令使用，参见fetchdt 。

Recovery Mode

通常，你会配置多个元数据存储位置。然后，如果一个存储位置损坏了，你可以从其他位置读取元数据。

但是，如果唯一的可用存储位置损坏了怎么办？这种情况下，有一种特殊的NameNode启动模式 Recovery mode ，可以允许你恢复大多数数据。

你可以启动NameNode的recovery mode，如下：namenode -recover

当位于recovery mode，NameNode会在命令行交互的提示可以采用哪些措施恢复数据。

如果你不需要提示，可以使用 -force 选项。该选项将强制recovery mode选择第一选项。通常，这是最合理的选项。

因为Recovery mode可能会导致丢失数据，你应该在使用前备份 edit log 和 fsimage 。

Upgrade and Rollback

当Hadoop在现有集群上升级时，和其他软件升级一样，可能会存在一些以前没发现的bug或者不兼容的变更，影响已经存在的应用。在任何正式HDFS安装中，都不可以丢失数据，更不用说从头重启HDFS。HDFS允许管理员返回到Hadoop的早期版本，并将集群回滚到升级之前的状态。HDFS升级在Hadoop Upgrade Wiki 有更详细的描述。HDFS一次可以有一个这样的备份。升级前，管理员需要删除已有备份，使用命令bin/hadoop dfsadmin -finalizeUpgrade。下面描述主要升级过程：

升级Hadoop前，确认是否已经存在备份
停止集群，分发新版本
以-upgrade参数运行新版本 (sbin/start-dfs.sh -upgrade)
大多数时候，集群工作的很好。一旦新HDFS被认为运行良好 (可能在运行几天后)，完成升级。注意，在集群完成之前，删除升级前存在的文件不会释放DataNodes上的真实磁盘空间。
如果需要回滚到旧版本，
- 停止集群，分发旧版本Hadoop
- 在namenode运行rollback命令(bin/hdfs namenode -rollback)
- 以rollback选项启动集群(sbin/start-dfs.sh -rollback)

当升级到新版本HDFS，有必要重命名或删除新版本HDFS的保留路径。如果NameNode在升级中遇到保留路径，会打印类似如下的报错：

/.reserved is a reserved path and .snapshot is a reserved path component in this version of HDFS. Please rollback and delete or rename this path, or upgrade with the -renameReserved [key-value pairs] option to automatically rename these paths during upgrade.

指定-upgrade -renameReserved [optional key-value pairs]参数会导致NameNode在启动时自动的重命名保留路径。比如，重命名所有.snapshot路径为 .my-snapshot and 重命名.reserved路径为 .my-reserved，一个用户将指定 -upgrade -renameReserved .snapshot=.my-snapshot,.reserved=.my-reserved。

如果-renameReserved没有指定键-值对，NameNode会给保留路径添加后缀：.UPGRADE_RENAMED，比如：snapshot.-51.UPGRADE_RENAMED。

重命名过程有些注意事项。如果可以，建议在升级前，首先hdfs dfsadmin -saveNamespace。这是因为，如果编辑日志操作引用自动重命名的文件的目标，可能会导致数据不一致。

DataNode Hot Swap Drive

Datanode支持热插拔。用户可以添加、替换HDFS数据卷而不需要关闭DataNode。如下主要描述了典型的热插拔过程：

如果有新存储目录，用户应该格式化并合适的挂载它们
用户升级DataNode配置dfs.datanode.data.dir来反映将被使用的数据卷目录
用户运行dfsadmin -reconfig datanode HOST:PORT start来启动重配置进程。用户可以使用dfsadmin -reconfig datanode HOST:PORT status来查询重配置任务的运行状态。
一旦重新配置完成，用户就可以安全的卸载数据卷目录并物理的移除磁盘

File Permissions and Security

文件权限被设计成与其他熟悉的平台（比如Linux）类似。目前，安全性仅限于简单的文件权限。启动NameNode的用户被视为HDFS的superuser。HDFS的未来版本将支持网络认证协议，比如Kerberos，来提供用户认证和数据传输加密。更多的细节在 Permissions Guide 有所讨论。

Scalability

Hadoop目前运行在有数千节点的集群上。 PoweredBy Wiki 页面列出了在大型集群上部署Hadoop的组织。HDFS每个集群都有一个NameNode。目前NameNode上总可用内存是主要扩展限制。在非常大的集群上，增加HDFS上文件的大小可以提升集群大小而不用增加NameNode的内存需求。默认设置不适合大集群。FAQ Wiki 列出了大型集群的配置优化建议。