LibreNMS 以 NCPA 監測 Linux 主機

Jason Cheng 發布 2026.10.27 瀏覽 1 次

Docker LibreNMS Linux Nagios NCPA Zimbra 系統監控系統管理開源軟體

本文目錄

與 Windows 版的差異
環境與準備
安裝 NCPA
設定
從 LibreNMS 測試
Linux 常用檢查
實際案例
自訂外掛的注意事項
升級
常見問題
結論
參考資料

上一篇〈LibreNMS 以 NCPA 監測 Windows 11〉整理了 Windows 的做法，這篇接著寫 Linux。NCPA 本來就是跨平台的 Agent，Linux 上的 API 路徑、check_ncpa 的寫法都和 Windows 相同，差別在安裝方式、執行身分與幾個 Linux 才有的細節。

我目前有 6 台 Linux 主機用 NCPA 3.5.0 接 LibreNMS：兩台 Zimbra 郵件主機（Ubuntu 22.04、20.04）、一台 Proxmox Mail Gateway（Debian 13）、兩台 UCS 網域控制站，以及一台跑 Docker 的主機。SNMP 已經在看 CPU、記憶體、流量，NCPA 補的是「服務與程序有沒有在跑」，以及內建模組做不到、要自己寫外掛的檢查。

這篇從安裝、設定、常用檢查寫到這幾台的實際案例，LibreNMS 端安裝 check_ncpa 與啟用服務功能的步驟和上一篇相同，就不重複。

與 Windows 版的差異

項目	Windows	Linux
安裝	`.exe` 安裝程式	`.deb`/`.rpm` 套件，或 Nagios 官方套件庫
安裝位置	`C:\Program Files\Nagios\NCPA`	`/usr/local/ncpa`
服務名稱	`NCPA`	`ncpa`（systemd，安裝後自動啟用並啟動）
執行身分	LocalSystem	以 root 啟動後降為 `nagios` 使用者
防火牆	安裝程式會自動開 5693	不會自動開，要自己設定
事件記錄 `logs`、效能計數器 `windowscounters`	有	沒有
`.py` 外掛	要另外裝 Python	用系統的 `python3`

NCPA 3 起 Linux 只有一個 ncpa 服務。網路上很多文章寫的 ncpa_listener、ncpa_passive 是 NCPA 2 的名稱，3.0.0 已合併。

環境與準備

項目	內容
受監測主機	Debian 12/13、Ubuntu 20.04～24.04、RHEL 8 以上，範例 IP `192.168.1.60`
監控主機	LibreNMS，已裝好 `check_ncpa`，範例 IP `192.168.1.10`
NCPA	3.5.0（2026/09/08 發佈），僅提供 x86_64 套件
連線	LibreNMS 到受監測主機的 TCP 5693

文中的 API Token 一律寫成 your-token，請換成自己設定的值。

安裝 NCPA

Debian、Ubuntu 官方套件庫

Nagios 的套件庫 Debian 與 Ubuntu 指令相同，用 lsb_release -cs 帶入版本代號：

sudo apt install curl gnupg lsb-release
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://repo.nagios.com/GPG-KEY-NAGIOS-V3 | sudo gpg --dearmor -o /etc/apt/keyrings/GPG-KEY-NAGIOS-V3.gpg

echo "Types: deb
URIs: https://repo.nagios.com/deb/$(lsb_release -cs)
Suites: /
Signed-By: /etc/apt/keyrings/GPG-KEY-NAGIOS-V3.gpg" | sudo tee /etc/apt/sources.list.d/nagios.sources > /dev/null

sudo apt update
sudo apt install ncpa

官方頁面另有 apt-key add 的舊寫法，新版 Debian、Ubuntu 已不建議使用 apt-key，用上面的 keyrings 寫法即可。

RHEL 系列

先裝 Nagios 的套件庫設定，再用 yum 安裝。下面是 RHEL 9，RHEL 8、10 把網址裡的 9 換成對應版本：

sudo rpm -Uvh https://repo.nagios.com/nagios/9/nagios-repo-9-2.el9.noarch.rpm
sudo yum install ncpa

官方支援清單列的是 RHEL、CentOS、Oracle Linux，沒有點名 Rocky、AlmaLinux，不過用的是同一個 RHEL 套件。

直接安裝套件檔

不想加套件庫的話，也可以從官方下載區取得套件檔。注意 GitHub 的 Release 頁面只有原始碼，編譯好的套件放在 Nagios 的下載區：

wget https://assets.nagios.com/downloads/ncpa3/ncpa-3.5.0-1.amd64.deb
sudo apt install ./ncpa-3.5.0-1.amd64.deb

RHEL 系列下載 ncpa-3.5.0-1.x86_64.rpm 再用 sudo yum install ./ncpa-3.5.0-1.x86_64.rpm 安裝。下載區沒有附 SHA256 檔，要驗證完整性的話，.deb 可以比對 repo.nagios.com 套件索引（Packages）裡的 SHA256，我比對過兩者相同。Debian 與 Ubuntu 各版本用的是同一個 .deb。

套件做了哪些事

程式裝在 /usr/local/ncpa，內含 Python 3.13 與 OpenSSL 3，主機上不需要另外裝 Python 套件
建立 nagios 使用者與群組（已存在就沿用）
安裝 systemd 服務 ncpa，並且自動啟用、立即啟動
第一次啟動時產生自簽憑證，放在 /usr/local/ncpa/var/

也就是說，裝完 NCPA 就已經用預設 Token mytoken 在 5693 埠對外提供服務，務必接著完成下一節的設定。

設定

用 ncpa.cfg.d 放自己的設定

主設定檔是 /usr/local/ncpa/etc/ncpa.cfg。NCPA 讀完它之後，會再依檔名順序讀 ncpa.cfg.d/ 裡所有 .cfg，相同的設定後面蓋前面。

建議不要直接改 ncpa.cfg，把自己的設定寫在 ncpa.cfg.d/ 的獨立檔案。原因是 ncpa.cfg 屬於套件的設定檔，官方版本有變動時（3.4.3 到 3.5.0 就改過 SSL 段落），升級時 dpkg 會停下來詢問要保留哪一份，RPM 則另存成 ncpa.cfg.rpmnew。改在 ncpa.cfg.d/ 就不會遇到。

我的主機都是建立 /usr/local/ncpa/etc/ncpa.cfg.d/librenms.cfg：

# LibreNMS 監控用設定
[listener]
allowed_hosts = 127.0.0.1, 192.168.1.10

[api]
community_string = your-token

community_string：API Token，預設是 mytoken，一定要換掉
allowed_hosts：只允許 LibreNMS 主機連線，其他來源會收到 HTTP 403。可以寫 IP、CIDR 或主機名稱，不支援萬用字元；留空代表不限制

檔案權限改成只有 root 與 nagios 群組可讀，和 ncpa.cfg 相同：

sudo chown root:nagios /usr/local/ncpa/etc/ncpa.cfg.d/librenms.cfg
sudo chmod 640 /usr/local/ncpa/etc/ncpa.cfg.d/librenms.cfg

另外幾個值得知道的預設值：

設定	預設	說明
`[general]` `uid`、`gid`	`nagios`	執行身分。注意是在 `[general]`，不是 `[listener]`
`[listener]` `port`	5693	註解掉時使用預設值
`[listener]` `ssl_version`	`TLSv1_2`	最低 TLS 版本，只接受 `TLSv1_2`、`TLSv1_3`
`[listener]` `admin_password`	`None`	網頁管理介面沒有密碼，能連到 5693 的人就進得去
`[plugin directives]` `plugin_timeout`	59 秒	外掛執行逾時

網頁管理介面用不到的話，可以在同一個檔案的 [listener] 加上 disable_gui = 1 只保留 API。

重新啟動與確認

sudo systemctl restart ncpa
systemctl status ncpa
sudo ss -tlnp | grep 5693

在本機用 Token 查版本，確認新 Token 生效：

curl -k 'https://127.0.0.1:5693/api/system/agent_version?token=your-token'

防火牆

Linux 套件不會動防火牆，有啟用防火牆的話要自己開，並限制只允許 LibreNMS 主機。

Debian、Ubuntu 用 ufw：

sudo ufw allow from 192.168.1.10 to any port 5693 proto tcp

RHEL 系列用 firewalld：

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.10" port port="5693" protocol="tcp" accept'
sudo firewall-cmd --reload

從 LibreNMS 測試

在 LibreNMS 主機上先用指令確認連得到：

/usr/lib/nagios/plugins/check_ncpa -H 192.168.1.60 -t 'your-token' -M 'system/agent_version'

OK: Agent_version was 3.5.0 | 'agent_version'=3.5.0;;;

check_ncpa 的參數與上一篇相同：-M 指定 API 路徑、-q 帶查詢條件、-w/-c 設門檻、-l 列出某個路徑底下有哪些資料。不確定路徑怎麼寫時，先用 -l 看實際的資料結構。

Linux 常用檢查

CPU、記憶體、Swap

-M 'cpu/percent' -q 'aggregate=avg' -w 80 -c 90
-M 'memory/virtual/percent' -w 85 -c 95
-M 'memory/swap/percent' -w 50 -c 80

cpu/percent 不加 aggregate=avg 會回傳每個核心各自的數值。

磁碟與 inode

NCPA 把掛接點路徑裡的 / 換成 |，所以根目錄是 disk/logical/|，/var/log 是 disk/logical/|var|log：

# 根目錄使用率
-M 'disk/logical/|/used_percent' -w 80 -c 90

# /var 剩餘空間（GiB），低於 10 警告、低於 5 嚴重
-M 'disk/logical/|var/free' -u Gi -w 10: -c 5:

# inode 使用率
-M 'disk/logical/|/inodes_used_percent' -w 80 -c 90

只有獨立的掛接點才有對應的節點，/var 沒有獨立分割區時會回傳 The node (/var) requested does not exist，不確定時先用 -M 'disk/logical' -l 列出來。

inode 是 Linux 才有的項目。郵件主機、快取目錄這類小檔案很多的環境，空間還有剩、inode 卻先用完的情況並不少見，值得一起監測。

服務

Linux 的 services 模組透過 systemctl 取得服務清單，名稱寫 systemd 的單元名稱，不加 .service：

-M 'services' -q 'service=ssh,service=cron,status=running'

OK: ssh is running, cron is running

一次可以檢查多個服務，任何一個狀態不符就是 CRITICAL
名稱找不到時回傳 UNKNOWN（No services found for service names: …）
發行版的名稱不一樣：SSH 在 Debian、Ubuntu 是 ssh，RHEL 是 sshd；cron 在 RHEL 是 crond
active (exited) 的一次性服務也算 running

程序

服務檢查只看 systemd 的狀態，程序檢查則是直接看程式有沒有在跑。用 name= 比對程序名稱，-c 1: 表示少於 1 個就 CRITICAL：

-M 'processes' -q 'name=nginx,short_output=true' -c 1:

同名的程序很多時，改用 cmd= 比對完整指令列，搭配 match=search 做部分比對：

-M 'processes' -q 'cmd=nginx: master process,match=search,short_output=true' -c 1:

注意：Linux 上不要用 exe= 比對 root 執行的程序。NCPA 以 nagios 身分執行，讀不到其他使用者程序的執行檔路徑。我在郵件主機實測，exe=/usr/sbin/sshd 回傳 0 個，name=sshd 才抓得到：

OK: Process count for exes named /usr/sbin/sshd was 0 | 'process_count'=0;;;
OK: Process count for processes named sshd was 1

而且沒設 -c 的話 0 個也是 OK，這種錯誤完全不會告警，設定時要特別注意。

其他

# 開機時間：不到 1 小時警告，可以發現非預期的重新開機
-M 'system/uptime' -w 3600: -c 600:

# 登入的使用者數
-M 'user/count' -w 3 -c 5

# 網路介面每秒接收量（MB/s），-d 表示計算變化量
-M 'interface/eth0/bytes_recv' -d -u M -w 50 -c 100

Linux 上沒有 logs 與 windowscounters，查詢會得到 UNKNOWN: The node (logs) requested does not exist.。系統記錄的檢查交給 Graylog、Wazuh 這類記錄平台比較合適。

實際案例

Zimbra 郵件主機：檢查各服務的程序

Zimbra 的服務不是一個個獨立的 systemd 單元，zmcontrol status 又要切換成 zimbra 使用者執行，所以我直接檢查每個服務對應的程序：

服務	查詢條件
ldap	`name=slapd`
mailbox	`name=java,cmd=-Dfile.encoding=UTF-8 -server,match=search`
mysql	`name=mysqld`
mta	`cmd=/opt/zimbra/common/libexec/master,match=search`
amavis	`cmd=amavisd (master),match=search`
proxy	`cmd=nginx: master process,match=search`
memcached	`name=memcached`
opendkim	`name=opendkim`
dnscache	`name=unbound`

每一項都加上 short_output=1 與 -c 1:，例如 mailbox：

-t 'your-token' -M 'processes' -q 'name=java,cmd=-Dfile.encoding=UTF-8 -server,match=search,short_output=1' -c 1:

Zimbra 主機上有不只一個 java 程序，mailbox 要再用指令列的參數區分。mta 的 Postfix 主程序名稱是 master，太常見，所以用完整路徑比對。

LibreNMS 裝置的服務頁：HTTP、SMTP、IMAP 等用內建外掛，檢查類型 ncpa 的幾列是用 NCPA 檢查 Zimbra 各服務的程序

HTTP、SMTP、IMAP、POP3、憑證效期用 LibreNMS 內建的外掛從外部檢查，Zimbra 內部的元件則交給 NCPA。對外的連接埠通了，不代表 LDAP、MySQL、amavis 都正常，兩種一起看才完整。

Proxmox Mail Gateway：一次檢查多個服務

PMG 的元件都是標準的 systemd 服務，用一筆 services 檢查全部列進去：

-t 'your-token' -M 'services' -q 'service=postfix,service=pmg-smtp-filter,service=pmgpolicy,service=pmgdaemon,service=pmgproxy,service=pmgmirror,service=pmgtunnel,service=clamav-daemon,service=clamav-freshclam,service=postgresql@17-main,service=rsyslog,service=ssh,service=unbound,status=running'

好處是 LibreNMS 上只有一列，任何一個服務停掉就變 CRITICAL，訊息會寫出是哪一個。PostgreSQL 的單元名稱帶版本號（PMG 9 是 postgresql@17-main），大版本升級後要記得改。

UCS 網域控制站：需要 root 權限的外掛

UCS 的複寫狀態沒有現成的檢查，我寫了一支 Python 外掛 check_ucs_rep.py，同時檢查兩件事：

UCS LDAP 複寫：Primary 的 notifier ID 與本機 listener 已處理的 ID 差距，落後而且一段時間沒有進度才告警，避免大量變更時誤報
Samba AD DRS 複寫：各分區的連續失敗次數

外掛與 sudoers 範例檔放在 GitHub 的 jt-lnms-plugins/check_ucs_rep，參數說明也在那裡。外掛放在 /usr/local/ncpa/plugins/，LibreNMS 這樣呼叫：

-t 'your-token' -M 'plugins/check_ucs_rep.py' -a "--lang zh-tw"

問題在 samba-tool drs showrepl 要 root 才能執行，而外掛是以 nagios 身分執行。NCPA 有 run_with_sudo 設定可以讓整支外掛用 sudo 執行，但這等於讓整支程式取得 root 權限。我的做法是只開放外掛裡需要的那一個指令，外掛內部用 sudo -n 呼叫：

sudo visudo -f /etc/sudoers.d/ncpa-ucs

nagios ALL=(root) NOPASSWD: /usr/bin/samba-tool drs showrepl --json

sudoers 寫到完整參數，nagios 就只能執行這一行，換了參數也不行。

如果還是要用 run_with_sudo，注意它比對的是含副檔名的檔名，而且 sudo 是加在整個指令最前面，.py 外掛實際執行的是 sudo python3 /usr/local/ncpa/plugins/xxx.py …，sudoers 要依這個寫，範圍會比較大。

Docker 主機：容器狀態

另一支 check_docker.py 透過 /var/run/docker.sock 讀 Docker Engine API，判斷規則：

重新啟動政策是 always、unless-stopped、on-failure 卻沒在執行：CRITICAL
重新啟動政策是 no 而且已停止：視為刻意停用，略過
健康檢查 unhealthy：CRITICAL；starting：WARNING
反覆重新啟動，或重新啟動次數超過門檻：WARNING
--require 指定的容器不存在：CRITICAL

外掛放在 GitHub 的 jt-lnms-plugins/check_docker，同樣放進 /usr/local/ncpa/plugins/：

-t 'your-token' -M 'plugins/check_docker.py' -a "--require web,db,auth"

nagios 要能讀 docker.sock，所以把它加進 docker 群組，再重新啟動 NCPA 讓新的群組生效：

sudo usermod -aG docker nagios
sudo systemctl restart ncpa

注意：docker 群組的權限等同 root，能存取 docker.sock 就能啟動特權容器。這台是內部管理用、只允許 LibreNMS 連線，我評估後接受這個風險；安全要求較高的環境，可以改用只開放唯讀 API 的 Docker socket proxy。

自訂外掛的注意事項

放置位置：/usr/local/ncpa/plugins/，3.5.0 起可以再分子目錄。檔案要讓 nagios 讀得到
直譯器：依副檔名決定，.sh 用 /bin/sh、.py 用系統的 python3（不是 NCPA 內建的 Python），所以外掛不需要執行權限。沒有副檔名的檔案會直接執行，就要給執行權限
參數：check_ncpa 的 -a 會照空白切開再傳給外掛，參數裡有空白時改用 -q "args=…" 的寫法
結束碼：外掛的結束碼原樣傳回，0 OK、1 WARNING、2 CRITICAL、3 UNKNOWN
逾時：超過 59 秒會被強制結束，耗時的檢查要自己控制時間
輸出：第一行寫狀態與效能資料，LibreNMS 會拿 | 後面的效能資料畫圖。效能資料的名稱固定，不要放會變動的內容

升級

用套件庫安裝的，直接升級：

sudo apt update && sudo apt install ncpa     # Debian、Ubuntu
sudo yum update ncpa                          # RHEL 系列

升級過程會先停止服務、裝完再啟動。設定寫在 ncpa.cfg.d/ 的話不受影響；改過 ncpa.cfg 的話，dpkg 會詢問要保留哪一份，預設保留自己的。升級後從 LibreNMS 查 system/agent_version 確認版本。

常見問題

連線被拒或 403

Connection refused：服務沒啟動或防火牆擋住，先看 systemctl status ncpa、ss -tlnp | grep 5693
HTTP 403：來源 IP 不在 allowed_hosts。改完記得 systemctl restart ncpa

服務找不到

回傳 No services found 時，先用 systemctl list-units --type=service --all 確認單元名稱。NCPA 只看得到已載入的單元，從來沒啟動過的停用服務可能不在清單裡。

程序數量是 0

改用 name= 或 cmd=，不要用 exe=；並且一定要設 -c 1:，否則 0 個也是 OK。

外掛權限不足

外掛以 nagios 身分執行，先切換身分手動跑一次，看錯誤訊息：

sudo -u nagios python3 /usr/local/ncpa/plugins/check_xxx.py

服務訊息太長

processes 沒加 short_output 時，會列出每個符合程序的 PID、使用者、記憶體與 CPU，LibreNMS 服務頁的訊息欄會拉得很長。程序檢查一律加上 short_output=1，只留數量與總用量。

結論

NCPA 在 Linux 上裝起來比 Windows 更單純，一個套件、一個服務，設定集中在 ncpa.cfg.d/ 的一個檔案。要注意的是裝完就會用預設 Token 對外提供服務，Token、allowed_hosts、防火牆要一起設好。

內建模組處理服務、程序、磁碟這類通用檢查，各系統自己的狀態，像 UCS 複寫、Docker 容器，就寫成外掛放進 plugins/。需要 root 權限時，我傾向只在 sudoers 開放必要的指令，而不是讓整支外掛用 root 執行。

參考資料

LibreNMS 以 NCPA 監測 Windows 11
https://blog.jason.tools/2026/10/librenms-ncpa-windows.html
NCPA 官方網站與下載
https://www.nagios.org/ncpa/
NCPA 3 套件下載區
https://assets.nagios.com/downloads/ncpa3/
Nagios 官方套件庫
https://repo.nagios.com/
NCPA 3.x 設定說明
https://www.nagios.org/ncpa/help/3.x/configuration.html
NCPA 3.x API 說明
https://www.nagios.org/ncpa/help/3.x/api.html
NCPA GitHub
https://github.com/NagiosEnterprises/ncpa
jt-lnms-plugins：我的 LibreNMS/Nagios 監控外掛
https://github.com/jasoncheng7115/jt-lnms-plugins
LibreNMS：Services
https://docs.librenms.org/Extensions/Services/

Jason Cheng

企業開源技術顧問，專注架構規劃與實務導入

關於作者 →

延伸閱讀

LibreNMS 以 NCPA 監測 Windows 11 2026.10.26

LibreNMS 企業實戰經驗分享 2018.11.10

jt-vc-portal：替 Jitsi Meet 補上會議管理入口 2026.07.30

監測 Proxmox VE 服務運作健康狀況 2019.02.08