ngIRCd 28 配置参数详解
目标：全面讲解 ngIRCd 28 的配置体系：七类配置段、全部参数的取值与默认行为、双实例互联实测、PAM 认证专题与 configtest 工作流。参数语义以官方源码示例模板与 28 版实机 configtest 输出为准（逐项实测核对）。
ngircdngircdIRC即时通讯2026/10/26
ngIRCd 28 配置参数详解
目标：全面讲解 ngIRCd 28 的配置体系：七类配置段、全部参数的取值与默认行为、双实例互联实测、PAM 认证专题与 configtest 工作流。参数语义以官方源码示例模板与 28 版实机 configtest 输出为准（逐项实测核对）。
一、配置体系总览
ngIRCd 的全部配置收敛在单一 ngircd.conf 中（本文环境为 /usr/local/etc/ngircd.conf，Debian 包安装为 /etc/ngircd/ngircd.conf），按段组织，共七类：
| 配置段 | 职责 | 可出现次数 |
|---|---|---|
[Global] | 服务器身份、监听、MOTD、运行用户 | 1 |
[Limits] | 连接数、超时、频率限制 | 1 |
[Options] | 可选行为开关 | 1 |
[SSL] | TLS 证书与加密监听 | 1 |
[Operator] | IRC 操作员账号 | 多 |
[Server] | 服务器互联 peer | 多 |
[Channel] | 预定义频道 | 多 |
基本规则：
- 注释以
#或;起始；官方模板用「;」前缀展示参数的默认值，去掉「;」即启用该参数。 - 片段目录（IncludeDir）：28 版默认读取主配置同目录的
ngircd.conf.d/（Debian 包为conf.d）下的*.conf，在主配置解析完成后追加合并——业务配置可用 drop-in 片段组织而无需改动主文件（本文 configtest 显示IncludeDir = /usr/local/etc/ngircd.conf.d）。 - 重复键：同一参数出现多次时取最后一个值（28 版行为，NEWS 明确记录对
Listen与Mask生效）。 - 自检：任何改动后先跑
ngircd --configtest，它会打印解析后实际生效的完整配置并报告错误行（第九节有完整工作流与错误实录）。
二、[Global] 段
服务器身份与监听（参数/默认值/说明）：
| 参数 | 默认 | 说明 |
|---|---|---|
Name | 从主机名推导 | IRC 网络内的服务器名，必须含至少一个点且全网唯一 |
Info | 软件名+版本 | 服务器描述，WHOIS/LINKS 展示 |
AdminInfo1 / AdminInfo2 / AdminEMail | 无 | 管理员信息（RFC 要求，ADMIN 命令返回） |
Network | 空 | 所属网络名（仅告知客户端，不含空格），设置后 005 行宣告 NETWORK= |
Listen | ::,0.0.0.0（编译 IPv6 时） | 监听 IP 列表，逗号分隔；默认监听全部地址 |
Ports | 6667 | 明文监听端口，逗号分隔可多个 |
Password | 空 | 全局连接口令（设置后客户端 USER 需携带） |
MotdFile | <etcdir>/ngircd.motd | MOTD 文本文件路径 |
MotdPhrase | 空 | 一句话 MOTD（<127 字符）。实测优先级高于 MotdFile：同时设置时 configtest 中 MotdFile 显示为空，仅短语生效 |
HelpFile | 内置路径 | HELP 命令的帮助文本（本文实测为 /usr/local/share/doc/ngircd/Commands.txt） |
PidFile | 无 | PID 文件路径；注意在降权后写入，目录须对运行用户可写 |
ServerUID / ServerGID | 不切换 | 以 root 启动后降权到的用户/组（用户名或数字）；必须以 root 启动才生效，且配置与 MOTD 文件须对该用户可读，否则 REHASH/RESTART 失效 |
三、[Limits] 段
连接与频率限制（默认值来自官方模板，实测 configtest 全部回显）：
| 参数 | 默认 | 说明 |
|---|---|---|
ConnectRetry | 60 | 对未连接 peer 的重连周期（秒） |
IdleTimeout | 0 | 空闲自动退出（0=永不；配合 systemd socket 激活或测试场景） |
MaxConnections | 0 | 全局并发连接上限（0=不限）；未设置时按进程 fd 上限自动适配（启动日志会提示 File descriptor limit is ...; "MaxConnections" is not set.） |
MaxConnectionsIP | 5 | 单一来源 IP 并发上限 |
MaxJoins | 10 | 单用户可加入频道数（0=不限） |
MaxNickLength | 9 | 昵称最大长度（RFC 2812 取 9）；全网所有服务器必须一致 |
MaxListSize | 100 | LIST 命令返回频道数上限（0=不限） |
MaxPenaltyTime | -1 | 单次惩罚上限秒数（-1=不限，0=禁用惩罚；正常运行惩罚不超过 2 秒，更大值鲜有意义） |
PingTimeout | 120 | 空闲多少秒后发 PING 探活 |
PongTimeout | 20 | PING 后未收到 PONG 的断开时限 |
四、[Options] 段
可选行为开关（28 版 configtest 实测 dump 共 26 项，逐项说明）：
| 参数 | 默认 | 说明 |
|---|---|---|
AllowedChannelTypes | #&+ | 允许本地新建的频道前缀白名单；置空可完全禁止本地建频道 |
AllowRemoteOper | no | 是否允许远端操作员控制本服务器（CONNECT/SQUIT 等） |
ChrootDir | 空 | chroot 目录（需 root 启动；静态编译时无需填充） |
CloakHost | 空 | 对所有客户端隐藏真实主机名为固定值，%x 为原主机名哈希 |
CloakHostModeX | 空 | 仅对设置 +x 的客户端使用的伪装主机；为空则普通用户不能自行 +x |
CloakHostSalt | 随机 | 伪装哈希的盐；默认每次启动随机生成（configtest 实测显示随机串）——多服务器组网需显式统一 |
CloakUserToNick | no | 把所有客户端的 user 名设为其昵称 |
ConnectIPv4 / ConnectIPv6 | yes | 出站连接的协议开关（监听由 Listen 控制） |
DefaultChannelModes | 空 | 28 版新增：新频道创建时自动设置的频道模式。⚠️ 模式值不带 + 前缀（写 n 而非 +n，实测写 +n 会导致 configtest 报错） |
DefaultUserModes | 空 | 新本地客户端的默认用户模式（不能设 a 等客户端自设模式） |
DNS | yes | 客户端接入时做 DNS 反解（关闭可降低接入延迟，来源显示 IP） |
Ident | yes | IDENT 查询（需编译 IDENT 特性）；IDENT 认证的用户名不带 ~ 前缀 |
IncludeDir | <etcdir>/conf.d | 配置片段目录（见第一节） |
MorePrivacy | no | 隐藏 idle/登录时间等信息（TOR/I2P 场景） |
NoticeBeforeRegistration | no | 注册完成前是否发送 NOTICE * 进度消息 |
OperCanUseMode | no | 操作员是否可对非其管理的频道使用 MODE（本文实测设 yes） |
OperChanPAutoOp | yes | 操作员在持久频道（+P）中是否自动获得 +o |
OperServerMode | no | 把 OPER 模式请求伪装为来自服务器（ircd-irc2 兼容） |
PAM | yes | 启用 PAM 认证（需编译 PAM 特性；强烈建议通读第八节专题再决定开关） |
PAMIsOptional | no | yes 时未通过 PAM 的客户端仍可连接（不标记 identified，用户名保留 ~） |
PAMServiceName | ngircd | 使用的 PAM 服务名（对应 /etc/pam.d/<名称>） |
RequireAuthPing | no | 注册前强制 PING/PONG 往返（对抗伪造地址灌水） |
ScrubCTCP | no | 静默丢弃入站 CTCP |
SyslogFacility | local5 | syslog facility（历史原因默认 local5，一般建议改 daemon） |
WebircPassword | 空 | WEBIRC 网关口令（空=禁用 WEBIRC） |
五、[SSL] 段
TLS 加密（需编译 SSL 特性；OpenSSL/GnuTLS 后端二选一）：
| 参数 | 默认 | 说明 |
|---|---|---|
Ports | 无 | TLS 监听端口（惯用 6697），与 [Global] Ports 分开 |
CertFile / KeyFile | 无 | 服务器证书与私钥（PEM） |
KeyFilePassword | 空 | 私钥口令（仅 OpenSSL 后端） |
CAFile | 空 | 信任的 CA 证书束；默认空=不信任任何对端证书（互联校验依据） |
CRLFile | 空 | 证书吊销列表 |
CipherList | OpenSSL: HIGH:!aNULL:@STRENGTH / GnuTLS: SECURE128 | 允许的加密套件（实测 dump 为 OpenSSL 默认值） |
DHFile | 无 | Diffie-Hellman 参数 |
六、[Operator]、[Server]、[Channel] 段
[Operator]（可多段，本地操作员账号）：
| 参数 | 说明 |
|---|---|
Name | 操作员 ID（可不等于昵称） |
Password | /OPER 口令 |
Mask | 可选：限制可发起 /OPER 的来源掩码（如 *!ident@host） |
[Server]（可多段，互联 peer；完整实测见第七节）：
| 参数 | 说明 |
|---|---|
Name | 对端服务器名，必须等于对端 [Global] Name |
Host / Port | 对端地址与端口；配置 Port 则本端主动连接，不配置则等待对端连入 |
Bind | 可选出站源地址 |
MyPassword | 本端为该连接设置的口令——对端须把它配为 PeerPassword |
PeerPassword | 对端设置的口令——对端须把它配为 MyPassword（两端互换） |
Group | 服务器组 ID：同组内不会同时连接两台，一台失联自动试下一台 |
Passive | yes=禁用主动连接（等对端连入或用 CONNECT 命令手动触发，便于调试） |
SSLConnect | 是否用 TLS 建链 |
SSLVerify | 是否校验对端 TLS 证书，27 版起默认 yes：自签/过期/域名不匹配即断链，确需跳过须显式 no |
ServiceMask | 经该 peer 引入的昵称掩码视为 IRC 服务（如 *Serv）；普通服务器留空 |
[Channel]（可多段，预定义频道）：
| 参数 | 说明 |
|---|---|
Name | 频道名（#/& 前缀） |
Topic | 频道主题 |
Modes | 初始频道模式（如 +tnk mykey +l 5）；列表模式（ban/invite/exception）可多行自上而下生效 |
Autojoin | yes=所有用户注册后自动加入 |
KeyFile | 频道口令文件（<user>:<nick>:<key> 行式） |
预定义频道随服务器启动创建并持久存在（自动带 P 持久模式，无人时也不消失）。
七、双实例互联实测
单机跑两个 ngIRCd 实例组成最小联邦，验证 [Server] 段配置（两实例同机，第二实例监听回环 127.0.0.1:6668 避免端口冲突）：
主实例 [Server] 段（configtest dump 实测）：
[SERVER]
Name = irc2.example.com
Host = 127.0.0.1
Port = 6668
SSLConnect = no
SSLVerify = yes
MyPassword = LinkPwdA
PeerPassword = LinkPwdB
Group = -1
Passive = no
第二实例 /usr/local/etc/ngircd2.conf（-f 参数指定配置启动）：
[Global]
Name = irc2.example.com
Info = ngIRCd 28 Demo Server #2
Listen = 127.0.0.1
Ports = 6668
Network = ExampleNet
MotdPhrase = Second demo server
PidFile = /run/ngircd/ngircd2.pid
ServerUID = irc
ServerGID = irc
[Server]
Name = irc.example.com
Host = 127.0.0.1
Port = 6667
MyPassword = LinkPwdB
PeerPassword = LinkPwdA
Passive = yes
配置要点核对：Name 互指（主配 irc2.example.com = 从的 Name）；口令互换（主 MyPassword=LinkPwdA ↔ 从 PeerPassword=LinkPwdA）；主端 Passive=no 主动连 6668，从端 Passive=yes 只等连入，避免双方同时发起。ConnectRetry 周期（默认 60 秒）内未连上会自动重试。
连接建立后，客户端注册时统计行即为铁证：
:irc.example.com 251 ctest :There are 1 users and 0 services on 2 servers
:irc.example.com 255 ctest :I have 1 users, 0 services and 1 servers
LINKS 命令查看联邦拓扑（实测）：
:irc.example.com 364 ctest irc2.example.com irc.example.com :1 ngIRCd 28 Demo Server #2
:irc.example.com 364 ctest irc.example.com irc.example.com :0 ngIRCd 28 Demo Server
:irc.example.com 365 ctest * :End of LINKS list
两行 364 分别是本端（hop 0）与对端（hop 1），末尾为各端 Info。
八、PAM 认证专题
PAM = yes（默认值）会让 ngIRCd 在用户注册阶段调用系统 PAM 认证。两个关键事实（官方 doc/PAM.txt 与实测一致）：
- PAM 校验的用户名取自客户端注册时发送的 NICK（而非 USER 的 username 字段）；
- 最常用的
pam_unix模块需要读取/etc/shadow，仅 root 可行——而生产部署通常已通过ServerUID降权，认证必然失败。
本文实测（PAM = yes 且以 irc 用户运行时，客户端发送任意注册命令）：
ERROR :Closing connection: ptest[~ptest@localhost] (Access denied: Bad password?)
连接在注册阶段即被关闭（收不到 001 欢迎行）。
实践建议：
- 降权运行（绝大多数部署）→ 设
PAM = no，需要认证时改用口令（[Global] Password/[Operator]）或外层网关； - 确要 PAM → 以 root 启动 + 降权配置，并改用不依赖 shadow 的 PAM 模块（如 LDAP 后端），
PAMServiceName指向专用的/etc/pam.d/<名称>； PAMIsOptional = yes可放宽为「认证可选」：未通过者仍可连接但保留~前缀、不计入 identified——注意与Ident同开时两者都无~前缀，无法区分身份来源。
九、configtest 工作流与配置错误实录
9.1 标准工作流
$ ngircd --configtest
ngIRCd 28-CHARCONV+IDENT+IPv6+IRCPLUS+PAM+SSL+SYSLOG+TCPWRAP+ZLIB-x86_64/pc/linux-gnu
Copyright (c)2001-2026 Alexander Barton (<alex@barton.de>) and Contributors.
...
Using default configuration file "/usr/local/etc/ngircd.conf" ...
Reading configuration from "/usr/local/etc/ngircd.conf" ...
Ok, dump of your server configuration follows:
[GLOBAL]
Name = irc.example.com
...
出现 Ok, dump of your server configuration follows: 即解析通过；dump 内容是实际生效值（含默认填充与片段合并结果），排障时以此为准而非配置文件原文。
9.2 配置错误实录（全部实测踩坑）
- 模式值带
+前缀报错：DefaultChannelModes = +n会让 configtest 报错误行，正确写法是不带+（DefaultChannelModes = n）。 - 注释符截断参数值：
AllowedChannelTypes = #这种把值丢在#后面的写法，#起始注释导致该行实际为空值；曾依赖 configtest dump 对照发现并修复。 - MotdPhrase 优先级：与
MotdFile同时设置时短语生效、文件被忽略（dump 中MotdFile =为空）；另外短语值不加引号——带引号时引号会原样出现在客户端 MOTD 里。 - 重复键：同键多次出现取最后一个值（28 版行为），旧版本会忽略新值；排查「改了不生效」时先查文件里是否有重复键。
十、参考链接
- 官方配置模板（源码树 doc/sample-ngircd.conf.tmpl）：https://github.com/ngircd/ngircd/blob/master/doc/sample-ngircd.conf.tmpl
- ngircd.conf(5) 手册：https://ngircd.barton.de/documentation.php.en
- NEWS（28 版配置行为变更）：https://github.com/ngircd/ngircd/blob/master/NEWS
- PAM 部署说明（源码树 doc/PAM.txt）：https://github.com/ngircd/ngircd/blob/master/doc/PAM.txt
- 站内对照：《ngIRCd 28 介绍与选型指南》、《Debian 12 安装 ngIRCd 28 指南》
章节目录