离线镜像查看器(Offline Image Viewer)是一款用于将HDFS fsimage文件内容转储为人类可读格式的工具，并提供只读的WebHDFS API接口，以便对Hadoop集群的命名空间进行离线分析和检查。该工具能够相对快速地处理非常大的镜像文件。它支持Hadoop 2.4及以上版本包含的布局格式。如需处理旧版布局格式，可以使用Hadoop 2.3的离线镜像查看器或oiv_legacy命令。若工具无法处理某个镜像文件，它将正常退出。离线镜像查看器不需要运行Hadoop集群即可工作，其操作完全处于离线状态。
离线镜像查看器提供了多种输出处理器：
Web是默认的输出处理器。它会启动一个HTTP服务器，提供只读的WebHDFS API接口。用户可以通过HTTP REST API交互式地查看命名空间。该处理器不支持安全模式，也不支持HTTPS。
XML会生成fsimage的XML文档，其中包含fsimage内的所有信息。该处理器的输出适合使用XML工具进行自动化处理和分析。由于XML语法的冗长性，此处理器也会产生最大量的输出。
FileDistribution 是用于分析命名空间镜像中文件大小的工具。要运行该工具，用户需通过指定maxSize和step来定义一个整数范围[0, maxSize]。该整数范围会被划分为大小为step的多个区间：[0, s[1], ..., s[n-1], maxSize]，处理器会计算系统中落入每个区间[s[i-1], s[i])的文件数量。请注意，大于maxSize的文件总是归入最后一个区间。默认情况下，输出文件格式为制表符分隔的两列表格：Size（区间起始值）和NumFiles（该区间内文件数量）。若指定-format选项，输出文件将以更易读的格式呈现，而非显示Size列中的字节数。此外，Size列将变更为Size Range列。
分隔符（实验性功能）：生成一个文本文件，包含inodes和inodes-under-construction共有的所有元素，并使用分隔符隔开。默认分隔符是\t，但可以通过-delimiter参数修改。
DetectCorruption (实验性功能): 通过选择性加载镜像部分内容并主动搜索不一致性，检测镜像可能存在的损坏。以分隔格式输出发现的损坏摘要。请注意，该检查并不全面，仅能在命名空间重建过程中捕获缺失节点。
ReverseXML (实验性功能): 这是XML处理器的反向操作；它能从XML文件重建fsimage。该处理器便于创建测试用的fsimage，并在文件损坏时手动编辑fsimage。
Web处理器启动一个HTTP服务器，该服务器提供只读的WebHDFS API接口。用户可以通过-addr选项指定监听地址（默认为localhost:5978）。
bash$ bin/hdfs oiv -i fsimage 14/04/07 13:25:14 INFO offlineImageViewer.WebImageViewer: WebImageViewer started. Listening on /127.0.0.1:5978. Press Ctrl+C to stop the viewer.
用户可以通过以下shell命令访问查看器并获取fsimage的信息：
bash$ bin/hdfs dfs -ls webhdfs://127.0.0.1:5978/ Found 2 items drwxrwx--* - root supergroup 0 2014-03-26 20:16 webhdfs://127.0.0.1:5978/tmp drwxr-xr-x - root supergroup 0 2014-03-31 14:08 webhdfs://127.0.0.1:5978/user
要获取所有文件和目录的信息，您只需使用以下命令：
bash$ bin/hdfs dfs -ls -R webhdfs://127.0.0.1:5978/
用户还可以通过HTTP REST API获取JSON格式的FileStatuses。
bash$ curl -i http://127.0.0.1:5978/webhdfs/v1/?op=liststatus
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 252
{"FileStatuses":{"FileStatus":[
{"fileId":16386,"accessTime":0,"replication":0,"owner":"theuser","length":0,"permission":"755","blockSize":0,"modificationTime":1392772497282,"type":"DIRECTORY","group":"supergroup","childrenNum":1,"pathSuffix":"user"}
]}}
Web处理器现在支持以下操作：
XML处理器用于转储fsimage中的所有内容。用户可以通过-i和-o命令行参数指定输入和输出文件。
bash$ bin/hdfs oiv -p XML -i fsimage -o fsimage.xml
这将创建一个名为fsimage.xml的文件，其中包含fsimage中的所有信息。对于非常大的镜像文件，此过程可能需要几分钟时间。
使用离线镜像查看器配合XML处理器将产生以下输出：
<?xml version="1.0"?>
<fsimage>
<NameSection>
<genstampV1>1000</genstampV1>
<genstampV2>1002</genstampV2>
<genstampV1Limit>0</genstampV1Limit>
<lastAllocatedBlockId>1073741826</lastAllocatedBlockId>
<txid>37</txid>
</NameSection>
<INodeSection>
<lastInodeId>16400</lastInodeId>
<inode>
<id>16385</id>
<type>DIRECTORY</type>
<name></name>
<mtime>1392772497282</mtime>
<permission>theuser:supergroup:rwxr-xr-x</permission>
<nsquota>9223372036854775807</nsquota>
<dsquota>-1</dsquota>
</inode>
...remaining output omitted...
ReverseXML处理器与XML处理器功能相反。用户可以通过命令行参数-i和-o指定输入XML文件和输出fsimage文件。
bash$ bin/hdfs oiv -p ReverseXML -i fsimage.xml -o fsimage
这将从XML文件重建一个fsimage。
FileDistribution处理器可以分析命名空间镜像中的文件大小。用户可以通过命令行参数-maxSize和-step以字节为单位指定最大大小（默认为128GB）和步长（默认为2MB）。
bash$ bin/hdfs oiv -p FileDistribution -maxSize maxSize -step size -i fsimage -o output
处理器将计算系统中有多少文件属于每个分段。输出文件格式为一个以制表符分隔的两列表格，如下所示：
Size NumFiles 4 1 12 1 16 1 20 1 totalFiles = 4 totalDirectories = 2 totalBlocks = 4 totalSpace = 48 maxFileSize = 21
为了使输出结果看起来更易读，用户还可以额外指定-format选项。
bash$ bin/hdfs oiv -p FileDistribution -maxSize maxSize -step size -format -i fsimage -o output
这将产生以下输出：
Size Range NumFiles (0 B, 4 B] 1 (8 B, 12 B] 1 (12 B, 16 B] 1 (16 B, 21 B] 1 totalFiles = 4 totalDirectories = 2 totalBlocks = 4 totalSpace = 48 maxFileSize = 21
分隔符处理器生成fsimage的文本表示，其中每个元素由分隔符字符串（默认为\t）分隔。用户可以通过-delimiter选项指定新的分隔符字符串。
bash$ bin/hdfs oiv -p Delimited -delimiter delimiterString -i fsimage -o output
此外，用户可以通过以下命令指定临时目录来缓存中间结果：
bash$ bin/hdfs oiv -p Delimited -delimiter delimiterString -t temporaryDir -i fsimage -o output
如果未设置，Delimited处理器将在内存中构建命名空间后再输出文本。该处理器的输出结果应如下所示：
Path Replication ModificationTime AccessTime PreferredBlockSize BlocksCount FileSize NSQUOTA DSQUOTA Permission UserName GroupName / 0 2017-02-13 10:39 1970-01-01 08:00 0 0 0 9223372036854775807 -1 drwxr-xr-x root supergroup /dir0 0 2017-02-13 10:39 1970-01-01 08:00 0 0 0 -1 -1 drwxr-xr-x root supergroup /dir0/file0 1 2017-02-13 10:39 2017-02-13 10:39 134217728 1 1 0 0 -rw-r--r-- root supergroup /dir0/file1 1 2017-02-13 10:39 2017-02-13 10:39 134217728 1 1 0 0 -rw-r--r-- root supergroup /dir0/file2 1 2017-02-13 10:39 2017-02-13 10:39 134217728 1 1 0 0 -rw-r--r-- root supergroup
DetectCorruption处理器会生成fsimage错误的文本表示（如果存在）。它显示以下情况：
在fsimage中提到了一个inode，但没有找到相关的元数据（CorruptNode）
一个inode至少有一个损坏的子节点（MissingChildren）
分隔符字符串可以通过-delimiter选项提供，处理器可以使用-t选项缓存中间结果。
bash$ bin/hdfs oiv -p DetectCorruption -delimiter delimiterString -t temporaryDir -i fsimage -o output
如果未发现损坏，此处理器的输出结果为空；否则，将以下列格式显示发现的条目：
CorruptionType Id IsSnapshot ParentPath ParentId Name NodeType CorruptChildren
MissingChild 16385 false / Missing Node 1
MissingChild 16386 false / 16385 dir0 Node 2
CorruptNode 16388 true 16386 Unknown 0
CorruptNode 16389 true 16386 Unknown 0
CorruptNodeWithMissingChild 16391 true 16385 Unknown 1
CorruptNode 16394 true 16391 Unknown 0
CorruptionType列可以是MissingChild（缺失子节点）、CorruptNode（损坏节点）或这两者的组合。IsSnapshot显示该节点是否保存在快照中。NodeType列根据节点类型可填写Node（节点）、Ref（引用）或Unknown（未知）——分别对应正常inode节点、引用节点或因损坏而无法识别的节点。CorruptChildren字段记录该inode可能包含的损坏子节点数量。
| 标志 | 描述 |
|---|---|
-i|--inputFile input file |
Specify the input fsimage file (or XML file, if ReverseXML processor is used) to process. Required. |
-o|--outputFile output file |
Specify the output filename, if the specified output processor generates one. If the specified file already exists, it is silently overwritten. (output to stdout by default) If the input file is an XML file, it also creates an <outputFile>.md5. |
-p|--processor processor |
Specify the image processor to apply against the image file. Currently valid options are Web (default), XML, Delimited, DetectCorruption, FileDistribution and ReverseXML. |
-addr address |
Specify the address(host:port) to listen. (localhost:5978 by default). This option is used with Web processor. |
-maxSize size |
Specify the range [0, maxSize] of file sizes to be analyzed in bytes (128GB by default). This option is used with FileDistribution processor. |
-step size |
Specify the granularity of the distribution in bytes (2MB by default). This option is used with FileDistribution processor. |
-format |
Format the output result in a human-readable fashion rather than a number of bytes. (false by default). This option is used with FileDistribution processor. |
-delimiter arg |
Delimiting string to use with Delimited or DetectCorruption processor. |
-t|--temp temporary dir |
Use temporary dir to cache intermediate result to generate Delimited outputs. If not set, Delimited processor constructs the namespace in memory before outputting text. |
-h|--help |
Display the tool usage and help information and exit. |
离线镜像查看器可以方便地收集关于hdfs命名空间的大量数据。这些信息随后可用于探索文件系统使用模式，或根据任意条件查找特定文件，以及其他类型的命名空间分析。
由于基于ProtocolBuffer的fsimage（HDFS-5698）引入的内部布局变更，离线镜像查看器会消耗过多内存并丢失部分功能（如缩进处理器）。如需在无需大量内存的情况下处理或使用这些处理器，可以使用oiv_legacy命令（与Hadoop 2.3中的oiv相同）。
将dfs.namenode.legacy-oiv-image.dir设置为适当的目录，以使备用NameNode或SecondaryNameNode在检查点期间以旧的fsimage格式保存其命名空间。
使用oiv_legacy命令处理旧格式的fsimage。
bash$ bin/hdfs oiv_legacy -i fsimage_old -o output
| 标志 | 描述 |
|---|---|
-i|--inputFile input file |
Specify the input fsimage file to process. Required. |
-o|--outputFile output file |
Specify the output filename, if the specified output processor generates one. If the specified file already exists, it is silently overwritten. Required. |
-p|--processor processor |
Specify the image processor to apply against the image file. Valid options are Ls (default), XML, Delimited, Indented, FileDistribution and NameDistribution. |
-maxSize size |
Specify the range [0, maxSize] of file sizes to be analyzed in bytes (128GB by default). This option is used with FileDistribution processor. |
-step size |
Specify the granularity of the distribution in bytes (2MB by default). This option is used with FileDistribution processor. |
-format |
Format the output result in a human-readable fashion rather than a number of bytes. (false by default). This option is used with FileDistribution processor. |
-skipBlocks |
Do not enumerate individual blocks within files. This may save processing time and outfile file space on namespaces with very large files. The Ls processor reads the blocks to correctly determine file sizes and ignores this option. |
-printToScreen |
Pipe output of processor to console as well as specified file. On extremely large namespaces, this may increase processing time by an order of magnitude. |
-delimiter arg |
When used in conjunction with the Delimited processor, replaces the default tab delimiter with the string specified by arg. |
-h|--help |
Display the tool usage and help information and exit. |