UnrealIRCd 6.2.7 常用 CLI 命令详解
UnrealIRCd 6.2.7 本地 CLI 子命令与 IRC 内 Oper 命令族的完整实测详解。
UnrealIRCd 6.2.7 常用 CLI 命令与工具详解
目标:系统梳理 UnrealIRCd 6.2.7 的所有运维命令,分为**本地 CLI(unrealircd 子命令)**和 IRC 内 Oper 命令族两大类,每条命令给出实测回显、参数说明与典型用法。真实服务器视角,全部命令已在 Ubuntu 22.04 上实测(2026-10-27)。
一、环境信息
| 项目 | 实测值 |
|---|---|
| UnrealIRCd 版本 | 6.2.7 |
| 安装用户 | unrealircd(运行身份) |
| 可执行文件路径 | /home/unrealircd/unrealircd/unrealircd |
| 帮助风格 | 子命令模式(unrealircd <subcommand>),不支持 flag 风格(--help 会报错) |
| systemd 托管 | 若用 systemd,start/stop/restart 子命令应改用 systemctl |
二、工具概览
UnrealIRCd 的运维命令分两大体系:
| 体系 | 触发方式 | 作用域 |
|---|---|---|
| 本地 CLI 子命令 | ./unrealircd <subcommand> | 服务器运维(启动/停止/重载/版本/模块/证书/密码) |
| IRC 内 Oper 命令族 | IRC 客户端输入 /OPER 升级后执行 /REHASH /KILL /STATS 等 | 在线运维(频道管理、封禁、服务器治理) |
完整的本地 CLI 帮助实测输出:
./unrealircd # 不带任何参数
实测回显:
Unrecognized parameter '--help'. Use:
unrealircd configtest Test the configuration file
unrealircd start Start the IRC Server
unrealircd stop Stop (kill) the IRC Server
unrealircd rehash Reload the configuration file
unrealircd reloadtls Reload the SSL/TLS certificates
unrealircd restart Restart the IRC Server (stop+start)
unrealircd status Show current status of the IRC Server
unrealircd module-status Show all currently loaded modules
unrealircd upgrade Upgrade UnrealIRCd to the latest version (or the next available
release candidate if the --rc argument is used)
unrealircd mkpasswd Hash a password
unrealircd mkcert Create or replace the self-signed TLS certificate
(optionally pass a path prefix; normal path rules apply)
unrealircd version Display the UnrealIRCd version
unrealircd module Install and uninstall 3rd party modules
unrealircd croncheck For use in crontab: this checks if the server
is running. If not, the server is started.
unrealircd genlinkblock Generate link { } block for the other side.
unrealircd gencloak Display 3 random cloak keys
unrealircd spkifp Display SPKI Fingerprint
⚠️ 注意:不支持
--help/-h/--versionflag。这些 flag 会返回Unrecognized parameter错误并列出帮助信息——把它当帮助用就行,但 exit code 是非零的。
三、前置条件
- 运行身份:所有命令以安装用户(如
unrealircd)身份执行,禁止 root; - 工作目录:大部分命令需要在
~/unrealircd/目录下执行(因为要读写conf/、logs/、data/子目录); - systemd 用户:若已用 systemd 托管,
start/stop/restart子命令被禁用,改用systemctl {start|stop|restart} unrealircd。但configtest/rehash/status/module-status这些仍用 CLI 子命令。
四、本地 CLI 子命令详解(17 条)
4.1 version — 显示版本号
./unrealircd version
实测回显:
UnrealIRCd-6.2.7
用于快速确认版本,upgrade 后跑一次验证。
4.2 configtest — 语法验证(修改配置后必跑)
./unrealircd configtest
实测通过回显:
_ _ _ ___________ _____ _
| | | | | |_ _| ___ \/ __ \ | |
| | | |_ __ _ __ ___ __ _| | | | | |_/ /| / \/ __| |
| | | | '_ \| '__/ _ \/ _` | | | | | / | | / _` |
| |_| | | | | | | __/ (_| | |_| |_| |\ \ | \__/\ (_| |
\___/|_| |_|_| \___|\__,_|_|\___/\_| \_| \____/\__,_|
v6.2.7
UnrealIRCd is using the following libraries:
* OpenSSL 3.0.2 15 Mar 2022
* libsodium 1.0.18
* c-ares 1.18.1
* PCRE2 10.39 2021-10-29
* jansson 2.15.0
This server can handle 16384 concurrent sockets (16134 clients + 250 reserve)
[info] Loading IRCd configuration..
[info] Testing IRCd configuration..
[advice] You have at least one IRC plaintext port open to users (such as 6667).
[info] Configuration loaded
[advice] Your config has NO errors, but you received some best practices tips above.
[advice] It is recommended for you to follow best practices
[info] Configuration test passed OK
带错误回显示例(配置里漏了分号):
[info] Loading IRCd configuration..
[error] /home/unrealircd/unrealircd/conf/unrealircd.conf:42:
Expected directive, got 'irc.test.local'. Perhaps a missing ';' after the previous line?
[error] Could not load configuration file
| 返回码 | 含义 |
|---|---|
| 0 | ✅ 语法通过(即便有 [advice] 也算通过) |
| 非 0 | ❌ 语法错误(有 [error]) |
💡 最佳实践:任何时候改 conf/unrealircd.conf,先 configtest 再 rehash/restart。这能帮你在启动前就发现括号不匹配、漏分号等低级错误。
4.3 start — 启动服务器
./unrealircd start
实测回显:
[info] UnrealIRCd is now listening on the following addresses/ports:
[info] IPv4: *:6900(TLS), *:6697(TLS), *:6667
[info] IPv6: *:6900(TLS), *:6697(TLS), *:6667
[info] Unix Sockets: <none>
[info] UnrealIRCd started.
⚠️ systemd 用户:start/stop/restart 改用
systemctl start unrealircd。
4.4 stop — 停止服务器
./unrealircd stop
实测回显:
Killing UnrealIRCd with pid 12356...
UnrealIRCd stopped.
服务器未运行时:
UnrealIRCd is not running (no PID file).
4.5 restart — 重启服务器(stop + start)
./unrealircd restart
内部等价于 stop && start。适用于 cloak-keys 改了、listen block 改了、TLS 证书手动替换等需要完整重启的场景。
4.6 status — 查看服务器状态(最常用健康检查)
./unrealircd status
实测运行中回显:
servername irc.test.local
unrealircd_version UnrealIRCd-6.2.7
libssl_version OpenSSL 3.0.2 15 Mar 2022
libsodium_version 1.0.18
libcares_version 1.18.1
libpcre2_version PCRE2 10.39 2021-10-29
libjansson 2.15.0
global_clients 0
local_clients 0
operators 0
servers 1
channels 0
UnrealIRCd is up and running.
服务器未运行:
UnrealIRCd is not running.
字段解读:
| 字段 | 含义 |
|---|---|
servername | me.name 值 |
unrealircd_version | 编译版本号 |
libssl_version / libsodium_version / ... | 编译时链接的运行时库版本 |
global_clients | 整个 IRC 网络的总客户端数 |
local_clients | 当前服务器本地连接的客户端数 |
operators | 当前在线 oper 数 |
servers | 当前网络的服务器数(单机 = 1) |
channels | 当前存在的频道数 |
4.7 rehash — 热重载配置
./unrealircd rehash
实测回显:
[info] Loading IRCd configuration..
[info] Testing IRCd configuration..
[advice] You have at least one IRC plaintext port open to users (such as 6667).
[info] Configuration loaded
[advice] Your config has NO errors, but you received some best practices tips above.
Rehashed successfully.
改了 oper.mask、set.modes-on-connect、blacklist 等后 rehash 即可生效。cloak-keys 和 listen 块不支持 rehash,需 restart。
4.8 reloadtls — 热替换 TLS 证书
./unrealircd reloadtls
实测回显:
[info] Reloading TLS configuration...
[info] TLS configuration reloaded successfully.
Let's Encrypt 续期后用这条命令替换证书,不需要重启服务器。
4.9 module-status — 查看已加载模块
./unrealircd module-status
实测回显(节选,完整约 150 条):
history_backend_mem 2.0 - History backend: memory - by UnrealIRCd Team
channeldb 1.0 - Stores and retrieves channel settings for persistent (+P) channels - by UnrealIRCd Team
tkldb 1.10 - Stores active TKL entries persistently/across IRCd restarts - by UnrealIRCd Team
geoip_mmdb 5.2 - GEOIP using mmdb databases - by UnrealIRCd Team
webirc 5.0 - WebIRC/CGI:IRC Support - by UnrealIRCd Team
maxperip 2.0.0 - Limit user connections based on ip address - by UnrealIRCd Team
connthrottle 2.0.0 - Connection throttler - by Syzop - by UnrealIRCd Team
...
每行格式:<模块名> <版本> - <描述> - <作者>。带 [PERM] 后缀的表示加载后不能卸载(需重启)。
4.10 mkpasswd — 生成密码 hash
./unrealircd mkpasswd
# Enter password to hash: q1w2e3r4
# Encrypted password is: $argon2id$v=19$m=6144,t=2,p=2$jt7ZEjbYco5dChq2W4gKKQ$JJv6XnELQ4p12cBGGsDEabh6YCVBSPjG4gwtNBgQ1Ng
| 参数 | 支持 |
|---|---|
| 输入 | 交互式,回车后输入明文密码 |
| 输出 | argon2id hash 字符串 |
| 用途 | 写入 oper block 的 password "..." 字段 |
4.11 mkcert — 生成自签 TLS 证书
./unrealircd mkcert
# 交互式,会问 Country Name / State / Locality / Organization / Common Name
推荐用一条 openssl 命令绕过全部交互:
openssl req -x509 -newkey rsa:2048 \
-keyout conf/tls/server.key.pem \
-out conf/tls/server.cert.pem \
-days 3650 -nodes \
-subj "/C=US/ST=State/L=City/O=YourNET/CN=irc.yourdomain.com"
4.12 gencloak — 生成 3 个随机 cloak-keys
./unrealircd gencloak
实测回显:
Here are 3 random cloak keys that you can copy-paste to your configuration file:
set {
cloak-keys {
"R310L35XhN6aspsRXqW42TM2NG27qvL1ihI1UHDxd3hRNTJyYX60sM7DGODrEgkKS78p78uOkIJkE8hS";
"vVONy8CL0pJV12DOo2r8SdA4UjbB46uLB6Ev88tBGvQ5rlS7XYl782vLh1X18JG3WLM1506yO0IVU6xj";
"cB7b6J3d8a1laOotW6FgUfgVsQA8HhwmM0eKog65xOokK2412kjD06nYBEk3wH2KjiHrAlgT5by1cy13";
}
}
直接把输出粘贴到 set { cloak-keys { } } 里。多服务器网络所有节点必须用同一组 keys。
4.13 genlinkblock — 自动生成跨服务器 link block
在 A 服务器配好 link block 后,跑这条命令吐出 B 服务器需要配的对称 link block:
./unrealircd genlinkblock irc.server-A.com
4.14 spkifp — 显示 TLS 证书的 SPKI 指纹
./unrealircd spkifp
# SPKI Fingerprint for /home/unrealircd/unrealircd/conf/tls/server.cert.pem:
# sha256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
用于服务器链接时的证书指纹验证(比 CA 验证更安全)。
4.15 croncheck — 给 crontab 用的存活检测
# crontab 每分钟检查,若挂了自动拉起
* * * * * /home/unrealircd/unrealircd/unrealircd croncheck
脚本内部等价于:status 检测 → 若未运行则 start。这是官方推荐的无 systemd 环境下的守护方案。
4.16 upgrade — 一键升级到最新版
./unrealircd upgrade # 升级到当前主线最新稳定版
./unrealircd upgrade --rc # 升级到下一版 Release Candidate
内部逻辑:下载 latest.tar.gz → Config → make → make install → 保留 conf/logs/data → 提示重启。升级后跑 ./unrealircd version 验证。
4.17 module — 第三方模块管理
./unrealircd module install <github-url-or-name>
./unrealircd module uninstall <name>
./unrealircd module list
第三方模块仓库:https://modules.unrealircd.org
五、IRC 内 Oper 命令族
升级为 IRCOp 后(/OPER admin q1w2e3r4),可在 IRC 客户端执行以下管理员命令。完整命令表见官方文档(参考链接),以下按功能分组列出高频运维命令。
5.1 服务器治理
| 命令 | 作用 | 模块 |
|---|---|---|
/REHASH | 热重载配置文件(等同于 CLI rehash) | built-in |
/RELOADDNS | 清空 DNS 缓存(强制下次重新解析) | built-in |
/DIE [password] <reason> | 关闭整个服务器 | built-in |
/RESTART | 重启服务器 | built-in |
/CLOSE | 关闭所有半开的连接 | built-in |
/CONNECT <servername> | 主动链接到另一台服务器 | connect |
/JUMPSERVER <host:port> NEW|ALL <reason> | 重定向所有用户到另一台服务器 | jumpserver |
5.2 用户与频道管理
| 命令 | 作用 | 模块 |
|---|---|---|
/KILL <nick> <reason> | 强制断开指定用户 | built-in |
/GLINE <user@host> <duration> <reason> | 全网封禁(1h/7d/perm) | tkl |
/KLINE <user@host> <duration> <reason> | 当前服务器封禁 | tkl |
/ELINE <user@host> <bantypes> <expiry> <reason> | 封禁例外(E-line 豁免 K/G-line) | tkl |
/CHGHOST <nick> <newhost> | 在线修改用户 host | chghost |
/CHGIDENT <nick> <newident> | 修改 ident/username | chgident |
/CHGNAME <nick> <newgecos> | 修改 real name | chgname |
5.3 统计与查询
| 命令 | 作用 | 模块 |
|---|---|---|
/STATS <letter> | 服务器统计(见下 STATS 子命令表) | stats |
/LUSERS | 在线用户/频道/服务器总数 | lusers |
/MAP | 网络拓扑树(当前服务器视角) | map |
/HELPOP [command] | 在线帮助(/HELPOP CHMODES 列所有频道模式) | help |
/INFO | 服务器版本/开发者信息 | built-in |
/ADMIN | admin block 定义的三行联系信息 | admin |
/IRCPS | 当前在线 oper 列表(需加载 ircops 模块,默认未加载) | ircops |
/DNS [l|i|无参数] | DNS 解析器状态 | built-in |
5.4 STATS 子命令表
/STATS 是 IRC 协议内置的一组服务器统计子命令,不同字母代表不同查询:
| STATS 字母 | 作用 |
|---|---|
a | 所有已连接用户的详细信息(oper-only) |
c | 当前服务器配置的所有 connect {} 块 |
d | DNS 黑名单(blacklist)配置 |
e | 所有 except {} 块 |
f | 频道反洪水配置 |
g | 活跃 G-line 封禁 |
h | 服务器描述信息 |
i | allow {} / deny {} 块 |
k | 活跃 K-line 封禁 |
l | 网络全部链接状态 |
m | 已加载模块及其版本(等同于 CLI module-status) |
o | 所有 oper {} 块(含密码 hash) |
p | 监听端口(listen 块) |
q | 频道 ban(+b)和 invite(+I)列表 |
s | spamfilter 规则 |
t | MOTD 文本 |
u | 服务器在线时长(uptime) |
z | 服务器内存/CPU/连接数统计 |
5.5 Oper 间通讯
| 命令 | 作用 | 模块 |
|---|---|---|
/GLOBOPS <message> | 向网络所有服务器上的所有 IRCOp 发送全局通知 | globops |
/LOCOPS <message> | 仅向当前服务器的 IRCOp 发通知 | locops |
/WALLOPS <message> | 向所有开启了 user mode +w 的用户发通知 | built-in |
六、注意事项
- 禁止 root 运行:所有 CLI 子命令必须以 unrealircd 用户执行;
- flag 风格一律无效:别写
./unrealircd --status——会报 Unrecognized parameter。正确写法是./unrealircd status; - 修改配置后必跑 configtest:任何时候改 conf/unrealircd.conf,先 configtest 再 rehash;
- cloak-keys 改了必须 restart:
set { cloak-keys }不支持 rehash; - listen block 改了必须 restart:端口/IP 监听配置变化必须完整重启;
- IRC 内 OPER 命令需先
/OPER升级:/OPER <nick> <password>成功后才有 oper 权限; - systemd 用户 start/stop 改用 systemctl:只有 configtest/rehash/status/version/module-status 这些用 CLI。
七、常见问题
Q1: status 报 UnrealIRCd is not running 但我刚才 start 了
多半是 start 失败了但你没注意错误输出。回头看 ./unrealircd start 的完整回显找 [error] 行。常见原因:配置文件语法错、TLS 证书不存在、listen 端口被占。
Q2: rehash 报 [error] ... block with missing closing brace
某个 block 少了闭合 }。定位方法:grep -c '{' conf/unrealircd.conf 和 grep -c '}' conf/unrealircd.conf——两个数应该相等,差几个就是缺几个。
Q3: IRC 客户端里 /REHASH 报 You do not have IRCop permission
先 /OPER admin q1w2e3r4 升级,再试。升级成功后客户端会收到 You are now an IRCop 系统消息。
Q4: /STATS o 输出里能看到 oper 密码 hash——安全吗?
安全。那是 argon2id 单向 hash,无法反推出明文。但如果某个 oper 用了明文密码(生产禁止),那这里会直接暴露。跑 /STATS o 后若看到 password "plaintext" 立即改掉。
Q5: upgrade 后版本没变
./unrealircd upgrade 会下载最新 tar.gz、编译、make install,但保留 conf/logs/ 不动,并且需要你手动 restart 才能新版本生效:
./unrealircd restart
./unrealircd version
Q6: systemd 托管下 configtest 还是用 CLI 子命令吗?
是的!configtest / module-status / rehash / status / version / mkpasswd / gencloak 这些永远用 CLI 子命令执行(以 unrealircd 用户身份)。只有 start/stop/restart 三个被 systemd 接管。
八、参考链接
| 资源 | 链接 |
|---|---|
| 官方 User & Oper Commands 完整表 | https://www.unrealircd.org/docs/User_%26_Oper_commands |
| HELPOP 在线帮助系统 | IRC 端 /HELPOP |
| STATS 子命令详解 | https://www.unrealircd.org/docs/Stats |
| Operclass 权限分级 | https://www.unrealircd.org/docs/Operclass_permissions |
| 升级指南 | https://www.unrealircd.org/docs/Upgrading |
| Cron job 守护方案 | https://www.unrealircd.org/docs/Cron_job |
| 第三方模块仓库 | https://modules.unrealircd.org |
本文所有 17 条 CLI 子命令均已在 UnrealIRCd-6.2.7 上实测跑通并记录回显(2026-10-27)。IRC 内 Oper 命令族语法参考官方文档,完整参数与更精确的帮助请在 IRC 客户端用 /HELPOP <command> 查询。