Naemon 1.5 配置参数详解

目标：在 Ubuntu 22.04 服务器上逐层拆解 Naemon 1.5.2 的配置体系：主配置文件 naemon.cfg 的 90 项生效参数按类详解、对象定义（host/service/command/contact/timeperiod）与模板继承机制、以及超时/外部命令/Livestatus 等关键参数的实测验证，并给出中型环境的生产配置模板。全部配置、命令与回显均在真实服务器上执行采集。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（amd64）
• Naemon Core：1.5.2（naemon-core 1.5.2-1，OBS home:naemon 仓库安装，安装过程见本专栏部署篇）
• 配套组件：naemon-livestatus 1.5.1、monitoring-plugins 2.3.1（插件路径 /usr/lib/nagios/plugins）
• 主配置文件：/etc/naemon/naemon.cfg（生效参数 90 项）
• 对象定义目录：/etc/naemon/conf.d/；模块配置目录：/etc/naemon/module-conf.d/
• 服务管理：systemd（naemon.service）

二、前置条件

1. 已按本专栏部署篇完成 Naemon 1.5 安装并确认服务运行：systemctl is-active naemon 返回 active；
2. 预检命令可用（必须以 naemon 用户执行）：su -s /bin/bash naemon -c "naemon -v /etc/naemon/naemon.cfg"；
3. 了解 Nagios 式对象模型的基本概念（host/service/command/contact），首次接触建议先读本专栏介绍篇第三节。

三、参数查看与修改方式

3.1 配置文件布局

Naemon 的配置由「主配置 + 对象定义 + 模块配置 + 资源宏」四部分组成，包安装后的布局：

ls -la /etc/naemon/

实测回显：

drwxr-xr-x 5 naemon naemon 4096 Nov  1 04:22 .
drwxr-xr-x 4 root   root   4096 Nov  1 04:22 ..
drwxr-xr-x 3 naemon naemon 4096 Nov  1 04:22 conf.d
drwxr-xr-x 2 naemon naemon 4096 Nov  1 04:22 module-conf.d
-rw-rw-r-- 1 naemon naemon 8355 May 18 14:48 naemon.cfg
-rw-rw-r-- 1 naemon naemon  830 May 18 14:48 resource.cfg

3.2 查看生效参数

主配置内大量注释行，提取「当前生效参数」用 grep 排除注释与空行：

grep -vE "^\s*#|^\s*$" /etc/naemon/naemon.cfg | wc -l
grep -vE "^\s*#|^\s*$" /etc/naemon/naemon.cfg | head -5

实测回显：

90
log_file=/var/log/naemon/naemon.log
cfg_dir=/etc/naemon/conf.d
object_cache_file=/var/lib/naemon/objects.cache
precached_object_file=/var/lib/naemon/objects.precache
resource_file=/etc/naemon/resource.cfg

更权威的「最终生效视图」是对象缓存文件——核心每次启动会把解析后的完整对象集写入 object_cache_file，改配置后可对照它确认解析结果：

head -3 /var/lib/naemon/objects.cache

实测回显：

########################################
#       NAEMON OBJECT CACHE FILE
#

3.3 修改与生效流程

固定三步：改文件 → 预检 → 重载。预检不过就重启是新手最常见的自伤路径，务必养成先预检的习惯：

# 1. 修改配置（示例：调整管理员邮箱）
sed -i 's/^admin_email=.*/admin_email=admin@example.com/' /etc/naemon/naemon.cfg

# 2. 预检（以 naemon 用户，核心拒绝 root）
su -s /bin/bash naemon -c "naemon -v /etc/naemon/naemon.cfg"

# 3. 平滑重载（SIGHUP）或完整重启
systemctl reload naemon

实测回显（预检部分）：

Total Warnings: 0
Total Errors:   0

Things look okay - No serious problems were detected during the pre-flight check

reload（SIGHUP）与 restart 的差异：reload 让核心重新读配置并保留状态数据与检查调度，绝大多数参数改动用 reload 即可；个别全局参数（如 interval_length）的调整建议走 restart 并观察日志确认调度重建。改动验证手段：核心日志会记录加载结果——

systemctl reload naemon; sleep 2; tail -3 /var/log/naemon/naemon.log

实测回显：

[1793509701] Naemon 1.5.2 starting... (PID=11566)
[1793509701] Local time is Sat Nov 01 04:28:21 UTC 2026
[1793509701] LOG VERSION: 2.0

四、参数总览

naemon.cfg 生效的 90 项参数按功能域分布如下（行数为实测统计）：

💡 技术拓展：Naemon 配置中的「布尔参数」沿用 Nagios 风格取值 0/1（而非 true/false）；「时间类参数」多数以 interval_length（默认 60 秒）为基准单位（如 check_interval=5 表示 5×60 秒），而超时类参数（service_check_timeout 等）是例外，直接以秒为单位。两套单位并存是误配重灾区，本文详解中会逐项标注单位。

五、核心参数分类详解

5.1 对象引入与路径参数

这一组参数决定「配置从哪里来、数据放到哪里去」，是改配置最先要弄懂的一组：

cfg_dir=/etc/naemon/conf.d
resource_file=/etc/naemon/resource.cfg
log_file=/var/log/naemon/naemon.log
object_cache_file=/var/lib/naemon/objects.cache
precached_object_file=/var/lib/naemon/objects.precache
status_file=/var/lib/naemon/status.dat
command_file=/var/lib/naemon/naemon.cmd
lock_file=/run/naemon/naemon.pid
temp_file=/var/lib/naemon/naemon.tmp
temp_path=/var/cache/naemon
check_result_path=/var/cache/naemon/checkresults
log_archive_path=/var/log/naemon/archives

逐项说明：

resource.cfg 的实测内容与关键细节——包安装时已把 $USER1$ 指到 naemon 自己的插件目录，而该目录是指向 Ubuntu 插件包的软链接：

grep -vE "^#|^$" /etc/naemon/resource.cfg
ls -la /usr/lib/naemon/plugins

实测回显：

$USER1$=/usr/lib/naemon/plugins
lrwxrwxrwx 1 root root 17 May 18 14:48 /usr/lib/naemon/plugins -> ../nagios/plugins

💡 说明：$USER1$ 是对象命令定义里插件路径的通用写法（command_line $USER1$/check_ping ...）。OBS 包通过 plugins -> ../nagios/plugins 软链接把 Naemon 宏与发行版插件包衔接，若你把插件装在自定义目录，改 resource.cfg 一行即可全局生效——这是比逐条改 commands.cfg 更推荐的做法。

5.2 日志行为参数

use_syslog=0
log_notifications=1
enable_notification_suppression_reason_logging=1
log_service_retries=1
log_host_retries=1
log_event_handlers=1
log_initial_states=0
log_current_states=1
log_external_commands=1
log_passive_checks=1
log_global_notifications=1

逐项说明：

• use_syslog=0：是否同时写 syslog；集中日志（rsyslog/日志服务器）场景改 1；
• log_notifications=1：记录每次通知发送（谁被通知了什么），排查"没收到告警"的第一现场；
• log_initial_states=0 / log_current_states=1：不记录初始状态快照、但记录周期性当前状态（CURRENT SERVICE STATE 行），控制日志量的一对旋钮；
• log_service_retries/log_host_retries=1：记录软状态（SOFT）重试，便于观察 max_check_attempts 的判定过程；
• log_external_commands=1：记录每条外部命令，审计自动化操作的关键开关（实测见 5.8）；
• enable_notification_suppression_reason_logging、log_global_notifications 是 Naemon 新增的日志增强：前者把"通知为何被抑制"的原因写进日志，后者记录全局通知开关动作——两者都是 Nagios 4 core 没有的，排障时非常有用。

日志轮转由包内 logrotate 配置管理，归档落 log_archive_path。

5.3 状态与保持参数

status_update_interval=10
retain_state_information=1
state_retention_file=/var/lib/naemon/retention.dat
retention_update_interval=60
use_retained_program_state=1
use_retained_scheduling_info=1
retained_scheduling_randomize_window=60
retained_host_attribute_mask=0
retained_service_attribute_mask=0
retained_process_host_attribute_mask=0
retained_process_service_attribute_mask=0
retained_contact_host_attribute_mask=0
retained_contact_service_attribute_mask=0

• status_update_interval=10：状态快照每 10 秒刷新一次。实测可从 naemonstats 的 Status File Age 直接看到节奏（Status File Age: 0d 0h 0m 10s，见部署篇）；
• retain_state_information=1 + state_retention_file：重启/重载后恢复历史状态、通知计数与调度时间，避免"每次重启都重新探测一轮"；
• retention_update_interval=60：retention.dat 每 60 秒落盘一次；
• use_retained_program_state：连全局开关状态（如临时禁用的通知）也一起恢复；
• retained_*_attribute_mask=0：按位掩码控制哪些属性不参与恢复（0 = 全部恢复，仅在做大改造时才需要动）；
• retained_scheduling_randomize_window=60：恢复调度时加 60 秒随机窗口，避免重启后全部检查同一秒扎堆。

5.4 检查调度与超时参数

interval_length=60
max_concurrent_checks=0
cached_host_check_horizon=15
cached_service_check_horizon=15
enable_predictive_host_dependency_checks=1
enable_predictive_service_dependency_checks=1
soft_state_dependencies=0
service_check_timeout=60
host_check_timeout=30
event_handler_timeout=30
notification_timeout=30
ocsp_timeout=5
perfdata_timeout=5
service_check_timeout_state=c
check_service_freshness=1
service_freshness_check_interval=60
check_host_freshness=0
host_freshness_check_interval=60
additional_freshness_latency=15
use_aggressive_host_checking=0

关键项说明：

• interval_length=60：调度单位 60 秒。生产不建议改——所有 interval 语义随之变化，且官方文档明确不建议调整；
• max_concurrent_checks=0：0 = 不限并发，由 worker 进程池自然消化（部署篇实测的 --worker 进程）。若要限制核心资源占用可设正值；
• cached_host_check_horizon / cached_service_check_horizon=15：15 秒内的最近检查结果可被依赖判定复用（跳过重复执行），是"缓存检查"机制的地平线；
• enable_predictive_*_dependency_checks=1：依赖对象状态变化时预判性检查被依赖对象，保证依赖链判定准确；
• service_check_timeout=60（单位：秒）：单个服务检查的最长执行时间，超时进程被终止并按 service_check_timeout_state 记状态；
• service_check_timeout_state=c：超时记为 CRITICAL（可选 s=WARNING/w、u=UNKNOWN/u，注意字母语义：c→CRITICAL、u→UNKNOWN、w→WARNING）；
• host_check_timeout=30：主机检查（通常是 ping 类）30 秒上限；
• use_aggressive_host_checking=0：非激进模式——DOWN 判定要求主机彻底不可达（慢但误报少）；改 1 则更敏感；
• freshness 组：被动检查场景的"新鲜度"兜底——超过周期没有收到被动结果就强制主动检查（check_service_freshness=1，主机侧默认关）。

超时参数实测（完整排障级验证）：把 service_check_timeout 从 60 改为 5，并挂一个会睡 30 秒的假检查命令，观察核心行为。测试对象定义：

define command {
  command_name    check_sleep
  command_line    /usr/local/bin/check_sleep.sh
}
define service {
  use                             generic-service
  host_name                       localhost
  service_description             SleepTest
  check_command                   check_sleep
  max_check_attempts              1
}

修改 service_check_timeout=5 并重载后，用外部命令强制立即执行（SCHEDULE_FORCED_SVC_CHECK），核心日志与 Livestatus 查询结果：

[1793507582] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;SleepTest;1793507582
[1793507587] SERVICE ALERT: localhost;SleepTest;CRITICAL;HARD;1;(Service check timed out after 5.00 seconds)
[1793507587] SERVICE NOTIFICATION: naemonadmin;localhost;SleepTest;CRITICAL;notify-service-by-email;(Service check timed out after 5.00 seconds)

python3 -c "
import socket
s=socket.socket(socket.AF_UNIX); s.connect('/var/cache/naemon/live')
s.sendall(b'GET services\nColumns: description state output execution_time\nFilter: description = SleepTest\n')
s.shutdown(socket.SHUT_WR); print(s.recv(65536).decode())
"

实测回显：

SleepTest;2;;5.0010810000e+00

结论：state=2（CRITICAL）、实际执行时间 5.001 秒——超时参数精确生效，检查进程在第 5 秒被收割并落日志。经验值：普通插件检查 30–60 秒足够；SNMP 慢设备、大目录扫描类检查按插件耗时上限再加 50% 余量设置，避免"误杀"正常慢检查。

5.5 通知与联系人参数

主配置层只有两个管理员地址参数，通知行为的主体在对象定义（contact/contactgroup/escalation）：

admin_email=naemon@localhost
admin_pager=pagenaemon@localhost

• admin_email / admin_pager：填充 $ADMINEMAIL$/$ADMINPAGER$ 宏，供通知命令引用（默认样例值，生产必须改）；
• 通知总开关 enable_notifications=1（5.7 节），每联系人还有自己的开关，取二者与；
• 包默认联系人 naemonadmin（/etc/naemon/conf.d/contacts.cfg）的 email 为 naemon@localhost——演示环境应改为真实收件地址，且通知命令 notify-service-by-email 依赖本机 MTA（mailx/sendemail 已被 naemon-core 依赖带入）。

5.6 抖动检测与新鲜度阈值参数

enable_flap_detection=1
low_service_flap_threshold=5.0
high_service_flap_threshold=20.0
low_host_flap_threshold=5.0
high_host_flap_threshold=20.0

• 抖动（flapping）指状态在 OK/非 OK 间高频翻转；核心按最近 21 次检查的状态变化率（%）判定，低于 low 视为停止抖动、高于 high 视为抖动中，5.0/20.0 是经典的 NCSA 推荐值，一般不动；
• 抖动中的对象默认不再发通知（防告警风暴），并可被 Web 界面单独筛选；
• 新鲜度阈值见 5.4 的 freshness 组。

5.7 执行开关参数

execute_service_checks=1
accept_passive_service_checks=1
execute_host_checks=1
accept_passive_host_checks=1
enable_notifications=1
enable_event_handlers=1
process_performance_data=0
obsess_over_services=0
obsess_over_hosts=0
translate_passive_host_checks=0
passive_host_checks_are_soft=0
check_for_orphaned_services=1
check_for_orphaned_hosts=1

• execute_* / accept_passive_*：主动检查执行与被动结果接收四开关。维护窗口临时停掉主动探测可置 execute_service_checks=0（重载即生效，状态保持恢复机制会记住）；
• enable_notifications=1：全局通知总开关（夜间发布窗口可临时置 0）；
• enable_event_handlers=1：事件处理器（故障自动响应脚本）开关；
• process_performance_data=0：性能数据采集总开关，接 PNP4Nagios/Grafana 类绘图链路时改 1 并配置 perfdata 命令；
• obsess_over_*：把每个检查结果再推送给 OCSP/OCHP 命令（分布式架构同步用），单机保持 0；
• check_for_orphaned_*=1：孤儿检查兜底——调度时间已过却迟迟没有结果的检查被标记孤儿并重新调度，防"检查黑洞"。

5.8 外部命令与事件代理参数

check_external_commands=1
command_file=/var/lib/naemon/naemon.cmd
event_broker_options=-1

• check_external_commands=1：开启外部命令通道。外部命令写法为「时间戳 命令名 参数」一行文本，追加到 command_file；核心周期收割。实测（写入 ENABLE_NOTIFICATIONS 命令并观察日志）：

printf '[%lu] ENABLE_NOTIFICATIONS\n' $(date +%s) >> /var/lib/naemon/naemon.cmd
sleep 3
grep "EXTERNAL COMMAND" /var/log/naemon/naemon.log | tail -1

实测回显：

[1793507515] EXTERNAL COMMAND: ENABLE_NOTIFICATIONS;

常用外部命令还有 SCHEDULE_FORCED_SVC_CHECK;host;service;epoch（强制立即检查，5.4 实测用过）、DISABLE_SVC_CHECK;host;service、ADD_SVC_COMMENT;host;service;0;作者;评论 等，全部命令清单见官网 Developers → External Commands。

• event_broker_options=-1：NEB（事件代理）全开，模块（如 Livestatus）才能拿到事件流；包内 Livestatus 模块经 include_dir=module-conf.d 加载，其实测配置：

grep -vE "^#|^$" /etc/naemon/module-conf.d/livestatus.cfg

实测回显：

broker_module=/usr/lib/naemon/naemon-livestatus/livestatus.so /var/cache/naemon/live
event_broker_options=-1

unix socket /var/cache/naemon/live 即 Livestatus 查询入口（部署篇已实测 GET hosts/services 查询）。

5.9 名称与宏字符约束参数

date_format=us
illegal_object_name_chars=`~!$%^&*|'"<>?,()=
illegal_macro_output_chars=`~$&|'"<>
use_regexp_matching=0
use_true_regexp_matching=0

• illegal_object_name_chars：对象名（主机名/服务名等）禁止字符集。默认集已含空格的近亲（逗号、括号等），因为对象名以空格分隔解析——主机/服务命名务必只留字母数字、-、_、.、:；
• illegal_macro_output_chars：插件输出进宏（如 $SERVICEOUTPUT$）前被剥离的危险字符，防注入到通知命令/邮件主题；
• use_regexp_matching=0：对象名匹配是否启用正则（0 = 仅 * 通配）；use_true_regexp_matching=1 时所有匹配都按完整正则处理（性能敏感，确有需要再开）。

5.10 调试参数

debug_level=0
debug_verbosity=1
debug_file=/var/lib/naemon/naemon.debug
max_debug_file_size=1000000

• debug_level=0：按位掩码，0 = 关闭；常用值 1（函数层）+2（配置）+4（进程）+8（调度）+16（事件代理）可相加组合；
• debug_verbosity=1：1=消息级，2=更啰嗦；
• max_debug_file_size=1000000：约 1MB 自动轮转，开启 debug 排障后记得改回 debug_level=0，否则高频写盘影响性能。

5.11 Naemon 特有参数

以下参数是相对 Nagios 4 core 的 Naemon 增量（Nagios 主配置里没有或语义不同）：

六、对象定义参数体系

6.1 对象类型与文件布局

conf.d/ 内按职责分文件（均可自行增删，cfg_dir 递归加载）：

ls /etc/naemon/conf.d/ /etc/naemon/conf.d/templates/

实测回显：

/etc/naemon/conf.d/:
commands.cfg
contacts.cfg
localhost.cfg
printer.cfg.sample
switch.cfg.sample
templates
thruk_templates.cfg
timeperiods.cfg
windows.cfg.sample

/etc/naemon/conf.d/templates/:
contacts.cfg
hosts.cfg
services.cfg

（windows/printer/switch 三个样例已按部署篇第七节改名停用。）

6.2 模板继承机制：register 与 use

对象定义的核心机制是模板继承：带 register 0 的定义不是真实对象，只是参数集模板；真实对象用 use 引用模板并覆写差异项。实测模板定义（摘自 templates/services.cfg）：

define service {
  name                           generic-service
  active_checks_enabled          1
  check_interval                 10
  check_period                   24x7
  contact_groups                 admins
  max_check_attempts             3
  notification_interval          60
  notification_options           w,u,c,r
  register                       0
}
define host {
  name                           linux-server
  use                            generic-host
  check_command                  check-host-alive
  check_interval                 5
  max_check_attempts             10
  notification_interval          120
  notification_options           d,u,r
  register                       0
}

• register 0：模板标记，必配；
• use：继承链（可多级，use a,b,c 后者覆盖前者）；
• 真实对象只需写差异：localhost.cfg 里一个服务定义通常只有 4 行（use/host_name/service_description/check_command），其余全部从模板继承。

6.3 五类核心对象的关键参数

命令与实参的联动实测样例（commands.cfg 与 localhost.cfg 的对应关系）：

# commands.cfg
define command {
  command_name    check_local_disk
  command_line    $USER1$/check_disk -w $ARG1$ -c $ARG2$ -p $ARG3$
}
# localhost.cfg
define service {
  service_description    Root Partition
  check_command          check_local_disk!20%!10%!/
}

check_command 中 ! 分隔的实参依次填充 $ARG1$/$ARG2$/$ARG3$；$USER1$ 来自 resource.cfg（5.1 节），$HOSTADDRESS$ 取 host 对象的 address。

6.4 常用宏速查

七、生产配置模板

适用场景：单节点 Naemon 监控 200 台主机 × 每台 10 项服务（2000 服务），8GB 内存、SSD、独立监控服务器。以下模板展示差异项（其余保持包默认），关键改动均有 5 节的依据：

# /etc/naemon/naemon.cfg —— 中型环境差异项（200 主机 × 10 服务，8GB，SSD）

# 路径：检查结果暂存区放 tmpfs（已在 /etc/fstab 挂 tmpfs 到 /var/cache/naemon）
temp_path=/var/cache/naemon
check_result_path=/var/cache/naemon/checkresults

# 日志：本地留全量 + 推 syslog 集中采集
log_file=/var/log/naemon/naemon.log
log_archive_path=/var/log/naemon/archives
use_syslog=1
log_initial_states=0
log_current_states=1
log_external_commands=1

# 调度与缓存：5 分钟一轮主动检查为主，缓存地平线保持默认
interval_length=60
max_concurrent_checks=0
cached_host_check_horizon=15
cached_service_check_horizon=15
service_check_timeout=60
host_check_timeout=30
service_check_timeout_state=c

# 状态：保持恢复开启，快照 10 秒一刷
retain_state_information=1
status_update_interval=10
retention_update_interval=60

# 抖动与新鲜度：默认阈值即可
enable_flap_detection=1
low_service_flap_threshold=5.0
high_service_flap_threshold=20.0
check_service_freshness=1
service_freshness_check_interval=60

# 外部命令与 NEB：开外部命令审计，broker 全开（Livestatus 依赖）
check_external_commands=1
event_broker_options=-1

# 管理员
admin_email=admin@example.com
admin_pager=admin-pager@example.com

💡 说明：2000 服务在 worker 池架构下的调度压力有限（包默认即可承载，naemonstats 的 Active Service Execution Time 是容量观察点——均值持续接近超时阈值就该分散检查或降低频率）。max_concurrent_checks=0（不限）依赖 worker 池自身平衡；确需硬限再设数值。改完按第三节流程：预检 → reload → 日志确认。

八、常见问题

Q1：改完配置 reload 后没生效？ 三步定位：① 预检是否真的以 naemon 用户执行且 Total Errors 为 0；② reload 是否执行（journalctl -u naemon -n 5 看 SIGHUP 记录）；③ 改的是不是被 cfg_dir 覆盖的另一份同名文件（cfg_dir 递归加载，同名对象定义后加载者覆盖前者）。

Q2：预检报 Error: Could not find any host matching 'xxx' 类错误？ 对象名引用打错或对象文件没被加载。先用 grep -rn "host_name xxx" /etc/naemon/conf.d/ 确认定义存在；若在新建文件里，检查文件名必须是 .cfg 结尾（cfg_dir 只认 .cfg）。

Q3：service_check_timeout 改小了，检查大量变 CRITICAL？ 那是超时"误杀"：插件真实耗时超过了新阈值。用 naemonstats 看 Active Service Execution Time 的最大值分布，按最大耗时 × 1.5 设阈值，别一刀切。

Q4：通知发了但收不到邮件？ 链路是 contact.email → notify-service-by-email 命令 → 本机 MTA。逐段验证：日志里 SERVICE NOTIFICATION 行是否存在（没有=通知条件不满足或有抑制，看 suppression 原因日志）；存在但没收到=MTA 出站问题（mailx/sendemail 配置），与 Naemon 无关。

Q5：对象缓存文件和 retention 文件能删吗？ objects.cache/objects.precache/status.dat 是运行产物，停服务后可删，重启自动重建；retention.dat 删了会丢历史状态与调度恢复（"重启后全部对象重新探测一轮"），不建议删。

九、参考链接

1. Naemon 用户手册 · Main configuration file options（主配置参数官方索引）：https://www.naemon.io/documentation/usersguide/configmain
2. Naemon 用户手册 · Object definitions（对象定义官方参考）：https://www.naemon.io/documentation/usersguide/objectdefinitions
3. Naemon 用户手册 · Configuration Overview（配置体系总览）：https://www.naemon.io/documentation/usersguide/config
4. Naemon 用户手册 · Object Inheritance（模板继承机制）：https://www.naemon.io/documentation/usersguide/objectinheritance
5. Naemon 用户手册 · Macros（宏参考）：https://www.naemon.io/documentation/usersguide/macros
6. Naemon 用户手册 · Verify configuration（预检官方说明）：https://www.naemon.io/documentation/usersguide/verifyconfig
7. 本专栏部署篇（安装与服务管理实测）：《Ubuntu 22.04 安装 Naemon 1.5 指南》