Munin 2.0.57 常用 CLI 命令与工具详解

目标：系统梳理 Munin 日常运维的核心命令行工具——munin-cron（采集总编排）、munin-node-configure（插件探测与启用）、munin-run（单插件手动执行）、munin-update / munin-limits / munin-graph / munin-html（四大子任务）、telnet 4949 节点协议（远程排障），逐一给出参数说明与真实回显。全文命令与输出均在 Ubuntu 22.04 + Munin 2.0.57-1ubuntu2 环境逐条实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Munin 版本：2.0.57-1ubuntu2（munin-cron --version 实测输出 munin version 2.0.57）
实测拓扑：master 主机 munin-master1（10.89.61.2，master/node 同机自监控）+ 远程节点 node2（10.89.61.3，已纳管）
组件路径：master 工具在 /usr/share/munin/ 与 /usr/bin/（由 munin-cron 调度），node 工具在 /usr/sbin/（munin-node/munin-run/munin-node-configure）
关键目录：数据 /var/lib/munin、输出 /var/cache/munin/www、日志 /var/log/munin、运行时 /var/run/munin

二、工具概览

工具	所在角色	端	核心用途	由谁调度
munin-cron	master	/usr/bin	采集总编排入口，按序执行四大子任务	/etc/cron.d/munin（每 5 分钟）
munin-update	master	/usr/share/munin	轮询各 node 拉取指标写入 RRD	munin-cron
munin-limits	master	/usr/share/munin	阈值检查与告警联络外发	munin-cron
munin-graph	master	/usr/share/munin	调 RRDtool 渲染趋势图	munin-cron
munin-html	master	/usr/share/munin	生成 HTML 页面导航	munin-cron
munin-node	node	/usr/sbin	4949 守护进程，响应协议请求	systemd
munin-run	node	/usr/sbin	以 node 环境手动执行单个插件（排障）	手动
munin-node-configure	node	/usr/sbin	插件探测/建议/批量启用（含 SNMP）	手动
telnet 4949	任意	—	节点协议交互（version/list/nodes/config/fetch）	手动

分工逻辑：master 侧四个子任务平时不单独跑，统一由 munin-cron 编排；单独执行主要用于「改配置后立即生效」「只重画图」「只发告警」等运维场景。node 侧三个工具是被监控机上的日常排障主力。

三、前置条件

master 与 node 已安装并运行（安装步骤见《Ubuntu 22.04 安装 Munin 2.0.57 指南》）：

systemctl is-active munin-node

实测回显：

active

master 侧命令以 munin 用户执行（root 直接跑会被拒绝）：

su - munin --shell /bin/bash -c "/usr/bin/munin-cron --version"

实测回显：

munin version 2.0.57.

node 侧命令（munin-run/munin-node-configure）以 root 执行，munin-run 内部会自行降权到插件所需的运行身份。

四、munin-cron：采集总编排

4.1 作用与默认调度

munin-cron 是 master 侧一切采集动作的入口，内部按序调用 munin-update → munin-limits → munin-graph → munin-html。默认由 /etc/cron.d/munin 每 5 分钟调度（实测文件节选）：

*/5 * * * *     munin if [ -x /usr/bin/munin-cron ]; then /usr/bin/munin-cron; fi

4.2 版本确认

munin-cron --version

实测回显（root 下执行会先给出拒绝提示，以 munin 用户执行输出如下）：

munin version 2.0.57.

4.3 手动触发一轮完整采集

su - munin --shell /bin/bash -c "/usr/bin/munin-cron"

实测回显：静默完成（成功时无 stdout 输出）。成败判据看日志与产物：

tail -2 /var/log/munin/munin-update.log

实测回显：

2026/10/19 22:42:21 [INFO] Reaping Munin::Master::UpdateWorker<node2;node2>.  Exit value/signal: 0/0
2026/10/19 22:42:21 [INFO]: Munin-update finished (3.94 sec)

ls /var/cache/munin/www/ | head -4

实测回显：

apache-day.html
apache-month.html
apache-week.html
apache-year.html

💡 说明：Exit value/signal: 0/0 表示该节点的 update worker 正常退出；Munin-update finished (3.94 sec) 是整轮 update 耗时。改完 munin.conf 后想立即生效，跑一次 munin-cron 即可，无需等服务。

4.4 常见执行约束（排障）

以 root 直接运行 munin-cron 会被明确拒绝（实测回显）：

This program will easily break if you run it as root as you are
trying now.  Please run it as user 'munin'.  The correct 'su' command

解决：统一用 su - munin --shell /bin/bash -c "/usr/bin/munin-cron" 或 sudo -u munin munin-cron。

五、munin-node-configure：插件探测与批量启用

5.1 查看当前插件清单（默认形态）

munin-node-configure 2>&1 | head -8

实测回显：

Plugin                     | Used | Extra information
------                     | ---- | -----------------
acpi                       | no   |
amavis                     | no   |
apache_accesses            | no   |
apache_processes           | no   |
apache_volume              | no   |
apc_envunit_               | no   |
apc_nis                    | no   |

💡 说明：逐行列出插件库（/usr/share/munin/plugins）中的每个插件，Used 列 yes/no 表示是否已在 /etc/munin/plugins 下挂链生效；带尾部下划线的名字（如 apc_envunit_）是通配插件，启用时需附加实例名（apc_envunit_单元号）。

5.2 --suggest：环境探测与启用建议

munin-node-configure --suggest 2>&1 | head -8

实测回显：

Plugin                     | Used | Suggestions
------                     | ---- | -----------
acpi                       | no   | no [failed to find thermal zones below /sys/class/thermal/thermal_zone*]
amavis                     | no   | no [command logtail or file /var/log/mail.info not found]
apache_accesses            | no   | no [LWP::UserAgent not found]
apache_processes           | no   | no [LWP::UserAgent not found]
apache_volume              | no   | no [LWP::UserAgent not found]
apc_envunit_               | no   | no [no units to monitor]
bonding_err_               | no   | no [No /proc/net/bonding]

💡 说明：Suggestions 列给出每个插件的判定结论与原因——no [原因] 指出缺什么（缺 Perl 库、缺配置文件、无对应硬件），yes 表示环境满足可启用。上例中 apache_* 三件套因缺 LWP::UserAgent（Perl HTTP 库）被判定不可用。

补齐依赖后重新探测（实测全流程）：

apt install -y libwww-perl libcache-cache-perl
munin-node-configure --suggest 2>&1 | grep apache

实测回显：

apache_accesses            | no   | yes
apache_processes           | no   | yes
apache_volume              | no   | yes

5.3 --shell：输出批量启用命令并执行

munin-node-configure --shell 2>/dev/null | grep "ln -s"

实测回显：

ln -s '/usr/share/munin/plugins/apache_accesses' '/etc/munin/plugins/apache_accesses'
ln -s '/usr/share/munin/plugins/apache_processes' '/etc/munin/plugins/apache_processes'
ln -s '/usr/share/munin/plugins/apache_volume' '/etc/munin/plugins/apache_volume'

输出的即「可执行启用命令」；经管道交给 bash 执行后重启 node 生效（单行单单元）：

munin-node-configure --shell 2>/dev/null | grep "ln -s" | bash
systemctl restart munin-node

验证插件已生效并采到数据（telnet list 出现 apache_*，munin-run 出数）：

munin-run apache_accesses

实测回显：

accesses80.value 21

💡 说明：accesses80.value 21 表示 80 端口虚拟主机本周期访问计数 21；启用插件的落地形态就是在 /etc/munin/plugins 建符号链接，--shell 只是把「探测→计算链接名→输出命令」自动化，规避手写链接的笔误。

5.4 --snmp：SNMP 设备批量探测（用法说明）

munin-node-configure --snmp <目标网段> --snmpcommunity public --shell

该形态用于扫描交换机/路由器/UPS 等 SNMP 设备并输出对应的 snmp__if_ 等插件启用命令；无 SNMP 设备环境时执行会报 no SNMP information 类错误，本文不做展开。被探测目标需开放 UDP 161 且 community 正确。

六、munin-run：单插件手动执行（node 排障主力）

6.1 语法与取值

munin-run <插件名>              # 取当前值
munin-run <插件名> config       # 取 config 声明段

实测取值：

munin-run load

实测回显：

load.value 1.50

实测 config 段：

munin-run cpu config | head -8

实测回显：

graph_title CPU usage
graph_order system user nice idle iowait irq softirq
graph_args --base 1000 -r --lower-limit 0 --upper-limit 1200
graph_vlabel %
graph_scale no
graph_info This graph shows how CPU time is spent.
graph_category system
graph_period second

💡 说明：<字段>.value <数值> 是插件取值的标准输出形态；config 段的 graph_title/graph_args/graph_vlabel/graph_category 分别控制图题、绘图参数（上限/基线）、纵轴单位与分组页归属——出图异常时先比对这两段输出即可定位是「取值坏」还是「声明坏」。

6.2 典型排障用法

插件在 Web 上缺图/断线时，按「munin-run 取值 → telnet fetch 对比 → 查 node 日志」三步定位。例如 Apache 插件启而不采：

munin-run apache_accesses

实测回显（正常出数）：

accesses80.value 21

若该命令报错（如 LWP::UserAgent not found 或 mod_status 未开 ExtendedStatus），则插件在真实轮询中同样失败——先修环境再谈图形。

七、munin-update：轮询拉取与 RRD 写入

7.1 参数总览

su - munin --shell /bin/bash -c "/usr/share/munin/munin-update --help"

实测回显（全量）：

Usage:
    munin-update [options]

     Options:
         --config_file=<file>    Use <file> as configuration file.
         --[no]debug             Enable [or disable] debug messages. [--nodebug]
         --[no]fork              Query hosts in parallel (--fork), or
                                 sequentially (--nofork). [--fork]
         --host <host>           Limit graphed hosts to <host>. Multiple --host
                                 options may be supplied.
         --service <service>     Limit graphed services to <service>. Multiple --service
                                 options may be supplied.
         --timeout=<seconds>     TCP timeout when talking to clients. [$timeout]
         --help                  View this message.
         --version               View version information.

常用参数说明：--fork（默认）并行轮询全部节点，--nofork 串行逐个查询（排障时输出干净）；--host/--service 把本轮动作限定到指定节点/插件（如只重拉 node2 的 cpu）。

7.2 单独执行一轮拉取（实测）

su - munin --shell /bin/bash -c "/usr/share/munin/munin-update --nofork"

实测回显（stdout 静默），以日志判定：

tail -2 /var/log/munin/munin-update.log

实测回显：

2026/10/19 22:40:27 [INFO]: Munin-update finished for node localdomain;localhost.localdomain (3.89 sec)
2026/10/19 22:40:27 [INFO]: Munin-update finished (3.92 sec)

7.3 日志判读要点

Munin-update finished for node <域>;<节点名> (<耗时>)：单节点完成，缺了哪台就是哪台不通；
No old data available for failed worker node2;node2. This node will disappear from the html web page hierarchy：节点拉取失败（多因 node 端 ACL 拒绝，见第十一章 FAQ 1）；
creating rrd-file for <插件>-><字段>: '<路径>'：首次纳管新节点/新插件时的建库记录，如 '/var/lib/munin/node2/node2-vmstat-wait-g.rrd'。

八、munin-limits / munin-graph / munin-html

8.1 munin-limits：阈值检查与告警外发

参数总览（实测 --help 节选）：

Options:
    --help              View this message.
    --debug             View debug messages.
    --stdout            Log to stdout as well as the log file.
    --always-send <severity list>
                        Send messages to contacts even if state has
                        not changed since the last run. The list is a
                        space or comma separated list of severities.
                        Choose from one or more of "critical",
                        "warning", "unknown" and "ok".
    --force             Alias for "--always-send ok,warning,critical,unknown".
    --service <service> Limit notified services to <service>.
    --host <host>       Limit notified hosts to <host>.

实测执行：

su - munin --shell /bin/bash -c "/usr/share/munin/munin-limits --stdout"

实测回显：无越限事件时 stdout 静默；日志记录轮次：

tail -2 /var/log/munin/munin-limits.log

实测回显：

2026/10/19 22:40:27 [INFO] Starting munin-limits, getting lock /var/run/munin/munin-limits.lock
2026/10/19 22:40:27 [INFO] munin-limits finished (0.01 sec)

💡 说明：告警来源是插件 config 段中声明的 warning/critical 阈值（可被 munin.conf 中 host 段的 <插件>.warning 覆盖）；外发通道在 munin.conf 的 contact 配置里定义（实测发行版默认 cron 里带了 --contact nagios --contact old-nagios 的日更任务）。--force 忽略状态缓存强制重发全部级别。

8.2 munin-graph：静态趋势图渲染

su - munin --shell /bin/bash -c "/usr/share/munin/munin-graph --cron"

实测回显：静默完成。验证产物时间戳刷新：

ls -l /var/cache/munin/www/localdomain/localhost.localdomain/cpu-day.png

实测回显：

-rw-r--r-- 1 munin munin 16578 Oct 19 22:42 /var/cache/munin/www/localdomain/localhost.localdomain/cpu-day.png

8.3 munin-html：页面导航生成

su - munin --shell /bin/bash -c "/usr/share/munin/munin-html"

实测回显（stdout 静默），日志确认：

tail -2 /var/log/munin/munin-html.log

实测回显：

2026/10/19 23:00:15 [INFO] Releasing lock file /var/run/munin/munin-html.lock
2026/10/19 23:00:15 [INFO] munin-html finished (0.24 sec)

💡 说明：graph 与 html 的单独执行用于「改了模板/只想重画图」场景；四个子任务有固定先后（update 先产数据，limits 判阈值，graph 画图，html 编导航），手动单独跑时注意顺序，否则页面与数据可能短暂不一致。

九、telnet 4949：节点协议交互（远程排障利器）

9.1 建立连接

telnet 127.0.0.1 4949

实测回显：

Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
# munin node at munin-master1

9.2 协议命令逐个实测

以下命令均在连接后逐条输入、每条独立展示（结果行后单独的 . 是协议结束符）：

version——确认 node 版本：

version
munins node on munin-master1 version: 2.0.57

list——列出全部已启用插件：

list
cpu df df_inode entropy forks fw_packets if_err_eth0 if_eth0 interrupts irqstats load memory munin_stats open_files open_inodes proc_pri processes swap threads uptime users vmstat

nodes——列出本 node 上报的主机名（master 验证纳管名一致性的依据）：

nodes
munin-master1
.

cap——节点能力声明（multigraph 支持多图插件、dirtyconfig 支持同轮取值）：

cap
cap multigraph dirtyconfig

config——拉取某插件的声明段（与 munin-run <插件> config 同构）：

config load
graph_title Load average
graph_args --base 1000 -l 0
graph_vlabel load
graph_scale no
graph_category system
load.label load
.

fetch——拉取某插件当前值（与 munin-run <插件> 同构）：

fetch load
load.value 1.66
.

quit——结束会话（回显 Connection closed by foreign host.）。

9.3 协议命令速查

命令	语法	作用	排障用途
version	`version`	node 版本号	确认双端版本一致
list	`list`	已启用插件清单	插件启用失败第一现场
nodes	`nodes`	上报主机名	与 munin.conf host 段名比对
cap	`cap`	能力声明	判断 multigraph/dirtyconfig 支持
config	`config <插件>`	插件声明段	图形属性异常定位
fetch	`fetch <插件>`	当前取值	数据缺失定位
quit	`quit`	断开	—

⚠️ 注意：telnet 无法连上或连上即断，是 node 端 ACL（allow/cidr_allow）拒绝的表现，node 日志会出现 Denying connection from: <来源IP>；跨机采集必须在被监控端放行 master 网段。

十、注意事项

执行身份严格区分：master 工具（munin-cron/update/limits/graph/html）必须以 munin 用户跑；node 工具（munin-run/munin-node-configure）以 root 跑（内部自行降权）。身份错位是 Munin 运维最常见的第一类错误。
锁文件与并发：四个子任务各持独立锁（/var/run/munin/*.lock），手动执行与 cron 周期撞车时会等待或失败；手动跑完建议 ls /var/run/munin/ 复核无残留锁，残留则 rm -f /var/run/munin/*.lock。
插件链路三段式：插件文件（/usr/share/munin/plugins）→ 启用链接（/etc/munin/plugins）→ 生效（重启 munin-node）。任何一段断了都表现为「插件不存在」，用 ls -l /etc/munin/plugins/<名字> 与 telnet list 两端比对。
通配插件命名：带尾部下划线的插件（df_inode 类推、snmp__ 系列同理）启用时实例名拼在链接名后，--shell 输出的命令已含完整实例名，优先用自动输出避免拼错。
RRD 只增改不清：删除插件后历史 RRD 文件仍留在 dbdir；恢复启用同名插件后历史曲线可续，无需清理。

十一、常见问题（FAQ）

Q1：munin-run 某插件报 Command 'xxx' failed 或超时？ 先用 munin-run <插件> config 区分声明段与取值段哪个失败；config 失败多为插件环境探测问题（缺依赖/缺配置），取值失败多为外部服务不可达（如 apache_ 插件连不上 mod_status）。修复后无需重启 node（munin-run 每次独立执行），但真实轮询依赖 node 进程环境，改完插件依赖建议 systemctl restart munin-node。

Q2：telnet 4949 输入命令无任何回显即断开？ ACL 拒绝。在被监控端 /var/log/munin/munin-node.log 找 Denying connection from 确认来源 IP，对应追加 allow ^<IP>$ 或 cidr_allow <网段>/24 后 systemctl restart munin-node。

Q3：手动跑 munin-update 报 Can't locate Munin/Common/Defaults.pm？ 组件不完整（常见于源码安装漏装 install-common-prime 目标），补齐对应模块组；发行版包不会出现该问题。

Q4：munin-limits 明明越限却没有告警？ 按序核查：插件 config 是否声明了 warning/critical → munin.conf 是否覆盖了阈值 → contact 通道配置是否存在 → 日志中是否有 state 变化记录（未变状态默认不重发，测试用 --force）。

Q5：cron 每 5 分钟在跑，但图形始终 5 分钟前一拍？ 确认 htmldir 与 Apache Alias 指向同一目录（默认 /var/cache/munin/www）；CGI 模式与静态模式并存时，页面链接优先走 munin-cgi-graph，其权限故障（FAQ 见部署与安装篇）会让人误判静态图未更新。

十二、参考链接

Munin 官方文档（2.0 命令参考）：https://guide.munin-monitoring.org/en/stable-2.0/reference/
munin-node 协议说明：https://guide.munin-monitoring.org/en/stable-2.0/reference/munin-node.html
插件开发指南（config/values 输出约定）：https://guide.munin-monitoring.org/en/stable-2.0/develop/plugins/
本专栏同族文档：《Ubuntu 22.04 安装 Munin 2.0.57 指南》（安装与多节点纳管）、《Munin 2.0.57 部署指南》（Compose 部署）、《Munin 2.0.78 介绍与选型指南》（架构与选型）