本文目錄
LibreNMS 更新之後,PVE 主機的虛擬機器清單怎麼不見了?
LibreNMS 過去監控 Proxmox VE 的 VM,要在 PVE 主機上放一支 proxmox 腳本,再開啟 enable_proxmox。從正式版 26.11.0 起,這套舊做法被移除了,改成內建的「Proxmox API」輪詢方式:LibreNMS 直接用 API Token 讀取 PVE,主機上不必再裝任何東西。升級時舊資料會被清掉,如果沒有另外設定新的方式,VM 清單就會是空的。
第一次想在 LibreNMS 看 PVE 上每台 VM 與容器的 CPU、記憶體、磁碟與流量的朋友,做法也完全相同。這篇整理我在自己的環境改用新做法的步驟,以及設定後會遇到的幾個現象。
升級後舊監控的變化
26.11.0 帶有一支資料庫遷移程式(2026_10_20_000000_remove_proxmox_table),升級時會執行下列動作:
- 刪除舊的
proxmox、proxmox_ports資料表 - 刪除各裝置的 Proxmox 應用程式資料
- 刪除
enable_proxmox設定 - 原本有資料的話,在 LibreNMS 跳一則「Proxmox application removed」通知
也就是說,一升級舊監控就停了,不會自動轉成新做法,管理員要自己替每台 PVE 主機加上 Proxmox API 輪詢方式。舊的流量圖表也不會接續過去;原本的 RRD 檔案留在 rrd/proxmox/,這次升級不會刪除,但網頁上已經沒有地方可以看這些舊圖。
新做法能取得的資料:
- VM 與 LXC 容器清單、電源狀態、記憶體與 vCPU 數
- CPU、記憶體、磁碟、磁碟 I/O、網路流量圖表
- VM 另有 Disk Ops(磁碟讀寫次數)
- VM 內有執行 QEMU Guest Agent 時,還有實際的作業系統版本與磁碟使用量
我的實作環境是 Proxmox VE 9.2,一組 5 節點叢集加 1 台單機。設定完成後,6 台節點共 161 個 VM 與容器都出現在清單裡。

步驟一:在 PVE 建立唯讀 API Token
在 PVE 主機上建立監控專用的使用者與 API Token,並給予 PVEAuditor 角色。叢集只要在任一節點做一次,使用者與 Token 是整個叢集共用的;不在叢集裡的單機要各自建立。
pveum user add librenms@pve
pveum aclmod / -user librenms@pve -role PVEAuditor
pveum user token add librenms@pve monitoring --privsep 0
執行後記下兩個值:
- Token ID
librenms@pve!monitoring - Secret
一串 UUID 格式的值,只會顯示這一次,畫面關掉就看不到了
PVEAuditor 是唯讀角色。要注意 --privsep 0 代表 Token 直接沿用帳號的權限,所以只有在這個帳號只被給予唯讀權限時,LibreNMS 才只能讀取、不能變更 PVE;日後若替帳號加了其他權限,Token 也會一併取得。請勿為了省事直接用 root@pam 或有管理權限的帳號給監控系統使用。
Guest Agent 權限與 PVE 版本
作業系統版本與 VM 內的磁碟使用量,是透過 QEMU Guest Agent 讀取的,需要對應的權限:
- PVE 9 以上
PVEAuditor已包含VM.GuestAgent.Audit,不必多做設定,Token 仍是唯讀 - PVE 8 以下
PVEAuditor不含 Guest Agent 權限,LibreNMS 讀不到作業系統,磁碟使用量改用 PVE 端的數值
PVE 8 若一定要這些資料,得另外給 VM.Monitor:
pveum role add LibreNMSGuestAgent --privs VM.Monitor
pveum aclmod /vms -user librenms@pve -role PVEAuditor,LibreNMSGuestAgent
第二行在 /vms 同時給 PVEAuditor 與新角色。PVE 的權限是較深層路徑的設定會取代從上層繼承的設定,只給新角色的話,這個帳號在 VM 上就只剩 VM.Monitor,反而讀不到 VM 清單需要的 VM.Audit。LibreNMS 官方文件的範例只寫了新角色,照抄要注意。
注意:VM.Monitor 也允許透過 Guest Agent 在 VM 內執行指令、寫入檔案、變更密碼,加上去之後這組 Token 就不再是唯讀。請評估風險後再決定,不需要作業系統資訊的話就不要加。
步驟二:在 LibreNMS 新增輪詢方式
每個 PVE 節點只回報自己身上執行的 VM,所以叢集裡的每一台節點都要加。沒加的節點,上面的 VM 就不會被監控。
- 進入該 PVE 主機的裝置頁,點選「編輯」→「Polling」分頁
- 新增「Proxmox API」方式
- 建立 Secret,填入 API Token ID 與 API Token Secret;同一個叢集的其他節點,直接選這個已建立的 Secret 即可
- 確認下方的設定值後儲存
| 設定 | 預設值 | 說明 |
|---|---|---|
| Hostname | 裝置的主機名稱 | 通常不用改 |
| Port | 8006 | PVE 網頁管理介面的連接埠 |
| Timeout | 10 秒 | 可設 1~300 秒 |
| Verify TLS Certificate | Yes | 見下方說明 |
Verify TLS Certificate 的預設值是 Yes。PVE 預設的節點憑證是由叢集自己的根憑證(自簽)簽發,LibreNMS 主機不信任它,連線測試就會失敗。要保留驗證有兩種做法:在 PVE 換上受信任的憑證,或把 PVE 的根憑證加進 LibreNMS 主機的信任清單,而且 Hostname 要和憑證上的名稱相符。選 No 會失去對伺服器身分的驗證,Token 有被攔截的風險,只建議在可信任的內網暫時使用。
儲存時 LibreNMS 會先用這組 Token 連一次 PVE API,讀取版本與叢集的根憑證(root CA),通過才會存檔。失敗時會出現「Could not connect to … using Proxmox API」,可以從錯誤細節判斷是連不上、憑證驗證失敗,還是 Token 不對。
加入這個方式後,裝置的 vminfo 模組會自動啟用。若在「編輯」→「模組」裡手動關過這個模組,以手動設定為準。
步驟三:驗證結果
VM 清單是在探索(discovery)時建立的,LibreNMS 預設每 6 小時探索一次。不想等排程的話,可以在 LibreNMS 主機上手動執行:
cd /opt/librenms
sudo -u librenms ./lnms device:discover <裝置 ID> -m vminfo
sudo -u librenms ./lnms device:poll <裝置 ID> -m vminfo
接著到裝置頁的「虛擬機器」分頁,就能看到這台節點上的 VM 與容器。上方可以切換 CPU、記憶體、磁碟、磁碟 I/O、Disk Ops、網路圖表;全部節點的 VM 則在頂端選單的虛擬機器清單裡。

圖表剛設定好時是空的,因為新的 RRD 從設定當下才開始寫入,等 15~30 分鐘、累積幾次輪詢就會出現曲線。
清單上的常見現象
關機的 VM 作業系統顯示 (Unknown)
作業系統資訊來自 VM 內的 Guest Agent,LibreNMS 只在探索時向執行中的 VM 讀取。所以 (Unknown) 代表設定之後,還沒在這台 VM 開機的狀態下讀到過;曾經讀到的 VM,關機後仍會顯示原本的作業系統。
開機中的 VM 若一直是 (Unknown),代表還沒成功取得作業系統資訊,可以依序檢查:
- VM 開機後是否已經跑過探索
- Token 是否有 Guest Agent 權限(PVE 8 以下的
PVEAuditor沒有) - VM 內是否已安裝並執行 Guest Agent:Linux 安裝
qemu-guest-agent套件,Windows 從 VirtIO 驅動程式 ISO 安裝 - PVE 該 VM 的「選項」是否開啟 QEMU Guest Agent;剛開啟時要讓 VM 完整關機再開機,重新開機不會生效
都確認後,在 PVE 的 VM 摘要頁看得到 IP 就表示 Agent 有回應,再手動跑一次探索即可。
LXC 容器只顯示 debian、ubuntu
LXC 容器沒有 Guest Agent,LibreNMS 只能取得 PVE 設定裡的系統類型(ostype),所以沒有版本號。這是資料來源的限制。
Windows 11 顯示成 Windows 10 Pro
Windows 11 登錄檔裡的 ProductName 仍寫著 Windows 10,Guest Agent 照實回報,PVE 自己的摘要頁也一樣。這不是 LibreNMS 的問題,要判斷實際版本,可以在 VM 內執行 winver:用戶端版本的 Build 22000 以上就是 Windows 11。伺服器版不適用這條規則,例如 Windows Server 2025 的組建編號是 26100。

磁碟使用量為 0
沒有 Guest Agent 的 VM,磁碟數值改用 PVE 端提供的資料:已用空間是 0,大小只算開機磁碟。要看到 VM 內各檔案系統的實際用量,一樣要裝 Guest Agent。
LXC 容器沒有 Disk Ops 圖表
PVE API 只對 VM 提供磁碟操作次數,容器沒有這項資料,屬於正常現象。
新建的 VM 沒有出現
輪詢只更新已知的 VM,新建的 VM 要等下一次探索才會加入清單,急著看可以手動跑一次探索。範本(template)不會列入清單。
VM 遷移到其他節點
VM 會顯示在它目前執行的節點底下。遷移之後,新節點在下一次輪詢時接手,並記錄一筆遷移事件,原本的頁面與圖表都會保留。前提是新節點也加了 Proxmox API 輪詢方式。
更換 PVE 根憑證後圖表重新開始
新做法的圖表依叢集存放在 rrd/proxmox-<叢集 ID>/,叢集 ID 取自 PVE 根憑證的指紋,所以名稱相同的兩個叢集不會混在一起。重新產生根憑證後,叢集 ID 會改變、圖表從頭開始。要接回舊圖,可以把舊目錄改名成新的叢集 ID,但新目錄這時通常已經有資料,改名前要先暫停輪詢、有用 rrdcached 的話先寫回、並備份新舊兩個目錄;直接改名不會把兩邊的資料合併。
清理舊做法的殘留
升級到 26.11.0 時 enable_proxmox 已被刪除,LibreNMS 這邊不用再關任何開關;config.php 裡如果還留著 $config['enable_proxmox'],可以順手刪掉。
PVE 主機上如果裝過舊腳本,也可以移除:
/usr/lib/check_mk_agent/local/proxmox/usr/lib/check_mk_agent/plugins/proxmox/etc/snmp/snmpd.conf裡的extend proxmox …,刪掉後要重新啟動 snmpd
舊圖表在 rrd/proxmox/,格式和新做法不同,沒辦法接續,網頁上也已經看不到,只能用 rrdtool 等工具自行讀取。需要歷史資料的話建議先備份;有設定 rrd_purge(預設 0,不清理)的環境,這些不再更新的檔案日後會被自動刪除。
批次建立時的型別錯誤
一般用網頁設定就好,不會遇到這個問題。我因為節點多,改用 php artisan tinker 寫腳本直接建立 Secret 與輪詢方式,存檔時沒有報錯,到輪詢時才出現:
SecretType::data(): Argument #1 ($data) must be of type array, ...ProxmoxApiSecretData given
原因是 Secret 的 data 欄位要給陣列,不能給 ProxmoxApiSecretData 物件。26.11.0 的原始碼在存檔時會把非陣列的值存成空的,所以就算錯誤訊息不同,用物件建立的 Secret 一樣不能用:
$secret->data = ['token_id' => 'librenms@pve!monitoring', 'token_secret' => '<Secret>'];
腳本裡的 Token 不要寫死在程式碼、也不要印到畫面上,用完把暫存檔刪掉。
結論
新做法最大的好處是 PVE 主機上不必再放任何腳本,一組唯讀 Token 就能讓 LibreNMS 取得整個叢集的 VM 資料,VM 遷移後圖表也能接續。PVE 9 的 PVEAuditor 已包含 Guest Agent 的讀取權限,連作業系統版本都不必放寬權限。
要注意的是,升級到 26.11.0 舊監控就會停止,而且舊圖表無法接續。有在用舊做法的朋友,建議升級前先準備好 Token,升級後立刻替每台節點加上輪詢方式,監控的空窗期就能縮到最短。
參考資料
- LibreNMS Docs:Proxmox
https://docs.librenms.org/Extensions/Proxmox/ - LibreNMS 26.11.0 Release
https://github.com/librenms/librenms/releases/tag/26.11.0 - LibreNMS PR #21066
https://github.com/librenms/librenms/pull/21066 - Proxmox VE Wiki:User Management
https://pve.proxmox.com/wiki/User_Management - Proxmox VE Wiki:Qemu-guest-agent
https://pve.proxmox.com/wiki/Qemu-guest-agent - 監測 Proxmox VE 服務運作健康狀況
https://blog.jason.tools/2019/02/pve-health-monitor.html



