Webmin 2.670 常用 CLI 命令与工具详解

Webmin 2.670 命令行工具全集实测：webmin 主 CLI 10 个子命令（server/list-config/set-config/passwd/patch 等）、changepass.pl 与 install-module.pl、/etc/webmin 服务控制脚本，全部命令配真实回显。

WebminWebmin服务器管理2026/10/21

Webmin 2.670 常用 CLI 命令与工具详解

目标：系统性讲清 Webmin 2.670 自带的命令行工具集——webmin 主 CLI 的全部子命令、独立 Perl 脚本（changepass.pl、install-module.pl 等）与 /etc/webmin 服务控制脚本，逐一给出语法、参数与实测回显，让运维可以在不开浏览器的情况下完成日常管理与自动化。全部输出取自 Ubuntu 22.04.5 实测环境。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 软件版本：Webmin 2.670、Authentic Theme 26.70
  • 安装方式：官方 apt 仓库（程序位于 /usr/share/webmin，配置位于 /etc/webmin）
  • 服务单元：webmin.service（systemd）
/usr/share/webmin/bin/webmin --version

2.670

二、工具概览

Webmin 的命令行工具分三层：

层工具用途
主 CLI/usr/share/webmin/bin/webmin统一入口，自带 10 个子命令（服务控制、配置读写、口令、补丁、代理、双因素等）
独立脚本/usr/share/webmin/changepass.pl、install-module.pl、setup.pl、oschooser.pl、copyconfig.pl 等初始化、改口令、装卸模块等单点操作
服务控制脚本/etc/webmin/start、stop、restart、reload、restart-by-force-killsystemctl 的便捷包装（systemd 系统）或直接拉起 miniserv（非 systemd 系统）

主 CLI 的子命令全集（--list-commands --describe 实测输出）：

/usr/share/webmin/bin/webmin --list-commands --describe

disable-proxy
Description:
    Disable proxy-related features in Webmin.

disable-twofactor
Description:
    Disable two factor authentication for a given user. Useful in cases
    where the second factor (e.g. phone or USB key) has been lost.

enable-proxy
Description:
    Configure the Webmin web server to be proxied through another web
    server, like Apache or nginx. This is not usually recommended, and
    disables some security features, but can help traverse a firewall.

language-manager
Description:
    Manage Webmin/Usermin module language files
    (lang|ulang|help|config|uconfig|module), to perform transcoding,
    translation, spell check and add/remove language strings.

list-config
Description:
    List one or all configuration directives for "miniserv.conf" or a module
    "config" file.

passwd
Description:
     This program allows you to change the password used by a Webmin user.
     When a matching Unix user exists, it can change the Unix password or set a
     separate password in the Webmin password file.

patch
Description:
    Apply a patch to Webmin core or its modules from GitHub/GitLab, a local
    file, or by downloading and replacing the entire file from a raw URL.

    Multiple patches can be given at once and are applied in the given
    order, stopping at the first failure. Webmin is restarted only once
    after all patches are applied.

server
Description:
     This program allows you to control Webmin web-server

set-config
Description:
    Set a configuration directive in either "miniserv.conf" (the core Webmin
    config) or in the specified module "config".

update-devel
Description:
    Update Webmin/Usermin and/or Authentic Theme from Git, with latest
    unstable, development version.

三、前置条件

  • 以 root 身份执行（配置读写与服务控制均需 root）；
  • tar.gz 方案安装时工具位于安装目录下的 bin/（如 /root/webmin-2.670/bin/webmin），deb/apt 方案位于 /usr/share/webmin/bin/；
  • 建议把 CLI 目录加入 PATH 或用别名，例如 alias webmin=/usr/share/webmin/bin/webmin（本文按绝对路径书写）。

四、webmin 主 CLI 详解

4.1 全局选项

webmin --help 实测输出（用法总览）：

/usr/share/webmin/bin/webmin --help

Name:
    webmin

Description:
    Webmin CLI command to perform many common Webmin tasks from the command
    line or from scripts.

Usage:
    webmin [options] subcommand [subcommand options]

Options:
    --help, -h
        Print this usage summary and exit. Subcommands may also have a usage
        summary.

    --config <path>, -c <path>
        Specify the full path to the Webmin configuration directory.
        Defaults to "/etc/webmin".

    --list-commands, -l
        List available subcommands.

    --describe, -d
        When listing commands, briefly describe what they do.

    --man <command>, -m <command>
        Display the manual page for the given subcommand.

    --version, -v
        Returns current Webmin version installed

    --versions
        Returns Webmin and other modules and themes versions installed (only
        those for which version is available)

Exit Codes:
    0 on success ; non-0 on error

License and Copyright:
     Copyright 2018 Jamie Cameron <jamie@webmin.com>
                    Joe Cooper <joe@virtualmin.com>
                    Ilia Ross <ilia@virtualmin.com>

版本与组件版本实测：

/usr/share/webmin/bin/webmin --versions

Webmin: 2.670 [/usr/share/webmin]
  Themes:
    Authentic Theme: 26.70 [authentic-theme]

--man 查看子命令手册（以 passwd 为例）：

/usr/share/webmin/bin/webmin --man passwd

Name:
     passwd

Description:
     This program allows you to change the password used by a Webmin user.
     When a matching Unix user exists, it can change the Unix password or set a
     separate password in the Webmin password file.

Usage:
     webmin passwd [options]

Options:
    --help, -h
         Print this usage summary and exit.

         Examples of usage:
          - webmin passwd root
          - webmin passwd --user root
          - webmin passwd --user root --unix
          - webmin passwd --user admin --webmin-only

--man --list-commands 列出所有有手册的子命令（实测返回 10 个子命令名，同第二章表）。

4.2 server——服务控制

语法：webmin server [status|start|stop|restart]（等价写法：webmin status/webmin restart，两者是 server 子命令的别名）。帮助实测：

/usr/share/webmin/bin/webmin server

Name:
     server

Description:
     This program allows you to control Webmin web-server

Usage:
     webmin server [command]
     webmin [command]

Options:
    --help, -h
         Print this usage summary and exit.

         Examples of usage:
           - webmin server status
           - webmin server restart
           - webmin server --config /usr/local/etc/webmin --command start
           - webmin status
           - webmin restart

    --config, -c
         Specify the full path to the Webmin configuration directory. Defaults to C</etc/webmin>

    --command, -x
         Available commands:
           - status
           - start
           - stop
           - restart

server status 实测（透出 systemd 单元状态）：

/usr/share/webmin/bin/webmin server status

● webmin.service - Webmin server daemon
     Loaded: loaded (/lib/systemd/system/webmin.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-21 06:58:26 UTC; 1min 37s ago
   Main PID: 5084 (miniserv.pl)
      Tasks: 2 (limit: 94371)
     Memory: 33.0M
        CPU: 859ms
     CGroup: /system.slice/webmin.service
             ├─5084 /usr/bin/perl /usr/share/webmin/miniserv.pl --nofork /etc/webmin/miniserv.conf
             └─5085 /usr/bin/perl /usr/share/webmin/miniserv.pl --nofork /etc/webmin/miniserv.conf

Oct 21 06:58:26 webmin.example.com systemd[1]: Started Webmin server daemon.
Oct 21 06:58:29 webmin.example.com webmin[5084]: Webmin starting
Oct 21 06:58:36 webmin.example.com webmin[5124]: Successful login as root from 127.0.0.1

server restart 实测（执行后无输出，需回查状态）：

/usr/share/webmin/bin/webmin server restart && systemctl is-active webmin

active

巡检脚本示例（可执行形态，server status 输出为空时非 0 退出）：

/usr/share/webmin/bin/webmin server status >/dev/null 2>&1 && echo webmin_ok || echo webmin_down

webmin_ok

4.3 list-config——读配置

三种用法（全量读核心配置 / 单键 / 读模块配置）：

/usr/share/webmin/bin/webmin list-config miniserv.conf

port=10000
root=/usr/share/webmin
mimetypes=/usr/share/webmin/mime.types
addtype_cgi=internal/cgi
realm=Webmin Server
logfile=/var/webmin/miniserv.log
errorlog=/var/webmin/miniserv.error
pidfile=/var/webmin/miniserv.pid
logtime=168
ssl=1
no_ssl2=1
no_ssl3=1
ssl_honorcipherorder=1
no_sslcompression=1
env_WEBMIN_CONFIG=/etc/webmin
env_WEBMIN_VAR=/var/webmin
atboot=1
logout=/etc/webmin/logout-flag
listen=10000
denyfile=\.pl$
log=1
nolistdir=1
blockhost_failures=5
blockhost_time=60
syslog=1

（全量 50 行，此处节选前 25 行。）

/usr/share/webmin/bin/webmin list-config --option ssl

1

/usr/share/webmin/bin/webmin list-config --module acl

ssleay=/usr/bin/openssl
order=0
display=1

⚠️ 注意：该命令的作用域是 miniserv.conf 与各模块 config；全局文件 /etc/webmin/config（含 lang、theme 等键）不在其内，实测 list-config --option lang 报 Unable to retrieve value of lang。

4.4 set-config——写配置

语法：webmin set-config [--module <名>] --option <键> --value <值>。不带 --module 写 miniserv.conf 并自动重启服务；带 --module 写模块配置不重启。实测（含自动重启提示）：

/usr/share/webmin/bin/webmin set-config --option blockhost_failures --value 3

Restarting Webmin to apply miniserv.conf changes...

/usr/share/webmin/bin/webmin list-config --option blockhost_failures

3

还原出厂值并验证：

/usr/share/webmin/bin/webmin set-config --option blockhost_failures --value 5 && /usr/share/webmin/bin/webmin list-config --option blockhost_failures

Restarting Webmin to apply miniserv.conf changes...
5

模块配置写实测（改 acl 模块 display 后回读）：

/usr/share/webmin/bin/webmin set-config --module acl --option display --value 2 && /usr/share/webmin/bin/webmin list-config --module acl | grep display

display=2

/usr/share/webmin/bin/webmin set-config --module acl --option display --value 1 && /usr/share/webmin/bin/webmin list-config --module acl | grep display

display=1

⚠️ 注意：短时间连续执行多条核心键 set-config 会因反复重启命中 systemd 启动频率限制（start-limit-hit），解锁方法：systemctl reset-failed webmin && systemctl start webmin（完整排障实录见本专栏《Webmin 2.670 配置参数详解》篇 Q6）。

4.5 passwd——改 Webmin 用户口令

帮助中的三种用法（实测 --help 输出）：

webmin passwd root                        # 改用户 root 的口令（联动 Unix 密码）
webmin passwd --user root                 # 同上，显式 --user
webmin passwd --user root --unix          # 强制改 Unix 侧密码
webmin passwd --user admin --webmin-only  # 只改 Webmin 侧密码（不碰 Unix）

该命令交互式输入新口令（不回显）。脚本化改口令用 4.6 的 changepass.pl。

4.6 changepass.pl——脚本化改口令

独立脚本，非交互、可直接进自动化。语法：changepass.pl <配置目录> <用户> <新口令>：

/usr/share/webmin/changepass.pl /etc/webmin root q1w2e3r4

Password for Webmin user root updated successfully

💡 说明：在 passwd_mode=0（Webmin 账号与 Unix 用户联动）的默认配置下，该命令实际改写的是系统 /etc/shadow 中该用户的口令；对仅存在于 miniserv.users 的独立账号则只改 Webmin 侧。

4.7 patch——给 Webmin 打补丁

语法与选项（webmin patch 无参数时的帮助实测）：

/usr/share/webmin/bin/webmin patch

Name:
    patch

Description:
    Apply a patch to Webmin core or its modules from GitHub/GitLab, a local
    file, or by downloading and replacing the entire file from a raw URL.

    Multiple patches can be given at once and are applied in the given
    order, stopping at the first failure. Webmin is restarted only once
    after all patches are applied.

Usage:
    webmin patch patch-url/file [patch-url/file ...]

Options:
    --help, -h
        Give this help list.

    --config, -c
        Specify the full path to the Webmin configuration directory.
        Defaults to /etc/webmin

        Examples of usage:

          Apply a patch from a URL.

用法要点：补丁源可以是 URL、GitLab/GitHub 引用或本地文件；多个补丁按顺序应用、首个失败即停；全部应用成功后只重启一次服务。

4.8 enable-proxy / disable-proxy——反代接入与还原

enable-proxy 把 Webmin 配置为「被 Apache/Nginx 反向代理」（官方说明：非推荐做法，会关闭部分安全特性），disable-proxy 还原。两者均无额外参数，实测 help：

/usr/share/webmin/bin/webmin enable-proxy --help

Usage:
    webmin enable-proxy [options]

Options:
    --help, -h
        Print this usage summary and exit.

    --config, -c
        Specify the full path to the Webmin configuration directory.
        Defaults to "/etc/webmin"

⚠️ 注意：反代接入后 Webmin 的会话与 SSL 行为会变化（官方注明 disables some security features），确有 80/443 统一入口诉求时再使用，用完 disable-proxy 还原。

4.9 其余子命令速览

子命令用途备注
disable-twofactor关闭指定用户的双因素认证语法实测：Usage: webmin disable-twofactor --user username；适用于第二因素丢失的应急
language-manager管理模块语言文件（转码/翻译/拼写检查/增删字符串）面向翻译贡献者与汉化定制
update-devel从 Git 更新 Webmin/Usermin/Authentic Theme 到最新开发版仅测试环境使用；apt 场景严禁（会绕过包管理器，/etc/webmin/config 的 noselfwebminup=1 即为此设防）

五、独立脚本与服务控制脚本

5.1 模块装卸（install-module.pl）

安装第三方 .wbm 模块包。无参数执行会打印用法（实测）：

perl /usr/share/webmin/install-module.pl

usage: install-module.pl [--nodeps] [--acl user]* <module.wbm> [config_directory] at /usr/share/webmin/install-module.pl line 16.

参数含义：--nodeps 跳过依赖检查；--acl user 授权指定 Webmin 用户使用该模块（可多次）；config_directory 缺省为 /etc/webmin。

5.2 服务控制脚本（/etc/webmin/start|stop|restart|reload）

deb/apt 安装后，这些脚本是对 systemctl 的包装（tar.gz 方案则直接控制 miniserv 进程）。实测内容：

cat /etc/webmin/start

#!/bin/sh
/usr/bin/systemctl start webmin

cat /etc/webmin/restart && echo --- && cat /etc/webmin/stop

#!/bin/sh
/usr/bin/systemctl restart webmin
---
#!/bin/sh
/usr/bin/systemctl stop webmin

配套脚本一览：

脚本动作
/etc/webmin/startsystemctl start webmin
/etc/webmin/stopsystemctl stop webmin
/etc/webmin/restartsystemctl restart webmin
/etc/webmin/reload向主进程发 HUP（对应 unit 的 ExecReload=/bin/kill -HUP $MAINPID）
/etc/webmin/restart-by-force-kill强杀 miniserv 进程后重新拉起（服务 hang 死时应急）

执行实测（stop → start 全链路；停止后单元短暂显示 failed 属本机实测表现，启动后即恢复 active）：

/etc/webmin/stop; sleep 2; systemctl is-active webmin

failed

/etc/webmin/start; sleep 3; systemctl is-active webmin

active

5.3 其他常用脚本

脚本用途
/usr/share/webmin/setup.pl（或 ./setup.sh）tar.gz 方案的初始化/升级安装器（交互问答实录见本专栏安装指南篇 6.4 节）
/usr/share/webmin/oschooser.pl发行版识别助手（setup 流程内部调用）
/usr/share/webmin/copyconfig.pl在多台服务器间复制模块配置
/usr/share/webmin/miniserv.plMiniServ 服务器本体（systemd unit 的 ExecStart 目标，一般不手工运行）

六、注意事项

  1. 作用域边界：webmin list-config/set-config 只覆盖 miniserv.conf 与模块 config；全局 /etc/webmin/config 用文件编辑 + 重启（实测报错回显见 4.3）。
  2. 每次核心键 set-config 都会重启服务：批量改配置时合并为一次文件修改 + 一次重启，或接受多次重启（注意 start-limit 风险）。
  3. 退出码：主 CLI 规范为「成功 0、失败非 0」（--help 原文 Exit Codes），可直接用于脚本判断。
  4. tar.gz 部署的路径差异：CLI 在 <安装目录>/bin/webmin，服务脚本在 /etc/webmin/，写自动化脚本时不要硬编码 /usr/share/webmin。
  5. passwd 与 changepass.pl 的选择：人工交互用 webmin passwd，自动化/批量用 changepass.pl（非交互、有明确成功回显）。

七、常见问题（FAQ）

Q1：执行 webmin man list-config 报 Error: Command 'man' doesn't exist？ 语法写错了：man 不是子命令，查看手册必须用选项形态 webmin --man <子命令>（两个连字符）。实测对比：

/usr/share/webmin/bin/webmin --man list-config | head -4

Name:
    list-config

Description:
    List one or all configuration directives for "miniserv.conf" or a module
    "config" file.

/usr/share/webmin/bin/webmin man list-config

Error: Command `man` doesn't exist

全部 10 个子命令均支持 --man 查看手册；个别子命令用 <子命令> --help 亦可获得同等帮助。

Q2：脚本里怎么判断 Webmin 服务是否正常？ 用退出码判断：webmin server status >/dev/null 2>&1 && echo webmin_ok || echo webmin_down（4.2 节实测输出 webmin_ok）；更严格的探测可叠加端口检查 ss -ltn | grep :10000。

Q3：改完配置想立即生效但不想重启整个服务？ miniserv.conf 的核心键必须重启生效（set-config 已自动重启，无需额外操作）；模块配置多数即时生效。无「免重启热加载」通道。

Q4：批量改多个键的最佳实践？ 方案一：逐条 set-config（每条自动重启，注意连续重启的 start-limit 风险）；方案二：一次编辑 /etc/webmin/miniserv.conf 后 systemctl restart webmin（只重启一次）。两者写同一文件，取其一。

八、参考链接

  1. Webmin 官方文档站：https://doxfer.webmin.com/Webmin/Main_Page
  2. 官方 GitHub 仓库（CLI 源码 bin/ 目录）：https://github.com/webmin/webmin
  3. 官方下载页：https://www.webmin.com/download.html
  4. 安装流程实测见本专栏《Ubuntu 22.04 安装 Webmin 2.670 指南》篇；本文涉及的配置键含义逐项说明见《Webmin 2.670 配置参数详解》篇。