LibreNMS 26.10.0 常用 CLI 命令与工具详解

目标：系统整理 LibreNMS 26.10.0 的命令行工具箱——lnms 主命令、Laravel artisan、健康检查 validate.php、日常维护 daily.sh、轮询脚本族（poller.php/poller-wrapper.py）——全部子命令与参数均附真实执行回显，本机自监控（snmpd + localhost 设备）即可复现。安装环境搭建见《Ubuntu 22.04 安装 LibreNMS 26.10.0 指南》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），主机名 librenms-server
LibreNMS 26.10.0（2026-10-19，标准路径 /opt/librenms，lnms 已软链 /usr/bin/lnms）
组件版本（validate.php 实测）：PHP 8.5.11 / MariaDB 10.6.23 / RRDTool 1.7.2 / SNMP 5.9.1 / Python 3.10.12 / DB Schema 408
监控对象：本机 localhost（snmpd 自监控，SNMP v2c community librenms-community），已出流量/传感器数据
命令执行身份：除特别注明外，均以 su - librenms 切换到 librenms 用户在 /opt/librenms 内执行（原因见"注意事项"）

二、工具概览

LibreNMS 的 CLI 工具箱分四类，全部位于 /opt/librenms：

类别	工具	说明
主命令	`lnms`	自定义 Laravel 控制台入口，日常运维首选（设备/配置/用户/API/维护全覆盖）
底层框架	`php artisan`	Laravel 原生命令（schedule/migrate/tinker 等），lnms 的底层
健康检查	`php validate.php`	安装/排障第一步，输出组件版本与逐项检查结果
维护脚本	`daily.sh`	每日维护总入口（更新代码/依赖/Schema/清理），cron 自动执行
轮询脚本族	`poller.php`、`discovery.php`、`poller-wrapper.py`、`discovery-wrapper.py`、`alerts.php`、`cronic`	单设备调试与批量轮询；前两者已标记废弃，等价命令转为 lnms 子命令

lnms 在 26.10.0 中共 59 个子命令（lnms list 统计），按前缀分组如下（实测节选）：

  api:token-create / api:token-list / api:token-revoke
  config:clear / config:get / config:list / config:set
  device:add / device:discover / device:ping / device:poll / device:remove / device:rename
  maintenance:cleanup-database / cleanup-networks / cleanup-syslog /
    discover-ssl-certificates / fetch-ouis / fetch-rss /
    refresh-ssl-certificates / rrd-step
  plugin:add / plugin:disable / plugin:enable / plugin:remove
  port:tune
  report:devices
  user:add
  about / reload / scan / update
  health:check

三、前置条件

已按安装指南完成部署且 php validate.php 全部 OK（至少 Database Connected + Active pollers found）。
有至少一台已纳管设备（本机自监控即可：lnms device:add localhost -2 -c librenms-community）。
以 librenms 用户执行：su - librenms（带连字符，自动落到 /opt/librenms）。

四、lnms 主命令详解

4.1 about：查看运行时信息

$ lnms about --no-ansi

  Environment ................................................................
  Application Name .................................................. LibreNMS
  Laravel Version .................................................... 12.69.3
  PHP Version ......................................................... 8.5.11
  Composer Version .................................................... 2.10.3
  Environment ..................................................... production
  Debug Mode ............................................................. OFF
  URL .............................................................. localhost
  Maintenance Mode ....................................................... OFF
  Timezone ..................................................... Asia/Shanghai
  Locale .................................................................. en
  OS ............................................................ Ubuntu 22.04

用途：快速核对版本栈（升级后第一时间跑一次）。

4.2 device:add：添加监控设备

$ lnms device:add --help
Description:
  Add a new device

Usage:
  device:add [options] [--] <device spec>

Arguments:
  device spec                                        Hostname or IP to add

Options:
  -1, --v1                                           Use SNMP v1
  -2, --v2c                                          Use SNMP v2c
  -3, --v3                                           Use SNMP v3
  -c, --community=COMMUNITY                          SNMP v1 or v2 community

实测添加本机（SNMP v2c）：

$ lnms device:add localhost -2 -c librenms-community
Added device localhost (1)

无 SNMP 的哑设备用 --ping-fallback（ICMP 监控兜底），实测：

$ lnms device:add localhost --ping-fallback
Added device localhost (1)

4.3 device:poll / device:discover / device:ping：轮询与发现三件套

单设备立即轮询（等价于旧 poller.php -h <设备>，输出末尾为各子系统耗时统计）：

$ lnms device:poll localhost
...（中略模块输出）...
### Start Device Groups ###
### End Device Groups (0.001s) ###

FPING [1/1.00s]: Ping[1/1.00s]
SNMP [37/0.38s]: Snmpget[20/0.21s] Snmpwalk[17/0.17s]
SQL [61/0.02s]: Select[29/0.02s] Update[31/0.01s] Delete[1/0.00s]
RRD [96/0.02s]: Update[96/0.02s]

单设备发现（探测 OS/端口/传感器，决定后续轮询内容）：

$ lnms device:discover localhost
FPING [1/1.00s]: Ping[1/1.00s]
SNMP [108/1.28s]: Snmpget[62/0.76s] Snmpwalk[46/0.52s]
SQL [116/0.04s]: Select[50/0.04s] Insert[63/0.02s] Update[2/0.00s] Delete[1/0.00s]
RRD [0/0.00s]:

连通性测试（ICMP，写回响应时间数据）：

$ lnms device:ping localhost
localhost : localhost : xmt/rcv/%loss = 3/3/0%, min/avg/max = 0.019/0.023/0.027

4.4 report:devices：设备清单报表

$ lnms report:devices
+-----------+-----+
| hostname  | ip  |
+-----------+-----+
| localhost | ::1 |
+-----------+-----+

⚠️ 注意：旧版常见的 lnms device:list 在 26.x 已不存在（实测报 Command "device:list" is not defined），设备清单用 report:devices。

4.5 device:remove / device:rename：移除与改名

$ lnms device:remove --help
Description:
  Remove a device

Usage:
  device:remove <device spec>

Arguments:
  device spec           Hostname, IP, or device id to remove

device:rename <旧名> <新名> 用于改主机名/IP 后同步平台记录（RDN 迁移场景），执行前建议先跑一次 device:poll 确认目标可达。

4.6 config:get / config:set / config:list：配置读写

读取默认探测 community（数组型返回 JSON）：

$ lnms config:get snmp.community
[
    "public"
]

写入标量配置（实测）：

$ lnms config:set default_port_association_mode ifIndex
$ lnms config:get default_port_association_mode
ifIndex

⚠️ 注意：config:set 会校验键名是否在官方配置定义内，乱传会实测报错：
$ lnms config:set disks.free 5
This is not a valid setting. Check your input.
可用键名先用 lnms config:list <关键词> 搜索，或查源码 resources/definitions/config_definitions.json。

4.7 user:add：创建本地用户

$ lnms user:add --help
Description:
  Add a local user. You can log in with this user only if auth is set to mysql.

Usage:
  user:add [options] [--] [<username>]

Arguments:
  username                   The username the user will log in with

Options:
  -p, --password=PASSWORD    Password for the user. If you do not give it, the command prompts you.
  -r, --role=ROLE            Set the user to the desired role [user, global-read, admin] [default: ["user"]] (multiple values allowed)
  -e, --email=EMAIL          Email to use for the user
  -l, --full-name=FULL-NAME  Full name for the user
  -s, --descr=DESCR          User description

实测创建管理员：

$ lnms user:add admin --password='Adm1n@LibreNMS26' --role=admin --email=admin@example.com --full-name="LibreNMS Admin"
Marked all notifications as read for user admin
Successfully added user: admin

弱口令实测被拒（内置泄露库校验）：

$ lnms user:add admin --password=q1w2e3r4 --role=admin
The given password has appeared in a data leak. Please choose a different password.

4.8 api:token-create / token-list / token-revoke：API 令牌管理

$ lnms api:token-create --help
Description:
  Create a new API token for a user

Usage:
  api:token-create [options] [--] <username>

Arguments:
  username              User to create the token for

Options:
      --name=NAME       Name for the token [default: "api-token"]

实测创建与列出（token 仅回显一次，注意保存）：

$ lnms api:token-create admin
Token created successfully.

1|LoJcjPNi7uitzYtsMrfg33A1XgStlpRRB0ZQYC6Gdd9880df

Save this token. It is not shown again.

$ lnms api:token-list admin
+----+-----------+-----------+---------------+
| ID | Name      | Last Used | Created       |
+----+-----------+-----------+---------------+
| 1  | api-token | Never     | 9 minutes ago |
+----+-----------+-----------+---------------+

令牌用于 REST API 认证（请求头 X-Auth-Token），吊销：lnms api:token-revoke admin 1。

4.9 scan：网段扫描发现

$ lnms scan --help
Description:
  Scan the network for hosts and try to add them to LibreNMS

Usage:
  scan [options] [--] [<network>...]

Arguments:
  network                  CIDR notation network(s) to scan, can be ommited if 'nets' config is set

用法：lnms scan 192.168.1.0/24（扫到可 SNMP 通的主机会尝试自动纳管）。

4.10 update / reload / maintenance:*：维护族

lnms update：拉取新代码并执行更新流程（等效 daily.sh 的更新部分，交互确认）。
lnms reload：通知运行中的 Dispatcher 服务重载配置（单机 cron 模式无 Dispatcher 时无操作对象）。
maintenance:*：数据库清理、过期 syslog 清理、SSL 证书发现/刷新、OUI 库更新等，均被每日任务自动调用，也可手工触发。

五、artisan 常用子命令

php artisan 是 Laravel 原生入口，lnms 的功能之外，排障时常看计划任务与迁移状态：

5.1 schedule:list：查看计划任务

$ php artisan schedule:list --no-ansi

  */5 * * * *      schedule operational check .... Next Due: 1 minute from now
  *   * * * * 10s  App\Jobs\DispatchPollingWork . Next Due: 7 seconds from now
  34  1 * * 0      php artisan maintenance:fetch-ouis  Next Due: 4 days from now
  2   2 * * 0      php artisan maintenance:cleanup-networks  Next Due: 4 days from now
  6   3 * * *      php artisan maintenance:fetch-rss  Next Due: 21 hours from now
  17  * * * *      php artisan maintenance:cleanup-syslog  Next Due: 48 minutes from now
  23  4 * * *      php artisan maintenance:discover-ssl-certificates  Next Due: 22 hours from now

5.2 migrate:status：迁移状态核对

$ php artisan migrate:status --no-ansi

  Migration name .............................................. Batch / Status
  2018_07_03_091314_create_access_points_table ....................... [1] Ran
  2018_07_03_091314_create_alert_device_map_table .................... [1] Ran
  2018_07_03_091314_create_alert_group_map_table .................... [1] Ran
  2018_07_03_091314_create_alert_log_table ........................... [1] Ran

升级后若怀疑 Schema 未跟上，用它确认最后一个迁移是否 Ran。

六、validate.php：健康检查详解

安装排障第一步，输出组件版本表 + 逐项检查：

$ php validate.php
===========================================
Component | Version
--------- | -------
LibreNMS  | 26.10.0 (2026-10-19T20:41:01+08:00)
DB Schema | 2026_10_09_000000_reset_invalid_alert_schedule_behavior (408)
PHP       | 8.5.11
Python    | 3.10.12
Database  | MariaDB 10.6.23-MariaDB-0ubuntu0.22.04.1
RRDTool   | 1.7.2
SNMP      | 5.9.1
===========================================

[OK]    Composer Version: 2.10.3
[OK]    Dependencies up-to-date.
[OK]    Database Connected
[OK]    Database Schema is current
[OK]    SQL Server meets minimum requirements
[OK]    lower_case_table_names is enabled
[OK]    MySQL engine is optimal
[OK]    Database and column collations are correct
[OK]    Database schema correct
[OK]    MySQL and PHP time match
[OK]    Active pollers found
[OK]    Dispatcher Service not detected
[OK]    Locks are functional
[OK]    Python poller wrapper is polling
[OK]    Redis is unavailable
[OK]    No errors found with polling frequencies.
[OK]    rrd_dir is writable
[OK]    rrdtool version ok

判读要点：

「Dispatcher Service not detected」「Redis is unavailable」是 OK 态提示：单机 cron 模式下这两项本就不需要。
「Active pollers found」「Python poller wrapper is polling」要求最近 300 秒内有过轮询——刚装完没跑过 cron 时这两项是 FAIL，手动触发一次 python3 poller-wrapper.py 16 或等 5 分钟 cron 周期即可转 OK。
常见 FAIL 项与修复实录（PHP 版本线、Python 依赖缺失、Scheduler 未启用、git 分支警告）见安装指南第八章 FAQ。

七、daily.sh：每日维护脚本

cron 每天自动执行的维护总入口，手工执行一次的实测回显：

$ bash daily.sh
Clearing caches                                    OK
Updating to latest codebase                        OK
Updating Composer packages                         OK
Updating SQL-Schema                                OK
Cleaning up DB                                     OK

五步分别完成：配置缓存清理 → git 拉取最新代码 → composer 依赖同步 → 数据库 Schema 升级 → 数据清理。任何一步 FAIL 都会中止后续步骤，排障从该步日志入手（/opt/librenms/logs/daily.log）。锁版本环境在 /opt/librenms/config.php 加 $config['update'] = 0; 关闭代码更新步。

八、poller.php 与轮询脚本族

8.1 poller.php：单设备轮询（已标记废弃）

$ php poller.php -h
Warning: poller.php is deprecated! Use lnms device:poll instead.

-h <device id> | <device hostname wildcard>  Poll single device
-h odd             Poll odd numbered devices
-h even            Poll even numbered devices
-h all             Poll all devices

Debugging and testing options:
-r                 Do not create or update RRDs
-f                 Do not insert data into InfluxDB
-p                 Do not insert data into Prometheus
-d                 Enable debugging output
-v                 Enable verbose debugging output
-m                 Specify module(s) to be run. Comma separate modules, submodules may be added with /
-q                 Quiet, minimal output /

实测单设备快速轮询（-r -f 跳过 RRD 与外部输出写入，纯调试）：

$ php poller.php -h localhost -r -f
>>> Polled localhost (1) in 1.332 seconds <<<
INFO: device:poll localhost (1) polled in 1.332s
#### Start Alerts ####
#### End Alerts (0.0049s) ####

FPING [1/1.00s]: Ping[1/1.00s]
SNMP [19/0.20s]: Snmpget[16/0.17s] Snmpwalk[3/0.03s]
SQL [135/0.04s]: Select[51/0.02s] Insert[62/0.02s] Delete[16/0.00s] Update[6/0.00s]
RRD [144/0.05s]: Create[72/0.04s] Update[72/0.01s]

⚠️ 注意：poller.php/discovery.php 在 26.x 运行即打印废弃警告（Warning: poller.php is deprecated! Use lnms device:poll instead.），新脚本统一用 lnms device:poll / lnms device:discover；旧脚本仅在老文档/老习惯场景保留兼容。

8.2 discovery.php：单设备发现（已标记废弃）

$ php discovery.php -h
Warning: discovery.php is deprecated! Use lnms device:discover instead.

-h <device id> | <device hostname wildcard>  Discover single device
-h odd             Discover odd numbered devices
-h even            Discover even numbered devices
-h all             Discover all devices
-h new             Discover all devices that have not had a discovery run before
--os <os_name>     Discover devices only with specified operating system

8.3 poller-wrapper.py：批量轮询器（生产主力）

cron 每 5 分钟调用的多线程轮询入口（poller-wrapper.py 16 = 16 线程）。手动执行一次的实测回显：

$ python3 poller-wrapper.py 16
2026-10-20 05:21:25,062 :: INFO :: starting the poller check at 2026-10-20 05:21:25 with 1 threads for 1 devices
2026-10-20 05:21:26,554 :: INFO :: worker Thread-2 (poll_worker) finished device 1 in 1 seconds
2026-10-20 05:21:26,554 :: INFO :: poller-wrapper checked 1 devices in 1 seconds with 1 workers with 0 errors

线程数按设备量与 CPU 核数调整（数百设备 16 线程是常见起点）。discovery-wrapper.py 同理负责批量发现（cron 每 6 小时一轮）。

8.4 cronic 与 alerts.php

cronic：cron 输出压缩器——命令成功时吞掉输出，失败时才把完整输出发给邮件，避免告警脚本刷屏（cron 文件中包裹 discovery-wrapper/poller-wrapper 使用）。
alerts.php：每分钟触发一次的告警判定脚本（cron 文件中 * * * * * librenms /opt/librenms/alerts.php），手工执行可立即强制一轮告警评估。

九、注意事项

身份：所有 /opt/librenms 内命令必须以 librenms 用户执行，root 直接执行会产生 root 属主文件导致后续轮询写失败。规范姿势：su - librenms（带连字符）。
工作目录：不带连字符的 su librenms -c "php validate.php" 会因工作目录不对报 Could not open input file，务必带连字符或先 cd /opt/librenms。
废弃命令：poller.php/discovery.php 已废弃但可用，新运维脚本统一用 lnms device:poll/device:discover。
config:set 白名单：键名必须在官方配置定义内（lnms config:list 检索），否则报 This is not a valid setting.。
令牌安全：api:token-create 的 token 仅显示一次；泄露后立即 api:token-revoke。生产环境示例口令务必更换，本文 Adm1n@LibreNMS26 仅为演示（弱口令会被内置校验直接拒绝）。

十、常见问题（FAQ）

Q1：Command "device:list" is not defined

26.x 移除了 device:list（实测提示 Did you mean one of these? ... device:add ...），设备清单用 lnms report:devices，单设备操作用 device:add/poll/remove/rename。

Q2：config:set 报 "This is not a valid setting. Check your input."

键名不在配置定义白名单（实测 disks.free 被拒）。先 lnms config:list <关键词> 找到官方键名再设置。

Q3：validate.php 报 "The poller is not running"

最近 300 秒无轮询记录（实测首次安装未跑 cron 时必现）。手动 python3 poller-wrapper.py 16 一轮或等 cron 周期，转 [OK] Active pollers found。

Q4：validate.php 报 "Could not open input file: validate.php"

执行身份/目录不对（root 或错误目录）。改用 su - librenms 后重试。

Q5：lnms 命令 Tab 补全失效

确认两步已做（安装指南 4.13）：ln -s /opt/librenms/lnms /usr/bin/lnms 与 cp /opt/librenms/misc/lnms-completion.bash /etc/bash_completion.d/，重开 shell 生效。

十一、参考链接

官方配置文档（lnms config 说明）：https://docs.librenms.org/Support/Configuration/
官方 Validator 文档：https://docs.librenms.org/Support/Validation/
官方 Dispatcher 服务文档：https://docs.librenms.org/Advanced/Dispatcher-Service/
GitHub 仓库：https://github.com/librenms/librenms
本站安装实战：《Ubuntu 22.04 安装 LibreNMS 26.10.0 指南》
本站部署实战：《LibreNMS 26.10.0 部署指南》
本站选型认知：《LibreNMS 26.10.0 介绍与选型指南》