Apache Kerby 2.1.2 常用 CLI 命令与工具详解

目标：掌握 Kerby 2.1.2 服务端与客户端全部命令行工具的调用方式、参数含义与典型输出，可作为 KDC 日常运维的命令手册。已在 Ubuntu 22.04（OpenJDK 17）实测通过。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS
系统架构	x86_64（amd64）
JDK	OpenJDK 17.0.20.1
组件版本	Apache Kerby 2.1.2
服务端工具目录	/opt/kerby/kdc-dist-2.1.2/bin
客户端工具目录	/opt/kerby/tool-dist-2.1.2/bin
示例 Realm	EXAMPLE.COM
示例账号	root@EXAMPLE.COM / admin@EXAMPLE.COM，密码 q1w2e3r4

表后逐项说明：服务端工具（kdcinit/start-kdc/kadmin/admin-server/remote-admin-client）都在 kdc-dist 的 bin；客户端工具（kinit/kinitConcurrent/klist）独立打包在 tool-dist 的 bin；所有命令既可用发行包脚本调用，也可用 java 主类直接调用，本文优先给出主类方式（不受脚本 classpath 相对路径影响）。

二、命令总览与调用模型

2.1 工具清单

工具	所在目录	主类	用途
kdcinit.sh	kdc-dist/bin	org.apache.kerby.kerberos.tool.kdcinit.KdcInitTool	初始化后端并导出管理 keytab
start-kdc.sh	kdc-dist/bin	org.apache.kerby.kerberos.kdc.KerbyKdcServer	启动嵌入式 KDC
kadmin.sh	kdc-dist/bin	org.apache.kerby.kerberos.tool.kadmin.KadminTool	主体增删改查/密码/keytab 管理
admin-server.sh	kdc-dist/bin	org.apache.kerby.kerberos.kerb.admin.server.KerbyAdminServer	独立 kadmin 管理服务
remote-admin-client.sh	kdc-dist/bin	org.apache.kerby.kerberos.kerb.admin.RemoteAdminClientTool	远程管理客户端
kinit.sh	tool-dist/bin	org.apache.kerby.kerberos.tool.kinit.KinitTool	申请初始票据（TGT/ST）
kinitConcurrent.sh	tool-dist/bin	org.apache.kerby.kerberos.tool.kinit.KinitToolWithConcurrence	并发批量认证（预热线程池）
klist.sh	tool-dist/bin	org.apache.kerby.kerberos.tool.klist.KlistTool	查看票据缓存

表后逐项说明：每个脚本内部都是对同名 Java 主类的包装；直接用 java -classpath "lib/*:." 主类名的方式调用等价且更可控（可加 -Xms256m -Xmx256m 限定堆内存）。

💡 技术拓展：MIT Kerberos 的 kadmin 分为 kadmin.local（直连数据库）与 kadmin（走 kadmin 服务）；Kerby 把这一套拆成了 KadminTool（本地后端模式）+ admin-server/remote-admin-client（远程模式），命令子集基本对齐（addprinc/cpw/ktadd 等关键字一致），有 MIT 运维经验可直接迁移。本文实验采用 KadminTool 本地模式。

2.2 通用调用前置

所有工具都依赖 lib 下的 40 个 jar 与 conf 配置，调用前先进入对应目录（脚本使用相对 classpath）：

cd /opt/kerby/kdc-dist-2.1.2
java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kdcinit.KdcInitTool 2>&1 | head -6

实测回显：

Usage: sh bin/kdcinit.sh <conf-dir> <keytab-dir>
        This tool initializes KDC backend and should only be performed the first time,
        and the output keytabs should be carefully kept to administrate/kadmin KDC later.
        Example:
                sh bin/kdcinit.sh conf keytabfolder

说明：不带参数调用任一工具都会打印 Usage 帮助，这是确认每个命令参数格式的最快方法；中文乱码时在命令前加 LC_ALL=C.UTF-8。

三、KDC 初始化工具 kdcinit

3.1 功能与调用

kdcinit 仅需执行一次：在身份后端创建内置主体（kadmin、krbtgt、adminprotocol），并把两个管理凭证导出为 keytab：

cd /opt/kerby/kdc-dist-2.1.2
mkdir -p keytab
java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kdcinit.KdcInitTool conf keytab

实测回显：

The keytab for kadmin principal has been exported to the specified file /opt/kerby/kdc-dist-2.1.2/keytab/admin.keytab, please keep it safe, in order to use kadmin tool later
The keytab for protocol principal has been exported to the specified file /opt/kerby/kdc-dist-2.1.2/keytab/protocol.keytab, please keep it safe, in order to use remote kadmin tool later
Finished initializing the KDC backend

验证产物：

ls -l keytab/

实测回显：

-rw-r--r-- 1 root root 148 Oct 14 17:09 admin.keytab
-rw-r--r-- 1 root root 158 Oct 14 17:09 protocol.keytab

逐项说明：参数一 conf 为配置目录（读取 backend.conf 确定后端与数据目录），参数二 keytab 为凭证导出目录；admin.keytab 对应 kadmin/EXAMPLE.COM@EXAMPLE.COM，供 kadmin 工具使用；protocol.keytab 供远程管理协议使用。

3.2 重复执行的后果

后端已初始化时再次 kdcinit 会重置内置主体密钥（keyVersion 递增），导致旧的 admin.keytab 失效，因此 keytab 目录务必与执行记录一起保存。

四、KDC 启动工具 start-kdc（KerbyKdcServer）

4.1 用法与参数

cd /opt/kerby/kdc-dist-2.1.2
sh bin/start-kdc.sh

实测回显：

No matches found
Usage: sh bin/start-kdc.sh <conf-dir> <working-dir>
        Example:
                sh bin/start-kdc.sh conf runtime

逐项说明：必须传两个参数——配置目录与工作目录；工作目录必须已存在，否则报 The work-dir is invalid or does not exist。脚本等价的手工启动方式（可加 JVM 参数）：

mkdir -p runtime
nohup java -Xms256m -Xmx256m -classpath "lib/*:." -DKERBY_LOGFILE=kdc org.apache.kerby.kerberos.kdc.KerbyKdcServer -start conf runtime > /tmp/kdc.log 2>&1 &
sleep 10
cat /tmp/kdc.log

实测回显：

KDC started.

4.2 进程与端口验证

jps -v

实测回显：

5721 KerbyKdcServer -Xms256m -Xmx256m -DKERBY_LOGFILE=kdc

python3 -c "import socket;s=socket.socket();print('tcp88_connect',s.connect_ex(('127.0.0.1',88)));s.close()"

实测回显：

tcp88_connect 0

逐项说明：jps -v 一行回显了完整 JVM 参数（堆 256MB 与日志前缀），是确认堆限制的标准手段；端口 connect_ex 为 0 表示 TCP 88 监听正常；停止进程用 jps 找到 PID 后 kill。

五、管理工具 kadmin（KadminTool）

5.1 登录方式与命令列表

cd /opt/kerby/kdc-dist-2.1.2
sh bin/kadmin.sh

实测回显：

Usage: sh bin/kadmin.sh <conf-dir> <-c cache_name>|<-k keytab>
        Example:
                sh bin/kadmin.sh conf -k admin.keytab

逐项说明：kadmin 支持两种身份——-k 指定 keytab（推荐，免密交互）或 -c 指定票据缓存；进入交互界面后输入 ? 可列出全部请求：

printf "?\nquit\n" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kadmin.KadminTool conf -k keytab/admin.keytab

实测回显（节选）：

KadminTool.local: Available KadminTool.local requests:

add_principal, addprinc, ank
                         Add principal
batch_anks, batch
                         Add principals
delete_principal, delprinc
                         Delete principal
modify_principal, modprinc
                         Modify principal
rename_principal, renprinc
                         Rename principal
change_password, cpw     Change password
get_principal, getprinc  Get principal
list_principals, listprincs, get_principals, getprincs
                         List principals
ktadd, xst               Add entry(s) to a keytab
ktremove, ktrem          Remove entry(s) from a keytab
list_requests, lr, ?     List available requests.
quit, exit, q            Exit program.

说明：帮助文本里 add_policy/get_policy 等策略类命令均标注 not implemented（未实现），可用命令集中在主体管理与 keytab 管理两类。

5.2 addprinc：创建主体

printf "addprinc -pw q1w2e3r4 admin@EXAMPLE.COM
quit
" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kadmin.KadminTool conf -k keytab/admin.keytab

实测回显（节选）：

KadminTool.local: Principal "admin@EXAMPLE.COM" created.

说明：-pw 直接在命令行给密码（密码 q1w2e3r4）；交互模式下不带 -pw 会提示输入两遍密码。

5.3 listprincs：列出主体

printf "listprincs
quit
" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kadmin.KadminTool conf -k keytab/admin.keytab

实测回显：

KadminTool.local: Principals are listed:
        admin@EXAMPLE.COM
        adminprotocol/localhost@EXAMPLE.COM
        alice@EXAMPLE.COM
        host/localhost@EXAMPLE.COM
        kadmin/EXAMPLE.COM@EXAMPLE.COM
        krbtgt/EXAMPLE.COM@EXAMPLE.COM
        root@EXAMPLE.COM

5.4 getprinc：查看主体详情

printf "getprinc alice@EXAMPLE.COM
quit
" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kadmin.KadminTool conf -k keytab/admin.keytab

实测回显（节选）：

KadminTool.local: Principal: alice@EXAMPLE.COM
Expiration data: generalized time [tag=0x18, len=2+15] Fri Dec 31 23:59:59 GMT 9999
Created time: generalized time [tag=0x18, len=2+15] Wed Oct 14 17:10:21 GMT 2026
KDC flags: 0
Key version: 1
Number of keys: 2
key: AES128_CTS_HMAC_SHA1_96
key: DES3_CBC_SHA1

逐项说明：输出包含过期时间、创建时间、KDC 标志位、密钥版本号（kvno）与全部加密类型；Expiration 显示 GMT 9999 表示永不过期。

5.5 delprinc / renprinc / cpw

同在交互界面执行，格式为 delprinc 主体名、renprinc 旧名新名、cpw -pw 新密码主体名，均即时写回后端文件（backend.json.dir）。批量建号可用 batch 命令组（batch_anks）。

5.6 ktadd：导出服务 keytab

交互内执行 ktadd host/localhost@EXAMPLE.COM 可把指定主体的当前密钥写入 keytab 文件，供服务端免密认证（如 NFS/HDFS 场景），输出会提示写入路径与条目序号。

六、客户端认证工具 kinit 与 klist

6.1 kinit 申请 TGT

cd /opt/kerby/tool-dist-2.1.2
java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kinit.KinitTool

实测回显（节选）：

No conf dir given.

Usage: sh bin/kinit.sh <-conf conf_dir> [-V] [-l lifetime] [-s start_time]
                [-r renewable_life] [-f | -F] [-p | -P] -n [-a | -A] [-C] [-E]
                [-v] [-R] [-k [-i|-t keytab_file]] [-c cachename]
                [-S service_name] [-T ticket_armor_cache]
                [-X <attribute>[=<value>]] <principal>

逐项说明：-conf 必须指向包含 krb5.conf 的目录；-l/-r 控制 TGT 有效期与续期；-k -t keytab_file 走密钥表认证；-S 直接请求指定服务的票据。

密码认证实测（脚本环境无 TTY，用管道传密码）：

echo "q1w2e3r4" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kinit.KinitTool -conf /opt/kerby/kdc-dist-2.1.2/conf root@EXAMPLE.COM

实测回显：

Couldn't get Console instance, maybe you're running this from within an IDE. Use scanner to read password.
Password for root@EXAMPLE.COM:
Successfully requested and stored ticket in /tmp/krb5cc_0

说明：第一行是无终端环境的提示（预期行为）；票据缓存默认写到 /tmp/krb5cc_0。

6.2 kinit -S 申请服务票据（ST）

先确认服务主体存在（本文已创建 host/localhost@EXAMPLE.COM），再用 TGT 换取 ST：

echo "q1w2e3r4" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kinit.KinitTool -conf /opt/kerby/kdc-dist-2.1.2/conf -S host/localhost@EXAMPLE.COM root@EXAMPLE.COM

实测回显：

Use tgt to request a service ticket.
host/localhost: knvo = 1

逐项说明：knvo 为工具输出的密钥版本号字段（即 kvno，工具拼写如此，照实引用）= 1，表示拿到了 host/localhost 的第一版服务票据；-S 流程复用已有 TGT，不再输密码即可再跑一次。

6.3 klist 查看票据

LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.klist.KlistTool -conf /opt/kerby/kdc-dist-2.1.2/conf

实测回显：

Ticket cache: /tmp/krb5cc_0
Default principal: root@EXAMPLE.COM
Valid starting          Expires                 Service principal
1970-01-01 00:00:00     2026-10-15 17:15:42     krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until     2026-10-16 17:15:42

逐项说明：Valid starting 列的 1970-01-01 是 Kerby klist 对票据内起始时间戳为 0（立即生效）的展示，不代表异常；Expires 与 renew until 均正常；不传 -conf 时 klist 会报 Create krbClient failed: krb5.conf not found，务必带上配置目录。

6.4 kinitConcurrent 并发认证

KinitToolWithConcurrence 与 KinitTool 参数一致，内部预建线程池并把认证请求并发化，适合压测或批量代理场景。调用方式：

java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kinit.KinitToolWithConcurrence -conf /opt/kerby/kdc-dist-2.1.2/conf <principal>

说明：用法与 kinit 相同，额外适合在同一主机对多主体并发出票的测试场景。

七、独立管理服务与远程管理

7.1 admin-server（独立管理服务）

Kerby 支持把管理通道独立成一个进程，脚本主类为 org.apache.kerby.kerberos.kerb.admin.server.KerbyAdminServer（bin/admin-server.sh 包装，日志前缀 -DKERBY_LOGFILE=admin-server）。嵌入式模式（start-kdc 启动的进程内管理）已经覆盖本实验全部需求，独立模式适合把管理面与数据面分开部署。

7.2 remote-admin-client（远程管理客户端）

远程客户端主类为 org.apache.kerby.kerberos.kerb.admin.RemoteAdminClientTool（bin/remote-admin-client.sh 包装），使用 kdcinit 导出的 protocol.keytab 连接管理服务执行与管理相同的命令集。要求 admin-server 已启动并放行对应端口。

八、典型运维场景命令串

8.1 新增业务账号并验证

printf "addprinc -pw q1w2e3r4 ops@EXAMPLE.COM
quit
" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kadmin.KadminTool conf -k keytab/admin.keytab
cd /opt/kerby/tool-dist-2.1.2
echo "q1w2e3r4" | LC_ALL=C.UTF-8 java -classpath "lib/*:." org.apache.kerby.kerberos.tool.kinit.KinitTool -conf /opt/kerby/kdc-dist-2.1.2/conf ops@EXAMPLE.COM

实测要点：第一段输出 Principal "ops@EXAMPLE.COM" created.，第二段输出 Successfully requested and stored ticket in /tmp/krb5cc_0 即全链路打通。

8.2 重启 KDC 的标准动作

PID=$(jps | awk '/KerbyKdcServer/ {print $1}')
kill "$PID"
sleep 3
cd /opt/kerby/kdc-dist-2.1.2
nohup java -Xms256m -Xmx256m -classpath "lib/*:." -DKERBY_LOGFILE=kdc org.apache.kerby.kerberos.kdc.KerbyKdcServer -start conf runtime > /tmp/kdc.log 2>&1 &
sleep 10
cat /tmp/kdc.log

实测回显：

KDC started.

说明：jps 定位 PID 可避免 pkill -f 误杀调用脚本自身（pkill 的 -f 匹配会把包含关键字的本条命令也命中）。

九、常见问题（FAQ）

Q1：bin/start-kdc.sh 在解压后的目录跑不起来，报找不到主类？ A：脚本 classpath 写的是 target/lib/（面向源码树），解压目录里没有 target。处理：ln -s . target 建自引用链接，或 sed 把脚本内 target/lib/ 改为 lib/*。两种方式实测等价。

Q2：kinit 提示 Create krb5Client failed / krb5.conf not found？ A：KinitTool/KlistTool 必须用 -conf 参数指向包含 krb5.conf 的目录（本实验为 /opt/kerby/kdc-dist-2.1.2/conf），缺少该参数时 klist 直接报 Create krb5Client failed: krb5.conf not found。

Q3：kinit 在脚本中报 java.util.NoSuchElementException: No line found？ A：无终端环境时工具退化为 Scanner 读密码，但 stdin 里没有内容。解决：把密码用管道传入，如 echo "q1w2e3r4" | java ... KinitTool -conf conf root@EXAMPLE.COM。

Q4：kadmin 连接报什么账号在用？如何免交互登录？ A：kadmin.sh conf -k keytab/admin.keytab 即以 keytab 免密登录，实际身份是 kadmin/EXAMPLE.COM@EXAMPLE.COM（回显 KeyTab is .../admin.keytab principal is kadmin/EXAMPLE.COM@EXAMPLE.COM Will use keytab）。用 -c 缓存认证则要求先持有该主体的票据。

Q5：? 命令显示一堆 not implemented 的命令还能用吗？ A：不能。policy 系列（add_policy/get_policy 等）与 lock/unlock/get_strings 系列在 2.1.2 的帮助文本中明确标注 not implemented，执行会被拒绝；可用命令集中在主体管理与 keytab 管理。

Q6：klist 里 Valid starting 显示 1970-01-01 是不是坏了？ A：不是。Kerberos 票据起始时间为 0 表示立即生效，Kerby 的 klist 未对 0 做美化，直接按 Unix 纪元显示。重点看 Expires 与 renew until 两列，实测 root 的 TGT 有效期 24 小时（17:15:42 到次日 17:15:42）。

Q7：kinit -S 输出 knvo = 1 是什么？ A：是服务主体的密钥版本号 kvno（工具输出拼写为 knvo）。ktadd 换 keytab 或 cpw 改密码后 kvno 递增，旧票据与旧 keytab 失效。实测首次为 1，与 getprinc 里 Key version: 1 一致。

Q8：jps 看不到 KerbyKdcServer 进程？ A：两种可能：进程已退出（cat /tmp/kdc.log 看启动错误，常见是工作目录不存在或后端未初始化）；或使用的是 JRE 而非 JDK（jps 属 JDK 工具），此时用 ps -ef | grep [j]ava 替代。

Q9：工具输出中文变问号？ A：非交互环境下 JVM 按系统 locale（POSIX/ANSI_X3.4-1968）编码 stdout。命令前加 LC_ALL=C.UTF-8 LANG=C.UTF-8 即可，实测中文正常输出。

Q10：忘记 admin.keytab 位置怎么办？ A：kadmin.sh 的 Usage 与 kdcinit 的输出都指明了导出路径（本文为 /opt/kerby/kdc-dist-2.1.2/keytab/admin.keytab）。彻底丢失时只能清空后端目录重新 kdcinit，并重建全部业务主体。

十、参考链接

Apache Kerby 官方文档：https://directory.apache.org/kerby/
Kerby 源码仓库（tool 目录含 KdcInitTool/KadminTool/KinitTool 源码）：https://github.com/apache/directory-kerby
Kerby 2.1.2 发行包：https://dlcdn.apache.org/directory/kerby/dist/2.1.2/
Kerberos RFC 4120（kinit/klist 行为语义）：https://datatracker.ietf.org/doc/html/rfc4120
MIT Kerberos kadmin 命令手册（命令名对照）：https://web.mit.edu/kerberos/krb5-latest/doc/admin/admin_commands/kadmin_local.html
OpenJDK jps 工具说明：https://docs.oracle.com/en/java/javase/17/docs/specs/man/jps.html