Cyrus IMAP 3.4 配置参数详解

imapd.conf/cyrus.conf 双配置体系逐项详解，含 TLS 证书、993 IMAPS、STARTTLS、禁明文与 SASL 机制白名单的端到端加固实测（3.4.3）。

Cyrus IMAPCyrus IMAP邮件服务器配置2026/10/25

Cyrus IMAP 3.4 配置参数详解

目标：讲清 Cyrus IMAP 3.4 的双配置体系（/etc/imapd.conf 服务参数 + /etc/cyrus.conf 进程编排），逐项解释核心参数，并完成 TLS 加密与 SASL 认证加固的端到端实测（143 禁明文、993 IMAPS、STARTTLS、机制白名单）。全文基于 Ubuntu 22.04 官方仓库 3.4.3 实测。

一、环境信息

  • 服务器：Ubuntu 22.04.5 LTS，主机名 mail.example.com
  • 软件：cyrus-imapd 3.4.3-3ubuntu0.3（安装过程见《Ubuntu 22.04 安装 Cyrus IMAP 3.4 指南》）
  • 配置文件：/etc/imapd.conf、/etc/cyrus.conf；证书目录 /etc/cyrus/tls/
  • 演示账号：cyrus（管理员）、admin（业务用户），密码 q1w2e3r4

二、前置条件

  • 已按安装篇完成 Cyrus IMAP 3.4 安装并能登录（imtest 返回 User logged in）；
  • 本文所有改动后均需 systemctl restart cyrus-imapd 生效（两个配置文件都不支持热加载）。

三、参数查看与修改方式

Cyrus 有两个配置文件，职责完全不同：

文件角色改动后生效方式
/etc/imapd.conf服务行为参数：存储、认证、TLS、配额、命名空间restart cyrus-imapd
/etc/cyrus.confmaster 进程编排：启动钩子、监听服务、定时事件restart cyrus-imapd

查看当前生效的全部 imapd.conf 参数（含默认值归一后的结果）：

/usr/lib/cyrus/bin/cyr_info conf

admins: cyrus
allowplaintext: yes
altnamespace: no
autocreate_quota: 0
configdirectory: /var/lib/cyrus
defaultpartition: default
hashimapspool: yes
httpmodules: caldav carddav

（输出较长，以上为实测节选）

修改方式：直接编辑文件后重启服务。改前建议备份：

cp /etc/imapd.conf /etc/imapd.conf.bak.$(date +%F)

四、参数总览

按职能把 imapd.conf 常用参数分六组（默认值取自 3.4.3 Debian 默认配置实测）：

分组代表参数说明
存储路径configdirectory、partition-default、hashimapspool元数据库与邮件存储布局
访问控制admins、allowplaintext、allowanonymouslogin管理员与登录安全基线
认证 SASLsasl_pwcheck_method、sasl_mech_list、sasl_sasldb_path认证后端与机制白名单
TLStls_server_cert、tls_server_key、tls_versions_min传输加密
命名空间altnamespace、unixhierarchysep、virtdomains邮箱名呈现与多域
配额与资源autocreate_quota、quotawarn新建邮箱默认配额等

五、核心参数分类详解

5.1 存储路径组

configdirectory: /var/lib/cyrus
defaultpartition: default
partition-default: /var/spool/cyrus/mail
hashimapspool: true
  • configdirectory：邮箱列表（mailboxes.db）、配额、订阅、已读状态、TLS 会话等元数据库所在目录，备份时与邮件存储同等重要。
  • partition-default：邮件正文与索引实际落盘位置；可用 partition-xxx: 定义多个分区挂到不同磁盘。
  • hashimapspool: yes（默认）：邮箱目录按用户名散列到子目录（如 user.admin → /var/spool/cyrus/mail/a/user/admin），避免单目录文件数爆炸。实测：
/usr/lib/cyrus/bin/mbpath user.admin

/var/spool/cyrus/mail/a/user/admin

5.2 访问控制组

admins: cyrus
allowanonymouslogin: no
allowplaintext: yes
  • admins：空格分隔的管理员列表，可对所有邮箱执行管理操作（建删邮箱、设 ACL/配额）。deb 非交互安装默认没有这一行，必须手工补。
  • allowanonymouslogin: no：默认即禁匿名，保持。
  • allowplaintext: yes：默认允许明文密码登录，是生产最大隐患，加固见第六章。

5.3 认证 SASL 组

sasl_pwcheck_method: auxprop
sasl_sasldb_path: /etc/sasldb2   # Debian 默认位置（可不写）
sasl_auto_transition: no
  • sasl_pwcheck_method：认证后端。auxprop 读本地 sasldb2（本文场景）；saslauthd 走系统认证守护进程（可桥接 PAM/LDAP）；大型企业可换 ldap 直连目录。
  • sasl_mech_list：SASL 机制白名单（默认全放），加固时收缩（第六章实测）。

💡 技术拓展：SASL 认证后端常见选项——

后端数据源适用
auxprop(sasldb2)本地 Berkeley DB 账号库中小规模、账号与系统账户隔离
saslauthd→PAM系统用户/shadow与系统账号打通的小团队
saslauthd→LDAPOpenLDAP/AD企业统一身份
Kerberos/GSSAPIKDC 票据已有 Kerberos 体系的组织

本文演示环境采用 auxprop(sasldb2)，账号独立于系统用户、迁移简单。

5.4 TLS 组

tls_server_cert: /etc/cyrus/tls/mail.example.com.crt
tls_server_key: /etc/cyrus/tls/mail.example.com.key
tls_versions_min: 1.2
tls_session_timeout: 1440
  • tls_server_cert/tls_server_key：服务证书与私钥路径，配置上后 STARTTLS 与 IMAPS 才可用；
  • tls_versions_min: 1.2：拒绝 TLS1.0/1.1 老协议；
  • tls_session_timeout: 1440（分钟）：TLS 会话缓存有效期，配合 cyrus.conf 的 tlsprune 定时清理。

5.5 命名空间组

altnamespace: no
unixhierarchysep: no
virtdomains: 默认未开
  • altnamespace: no：客户端看到的个人邮箱为 INBOX 顶级视图；改 yes 后共享/他人邮箱平级呈现，老客户端兼容性好的是默认值。
  • unixhierarchysep: no：层级分隔符用 .（user.admin.Sent）；置 yes 改用 /，且允许用户名中带 .。
  • virtdomains：多域名托管时开启，登录名变为 user@domain 全限定形式；单域场景保持默认即可。

5.6 配额组

autocreate_quota: 0

5.7 cyrus.conf 进程编排

START {
	recover		cmd="/usr/sbin/cyrus ctl_cyrusdb -r"
	delprune	cmd="/usr/sbin/cyrus expire -E 3"
	tlsprune	cmd="/usr/sbin/cyrus tls_prune"
}
SERVICES {
	imap		cmd="imapd -U 30" listen="imap" prefork=0 maxchild=100
	imaps		cmd="imapd -s -U 30" listen="imaps" prefork=0 maxchild=100
	lmtpunix	cmd="lmtpd" listen="/run/cyrus/socket/lmtp" prefork=0 maxchild=20
	sieve		cmd="timsieved" listen="localhost:sieve" prefork=0 maxchild=100
	notify		cmd="notifyd" listen="/run/cyrus/socket/notify" proto="udp" prefork=1
}
EVENTS {
	checkpoint	cmd="/usr/sbin/cyrus ctl_cyrusdb -c" period=30
	delprune	cmd="/usr/sbin/cyrus expire -E 3" at=0401
	tlsprune	cmd="/usr/sbin/cyrus tls_prune" at=0401
	deleteprune	cmd="/usr/sbin/cyrus expire -E 4 -D 28" at=0430
	expungeprune	cmd="/usr/sbin/cyrus expire -E 4 -X 28" at=0445
}
  • START：master 启动时先跑一次的任务——recover 恢复数据库一致性（断电后自愈的第一道）、两个清理任务。
  • SERVICES：每行定义一个监听服务，cmd 是可执行文件（必须在磁盘存在，否则 master 拒绝启动——安装篇的 pop3 排障即此机制），listen 可为服务名（查 /etc/services 得端口）或绝对路径套接字，maxchild 限制并发 fork 数。
  • EVENTS：cron 式定时任务，period（分钟周期）或 at（每日时刻）。checkpoint 每 30 分钟刷一次数据库检查点；deleteprune/expungeprune 每日清理 28 天前的延迟删除邮件。

六、TLS 与 SASL 加固实测（生产必做）

目标：143 端口禁明文密码、启用 993 IMAPS 与 143 STARTTLS、SASL 机制收缩白名单。以下全程实测。

6.1 生成自签名证书

内网/演示用自签名证书（生产替换为受信 CA 证书）：

mkdir -p /etc/cyrus/tls
openssl req -x509 -newkey rsa:2048 \
  -keyout /etc/cyrus/tls/mail.example.com.key \
  -out /etc/cyrus/tls/mail.example.com.crt \
  -days 3650 -nodes \
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Example/CN=mail.example.com"
chown -R cyrus:mail /etc/cyrus/tls
chmod 600 /etc/cyrus/tls/mail.example.com.key
ls -l /etc/cyrus/tls/

-rw-r--r-- 1 cyrus mail 1318 Oct 25 04:19 mail.example.com.crt
-rw------- 1 cyrus mail 1704 Oct 25 04:19 mail.example.com.key

⚠️ 注意：私钥必须 600 且属主含 cyrus 可读，否则 imapd 以 cyrus 身份启动后读不到私钥，TLS 握手直接失败。

6.2 配置 TLS 参数并启用 imaps 服务

imapd.conf 追加三行：

cat >> /etc/imapd.conf <<EOF
tls_server_cert: /etc/cyrus/tls/mail.example.com.crt
tls_server_key: /etc/cyrus/tls/mail.example.com.key
tls_versions_min: 1.2
EOF

cyrus.conf 放开 imaps 行（注意：Murder 代理段还有一行同名的 #imaps cmd="proxyd -s ..."，只能放开 imapd -s 那一行）：

sed -i -E 's/^(\s*)#(imaps\tcmd="imapd)/\1\2/' /etc/cyrus.conf
grep -nE 'imaps' /etc/cyrus.conf

32:	imaps		cmd="imapd -s -U 30" listen="imaps" prefork=0 maxchild=100
66:	#imaps		cmd="proxyd -s" listen="imaps" prefork=0 maxchild=100

重启并验证 993 监听：

systemctl restart cyrus-imapd
systemctl is-active cyrus-imapd
ss -ltn | grep -E ':(143|993|4190)'

active
LISTEN 0 32 127.0.0.1:4190 0.0.0.0:*
LISTEN 0 32 0.0.0.0:993    0.0.0.0:*
LISTEN 0 32 0.0.0.0:143    0.0.0.0:*

排障实录：若误放开两行 imaps，启动报 master: multiple entries for service 'imaps'、服务 status=78/CONFIG 退出；按上面 grep 结果把 proxyd 那行恢复注释即可。

6.3 验证 993 IMAPS 与证书

echo | openssl s_client -connect localhost:993 -servername mail.example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates

subject=C = CN, ST = Shanghai, L = Shanghai, O = Example, CN = mail.example.com
issuer=C = CN, ST = Shanghai, L = Shanghai, O = Example, CN = mail.example.com
notBefore=Oct 25 04:19:30 2026 GMT
notAfter=Oct 22 04:19:30 2036 GMT

用测试客户端走 TLS 登录：

/usr/lib/cyrus/bin/imtest -s -m login -u admin -a admin -w q1w2e3r4 localhost

TLS connection established: TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
S: * OK [CAPABILITY IMAP4rev1 LITERAL+ ID ENABLE AUTH=SCRAM-SHA-1-PLUS AUTH=SCRAM-SHA-1 AUTH=SCRAM-SHA-256-PLUS AUTH=SCRAM-SHA-256 AUTH=DIGEST-MD5 AUTH=NTLM AUTH=CRAM-MD5 AUTH=LOGIN AUTH=PLAIN SASL-IR] mail.example.com Cyrus IMAP 3.4.3-dirty-Debian-3.4.3-3ubuntu0.3 server ready
Authenticated.

TLSv1.3 握手成功；TLS 通道建立后 SASL 机制里多出 SCRAM-*-PLUS（通道绑定变体），说明加密层已生效。

6.4 禁明文登录 + SASL 机制白名单

sed -i 's/^allowplaintext: yes/allowplaintext: no/' /etc/imapd.conf
echo 'sasl_mech_list: PLAIN LOGIN SCRAM-SHA-256' >> /etc/imapd.conf
systemctl restart cyrus-imapd

验证 143 端口已拒绝明文密码登录：

/usr/lib/cyrus/bin/imtest -m login -u admin -a admin -w q1w2e3r4 localhost

S: * OK [CAPABILITY IMAP4rev1 LITERAL+ ID ENABLE STARTTLS LOGINDISABLED AUTH=SCRAM-SHA-256 SASL-IR] mail.example.com Cyrus IMAP 3.4.3-dirty-Debian-3.4.3-3ubuntu0.3 server ready
[Server advertised LOGINDISABLED]
Authentication failed. generic failure

三个信号同时生效：banner 出现 LOGINDISABLED（禁 LOGIN/PLAIN 于未加密连接）、AUTH= 只剩 SCRAM-SHA-256（白名单生效）、明文登录被拒。

143 端口的正确姿势是先 STARTTLS 升级再认证：

/usr/lib/cyrus/bin/imtest -t "" -m login -u admin -a admin -w q1w2e3r4 localhost

S: * OK [CAPABILITY IMAP4rev1 LITERAL+ ID ENABLE STARTTLS LOGINDISABLED AUTH=SCRAM-SHA-256 SASL-IR] mail.example.com Cyrus IMAP 3.4.3-dirty-Debian-3.4.3-3ubuntu0.3 server ready
C: S01 STARTTLS
S: S01 OK Begin TLS negotiation now
TLS connection established: TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)

993 端口上白名单内机制完整可见（TLS 内允许 PLAIN/LOGIN）：

S: * OK [CAPABILITY IMAP4rev1 LITERAL+ ID ENABLE AUTH=PLAIN AUTH=LOGIN AUTH=SCRAM-SHA-256-PLUS AUTH=SCRAM-SHA-256 SASL-IR] mail.example.com Cyrus IMAP 3.4.3-dirty-Debian-3.4.3-3ubuntu0.3 server ready

💡 技术拓展：SASL 机制安全性梯度——

机制密码形态评价
PLAIN / LOGIN明文 base64仅在 TLS 内可接受
CRAM-MD5 / DIGEST-MD5挑战-响应算法老旧，建议淘汰
SCRAM-SHA-256加盐迭代哈希现代推荐，本文白名单保留
SCRAM-*-PLUSSCRAM + TLS 通道绑定防降级，TLS 下自动出现
GSSAPIKerberos 票据企业 Kerberos 环境

本文白名单 PLAIN LOGIN SCRAM-SHA-256 的取舍：TLS 内兼容老客户端（PLAIN/LOGIN），同时提供现代机制（SCRAM-SHA-256）。

七、生产配置模板

适用场景：16GB 内存、SSD、单域、500 邮箱以内的小型生产（TLS 强制 + 白名单 + 配额兜底）。

# /etc/imapd.conf 生产模板
servername: mail.example.com
admins: cyrus
configdirectory: /var/lib/cyrus
proc_path: /run/cyrus/proc
mboxname_lockpath: /run/cyrus/lock
defaultpartition: default
partition-default: /var/spool/cyrus/mail
hashimapspool: true
altnamespace: no
unixhierarchysep: no
allowanonymouslogin: no
allowplaintext: no
sasl_pwcheck_method: auxprop
sasl_mech_list: PLAIN LOGIN SCRAM-SHA-256
sasl_auto_transition: no
tls_server_cert: /etc/cyrus/tls/mail.example.com.crt
tls_server_key: /etc/cyrus/tls/mail.example.com.key
tls_versions_min: 1.2
tls_session_timeout: 1440
autocreate_quota: 102400
sievedir: /var/spool/sieve
sieveusehomedir: false
lmtpsocket: /run/cyrus/socket/lmtp
idlesocket: /run/cyrus/socket/idle
notifysocket: /run/cyrus/socket/notify
syslog_prefix: cyrus
umask: 077

cyrus.conf 使用 5.7 的裁剪版（imap + imaps + lmtpunix + sieve + notify）。autocreate_quota: 102400 即新邮箱默认 100MB 配额，按磁盘容量调整。

八、常见问题（FAQ)

Q1：改完配置不生效？ 两个配置文件都不热加载，必须 systemctl restart cyrus-imapd；用 cyr_info conf 核对生效值。

Q2：993 起不来、日志说找不到证书？ 检查 ls -l /etc/cyrus/tls/：私钥属主/权限必须允许 cyrus 用户读取（建议 cyrus:mail + 600）。

Q3：143 上客户端提示「服务器不支持登录」？ 这是 allowplaintext: no 生效的标志（LOGINDISABLED），客户端需勾选「STARTTLS」或改用 993 的 SSL/TLS 直连。

Q4：sasl_mech_list 把客户端挡在门外？ 白名单外的机制（如 CRAM-MD5）被移除后，只支持旧机制的客户端会认证失败；先 imtest 看 banner 的 AUTH= 列表，再让客户端换机制或走 TLS 内 PLAIN。

九、参考链接