SquirrelMail 1.4.22 常用 CLI 命令与工具详解

SquirrelMail 1.4.22 运维工具箱实测：conf.pl 交互向导用法与无 CLI 参数结论、配置体检三件套、doveadm/postconf 后端诊断链、curl 端到端探活与 config_local.php 配置分发实践。

SquirrelMailSquirrelMail邮件服务2026/10/27

SquirrelMail 1.4.22 常用 CLI 命令与工具详解

目标：整理 SquirrelMail 1.4.22 日常运维可用的命令行工具与诊断手段——官方配置向导 conf.pl 的交互用法与自动化边界、配置文件体检、官方自检页、邮件后端诊断命令与端到端探活。SquirrelMail 自身无守护进程、无专属服务管理命令，其 CLI 运维面由「配置向导 + 配置文件工具链 + 后端诊断命令」构成，本篇逐项实测。全部回显来自 2026-10-27 在 Ubuntu 22.04（Apache + PHP 7.4.33 + Postfix + Dovecot）实测环境。

一、环境信息

  • 实测系统：Ubuntu 22.04（jammy），x86_64
  • 实测应用：SquirrelMail 1.4.22（/usr/share/squirrelmail-webmail-1.4.22），Apache/2.4.52 + PHP 7.4.33（ppa:ondrej/php）
  • 实测后端：本机 Postfix（SMTP 25）+ Dovecot 2.3.16（IMAP 143），演示域 example.com、演示账号 admin
  • 访问入口：http://127.0.0.1/webmail/（Apache Alias）
  • 安装过程见《Ubuntu 22.04 安装 SquirrelMail 1.4.22 指南》；参数逐项语义见《SquirrelMail 1.4.22 配置参数详解》

二、工具总览

实测确认的运维工具清单与定位：

工具/命令类型定位自动化能力
config/conf.pl官方交互向导（Perl TUI）十项菜单改 config.php 并写盘无（实测不支持任何 CLI 参数，无法脚本化）
php7.4 -l config.phpPHP 语法体检配置改动后的快速排错好（可脚本化）
php7.4 -r "include config.php; ..."配置值断言无界面读取生效参数好（可脚本化）
src/configtest.php（curl 访问）官方自检页运行时/路径/扩展全项自检好（HTTP 状态+关键词断言）
doveadm auth testIMAP 侧诊断验证账号凭据（登录排障第一步）好
doveconf / postconfIMAP/SMTP 侧诊断读后端生效配置好
/var/log/mail.log日志IMAP 认证与投递记录好
curl（登录链路三连）端到端探活无浏览器验证登录+收件箱好（可纳入巡检脚本）

💡 技术拓展：为什么 SquirrelMail 没有 service/squirrelmailctl 之类的管理命令？它是一组纯 PHP 页面（CGI 模型），没有常驻服务进程，Apache 才是承载它的服务（systemctl restart apache2 是唯一涉及的服务动作，且仅在改 PHP 运行时参数时才需要）；配置全部是文件，因此其"CLI 面"围绕文件与 HTTP 自检展开。

三、官方配置向导 conf.pl（交互式）

3.1 启动与主菜单

perl /usr/share/squirrelmail-webmail-1.4.22/config/conf.pl

实测主菜单回显（节选）：

SquirrelMail Configuration : Read: config.php (1.4.0)
---------------------------------------------------------
Main Menu --
1.  Organization Preferences
2.  Server Settings
3.  Folder Defaults
4.  General Options
5.  Themes
6.  Address Books
7.  Message of the Day (MOTD)
8.  Plugins
9.  Database
10. Languages

导航规则（实测确认）：输入编号进子菜单 → 子菜单内输编号/字母改项 → 输入新值 → S 保存写盘 → R 返回上级 → Q 退出。头部 Read: config.php (1.4.0) 指明读写对象。

3.2 写回实测

实测路径：1（组织偏好）→ 1（Organization Name）→ 输入 SM Test Lab → S → Q，随后核对：

grep -n org_name /usr/share/squirrelmail-webmail-1.4.22/config/config.php

实测输出（向导写入后）：

12:$org_name      = "SM Test Lab";

向导确实把值写进了 config.php；未保存就退出会得到确认提示（实测存在保存前缓冲，S 后再退出才落盘）。保存后页面即时生效（PHP 每请求加载配置）。

3.3 自动化边界（重要实测结论）

perl config/conf.pl --help 2>&1 | head -3; echo "EXIT=$?"

实测输出（传入参数仍进入交互界面等待输入，管道未接终端时自动退出）：

EXIT=0

结论：conf.pl 不支持非交互模式——没有 --set key=value、没有应答文件。多机批量/巡检自动化应绕开向导，直接对 config.php 做文件级分发（见第七章），或用 config_local.php 覆盖（见第七章）。本篇因此把 conf.pl 定位为「单机一次性初始化工具」，这也是本系列把 CLI 篇做成运维工具箱（而非纯服务管理命令手册）的原因。

四、配置体检三件套（可脚本化）

4.1 语法体检：php -l

php7.4 -l /usr/share/squirrelmail-webmail-1.4.22/config/config.php

实测输出：

No syntax errors detected in /usr/share/squirrelmail-webmail-1.4.22/config/config.php

手工编辑 config.php 后先过这关——配置文件语法坏了整站白屏，-l 不执行代码无副作用。

4.2 配置值断言：php -r include

无界面读出生效值（比 grep 更接近运行时真相，能发现被 config_local.php 覆盖后的实际结果）：

php7.4 -r "include '/usr/share/squirrelmail-webmail-1.4.22/config/config.php'; echo \"org_name=\$org_name imap=\$imapServerAddress:\$imapPort smtp=\$smtpServerAddress:\$smtpPort plugins=\".count(\$plugins).PHP_EOL;"

实测输出（默认发布包形态）：

org_name=SquirrelMail imap=localhost:143 smtp=localhost:25 plugins=0

把该命令接进巡检脚本即可对关键参数（IMAP/SMTP 指向、语言、Cookie 策略）做断言比对。

4.3 官方自检页：src/configtest.php

curl -s -o /tmp/ct.html -w "configtest HTTP:%{http_code}\n" http://127.0.0.1/webmail/src/configtest.php

实测输出：

configtest HTTP:200

正文自检项实测回显（节选）：

SquirrelMail version:  1.4.22
Config file version:  1.4.0
Checking PHP configuration...
    PHP version 7.4.33 OK.
    Running as www-data(33) / www-data(33)
    variables_order OK: GPCS.
    PHP extensions OK. Dynamic loading is disabled.
Checking paths...
    Data dir OK.
    Attachment dir OK.
    Themes OK.

巡检脚本可断言两件事：HTTP 200，以及页面中不出现 ERROR/WARNING 关键词（自检页对每个失败项都会以这两个词打头）。

五、邮件后端诊断（IMAP/SMTP 侧）

SquirrelMail 登录/收发问题多数根源在后端，以下命令构成定位链：

5.1 凭据验证（登录排障第一步）

doveadm auth test admin q1w2e3r4

实测输出：

passdb: admin auth succeeded
extra fields:

  user=admin

auth succeeded 才说明凭据在 IMAP 侧有效；失败时同步看 5.3 的日志行定位原因（明文认证被禁/密码错/用户不存在三种最常见）。

5.2 后端生效配置读取

doveconf disable_plaintext_auth
doveconf mail_location
postconf myhostname mydestination

实测输出：

disable_plaintext_auth = no
mail_location = mbox:~/mail:INBOX=/var/mail/%u
myhostname = sm-webmail.localdomain
mydestination = $myhostname, example.com, sm-webmail, localhost.localdomain, localhost

与 SquirrelMail 侧的关联：disable_plaintext_auth = no 必须放开（1.4.22 默认明文 PLAIN 认证）；mail_location 决定收件箱落点（与 $default_folder_prefix 语义对齐）；mydestination 含 $domain 域名才能收本域信。

5.3 日志观测

tail -20 /var/log/mail.log | grep -E "imap-login|Warning" | tail -3

实测输出（成功登录样例）：

Oct 27 05:38:12 sm-webmail dovecot: imap-login: Login: user=<admin>, method=PLAIN, rip=127.0.0.1, lip=127.0.0.1, mpid=12421, TLS

日志里能直接读出认证方式（method=PLAIN）、来源 IP 与成败——「页面报 Unknown user or password incorrect」时这行日志就是判决书。

六、端到端探活（curl 三连）

无浏览器验证整条链路（登录 POST → 会话 → 收件箱页），可原样纳入巡检：

rm -f /tmp/sm_cookie
curl -s -c /tmp/sm_cookie -o /tmp/rd.html -w 'login POST HTTP:%{http_code}\n' \
  -d 'login_username=admin' -d 'secretkey=q1w2e3r4' \
  -d 'js_autodetect_results=0' -d 'just_logged_in=1' \
  http://127.0.0.1/webmail/src/redirect.php
curl -s -b /tmp/sm_cookie -o /tmp/in.html -w 'right_main HTTP:%{http_code} SIZE:%{size_download}\n' \
  http://127.0.0.1/webmail/src/right_main.php
grep -oE '<title>[^<]*</title>' /tmp/in.html

实测输出（健康态）：

login POST HTTP:302
right_main HTTP:200 SIZE:5863
<title>SquirrelMail 1.4.22</title>

断言口径：登录 POST 应 302（失败是 200 + 错误页）；收件箱应 200 且标题含版本号；正文出现 Unknown user or password incorrect 即 IMAP 认证层失败（回第五章凭据链排查）。

七、配置分发与本地覆盖（运维实践）

7.1 config_local.php 覆盖模式

config.php 末行实测存在 @include SM_PATH . 'config/config_local.php';，把站点本地化参数集中写入该文件，官方文件保持原样：

cd /usr/share/squirrelmail-webmail-1.4.22
cp config/config_local.php.bak config/config_local.php
echo '<?php $org_name = "Override Lab";' > config/config_local.php
php7.4 -r "include 'config/config.php'; echo \"org_name=\$org_name\n\";"

实测输出（覆盖生效且 config.php 未动）：

org_name=Override Lab

7.2 文件级分发

多机统一配置的实测可行做法：以一台验证机为准，分发两个文件到各机同路径——config/config.php（全量基准）与 config/config_local.php（站点差异），分发后跑第四章三件套体检。由于 1.4.22 上游已停止演进（2011-07 后无版本），该基准可长期冻结，分发链路一次建成即稳定。

八、常见问题（FAQ）

Q1：conf.pl 能写自动化脚本吗？

不能。实测传入任何 CLI 参数（含 --help）都仍进入交互 TUI，无应答文件、无环境变量开关。批量配置走第七章文件分发；单机交互初始化才用 conf.pl。

Q2：conf.pl 保存后页面显示的还是旧值？

确认 S 是否真的执行（退出层级时 Q 不会替代保存）；再用 4.2 的 php -r include 打印实际值，区分「文件没写进去」与「被 config_local.php 覆盖」两种情况。

Q3：巡检脚本怎么判断站点健康？

三层断言：① src/configtest.php 返回 200 且无 ERROR/WARNING（环境层）；② curl 三连 302/200/标题带版本号（链路层）；③ php -r include 关键参数符合预期（配置层）。三层全绿即健康。

Q4：改了 config.php 要重启 Apache 吗？

不需要。PHP 每请求重新加载配置文件，保存即生效；只有改 php.ini/Apache 配置才需要 systemctl restart apache2（实测确认）。

Q5：日志里 imap-login 显示 TLS 但登录仍失败？

看日志行尾的错误码：auth failed 前一行通常有 auth-worker 明细（密码错/用户不存在）；若提示 plaintext auth disabled 则回 5.2 放开 disable_plaintext_auth（这是 1.4.22 对接 Dovecot 最常见的坑）。

九、参考链接