Ubuntu 22.04 安装 Icinga 2.16.5 指南
在 Ubuntu 22.04 上从零安装 Icinga 2.16.5 与 Icinga Web 2.12.7 的完整实录:官方仓库与离线 deb 双方案、IDO/API 特性配置与证书排障、Setup 向导全流程与登录验收,全部命令与回显实测。
Ubuntu 22.04 安装 Icinga 2.16.5 指南
目标:在 Ubuntu 22.04 服务器上从零安装 Icinga 2 监控核心(2.16.5)与 Icinga Web 2 界面层(2.12.7),完成 IDO 数据库落库、REST API 启用、Setup 向导初始化并登录 Dashboard 验收。全文命令与回显均在 Ubuntu 22.04.5 LTS(主机名 icinga1.example.com)上实测通过,过程中遇到的"启用 api 后服务起不来"等真实故障已完整沉淀。
一、环境信息
- 操作系统:Ubuntu 22.04.5 LTS (Jammy Jellyfish),x86_64(
icinga2 --version实测回显) - 内核:6.8.0-138-generic
- Icinga 2:2.16.5-1+ubuntu22.04(来自 packages.icinga.com 官方源 icinga-jammy)
- Icinga Web 2:2.12.7-1+ubuntu22.04(jammy 源内最新,上游已到 2.14.0,22.04 未打包,见版本选型说明)
- 数据库:MariaDB 10.6.23(Ubuntu 22.04 仓库自带
mariadb-server) - PHP:8.1.2-1ubuntu2.27(icingaweb2 包自动依赖)
- Web 服务:Apache 2.4.52(icingaweb2 包自动依赖)
- 检测插件:monitoring-plugins(Ubuntu 仓库,Nagios 插件族)
- 关键端口:5665(Icinga 2 REST API 与集群通信)、80(Icinga Web 2)
- 关键路径:
/etc/icinga2(核心配置)、/var/lib/icinga2(证书与状态)、/etc/icingaweb2(Web 配置)、/var/log/icinga2(日志) - 演示口令约定:数据库业务账号与 API 账号统一使用
q1w2e3r4(演示环境实测值),Web 管理账号admin / q1w2e3r4
二、前置条件
- 一台 Ubuntu 22.04 服务器,具备 root 或 sudo 权限,能访问互联网(packages.icinga.com 与 Ubuntu 镜像源)。
- 已规划数据库名与账号:本文使用两个库——
icinga2(IDO 状态落库,安装时自动创建)与icingaweb(Web 界面自身的配置/认证库,需手工创建)。 - 时区与时间同步正常(监控历史与通知时间依赖正确时钟):
timedatectl确认。 - 防火墙放行 80(Web 界面)与 5665(API/集群,仅当有 satellite/agent 接入或需要远程调 API 时)。
三、版本选型说明
Ubuntu 22.04 有两个可用来源:官方 packages.icinga.com(推荐,版本最新)与 Ubuntu 自带 universe 源(版本旧,应急可用)。先看官方源的版本全貌(实测回显):
apt-cache policy icinga2 icingaweb2 | head -14
icinga2:
Installed: (none)
Candidate: 2.16.5-1+ubuntu22.04
Version table:
2.16.5-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
2.16.4-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
2.16.3-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
2.16.2-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
2.16.1-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
apt-cache policy icingaweb2 | head -6
icingaweb2:
Installed: (none)
Candidate: 2.12.7-1+ubuntu22.04
Version table:
2.12.7-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
2.12.6-1+ubuntu22.04 500
500 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
关键差异与结论:官方源 icinga2 与 GitHub 最新稳定版 v2.16.5 同步(2.16.5 发布于 2026-08-18);icingaweb2 在 jammy 源止步 2.12.7,而上游 2.14.0(2026-07-03 发布)只为 24.04(noble)等更新发行版提供 2.13/2.14 包(实查 icinga-noble 源为 icingaweb2 2.14.0-2+ubuntu24.04)。因此 22.04 上按 2.16.5 + Web 2.12.7 组合安装,这是官方源给出的最新可得组合;若坚持 Web 2.14 需换 24.04 或用源码部署,不在本篇展开。
四、方案 A:官方仓库在线安装(推荐)
本方案从零开始:基础依赖与数据库 → 添加官方源 → 安装核心与 IDO 后端 → 启用特性(含一次真实的服务启动失败排障)→ systemd 托管 → 验证。
4.1 安装基础依赖与数据库
先装 MariaDB(提供 IDO 与 Web 两个库)、检测插件族与证书工具:
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y gnupg curl apt-transport-https ca-certificates mariadb-server monitoring-plugins
实测安装完成后启动数据库并确认版本:
systemctl start mariadb
systemctl is-active mariadb
mariadb --version
mysqladmin --version
active
mariadb Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using EditLine wrapper
mysqladmin Ver 10.0 Distrib 10.6.23-MariaDB, for debian-linux-gnu on x86_64
💡 说明:Ubuntu 22.04 的 MariaDB 默认对 root 使用 unix_socket 认证——本机 root 用户执行
mariadb无需密码即可进入,mysql_secure_installation一步不是必须的;远程管理需求出现时再单独为 root 设置口令。本篇所有数据库操作都在服务器本机以 root 执行。
4.2 添加官方软件源
导入 packages.icinga.com 的签名密钥并写入源定义:
curl -fsSL https://packages.icinga.com/icinga.key | gpg --dearmor -o /usr/share/keyrings/icinga-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/ubuntu icinga-jammy main" > /etc/apt/sources.list.d/icinga.list
apt-get update
apt-get update 中与 Icinga 相关的实测输出:
Get:5 https://packages.icinga.com/ubuntu icinga-jammy InRelease [9149 B]
Get:6 https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages [142 kB]
校验一下密钥指纹,确认拿到的是 Icinga GmbH 官方构建签名钥:
gpg --show-keys --with-colons /usr/share/keyrings/icinga-archive-keyring.gpg | head -4
pub:-:4096:1:CC116F55AA7F2382:1716285309:::-:::scSC::::::23::0:
fpr:::::::::DD3AF6198ED000B4C0B73956CC116F55AA7F2382:
uid:-::::1716285309::F8C6CE97CC9FFBB3F473055DF12D5F1F2D708D45::Icinga GmbH (Build server) <info@icinga.com>::::::::::0:
4.3 安装 icinga2 与 IDO 后端
export DEBIAN_FRONTEND=noninteractive
apt-get install -y icinga2 icinga2-ido-mysql
实测安装尾部输出(注意 dbconfig-common 的自动建库行为):
creating database icinga2: success.
verifying database icinga2 exists: success.
populating database via sql... done.
dbconfig-common: flushing administrative password
Setting up icinga2 (2.16.5-1+ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
INSTALL_EXIT=0
解读:非交互模式下 dbconfig-common 利用了本机 root 的 unix_socket 认证,自动完成了三件事——创建名为 icinga2 的数据库、创建 icinga2@localhost 数据库用户并赋权、导入 IDO 全部表结构(实测 61 张表)。它会生成一个随机口令并写进两处:
grep -E "dbuser|dbpass|dbname" /etc/dbconfig-common/icinga2-ido-mysql.conf
dbc_dbuser='icinga2'
dbc_dbpass='pqpoHefgqTVT'
dbc_dbname='icinga2'
同时写进 Icinga 2 的 IDO 特性配置文件 /etc/icinga2/features-available/ido-mysql.conf(去掉注释后的实际内容):
library "db_ido_mysql"
object IdoMysqlConnection "ido-mysql" {
user = "icinga2",
password = "pqpoHefgqTVT",
host = "localhost",
database = "icinga2"
}
⚠️ 注意:此时包把随机口令落在配置里但并未启用 ido-mysql 特性(
ls /etc/icinga2/features-enabled/实测只有 checker、mainlog、notification)。若不希望使用随机口令,按下一节把口令统一改成约定值——两处必须同步改,漏一处 IDO 就连不上库。
4.4 规范化 IDO 数据库口令
把数据库用户口令与特性配置统一改为演示口令 q1w2e3r4(生产环境请用强随机值并同样保持两处一致):
mariadb -e "ALTER USER 'icinga2'@'localhost' IDENTIFIED BY 'q1w2e3r4'; FLUSH PRIVILEGES;"
sed -i 's/pqpoHefgqTVT/q1w2e3r4/' /etc/icinga2/features-available/ido-mysql.conf
4.5 启用特性与 API 排障实录
启用 IDO 落库与 REST API 两个特性,并设置开机自启:
icinga2 feature enable ido-mysql
icinga2 feature enable api
systemctl enable icinga2
systemctl restart icinga2
实测 feature enable 回显:
Enabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
排障实录:restart 失败。 此处实测 systemctl restart icinga2 报错:
Job for icinga2.service failed because the control process exited with error code.
See "systemctl status icinga2.service" and "journalctl -xeu icinga2.service" for details.
failed
定位过程:
journalctl -u icinga2 --no-pager -n 15 | grep -E "critical"
critical/SSL: Error on bio X509 AUX reading pem file '/var/lib/icinga2/certs//icinga1.example.com.crt': 2147483650, "error:80000002:system library::No such file or directory"
critical/config: Error: Cannot get certificate from cert path: '/var/lib/icinga2/certs//icinga1.example.com.crt'.
critical/config: 1 error
critical/cli: Config validation failed. Re-run with 'icinga2 daemon -C' after fixing the config.
原因:icinga2 feature enable api 只写特性软链,不会生成 TLS 证书;ApiListener 起不来是因为节点证书不存在。解决:执行 icinga2 api setup,一次性生成 CA、节点证书/私钥、API 用户并确认 api 特性:
icinga2 api setup
information/cli: Adding new ApiUser 'root' in '/etc/icinga2/conf.d/api-users.conf'.
information/cli: Reading '/etc/icinga2/icinga2.conf'.
information/cli: Enabling the 'api' feature.
warning/cli: Feature 'api' already enabled.
information/cli: Updating 'NodeName' constant in '/etc/icinga2/constants.conf'.
information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
information/cli: Updating 'ZoneName' constant in '/etc/icinga2/constants.conf'.
information/cli: Backup file '/etc/icinga2/constants.conf.orig' already exists. Skipping backup.
Done.
Now restart your Icinga 2 daemon to finish the installation!
api setup 生成的证书与 API 用户(实测 ls /var/lib/icinga2/certs/):
ca.crt
icinga1.example.com.crt
icinga1.example.com.csr
icinga1.example.com.key
API 用户配置 /etc/icinga2/conf.d/api-users.conf 生成的是随机口令(password = "03e66d029c2c98cd" 形态、权限 permissions = [ "*" ])。演示环境统一改为 q1w2e3r4:
sed -i 's/password = "03e66d029c2c98cd"/password = "q1w2e3r4"/' /etc/icinga2/conf.d/api-users.conf
4.6 systemd 托管与开机自启
再次重启并确认运行状态:
systemctl restart icinga2
systemctl is-active icinga2
ss -ltnp | grep 5665
systemctl status icinga2 --no-pager -l | head -12
active
LISTEN 0 4096 *:5665 *:* users:(("icinga2",pid=8800,fd=18))
● icinga2.service - Icinga host/service/network monitoring system
Loaded: loaded (/lib/systemd/system/icinga2.service; enabled; vendor preset: enabled)
Drop-In: /etc/systemd/system/icinga2.service.d
└─limits.conf
Active: active (running) since Mon 2026-10-19 20:25:08 UTC; 4min 56s ago
Main PID: 8758 (icinga2)
Status: "Startup finished."
Tasks: 89
Memory: 22.9M
CPU: 13.671s
验证已通过:服务 active、5665 端口监听、开机自启 enabled(4.5 步 systemctl enable icinga2 的回显为 Executing: /lib/systemd/systemd-sysv-install enable icinga2)。limits.conf drop-in 是官方包自带的文件描述符限制配置,说明 22.04 的包已内置 systemd 单元,无需自己写 unit。
4.7 验证核心与 API
配置全量校验(第一次跑 CLI 前建议都做一遍):
icinga2 daemon -C
[2026-10-19 20:30:04 +0000] information/ConfigItem: Instantiated 3 ServiceGroups.
[2026-10-19 20:30:04 +0000] information/ConfigItem: Instantiated 3 TimePeriods.
[2026-10-19 20:30:04 +0000] information/ConfigItem: Instantiated 12 Services.
[2026-10-19 20:30:04 +0000] information/ConfigItem: Instantiated 1 ScheduledDowntime.
[2026-10-19 20:30:04 +0000] information/ScriptGlobal: Dumping variables to file '/var/cache/icinga2/icinga2.vars'
[2026-10-19 20:30:04 +0000] information/cli: Finished validating the configuration file(s).
特性清单确认:
icinga2 feature list
Disabled features: command compatlog debuglog elasticsearch gelf graphite icingadb influxdb influxdb2 journald livestatus opentsdb perfdata syslog
Enabled features: api checker ido-mysql mainlog notification
REST API 查询运行状态(-k 是因为证书是自建 CA 签发):
curl -sk -u root:q1w2e3r4 -X GET "https://localhost:5665/v1/status/IcingaApplication"
{"results":[{"name":"IcingaApplication","perfdata":[],"status":{"icingaapplication":{"app":{"enable_event_handlers":true,"enable_flapping":true,"enable_host_checks":true,"enable_notifications":true,"enable_perfdata":true,"enable_service_checks":true,"environment":"","node_name":"icinga1.example.com","pid":8800,"program_start":1792441508.364058,"version":"r2.16.5-1"}}}}]}
IDO 落库验证:等 1 分钟左右让首个状态周期写入后查询(IDO 表按 icinga_objects 关联取对象名,实测语句与回显):
mariadb icinga2 -e "SELECT o.name1 AS host, hs.current_state, hs.output, hs.status_update_time FROM icinga_hoststatus hs JOIN icinga_objects o ON o.object_id=hs.host_object_id AND o.objecttype_id=1;"
host current_state output status_update_time
icinga1.example.com 0 PING OK - Packet loss = 0%, RTA = 0.04 ms 2026-10-19 20:30:09
current_state = 0 即 UP,插件 check_ping 已真实跑通。至此监控核心安装完成。
五、方案 B:离线 deb 包安装
适用于目标服务器无法访问 packages.icinga.com、但可以访问 Ubuntu 内网镜像源(或已缓存系统依赖)的场景。思路:在有网的"管理机"上用 apt 把官方 deb 下载成离线包,拷贝到目标服务器后用 apt-get install ./xxx.deb 安装——本地 deb 优先安装,系统依赖仍从可达的源解析。
5.1 管理机下载离线包
在能访问官方源的管理机上(或临时把源加到目标机)执行:
mkdir -p /root/debs && cd /root/debs
apt-get download icinga2 icinga2-bin icinga2-common
ls -lh
total 5.0M
-rw-r--r-- 1 root root 4.8M Aug 18 08:10 icinga2-bin_2.16.5-1+ubuntu22.04_amd64.deb
-rw-r--r-- 1 root root 68K Aug 18 08:10 icinga2-common_2.16.5-1+ubuntu22.04_all.deb
-rw-r--r-- 1 root root 128K Aug 18 08:10 icinga2_2.16.5-1+ubuntu22.04_amd64.deb
💡 说明:jammy 源中
icinga2元包依赖icinga2-bin(程序与库,4.8M)与icinga2-common(配置与脚本),三个 deb 即核心全部;如需 IDO 后端同法追加下载icinga2-ido-mysql。下载时的 warningDownload is performed unsandboxed as root...是 root 执行apt-get download的无害提示,可忽略。下载完成后把这 3 个文件拷贝(U 盘/scp)到目标服务器。
5.2 目标服务器离线安装
目标服务器保持不配置 Icinga 源,进入 deb 所在目录安装(系统依赖会从其可达的 Ubuntu 镜像源解析;实测同步安装了 20 个系统依赖,共 23 包):
cd /root/debs
apt-get install -y ./icinga2_2.16.5-1+ubuntu22.04_amd64.deb ./icinga2-bin_2.16.5-1+ubuntu22.04_amd64.deb ./icinga2-common_2.16.5-1+ubuntu22.04_all.deb
实测关键回显:
0 upgraded, 23 newly installed, 0 to remove and 2 not upgraded.
Setting up icinga2-common (2.16.5-1+ubuntu22.04) ...
Setting up icinga2-bin (2.16.5-1+ubuntu22.04) ...
Setting up icinga2 (2.16.5-1+ubuntu22.04) ...
5.3 验证
icinga2 --version | head -1
icinga2 - The Icinga 2 network monitoring daemon (version: r2.16.5-1)
⚠️ 注意:若目标服务器连 Ubuntu 镜像源也不可达,
apt-get install ./...deb会报Depends: libboost-thread1.74.0 ... but it is not installable(实测报错原文),此时需要把依赖 deb 一并离线携带,或在内网自建完整镜像源。
六、方案对比与选择建议
| 维度 | 方案 A:官方仓库在线 | 方案 B:离线 deb 包 |
|---|---|---|
| 版本 | 2.16.5(与上游同步) | 2.16.5(下载时锁定) |
| 是否需联网 | 需访问 packages.icinga.com | 管理机需联网一次;目标机仅需 Ubuntu 依赖源 |
| 安装方式 | apt 源,后续 apt upgrade 自动跟进 | 本地 deb,升级需重新下载新版本 deb |
| systemd 服务名 | icinga2.service(包自带) | 相同(同一批 deb) |
| 优缺点 | 升级/依赖维护最省心 | 内网隔离环境唯一可行路径,升级手动 |
选择建议:能出网选方案 A;内网隔离选方案 B 并规划好依赖源;两方案安装后的配置路径与 systemd 托管完全一致,后续章节对两者通用。
七、Icinga Web 2 界面层安装与初始化
监控核心装完还没有界面。本节安装 Icinga Web 2(含 Apache/PHP 依赖)、准备 Web 数据库、用 Setup 向导完成初始化并登录验收。向导既有浏览器操作路径,本节把每一步的真实输入值完整记录,读者照做即可得到同样的界面。
7.1 安装 icingaweb2 与 icingacli
export DEBIAN_FRONTEND=noninteractive
apt-get install -y icingaweb2 icingacli
icingacli --version
Icinga Web 2 2.12.7
Git Commit 36bafad37c6edc138b0353d6ade2f1b99704454d
PHP Version 8.1.2-1ubuntu2.27
MODULE VERSION
setup 2.12.7
包会自动装好 Apache 2.4.52、PHP 8.1 及所需扩展,并写入 /etc/apache2/conf-available/icingaweb2.conf。启动 Web 服务:
systemctl start apache2
systemctl is-active apache2
active
7.2 准备 Web 数据库
Web 界面需要自己的库存配置、认证用户与会话(注意这是 Web 自身用的库,与 IDO 的 icinga2 库是两回事):
mariadb -e "CREATE DATABASE IF NOT EXISTS icingaweb CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; GRANT ALL PRIVILEGES ON icingaweb.* TO 'icingaweb'@'localhost' IDENTIFIED BY 'q1w2e3r4'; FLUSH PRIVILEGES;"
mariadb -e "SHOW DATABASES;"
Database
icinga2
icingaweb
information_schema
mysql
performance_schema
sys
7.3 生成 Setup Token 并完成向导
首次访问时 Web 处于未初始化状态,需要凭 setup token 进入向导:
icingacli setup token create
The newly generated setup token is: ca66327a1c2e5a45
浏览器访问 http://<服务器IP>/icingaweb2/setup(实测未初始化状态下 /icingaweb2 会 302 跳转到登录页、/icingaweb2/setup 返回 200,curl 实测:HTTP/1.1 302 Found ... Location: /icingaweb2/authentication/login)。向导各步骤实测输入如下,逐步照填:
| 步骤 | 页面 | 实测输入 |
|---|---|---|
| 1 | Welcome / Token | 输入 ca66327a1c2e5a45 |
| 2 | Modules | 勾选 Monitoring |
| 3 | Requirements | 全绿校验通过(PHP 模块/权限由包配置好) |
| 4 | Authentication | 选择 Database |
| 5 | Database Resource | name=icingaweb_db、Database Type=MySQL、Host=localhost、Database Name=icingaweb、Username=icingaweb、Password=q1w2e3r4、Character Set=utf8mb4,点 Validate Configuration 通过 |
| 6 | Authentication Backend | name=icingaweb2、Backend=Database |
| 7 | Create Administrative Account | Username=admin、Password=q1w2e3r4(两遍) |
| 8 | Application Configuration | Logging=syslog、Level=Information,其余默认 |
| 9 | Summary | 确认生成配置(写入 /etc/icingaweb2/) |
| 10 | Monitoring: IDO Resource | name=icinga_ido、Database Type=MySQL、Host=localhost、Database Name=icinga2、Username=icinga2、Password=q1w2e3r4,校验通过 |
| 11 | Monitoring: Command Transport | Transport=Icinga 2 API、Host=localhost、Port=5665、API Username=root、API Password=q1w2e3r4,校验通过 |
| 12 | Monitoring Security | 默认 Protected Custom Variables=*pw*,*pass*,community |
| 13 | Finish | 完成后 monitoring 模块自动启用 |
完成后在服务器上核对配置落盘与模块状态(实测):
ls /etc/icingaweb2/
ls /etc/icingaweb2/enabledModules/
icingacli module list
authentication.ini
config.ini
enabledModules
groups.ini
modules
resources.ini
roles.ini
monitoring
MODULE VERSION STATE DESCRIPTION
monitoring 2.12.6 enabled Icinga monitoring module
7.4 登录验证
访问 http://<服务器IP>/icingaweb2,用 admin / q1w2e3r4 登录(实测登录后标题栏为 Current Incidents :: Dashboard :: Icinga Web,Dashboard 正常显示监控数据)。命令行同样能确认监控链路已经打通:
icingacli monitoring list hosts
UP icinga1.example.com: PING OK - Packet loss = 0%, RTA = 0.03 ms
💡 说明:这条输出直接来自 IDO 库中
check_ping的真实结果,说明"核心检查 → IDO 落库 → Web 读取"整条链路已工作。
八、配置说明
安装完成后值得掌握的关键文件(均在实测环境核对过):
| 文件/目录 | 作用 | 常用项 |
|---|---|---|
/etc/icinga2/icinga2.conf | 核心主配置,include 全局模板与 conf.d | include <itl> 引入 ITL 插件模板库 |
/etc/icinga2/constants.conf | 常量(NodeName、ZoneName,api setup 会改写) | 改节点名时同步证书 CN |
/etc/icinga2/conf.d/hosts.conf | 被监控主机对象 | 默认含本机(address 127.0.0.1,hostalive 检查) |
/etc/icinga2/conf.d/services.conf | 服务对象与 apply 规则 | ping4/ping6/http/disk/apt 等默认服务 |
/etc/icinga2/features-available/ | 全部特性配置 | ido-mysql.conf(连接串)、api.conf(监听 5665) |
/etc/icinga2/features-enabled/ | 已启用特性软链 | feature enable/disable 实际在改这里 |
/etc/icinga2/conf.d/api-users.conf | API 用户 | password、permissions = [ "*" ] |
/etc/icinga2/zones.conf | 集群 zone/endpoint 定义 | 单机默认只有本节点 |
/var/lib/icinga2/certs/ | 节点证书/私钥/CA | 换主机名需重新 api setup |
/etc/dbconfig-common/icinga2-ido-mysql.conf | dbconfig 记录的 IDO 库账号 | 改库口令时与 features 配置同步 |
/etc/icingaweb2/ | Web 配置 | resources.ini(两个库连接)、authentication.ini、roles.ini |
/etc/icingaweb2/modules/monitoring/ | monitoring 模块配置 | backends.ini(IDO 资源)、commandtransports.ini(命令通道) |
新增一台被监控主机的最小示例(追加到 /etc/icinga2/conf.d/hosts.conf 后 icinga2 daemon -C && systemctl reload icinga2 生效):
object Host "web1.example.com" {
import "generic-host"
address = "192.168.1.100"
check_command = "hostalive"
}
九、升级、降级与多版本管理
- 查看可用版本:
apt-cache madison icinga2(实测回显):
icinga2 | 2.16.5-1+ubuntu22.04 | https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
icinga2 | 2.16.4-1+ubuntu22.04 | https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
icinga2 | 2.16.3-1+ubuntu22.04 | https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
icinga2 | 2.16.2-1+ubuntu22.04 | https://packages.icinga.com/ubuntu icinga-jammy/main amd64 Packages
- 升级到最新:
apt-get update && apt-get upgrade(官方源 2.14/2.15/2.16 三条版本线都在持续发补丁版本,常规补丁升级直接跟进即可;跨大版本升级先读官方 upgrade 文档)。 - 安装指定版本(降级/锁版本):
apt-get install icinga2=2.16.4-1+ubuntu22.04 icinga2-bin=2.16.4-1+ubuntu22.04 icinga2-common=2.16.4-1+ubuntu22.04,然后用apt-mark hold icinga2固定,解除用apt-mark unhold icinga2。 - 离线场景升级:按方案 B 重新下载新版 deb,
apt-get install ./icinga2_<新版本>_amd64.deb ...覆盖安装。
十、常见问题(FAQ)
Q1:icinga2 feature enable api 后服务起不来,报证书文件不存在?
正常现象,feature enable api 不生成证书。执行 icinga2 api setup 生成 CA 与节点证书后再 systemctl restart icinga2(完整排障实录见 4.5 节)。另外注意:节点证书 CN 默认取主机名(实测为 icinga1.example.com),装完 icinga2 之后不要改主机名;若必须改,删除 /var/lib/icinga2/certs/ 后重跑 icinga2 api setup。
Q2:IDO 数据库口令放在哪里?改口令要改几处?
dbconfig-common 生成口令记录在 /etc/dbconfig-common/icinga2-ido-mysql.conf(dbc_dbpass),Icinga 2 实际使用的是 /etc/icinga2/features-available/ido-mysql.conf 里的 password。改库口令时这两处(加上 MariaDB 侧 ALTER USER)共三处保持一致。
Q3:为什么本机 mariadb 不输密码就能进?
Ubuntu 22.04 的 MariaDB 对 root 用 unix_socket 认证,仅限本机 root;要给 root 设传统口令用 mariadb -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'q1w2e3r4';",设置后本机登录也需口令,脚本化操作请改用业务账号。
Q4:直接 SELECT * FROM icinga_hoststatus 想看主机名/状态为什么报错?
IDO 表结构里 icinga_hoststatus 没有主机名列(它存 host_object_id),状态列叫 current_state 而不是 host_state。正确查法(实测):
SELECT o.name1 AS host, hs.current_state, hs.output
FROM icinga_hoststatus hs
JOIN icinga_objects o ON o.object_id = hs.host_object_id AND o.objecttype_id = 1;
Q5:icinga2 object list --type Host 报 Cannot open objects file '/var/cache/icinga2/icinga2.debug'?
对象缓存默认不落盘。先执行 icinga2 daemon -C --dump-objects 生成缓存文件,再跑 object list 即可(实测修复过程)。
Q6:Web 界面登录页打不开或样式错乱?
确认 Apache 已启动(systemctl is-active apache2)且访问路径是 /icingaweb2(包默认挂在子路径,不是根路径);初始化入口固定是 /icingaweb2/setup,token 用 icingacli setup token create 重新生成即可(旧 token 作废)。
Q7:apt 下载或安装时出现 Download is performed unsandboxed as root 警告?
root 执行 apt-get download/install ./deb 的无害提示,不影响结果。
十一、卸载与清理
systemctl stop icinga2 apache2
apt-get purge -y icinga2 icinga2-ido-mysql icingaweb2 icingacli
apt-get autoremove -y
mariadb -e "DROP DATABASE IF EXISTS icinga2; DROP DATABASE IF EXISTS icingaweb; DROP USER IF EXISTS 'icinga2'@'localhost'; DROP USER IF EXISTS 'icingaweb'@'localhost'; FLUSH PRIVILEGES;"
rm -f /etc/apt/sources.list.d/icinga.list /usr/share/keyrings/icinga-archive-keyring.gpg
rm -rf /var/lib/icinga2 /var/log/icinga2 /var/cache/icinga2
purge 会移除 conffiles 与 /etc/icinga2、/etc/icingaweb2 下的包托管内容;/var/lib/icinga2(证书/状态)等运行时目录按上面最后一步手工删除,即完成全部清理。
十二、参考链接
- 官方安装文档(Icinga 2 / Ubuntu):
https://icinga.com/docs/icinga-2/latest/(Get Started → Ubuntu 章节) - 官方软件源索引:https://packages.icinga.com/
- Icinga 2 发布流:https://github.com/Icinga/icinga2/releases.atom
- Icinga Web 2 文档:https://icinga.com/docs/icinga-web-2/latest/
- 介绍与选型背景(版本、生态对比):见《Icinga 2.16.5 介绍与选型指南》
icinga2/icingacli每条命令的逐条实测详见本专栏《Icinga 2.16.5 常用 CLI 命令与工具详解》篇