Apache Ranger 2.6.0 常用 CLI 命令与工具详解

Apache Ranger 2.6.0 常用 CLI 命令与工具详解：服务启停与 metric 查询、setup.sh 初始化、changepasswordutil 改密、HDFS 插件脚本及 REST API 管理，命令与回显均实测。

Apache RangerApache Ranger2026/10/13

Apache Ranger 2.6.0 常用 CLI 命令与工具详解

目标：详解 Apache Ranger 2.6.0 Admin 的常用命令行工具——ranger-admin-services.sh 服务生命周期管理与指标查询、setup.sh 初始化、changepasswordutil.py 密码修改、HDFS 插件启停脚本，以及 curl 调 REST API 管理服务仓库。所有命令与回显均为真实环境实测。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Apache Ranger：2.6.0，安装目录 /opt/ranger-admin
  • 服务脚本：/opt/ranger-admin/ews/ranger-admin-services.sh
  • 初始化脚本：/opt/ranger-admin/setup.sh、/opt/ranger-admin/db_setup.py
  • 改密工具：/opt/ranger-admin/changepasswordutil.py
  • 管理台端口：6080（REST API 入口）
  • 审计存储：Solr 8.11.4（端口 6083，collection ranger_audits）
  • 示例账号：admin（改密后密码 Q1w2e3r4）

二、工具概览

工具位置用途
ranger-admin-services.sh/opt/ranger-admin/ews/启动/停止/重启 Admin 服务、查询版本与指标
setup.sh/opt/ranger-admin/初始化安装（建库建表、部署 webapp、建系统用户）
db_setup.py/opt/ranger-admin/setup.sh 内部调用的数据库初始化/补丁脚本
changepasswordutil.py/opt/ranger-admin/修改 Ranger 用户密码
enable-hdfs-plugin.sh / disable-hdfs-plugin.sh/opt/ranger-hdfs-plugin/HDFS 插件启用/禁用（以 HDFS 为例）
curl系统自带调用管理台 REST API（登录、服务仓库管理）
jpsJDK 自带查看 Java 进程及 JVM 参数生效值

三、前置条件

  • Ranger Admin 已按《Ubuntu 22.04 安装 Apache Ranger 2.6.0 指南》安装完成（setup.sh 已执行、服务已启动）。
  • 已安装 openjdk-8-jdk-headless（含 jps）、net-tools、curl。
  • 执行 setup.sh / 插件脚本前需 export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64。

四、工具详解

4.1 ranger-admin-services.sh 服务管理命令

服务脚本位于 /opt/ranger-admin/ews/，仅支持 5 种子命令：

Usage: Only start | stop | restart | metric | version, are supported.
For metric Usage: metric -type policies | audits | usergroup | services | database | contextenrichers | denyconditions
命令说明
start启动 Admin 服务（写 PID 到 /var/run/ranger/rangeradmin.pid）
stop停止服务
restart重启服务
metric -type <类别>查询指标计数（policies/audits/usergroup/services/database/contextenrichers/denyconditions）
version打印版本与构建信息
status不支持（回显见 4.1.5）

4.1.1 启动

bash /opt/ranger-admin/ews/ranger-admin-services.sh start

回显：

Starting Apache Ranger Admin Service
Apache Ranger Admin Service with pid 21292 has started.

4.1.2 停止

bash /opt/ranger-admin/ews/ranger-admin-services.sh stop

回显：

Getting pid from /var/run/ranger/rangeradmin.pid ..
Found Apache Ranger Admin Service with pid 21292, Stopping it...
Apache Ranger Admin Service with pid 21292 has been stopped.

4.1.3 重启

bash /opt/ranger-admin/ews/ranger-admin-services.sh restart

回显：

Found Apache Ranger Admin Service with pid 21655, Stopping it...
Apache Ranger Admin Service with pid 21655 has been stopped.
Starting Apache Ranger Admin Service
Apache Ranger Admin Service with pid 22669 has started.

4.1.4 查询版本

bash /opt/ranger-admin/ews/ranger-admin-services.sh version

回显：

Ranger 2.6.0
Subversion git://21127//private/tmp/release-2.6.0/ranger/ranger-util/src -r a1786ac2fe02196af9cda2ed25716310cac44d43
Compiled by abhishek.kumar on 10:19PM on February 28, 2025
From source with checksum a0c9e2d6f7ad361970fef780c8740e76ed3265de2ea72b612678e20d3ed01f18b3101dd48c5c57f663a7bc3a84e01e28ff7cd5355202548b6b967b9f570dfc9d

4.1.5 查询指标

bash /opt/ranger-admin/ews/ranger-admin-services.sh metric -type services

回显：

{"serviceBasedCountList":{"hdfs":1,"tag":1},"totalCount":2}

4.1.6 status 命令（不支持）

bash /opt/ranger-admin/ews/ranger-admin-services.sh status

回显：

Invalid argument [status];
Usage: Only start | stop | restart | metric | version, are supported.
For metric Usage: metric -type policies | audits | usergroup | services | database | contextenrichers | denyconditions

⚠️ 服务状态排查以端口与日志为准：ss -tlnp | grep 6080 应看到 *:6080 LISTEN；日志目录 /var/log/ranger/admin/。

4.2 setup.sh 初始化命令

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
cd /opt/ranger-admin && bash setup.sh

setup.sh 完成：校验 Java/驱动/文件 → 建系统用户 ranger → 复制 MySQL 驱动 → 导入 ranger_core_db_mysql.sql schema → 应用 DB/JAVA 补丁 → 改密环节（密码非默认时可能失败，不阻断）→ 部署 webapp。

关键回显（logfile 摘要）：

[I] Setting up UNIX user : ranger and group: ranger DONE
[I] Copying MYSQL Connector to /opt/ranger-admin/ews/webapp/WEB-INF/lib DONE
[I] Importing DB schema to database ranger from file: ranger_core_db_mysql.sql
[I] ranger_core_db_mysql.sql file imported successfully
[I] CORE_DB_SCHEMA import status has been updated
[I] DB_PATCHES have already been applied
[I] JAVA_PATCHES have already been applied
[I] Checking connection passed.
[I] Starting setup based on user authentication method=NONE
[I] Finished setup based on user authentication method=NONE

⚠️ 常见失败：未 export JAVA_HOME 报 [E] JAVA_HOME environment property not defined, aborting installation.；未先建库建用户报 Access denied（见 FAQ 6.2）。

4.3 changepasswordutil.py 改密命令

用法：python3 changepasswordutil.py <loginID> <currentPassword> <newPassword>。

cd /opt/ranger-admin && python3 changepasswordutil.py admin admin Q1w2e3r4

回显：

2026-10-12 16:53:22,664  [I] Password updated successfully

验证新密码生效（旧密码登录失败）：

curl -s -X POST http://localhost:6080/login -d "username=admin&password=Q1w2e3r4"

回显：

{"statusCode":200,"msgDesc":"Login Successful"}

curl -s -X POST http://localhost:6080/login -d "username=admin&password=admin"

回显：

{"statusCode":401,"msgDesc":"The username or password you entered is incorrect."}

💡 密码策略：至少 8 位且同时含大写字母、小写字母、数字。演示密码 q1w2e3r4 不含大写不满足策略，Q1w2e3r4 符合。

4.4 HDFS 插件启停脚本

插件目录 /opt/ranger-hdfs-plugin/，含 enable-hdfs-plugin.sh / disable-hdfs-plugin.sh（另有 install、upgrade-hdfs-plugin.sh、upgrade-plugin.py）。

4.4.1 启用插件

启用前先 export JAVA_HOME（未设置时报 ERROR: JAVA_HOME environment property not defined, aborting installation.）：

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
bash /opt/ranger-hdfs-plugin/enable-hdfs-plugin.sh

回显（节选）：

Custom group is available, using default user and custom group.
+ Mon Oct 12 16:59:10 UTC 2026 : hadoop: lib folder=/opt/hadoop/share/hadoop/hdfs/lib conf folder=/opt/hadoop/etc/hadoop
+ ... Saving /opt/hadoop/etc/hadoop/ranger-hdfs-audit.xml to .ranger-hdfs-audit.xml.20261012-165910 ...
+ ... Saving /opt/hadoop/etc/hadoop/ranger-hdfs-security.xml ...
+ ... Saving /opt/hadoop/etc/hadoop/ranger-policymgr-ssl.xml ...
+ ... Saving current config file: /opt/hadoop/etc/hadoop/hdfs-site.xml ...
+ ... Saving current JCE file: /etc/ranger/rangerdevhdfs/cred.jceks ...
Ranger Plugin for hadoop has been enabled. Please restart hadoop services.

4.4.2 禁用插件

bash /opt/ranger-hdfs-plugin/disable-hdfs-plugin.sh

禁用脚本回滚 enable 时对 hdfs-site.xml / ranger-*.xml 的注入，并清理 /etc/ranger/<repo> 下的 cred.jceks 与 policycache。

4.5 curl REST API 管理命令

管理台 REST API 基址 http://localhost:6080，需先登录拿 cookie。

4.5.1 登录

curl -s -c /tmp/ranger_cookies.txt -X POST http://localhost:6080/login -d "username=admin&password=Q1w2e3r4"

回显：

{"statusCode":200,"msgDesc":"Login Successful"}

4.5.2 查询服务仓库列表

curl -s -b /tmp/ranger_cookies.txt http://localhost:6080/service/plugins/services

回显：

{"startIndex":0,"pageSize":0,"totalCount":2,"resultSize":2,..."services":[{"name":"rangerdevhdfs","type":"hdfs"},{"name":"tag","type":"tag"}]}

4.5.3 创建服务仓库

首次创建缺必填参数回显（错误码 1011 列出缺失参数）：

curl -s -b /tmp/ranger_cookies.txt -X POST http://localhost:6080/service/plugins/services \
  -H "Content-Type: application/json" \
  -d '{"name":"rangerdevhdfs","type":"hdfs","configs":{"username":"hadoop","password":"q1w2e3r4","namenode_url":"hdfs://localhost:8020","enable":"true"}}'

回显：

{"statusCode":1,"msgDesc":"(0) Validation failure: error code[1011], reason[Missing required configuration parameter(s): missing parameters=[hadoop.security.authentication, fs.default.name, hadoop.security.authorization]], field[configuration], subfield[hadoop.security.authentication], type[missing] "}

补全必填参数后创建成功：

curl -s -b /tmp/ranger_cookies.txt -X POST http://localhost:6080/service/plugins/services \
  -H "Content-Type: application/json" \
  -d '{"name":"rangerdevhdfs","type":"hdfs","configs":{"username":"hadoop","password":"q1w2e3r4","namenode_url":"hdfs://localhost:8020","hadoop.security.authentication":"simple","hadoop.security.authorization":"false","fs.default.name":"hdfs://localhost:8020","enable":"true"}}'

回显（节选）：

{"id":1,"guid":"78baf720-47c1-4933-8382-41624e80ef26","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":...,"type":"hdfs","name":"rangerdevhdfs","displayName":"rangerdevhdfs",...}

4.5.4 REST 端点速查

端点方法说明
/loginPOST登录（表单 username/password，写 cookie）
/service/plugins/servicesGET服务仓库列表
/service/plugins/servicesPOST创建服务仓库（必填 name/type/configs）
/service/plugins/services/{id}GET查看单个服务
/service/plugins/services/{id}DELETE删除服务仓库

4.6 审计存储验证命令（Solr）

Ranger 审计写入 Solr（6083），用 curl 校验 core 状态与数据：

curl -s "http://localhost:6083/solr/admin/cores?action=STATUS"

回显（节选）：

"ranger_audits":{
  "name":"ranger_audits",
  "instanceDir":"/opt/solr/ranger_audit_server/ranger_audits",
  "dataDir":"/opt/solr/ranger_audit_server/data/",
  "config":"solrconfig.xml",
  "schema":"managed-schema",
  "index":{"numDocs":0,...}}

💡 审计由各数据组件 agent 上报，管理台刚装完时 numDocs=0 属正常；有组件操作后（如 HDFS 访问）会持续增长。

4.7 JVM 参数生效值校验（jps）

修改 /opt/ranger-admin/ews/ranger-admin-services.sh（-Xms256m -Xmx512m）并重启后，用 jps 核对：

jps -v | grep EmbeddedServer

回显（节选，可见 -Xms256m -Xmx512m 生效）：

21655 EmbeddedServer -Dproc_rangeradmin ... -Xmx512m -Xms256m -Xloggc:/var/log/ranger/admin/gc-worker.log ...

五、注意事项

  • ranger-admin-services.sh 不支持 status，服务状态以 ss -tlnp | grep 6080 + /var/log/ranger/admin/ 日志为准。
  • setup.sh 与插件脚本执行前必须先 export JAVA_HOME，否则立即中止。
  • 改密密码必须满足策略（≥8 位 + 大写 + 小写 + 数字），否则 changepasswordutil.py 或管理台改密失败。
  • REST 创建服务仓库需补齐组件必填参数（HDFS 缺 hadoop.security.authentication、fs.default.name、hadoop.security.authorization 时返回错误码 1011）。
  • 登录 cookie 保存在 -c 指定的文件，后续请求用 -b 携带；cookie 过期后需重新登录。
  • 每条命令逐个单独执行；管理多个仓库/服务时逐条操作，避免批量循环。

六、常见问题

6.1 执行 status 报 Invalid argument [status]

原因：ranger-admin-services.sh 只支持 start|stop|restart|metric|version。

解决：用 bash ranger-admin-services.sh metric -type services 或 ss -tlnp | grep 6080 确认服务状态。

6.2 setup.sh / 插件脚本报 JAVA_HOME environment property not defined

解决：执行 export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 后重跑。

6.3 changepasswordutil.py 报密码不符合策略

错误回显（节选）：

Password should be minimum 8 characters, at least one uppercase letter, one lowercase letter and one numeric.

解决：使用同时含大写、小写、数字且 ≥8 位的密码，如演示密码 Q1w2e3r4。

6.4 登录返回 401 The username or password you entered is incorrect.

解决：确认密码已被修改（setup 改密失败时 admin 仍为默认 admin/admin）；或重新执行 python3 /opt/ranger-admin/changepasswordutil.py admin <旧密码> <新密码> 重置。

七、参考链接