# HDFS客户端使用实践
#### 操作场景
该任务指导用户在运维场景或业务场景中使用HDFS客户端对HDFS文件系统进行操作，例如读文件、写文件等操作。
#### 前提条件
- 已安装客户端。 例如安装目录为"/opt/client"，以下操作的客户端目录只是举例，请根据实际安装目录修改。
  
- 各组件业务用户由MRS集群管理员根据业务需要创建。安全模式下，"机机"用户需要下载keytab文件。"人机"用户第一次登录时需修改密码。（普通模式不涉及）
 
#### 使用HDFS客户端
1. 安装客户端，如果已安装则跳过。 
   例如安装目录为"/opt/client"，以下操作的客户端目录只是举例，请根据实际安装目录修改。
   下载并安装集群客户端的具体操作，请参考[安装MRS集群客户端](https://support.huaweicloud.com/usermanual-mrs/mrs_01_0089.html)。
   
   
2. 以客户端安装用户，登录安装客户端的节点。
3. 执行以下命令，切换到客户端安装目录，例如"/opt/client"。 
   ```
   cd /opt/client
   ```
   
   
4. 执行以下命令配置环境变量。 
   ```
   source bigdata_env
   ```
   
   
5. 如果集群为安全模式，执行以下命令进行用户认证。普通模式集群无需执行用户认证。 
   ```
   kinit 组件业务用户
   ```
   
   
6. 执行HDFS Shell命令。例如： 
   ```
   hdfs dfs -ls /
   ```
   
   
 
#### HDFS客户端常用命令
- **HDFS客户端常用命令**
  常用的HDFS客户端命令如[表1]所示。
   表1HDFS客户端常用命令 
  | 说明              | 命令                                           | 描述                                                                                                                                     |
  |:---|:---|:---|
  | 创建文件夹           | **hdfs dfs -mkdir** *文件夹名称*                  | 例如，创建"/tmp/mydir"文件夹： **hdfs dfs -mkdir /tmp/mydir**                             |
  | 查看文件夹           | **hdfs dfs -ls** *文件夹名称*                     | **hdfs dfs -ls /tmp**                                                                                                                  |
  | 上传本地文件到HDFS指定路径 | **hdfs dfs -put** *客户端节点上本地文件* *HDFS指定路径*    | 例如，上传客户端节点"/opt/test.txt"文件到HDFS的"/tmp"路径下： **hdfs dfs -put /opt/test.txt /tmp** |
  | 下载HDFS文件到本地指定路径 | **hdfs dfs -get** *HDFS指定文件* *客户端节点上* *指定路径* | 例如，下载HDFS的"/tmp/test.txt"文件到客户端节点的"/opt"路径下： **hdfs dfs -get /tmp/test.txt /opt/**  |
  | 删除文件夹           | **hdfs dfs -rm -r -f** *HDFS指定文件夹*           | 例如，删除"/tmp/mydir"文件夹： **hdfs dfs -rm -r -f /tmp/mydir**                            |
  | 为用户设置HDFS目录权限   | **hdfs dfs -chmod** *权限参数 文件目录*              | 例如，为"/tmp/test"目录设置700权限： **hdfs dfs -chmod 700 /tmp/test**                        |
     
  
- **透明加密相关命令**
  表2透明加密相关命令 
  | **操作** | **命令**                                                                                                                                                                            | **描述**                                                                                                                                                                                                                                                                      |
  |:---|:---|:---|
  | 创建密钥   | **hadoop key create** *\<keyname\> \[-cipher \<cipher\>\] \[-size \<size\>\] \[-description \<description\>\] \[-attr \<attribute=value\>\] \[-provider \<provider\>\] \[-help\]* | create子命令为provider中\<keyname\>参数指定的name创建一个新的密钥，provider是由-provider参数指定。用户可以使用参数-cipher定义一个密码。目前默认的密码为"AES/CTR/NoPadding"。 默认密钥的长度为128。用户可以使用参数-size定义需要的密钥的长度。任意的attribute=value类型属性可以用参数-attr定义。每一个属性，-attr可以被定义多次。 |
  | 回滚操作   | **hadoop key roll** *\<keyname\> \[-provider \<provider\>\] \[-help\]*                                                                                                            | roll子命令为provider中指定的key创建一个新的版本，provider是由-provider参数指定。                                                                                                                                                                                                                    |
  | 删除密钥   | **hadoop key delete** *\<keyname\> \[-provider \<provider\>\] \[-f\] \[-help\]*                                                                                                   | delete子命令删除key的所有版本，key是由provider中的\<keyname\>参数指定，provider是由-provider参数指定。除非-f被指定否则该命令需要用户确认。                                                                                                                                                                              |
  | 查看密钥   | **hadoop key list** *\[-provider \<provider\>\] \[-metadata\] \[-help\]*                                                                                                          | list子命令显示provider中所有的密钥名，这个provider由用户在core-site.xml中配置或者由-provider参数指定。-metadata参数显示的是元数据。                                                                                                                                                                                 |
     
  
- **Colocation客户端Shell命令**
  表3Colocation客户端Shell命令 
  | 操作                    | 命令                                                                                                                                                                                                                                | 描述                                                                                                                                              |
  |:---|:---|:---|
  | 创建组                   | **hdfs colocationadmin -createGroup -groupId** *\<groupID\>* **-locatorIds** *\<comma separated locatorIDs\>* **or -file** *\<path of the file contains all of locatorIDs\>* | 创建组，groupID为组名，locatorID为locator名，locatorID可通过命令行输入，多个locatorID之间用逗号分隔；也可将locatorID写入文件，通过读文件获取。                                                |
  | 删除组                   | **hdfs colocationadmin -deleteGroup** *\<groupID\>*                                                                                                                                                                               | 删除指定组。                                                                                                                                          |
  | 查询组                   | **hdfs colocationadmin -queryGroup** *\<groupID\>*                                                                                                                                                                                | 查询指定组的详细信息，包括该group包含的locators以及每个locator及其对应的DataNode。                                                                                         |
  | 查看所有组                 | **hdfs colocationadmin -listGroups**                                                                                                                                                                                              | 列出所有组及其创建时间。                                                                                                                                    |
  | 设置colocation根目录的acl权限 | **hdfs colocationadmin -setAcl**                                                                                                                                                                                                  | 设置ZooKeeper中colocation根目录的ACL权限。 colocation在ZooKeeper中的根目录默认为"/hadoop/colocationDetails"。 |
     
  
 
#### 相关文档
- 如果HDFS客户端写文件close失败，客户端提示数据块没有足够副本数，处理方法请参见[HDFS客户端写文件close失败](https://support.huaweicloud.com/trouble-mrs/mrs_03_0081.html)。
- 如果需要调整客户端日志级别，处理方法请参见[调整HDFS Shell客户端日志级别](https://support.huaweicloud.com/trouble-mrs/mrs_03_0086.html)。
- 如果使用HDFS客户端命令删除超长目录报错，处理方法请参见[HDFS客户端无法删除超长目录](https://support.huaweicloud.com/trouble-mrs/mrs_03_0319.html)。
- 如果集群外节点安装客户端使用hdfs命令上传文件失败，报错no route to host，处理方法请参见[集群外节点安装客户端上传HDFS文件失败](https://support.huaweicloud.com/trouble-mrs/mrs_03_0259.html)。
- 更多使用HDFS客户端常见问题如下：
 
#### 执行HDFS客户端命令时，报错"java.lang.OutOfMemoryError"
当执行HDFS客户端命令时，客户端程序异常退出，报"java.lang.OutOfMemoryError"的错误。
该问题是由于HDFS客户端运行时所需的内存超过了HDFS客户端设置的内存上限（默认为128MB）。可以通过修改"*\<客户端安装路径\>*/HDFS/component_env"中的"CLIENT_GC_OPTS"来修改HDFS客户端的内存上限。例如，需要设置该内存上限为1GB，则设置：
```
CLIENT_GC_OPTS="-Xmx1G"
```
在修改完后，使用如下命令刷新客户端配置，使之生效：
```
source <客户端安装路径>/bigdata_env
```
#### 如何设置HDFS客户端运行时的日志级别？
HDFS客户端运行时的日志是默认输出到管理控制台的，其级别默认为INFO。如果需要开启DEBUG级别日志，可以通过导出一个环境变量来设置，命令如下：
```
export HADOOP_ROOT_LOGGER=DEBUG,console
```
在执行完上面命令后，再执行HDFS Shell命令时，即可打印出DEBUG级别日志。
如果想恢复INFO级别日志，可执行如下命令：
```
export HADOOP_ROOT_LOGGER=INFO,console
```
#### 如何彻底删除HDFS文件？
由于HDFS的回收站机制，一般删除HDFS文件后，文件会移动到HDFS的回收站中。如果确认文件不再需要并且需要立马释放存储空间，可以继续清理对应的回收站目录（例如：hdfs://hacluster/user/*xxx* /.Trash/Current/*xxx*）。
- 使用HDFS客户端相关更多命令可参考[User_Commands](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/CommandsManual.html#User_Commands)、[FileSystemShell](https://hadoop.apache.org/docs/r3.1.1/hadoop-project-dist/hadoop-common/FileSystemShell.html)。