Ubuntu 22.04 安装 Wren:DS 5.1.1 指南
Ubuntu 22.04 上以官方二进制包完成 Wren:DS 5.1.1 的下载校验、非交互初始化、启动验收、JVM 堆限制与 TLS 验证，并沉淀 4 条实测排障记录。
Wren:DS目录服务LDAP身份认证Java2026/11/02
Ubuntu 22.04 安装 Wren:DS 5.1.1 指南
目标：在 Ubuntu 22.04 服务器上，用官方二进制发行包完成 Wren:DS 5.1.1 的全新安装、初始化、启动与验收，并通过 JVM 参数把堆内存限制在 256MB。全文命令与回显均为 2026-11-02 在测试服务器
wrends01上的实测记录。
一、部署前准备
1.1 实测环境
| 项目 | 值 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS (Jammy Jellyfish) | PRETTY_NAME="Ubuntu 22.04.5 LTS" |
| 主机名 | wrends01 | hostname 输出 |
| 服务器地址 | 10.89.57.10 | hostname -I 输出 |
| JDK | OpenJDK 17.0.20.1 | java -version 输出 |
| Wren:DS | 5.1.1，Build 2026-05-22T13:11:32Z | start-ds --version 输出 |
| 安装目录 | /opt/wren-ds | 下文所有命令均以此为基准 |
| LDAP 端口 | 1389 | 初始化参数 --ldapPort 1389 |
| LDAPS 端口 | 1636 | 初始化参数 --ldapsPort 1636 |
| 管理连接器端口 | 4444 | 初始化参数 --adminConnectorPort 4444 |
| 根用户 | cn=Directory Manager | 初始化参数 --rootUserDN |
| 根口令 | q1w2e3r4 | 初始化参数 --rootUserPassword |
| 业务后缀 | dc=example,dc=com | 初始化参数 --baseDN |
| JVM 堆 | -Xms256m -Xmx256m | 修改 config/java.properties |
端口说明：Wren:DS 沿用 OpenDJ 默认值 389/636/5444。本文为了不与测试机上其他目录服务冲突，显式改成 1389/1636/4444。生产环境按防火墙与端口规划决定，不要求照抄。
1.2 目录规划
| 路径 | 用途 |
|---|---|
/opt/wren-ds | 程序与配置根目录 |
/opt/wren-ds/config/config.ldif | 主配置（cn=config 树） |
/opt/wren-ds/config/java.properties | 各 Java 工具的 JVM 参数 |
/opt/wren-ds/db | 用户后端数据与索引 |
/opt/wren-ds/logs | access/errors/audit 日志 |
/opt/wren-ds/ldif | 初始化与导入导出 LDIF 存放区 |
/opt/wren-ds/bin | 全部命令行工具 |
1.3 安装前检查
root@wrends01:~# uname -a
root@wrends01:~# free -m
root@wrends01:~# df -h /opt
建议至少预留 2GB 可用内存与 1GB 磁盘空间：JVM 堆 256MB 只是堆上限，元空间、线程栈、直接内存与页缓存还会额外占用。
二、安装 JDK 与基础工具
Wren:DS 官方发行包是 Java 应用，不附带 JDK，需要服务器自备。实测使用 Ubuntu 仓库中的 OpenJDK 17：
root@wrends01:~# apt-get update
root@wrends01:~# apt-get install -y openjdk-17-jdk-headless ldap-utils curl unzip
安装过程节选（重复执行时为已安装状态）：
Unpacking libpam-cap:amd64 (1:2.44-1ubuntu0.22.04.3) ...
Setting up libpam-cap:amd64 (1:2.44-1ubuntu0.22.04.3) ...
Setting up libbpf0:amd64 (1:0.5.0-1ubuntu22.04.1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
验证 Java：
root@wrends01:~# java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
如果服务器同时存在多个 JDK，后续所有命令都要显式
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64，否则可能用到系统默认的其他版本。
三、下载发行包并校验
3.1 下载
从 GitHub Releases 下载 5.1.1 的官方资产：
root@wrends01:~# curl -L -o /opt/wrends-5.1.1.zip \
https://github.com/WrenSecurity/wrends/releases/download/5.1.1/wrends-5.1.1.zip
文件大小与实测一致：
root@wrends01:~# ls -l /opt/wrends-5.1.1.zip
-rw-r--r-- 1 root root 51144630 Nov 2 12:33 /opt/wrends-5.1.1.zip
3.2 校验哈希
root@wrends01:~# sha256sum /opt/wrends-5.1.1.zip
5cf4a6bc801fad87fa2afab67c606b5a58d51f5c718a417bd9469ed662fb565c /opt/wrends-5.1.1.zip
该值是本篇实测日期的官方包哈希。若从其他下载站点或代理获取，必须重新核对官方发布页的哈希，不能沿用本文数值。
3.3 完整性检查
root@wrends01:~# unzip -t /opt/wrends-5.1.1.zip | tail -3
testing: wrends/template/config/upgrade/schema.ldif.366dea1eaf117b80242da38cae742cf737a34c77 OK
testing: wrends/template/config/wordlist.txt OK
No errors detected in compressed data of /opt/wrends-5.1.1.zip.
压缩包内根目录是 wrends/，不是版本号目录：
root@wrends01:~# unzip -l /opt/wrends-5.1.1.zip | head -8
Archive: /opt/wrends-5.1.1.zip
Length Date Time Name
--------- ---------- ----- ----
0 2026-05-22 15:14 wrends/
0 2026-05-22 15:14 wrends/QuickSetup.app/
0 2026-05-22 15:11 wrends/QuickSetup.app/Contents/
0 2026-05-22 15:11 wrends/QuickSetup.app/Contents/MacOS/
0 2026-05-22 15:11 wrends/QuickSetup.app/Contents/Resources/
四、解压与目录部署
root@wrends01:~# rm -rf /tmp/wrends-dist
root@wrends01:~# unzip -q /opt/wrends-5.1.1.zip -d /tmp/wrends-dist
root@wrends01:~# mv /tmp/wrends-dist/wrends /opt/wren-ds
root@wrends01:~# ls /opt/wren-ds
QuickSetup.app
README
Uninstall.app
bak
bat
bin
changelogDb
classes
config
db
example-plugin.zip
import-tmp
ldif
legal-notices
lib
locks
logs
setup
setup.bat
template
uninstall
uninstall.bat
upgrade
upgrade.bat
wrends_logo.png
许可文件在 legal-notices/CDDLv1_0.txt，发行包采用 CDDL-1.0。
五、非交互式初始化
setup 默认启动图形界面，服务器环境必须加 -i 使用命令行模式。下面这条命令一次完成：接受许可、设置主机名与端口、生成自签证书、开启 StartTLS、设置根 DN 与口令、创建基础后缀条目。
root@wrends01:~# cd /opt/wren-ds
root@wrends01:/opt/wren-ds# export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
root@wrends01:/opt/wren-ds# ./setup -i -n --acceptLicense \
--hostname wrends01 \
--ldapPort 1389 \
--ldapsPort 1636 \
--adminConnectorPort 4444 \
--generateSelfSignedCertificate \
--enableStartTLS \
--rootUserDN 'cn=Directory Manager' \
--rootUserPassword q1w2e3r4 \
--baseDN 'dc=example,dc=com' \
--addBaseEntry
实测回显：
Configuring Directory Server ..... Done.
Configuring Certificates ..... Done.
Creating Base Entry dc=example,dc=com ..... Done.
Starting Directory Server ...... Done.
参数说明：
| 参数 | 作用 |
|---|---|
-i | 使用命令行安装，禁用图形界面 |
-n | 不提示确认，直接使用传入参数 |
--acceptLicense | 自动接受 CDDL 许可 |
--hostname | 证书 CN 与服务标识，复制场景必须各节点唯一 |
--ldapPort | 明文 LDAP 监听端口 |
--ldapsPort | LDAPS 监听端口，显式传入才会配置 SSL |
--adminConnectorPort | 管理连接器端口，dsconfig/status 依赖它 |
--generateSelfSignedCertificate | 生成自签证书，测试可用，生产应换 CA 证书 |
--enableStartTLS | 允许在 LDAP 端口上做 StartTLS 升级 |
--rootUserDN | 根用户 DN，默认 cn=Directory Manager |
--rootUserPassword | 根用户口令，建议用文件或交互方式，避免留在 shell 历史 |
--baseDN | 业务后缀，可重复传入多个 |
--addBaseEntry | 自动创建后缀根条目 |
验证版本：
root@wrends01:/opt/wren-ds# ./bin/start-ds --version
Wren:DS Server 5.1.1
Build 2026-05-22T13:11:32Z
六、启动与端口验证
6.1 启动
root@wrends01:/opt/wren-ds# export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
root@wrends01:/opt/wren-ds# ./bin/start-ds
实测回显节选：
[02/Nov/2026:12:57:54 +0000] category=JVM severity=NOTICE msgID=19 msg=JVM Arguments: "-Xms256m", "-Xmx256m", "-Dorg.opends.server.scriptName=start-ds"
[02/Nov/2026:12:57:55 +0000] category=BACKEND severity=NOTICE msgID=513 msg=The database backend userRoot containing 4 entries has started
[02/Nov/2026:12:57:56 +0000] category=PROTOCOL severity=NOTICE msgID=276 msg=Started listening for new connections on Administration Connector 0.0.0.0 port 4444
[02/Nov/2026:12:57:56 +0000] category=PROTOCOL severity=NOTICE msgID=276 msg=Started listening for new connections on LDAPS Connection Handler 0.0.0.0 port 1636
[02/Nov/2026:12:57:56 +0000] category=PROTOCOL severity=NOTICE msgID=276 msg=Started listening for new connections on LDAP Connection Handler 0.0.0.0 port 1389
[02/Nov/2026:12:57:56 +0000] category=CORE severity=NOTICE msgID=135 msg=The Directory Server has started successfully
6.2 端口监听
root@wrends01:~# ss -ltnp | grep -E '1389|1636|4444'
LISTEN 0 128 *:4444 *:* users:("java",pid=11802,fd=125)
LISTEN 0 128 *:1389 *:* users:("java",pid=11802,fd=127)
LISTEN 0 128 *:1636 *:* users:("java",pid=11802,fd=126)
ss输出里的进程名会因版本显示为java；只要 PID 与ps -ef | grep DirectoryServer一致即可。
6.3 LDAP 连通性验证
root@wrends01:/opt/wren-ds# ./bin/ldapsearch -p 1389 \
-D 'cn=Directory Manager' -w q1w2e3r4 \
-b 'dc=example,dc=com' -s base '(objectClass=*)'
dn: dc=example,dc=com
objectClass: top
objectClass: domain
dc: example
七、JVM 堆限制与验证
7.1 修改位置
Wren:DS 的服务端 JVM 参数在 config/java.properties，不是环境变量 JAVA_OPTS。原始行是：
start-ds.java-args=-server
改为：
start-ds.java-args=-server -Xms256m -Xmx256m
实测文件中的行号与内容：
root@wrends01:~# grep -n 'start-ds.java-args' /opt/wren-ds/config/java.properties
22:# start-ds.java-args=-server -Xms256m
64:start-ds.java-args=-server -Xms256m -Xmx256m
第 22 行是带
#的注释示例，不生效；真正生效的是第 64 行。修改后必须重启服务进程。
7.2 进程级验证
root@wrends01:~# ps -ef | grep '[D]irectoryServer'
root 11802 1 1 13:00 ? 00:00:13 /usr/bin/java -server -Xms256m -Xmx256m -Dorg.opends.server.scriptName=start-ds org.opends.server.core.DirectoryServer --configFile /opt/wren-ds/config/config.ldif
有 JDK 时可用 jps -v 复核：
root@wrends01:~# jps -v
11802 DirectoryServer -Xms256m -Xmx256m -Dorg.opends.server.scriptName=start-ds
7.3 日志级验证
root@wrends01:~# grep 'heap size' /opt/wren-ds/logs/errors | tail -1
[02/Nov/2026:13:00:56 +0000] category=JVM severity=NOTICE msgID=17 msg=JVM Information: 17.0.20.1+1-1-22.04-Ubuntu by Ubuntu, 64-bit architecture, 268435456 bytes heap size
268435456 字节正好等于 256MB，说明 -Xmx256m 已生效。
八、生成启停脚本
Wren:DS 不提供 restart-ds，只有 start-ds 与 stop-ds。需要系统级启停时，可用自带工具生成 RC 脚本：
root@wrends01:/opt/wren-ds# ./bin/create-rc-script \
-f /tmp/wrends-rc \
-j /usr/lib/jvm/java-17-openjdk-amd64 \
-u root
脚本开头实测内容：
#!/bin/sh
#
# The contents of this file are subject to the terms of the Common Development and
# Distribution License (the License). You may not use this file except in compliance with the
# License.
#
# You can obtain a copy of the License at legal-notices/CDDLv1_0.txt. See the License for the
# specific language governing permission and limitations under the License.
#
# When distributing Covered Software, include this CDDL Header Notice in each file and include
# the License file at legal-notices/CDDLv1_0.txt. If applicable, add the following below the CDDL
# Header, with the fields enclosed by brackets [] replaced by your own identifying
# information: "Portions Copyright [year] [name of copyright owner]".
#
# chkconfig: 345 95 5
# description: Control the Wren:DS Directory Server
# Set the path to the Wren:DS instance to manage
INSTALL_ROOT="/opt/wren-ds"
export INSTALL_ROOT
生成后先人工检查
INSTALL_ROOT、OPENDJ_JAVA_HOME与运行用户，再放到/etc/init.d/。不同发行版的 init 体系不同，若服务器使用 systemd，RC 脚本只作为参考，建议另写 unit 文件并复用脚本里的启动命令。
九、TLS 现状与验证
9.1 证书与协议
初始化时 --generateSelfSignedCertificate 生成两张自签证书：
server-cert：LDAP/LDAPS 使用，CN 为wrends01，组织为OpenDJ RSA Self-Signed Certificate。admin-cert：管理连接器使用。
config/config.ldif 中三个入口均带 ds-cfg-ssl-protocol: TLSv1.2。这是本篇测试环境为绕开新 JDK 的 TLS 兼容问题所做的调整，默认值可能不同，生产环境应结合客户端能力统一规划。
9.2 用 openssl 验证握手
root@wrends01:~# echo | openssl s_client -connect 127.0.0.1:1636 -tls1_2 2>&1 | head -10
Can't use SSL_get_servername
depth=0 CN = wrends01, O = OpenDJ RSA Self-Signed Certificate
verify error:num=18:self-signed certificate
verify return:1
depth=0 CN = wrends01, O = OpenDJ RSA Self-Signed Certificate
verify return:1
CONNECTED(00000003)
确认协商协议：
root@wrends01:~# echo | openssl s_client -connect 127.0.0.1:1636 2>&1 | grep 'Protocol'
Protocol : TLSv1.2
强制 TLS 1.3 会握手失败：
root@wrends01:~# echo | openssl s_client -connect 127.0.0.1:1636 -tls1_3 2>&1 | head -4
40E7934D71720000:error:0A000126:SSL routines:ssl3_read_n:unexpected eof while reading:../ssl/record/rec_layer_s3.c:317:
CONNECTED(00000003)
---
no peer certificate available
结论：测试环境只接受 TLS 1.2。若客户端只支持 TLS 1.3，需要调整服务端
ds-cfg-ssl-protocol，并先做兼容性回归。
十、卸载与回退
停止服务后删除安装目录即可完成卸载：
root@wrends01:/opt/wren-ds# ./bin/stop-ds
root@wrends01:~# rm -rf /opt/wren-ds
实测停止回显：
Stopping Server...
[02/Nov/2026:13:00:37 +0000] category=PROTOCOL severity=NOTICE msgID=277 msg=Stopped listening for new connections on LDAP Connection Handler 0.0.0.0 port 1389
[02/Nov/2026:13:00:37 +0000] category=PROTOCOL severity=NOTICE msgID=277 msg=Stopped listening for new connections on Administration Connector 0.0.0.0 port 4444
[02/Nov/2026:13:00:37 +0000] category=PROTOCOL severity=NOTICE msgID=277 msg=Stopped listening for new connections on LDAPS Connection Handler 0.0.0.0 port 1636
[02/Nov/2026:13:00:41 +0000] category=BACKEND severity=NOTICE msgID=370 msg=The backend userRoot is now taken offline
[02/Nov/2026:13:00:41 +0000] category=CORE severity=NOTICE msgID=203 msg=The Directory Server is now stopped
卸载前先确认已备份
db/与config/，删除目录不可恢复。
十一、排障实录
11.1 OpenLDAP 客户端访问 LDAPS 失败
现象：openssl s_client 握手成功，但 ldapsearch 报无法连接。
root@wrends01:~# ldapsearch -x -H ldaps://127.0.0.1:1636 \
-D 'cn=Directory Manager' -w q1w2e3r4 \
-b 'dc=example,dc=com' '(uid=alice)' dn
ldap_result: Can't contact LDAP server (-1)
强制客户端 TLS 1.2 后仍然失败：
root@wrends01:~# LDAPTLS_REQCERT=never LDAPTLS_PROTOCOL_MIN=3.3 LDAPTLS_PROTOCOL_MAX=3.3 \
ldapsearch -x -H ldaps://127.0.0.1:1636 \
-D 'cn=Directory Manager' -w q1w2e3r4 -b 'dc=example,dc=com' '(uid=alice)' dn
ldap_result: Can't contact LDAP server (-1)
服务端 logs/errors 同时出现 Grizzly 传输层异常：
GRIZZLY0013: Exception during FilterChain execution exception=ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0 (VarHandle.java:2187 ... PooledMemoryManager.java:602 ... SSLBaseFilter.java:103 ...)
处理建议：这是 5.1.1 的 TLS 传输层兼容缺陷，不是证书配置问题。测试环境可先用明文 LDAP 完成功能验证；生产环境必须先用目标 JDK + 目标客户端做 TLS 回归，必要时降级 JDK 或等待上游修复。
11.2 status 报空指针
root@wrends01:/opt/wren-ds# ./bin/status -D 'cn=Directory Manager' -w q1w2e3r4
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "org.forgerock.opendj.ldap.responses.SearchResultEntry.parseAttribute(String)" because the return value of "org.opends.guitools.controlpanel.util.ConfigFromConnection.getVersionMonitor()" is null
at org.opends.guitools.controlpanel.datamodel.ControlPanelInfo.regenerateDescriptor(ControlPanelInfo.java:522)
at org.opends.server.tools.status.StatusCli.execute(StatusCli.java:310)
at org.opends.server.tools.status.StatusCli.mainCLI(StatusCli.java:176)
at org.opends.server.tools.status.StatusCli.main(StatusCli.java:139)
同一个管理连接器问题也会让 dsconfig 报：
The version of the installed OpenDJ could not be determined because an error
occurred while reading the current configuration: ConnectionException: Server
Connection Closed
处理建议：以 start-ds/stop-ds 的退出码与 logs/errors 判断服务状态；配置变更优先停机改 config/config.ldif，改前备份。
11.3 在线校验索引被数据库锁拒绝
root@wrends01:/opt/wren-ds# ./bin/verify-index --baseDN 'dc=example,dc=com' --index uid
An error occurred while attempting to perform index verification: The
database environment could not be opened:
com.sleepycat.je.EnvironmentLockedException: (JE 18.3.12)
/opt/wren-ds/db/userRoot The environment cannot be locked for single writer
access. ENV_LOCKED: The je.lck file could not be locked. Environment is
invalid and must be closed.
处理建议：verify-index、rebuild-index、export-ldif、import-ldif 在服务运行时默认会争抢数据库写锁。先 stop-ds，再执行；执行完再启动。具体离线命令见 《Wren:DS 5.1.1 常用 CLI 命令与工具详解》。
11.4 根口令出现在 shell 历史
setup 与 ldapsearch 的 -w q1w2e3r4 会留在 shell 历史。生产环境应改用：
setup的--rootUserPasswordFile；- 客户端工具的
-j（口令文件）或-w -（交互输入）。
十二、验收清单
-
java -version为目标 JDK 版本 - 发行包 SHA-256 与官方发布页一致
-
setup四项均为Done. -
start-ds --version显示5.1.1 -
ss -ltnp能看到 1389/1636/4444 三个监听 -
ldapsearch -s base能读回后缀根条目 -
ps -ef或jps -v能看到-Xms256m -Xmx256m -
logs/errors中 heap size 为 268435456 -
stop-ds能干净退出，无残留 java 进程 - 已记录 TLS 握手结果与客户端兼容性结论 </content>
章节目录