Wazuh 5.x 升级指南Manager 与 Agent 版本升级的完整操作、文件保留机制与回滚策略【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh本文基于 Wazuh 仓库的升级参考文档docs/ref/upgrade.md系统讲解 Wazuh 5.x 版本中 Manager服务端与 Agent代理端的升级流程从升级前备份、5.x 版本间的 preserve/restore 文件保留机制、集群滚动升级顺序到升级失败后的回滚与排障方法。读完后你可以独立完成单节点与集群环境下的 Wazuh 升级并理解升级脚本底层如何保证配置文件不被新包覆盖。需要特别强调的是版本支持范围Wazuh Manager 从 4.x 升级到 5.x 不受支持跨主版本升级 Manager 必须全新安装而Wazuh Agent 支持从 4.x 升级到 5.x并且 5.x Agent 可以连接到 5.x Manager。这一限制不只是文档约定在仓库中有源码级的硬性拦截见下文 升级入口的版本硬拦截。升级前准备要求、备份与适用前提升级前检查清单按照升级文档的要求在执行任何升级操作之前应完成以下准备工作查阅 release notes确认新版本的 breaking changes破坏性变更与新特性确认目标系统满足新版本的要求按照 备份与恢复指南 创建备份规划升级维护窗口通知相关干系人。当前仓库的版本状态可由 VERSION.json 确认当前为 5.1.0 阶段版本因此本文描述的流程适用于5.x 到 5.x的升级路径。升级前备份升级前必须先创建备份。文档给出的标准备份脚本如下# Create backup directory BACKUP_DIR/backup/wazuh-manager-$(date %Y%m%d-%H%M%S) sudo mkdir -p $BACKUP_DIR/db # Backup configuration and database sudo tar -czf $BACKUP_DIR/wazuh-etc.tar.gz -C /var/wazuh-manager etc/ sudo sqlite3 /var/wazuh-manager/var/db/global.db .backup $BACKUP_DIR/db/global.db # Verify backup integrity tar -tzf $BACKUP_DIR/wazuh-etc.tar.gz /dev/null echo Backup successful sudo sqlite3 $BACKUP_DIR/db/global.db PRAGMA integrity_check要点说明备份对象是/var/wazuh-manager/etc/完整配置目录包含client.keys、证书等与global.dbSQLite 全局数据库存放 Agent 注册与分组信息使用sqlite3 .backup而非直接cp保证数据库文件在写状态下的一致性两条验证命令分别确认 tar 包可正常解包、数据库integrity_check通过。更完整的备份范围如 SSL 证书、共享文件目录参见 备份与恢复指南。ManagerServer升级流程下载与安装新包下载对应平台与版本的 Wazuh Manager 包可参考 Package Download 一节获取仓库与下载说明然后安装Debian 系平台sudo dpkg -i wazuh-manager_*.debRed Hat 系平台sudo rpm -Uvh wazuh-manager-*.rpm包管理器在安装过程中会自动完成四件事停止当前服务、保留原有配置与运行时数据机制见下文、安装新二进制文件、重新拉起服务。文件保留机制preserve / restore在 5.x 到 5.x 的升级中.deb、.rpm与源码升级脚本都会应用一套preserve / restore机制升级后的路径行为如下路径升级后结果etc/完整保留自上一版本安装包括localtimedata/*除data/tzdb完整保留自上一版本安装data/tzdb不走升级备份/恢复流程由新包或源码中的时区数据库更新bin/、库文件、资产文件被新包替换文件内容、权限与属主在上述路径上均被保留升级过程不会归一化或重置管理员自行设置的任何权限与属主。新默认值如何生效。由于etc/被完整保留新包携带的新默认值不会自动应用到已有文件DEB Manager 升级会在生效配置旁边写出一个wazuh-manager.conf.new侧文件供人工对比RPM 则为保留路径生成等价侧文件需要时请手动与包内默认值对比。升级失败时的保留目录。源码升级在 preserve 步骤之后失败或被打断时会自动尝试恢复保留的文件若自动恢复失败或包升级在恢复完成前失败保留目录会被原样留在系统中供手动恢复升级栈Preserve 目录DEB/var/wazuh-manager/packages_files/manager_upgrade_preserveRPM/var/wazuh-manager/tmp/manager_upgrade_preserve源码${TMPDIR:-/tmp}/wazuh-manager-upgrade-preserve.*恢复数据后重试升级前必须删除保留目录。DEB/RPM 升级一旦发现已存在的 preserve 备份会直接中止源码升级每次尝试都会创建新的临时保留目录旧的源码保留目录不会阻塞重试但手动恢复后仍应清理。升级入口的版本硬拦截从源码结构看文档中4.x Manager 不可升级到 5.x是一条硬编码约束。在 DEB 前置脚本 preinst 中升级分支首先从 dpkg 传入的旧版本号提取主版本若小于 5 立即输出错误并exit 1随后还会通过wazuh-manager-control info -v或安装目录下的VERSION.json二次校验检测不到版本no_version或版本过低old_version同样会打印如下提示并中止ERROR: Upgrade from Wazuh manager versions prior to 5.x is not supported. A clean installation of Wazuh manager 5.x is required.RPM 侧在 wazuh-manager.spec 中实现了相同的保护%pre升级段先检查UPGRADE_PRESERVE_DIR是否已存在存在则报Existing manager upgrade preserve backup found并退出再用cp -a将etc/与data/跳过tzdb完整复制到保留目录。保留/恢复的源码实现理解这套机制最有价值的部分是三个脚本文件1. DEB preinst —— 备份阶段。preinst 的backup_upgrade_preserve()逻辑为若/var/wazuh-manager/packages_files/manager_upgrade_preserve已存在打印ERROR: Existing manager upgrade preserve backup found并exit 1即文档中DEB 升级遇到已有保留备份会中止的出处用cp -a保留属性复制整个etc/遍历data/下所有条目含隐藏文件显式跳过tzdb后逐条cp -a到保留目录。preinst 同时负责停服务systemd / SysV /wazuh-manager-control多重兜底、清理旧的~api备份与 3.x 遗留的wazuh-api服务、迁移logs/ossec→logs/wazuh与queue/ossec→queue/sockets目录结构。2. DEB postinst —— 恢复阶段。postinst 的restore_upgrade_preserve()在新包文件落盘后执行先把保留目录中的etc/内容cp -a回/var/wazuh-manager/etc/再恢复data/各条目最后rm -rf删除保留目录。注释明确说明这是对这两个目录树的最后一步内容恢复与 RPM 的%posttrans顺序对齐严格满足etc/ 绝不被覆盖的升级契约。此外 postinst 还会将global.db从var/db/迁移到queue/db/并重新设置属主权限660升级场景下用新默认配置生成wazuh-manager.conf.new侧文件postinst 第 82-84 行属主root:wazuh-manager、权限 660——这就是文档提到的 DEB 侧文件恢复 API 的rbac.db与api.yaml升级前已被 preinst 暂存。3. 源码安装 —— 失败自动恢复。仓库根目录的 install.sh 实现了源码升级路径PrepareUpgradePreserve()用mktemp -d在${TMPDIR:-/tmp}下创建wazuh-${INSTYPE}-upgrade-preserve.XXXXXX目录并保存etc/与data/同样跳过tzdbRestoreUpgradePreserve()负责回拷AttemptUpgradePreserveRestore()在升级出错时先尝试自动恢复失败则打印Preserved files left at ... for manual recovery保留现场。值得注意的是源码恢复使用cp -R不带-p/-a而非备份时的cp -a注释说明这是为了让源码升级沿用安装器指定的属主与模式。验证升级# Check service status sudo systemctl status wazuh-manager # Check logs for errors sudo tail -50 /var/wazuh-manager/logs/wazuh-manager.log # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db PRAGMA integrity_check集群升级Worker 优先、Master 最后升级顺序集群部署必须按以下顺序升级Worker 节点一次只升一个Master 节点最后升级。这样安排是为了把服务中断降到最小单节点升级期间Agent 流量可以由其他 Worker 节点承接。备份所有节点Master 节点完整备份BACKUP_DIR/backup/wazuh-master-$(date %Y%m%d-%H%M%S) sudo mkdir -p $BACKUP_DIR/db # Full backup of master sudo tar -czf $BACKUP_DIR/wazuh-master-etc.tar.gz -C /var/wazuh-manager etc/ sudo sqlite3 /var/wazuh-manager/var/db/global.db .backup $BACKUP_DIR/db/global.db # Verify backup tar -tzf $BACKUP_DIR/wazuh-master-etc.tar.gz /dev/null echo Master backup successful每个 Worker 节点仅配置备份BACKUP_DIR/backup/wazuh-worker-$(hostname)-$(date %Y%m%d-%H%M%S) sudo mkdir -p $BACKUP_DIR # Configuration backup only sudo tar -czf $BACKUP_DIR/wazuh-worker-config.tar.gz -C /var/wazuh-manager/etc wazuh-manager.conf local_internal_options.conf # Verify backup tar -tzf $BACKUP_DIR/wazuh-worker-config.tar.gz /dev/null echo Worker backup successful逐个升级 Worker 节点在每个 Worker 节点上执行升级前检查集群状态sudo /var/wazuh-manager/bin/cluster_control -l下载新包见 Package Download。升级包# Debian 系 sudo dpkg -i wazuh-manager_*.deb # Red Hat 系 sudo rpm -Uvh wazuh-manager-*.rpm验证升级# Check service status sudo systemctl status wazuh-manager # Check cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l # Monitor cluster synchronization sudo tail -f /var/wazuh-manager/logs/cluster.log等待同步完成后再升级下一个 Worker# Monitor synchronization status sudo /var/wazuh-manager/bin/cluster_control -i # Check cluster logs sudo tail -50 /var/wazuh-manager/logs/cluster.log | grep -i sync对每个剩余 Worker 重复以上流程确保当前节点完全同步后再动下一个。最后升级 Master 节点Master 节点上执行确认所有 Worker 已升级且健康# Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Verify all workers are connected sudo /var/wazuh-manager/bin/cluster_control -i下载新包。升级包dpkg -i/rpm -Uvh同上。验证升级# Check service status sudo systemctl status wazuh-manager # Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Verify cluster health sudo /var/wazuh-manager/bin/cluster_control -i # Check logs sudo tail -50 /var/wazuh-manager/logs/wazuh-manager.log sudo tail -50 /var/wazuh-manager/logs/cluster.log验证集群同步# Check that all workers are synchronized with the master sudo /var/wazuh-manager/bin/cluster_control -l # Monitor cluster logs on master sudo tail -f /var/wazuh-manager/logs/cluster.log集群升级后的综合验证所有节点升级完成后在Master 节点执行# Check cluster status sudo /var/wazuh-manager/bin/cluster_control -l # Check cluster health sudo /var/wazuh-manager/bin/cluster_control -i # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db PRAGMA integrity_check # Monitor logs for errors sudo tail -100 /var/wazuh-manager/logs/wazuh-manager.log | grep -i error sudo tail -100 /var/wazuh-manager/logs/cluster.log | grep -i error在每个 Worker 节点执行# Check cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l # Monitor logs sudo tail -50 /var/wazuh-manager/logs/cluster.logAgent 升级流程升级前建议升级 Agent 之前预防性备份 Agent 配置ossec.conf与client.keys虽会被自动保留仍建议做外部备份分批升级避免所有 Agent 同时升级先在非生产 Agent 上验证确认 Manager 与新 Agent 版本的兼容性注册口令注意事项Wazuh 5.0 默认启用 Agent 注册的口令保护。若升级期间或之后需要重新注册 Agent必须使用注册口令。如果 5.0 Manager 是全新安装的请用sudo cat /var/wazuh-manager/etc/authd.pass在 Manager 上取回新口令并配置到 Agent或把旧authd.pass文件恢复到新 Manager。注意Wazuh Agent 4.x 及以后版本支持升级到 5.x。Agent 文件保留机制5.x 到 5.x 的 Agent 升级同样应用 preserve / restore 机制路径升级后结果etc/ossec.conf、client.keys、local_internal_options.conf、localtime等完整保留自上一版本安装bin/、库文件被新包替换DEB 升级会写出ossec.conf.new侧文件新默认配置供对比这一点在 wazuh-agent 的 postinst 中可以确认它在新装/升级分支用gen_wazuh.sh生成新配置并写入ossec.conf.new、权限 640。与 Server 相同文件内容、权限与属主均被保留升级不会重置管理员设置的权限。Agent 的保留目录位置升级栈Preserve 目录DEB/var/ossec/packages_files/agent_upgrade_preserveRPM/var/ossec/tmp/agent_upgrade_preserve源码${TMPDIR:-/tmp}/wazuh-agent-upgrade-preserve.*Linux AgentDebian 系sudo dpkg -i wazuh-agent_*.deb sudo systemctl status wazuh-agentRed Hat 系与 SUSE 系sudo rpm -Uvh wazuh-agent-*.rpm sudo systemctl status wazuh-agentmacOSsudo installer -pkg wazuh-agent-*.pkg -target / # 验证 sudo /Library/Ossec/bin/wazuh-control statusWindowswazuh-agent-*.msi /q # 验证 Get-Service -Name wazuh补充说明仓库中还存在面向 Agent 的远端升级路径——upgrade.sh 是下发到 Agent 侧var/upgrade/目录的升级脚本会在后台调用pkg_installer.sh完成新包的下载与安装配合 agent_upgrade.py 脚本可发起远程批量升级。若你的部署规模较大可评估该通道替代逐台手工dpkg/rpm操作。回滚Rollback升级失败或引发问题时可回滚到上一版本。Server 回滚Step 1停止服务sudo systemctl stop wazuh-managerStep 2移除新包# Debian 系 sudo dpkg -r wazuh-manager # Red Hat 系 sudo rpm -e wazuh-managerStep 3从备份恢复# Restore configuration sudo tar -xzf $BACKUP_DIR/wazuh-etc.tar.gz -C /var/wazuh-manager # Restore database sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db # Set permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/var/dbStep 4重装旧版本包。Step 5验证回滚sudo systemctl start wazuh-manager sudo systemctl status wazuh-manager集群回滚集群升级失败时按与升级相反的顺序回滚先回滚 Master若已升级再按升级顺序的逆序回滚 Worker。回滚 Worker 节点# Stop the service sudo systemctl stop wazuh-manager # Remove the new package (Debian) sudo dpkg -r wazuh-manager # Or remove the new package (Red Hat) sudo rpm -e wazuh-manager # Restore configuration sudo tar -xzf $BACKUP_DIR/wazuh-worker-config.tar.gz -C /var/wazuh-manager/etc # Reinstall previous version package # Start the service sudo systemctl start wazuh-manager # Verify cluster connectivity sudo /var/wazuh-manager/bin/cluster_control -l回滚 Master 节点# Stop the service sudo systemctl stop wazuh-manager # Remove the new package (Debian) sudo dpkg -r wazuh-manager # Or remove the new package (Red Hat) sudo rpm -e wazuh-manager # Restore configuration and database sudo tar -xzf $BACKUP_DIR/wazuh-master-etc.tar.gz -C /var/wazuh-manager sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db # Set permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/etc sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager/var/db # Reinstall previous version package # Start the service sudo systemctl start wazuh-manager # Verify cluster status sudo /var/wazuh-manager/bin/cluster_control -l故障排查Server 问题Manager 升级后无法启动# Check logs for specific errors sudo tail -100 /var/wazuh-manager/logs/wazuh-manager.log # Verify permissions sudo chown -R wazuh-manager:wazuh-manager /var/wazuh-manager # Check database integrity sudo sqlite3 /var/wazuh-manager/var/db/global.db PRAGMA integrity_checkManager 升级后 Agent 无法重连# Verify manager is listening on agent ports sudo netstat -tulpn | grep wazuh-manager # Check remoted process ps aux | grep wazuh-manager-remoted # Review remoted logs sudo tail -f /var/wazuh-manager/logs/wazuh-manager.log | grep remoted # Verify client.keys integrity sudo ls -l /var/wazuh-manager/etc/client.keys集群节点升级后不同步# Check cluster configuration sudo grep -A10 cluster /var/wazuh-manager/etc/wazuh-manager.conf # Verify network connectivity ping master_node_ip telnet master_node_ip 1516 # Check cluster daemon ps aux | grep wazuh-manager-clusterd # Review cluster logs sudo tail -100 /var/wazuh-manager/logs/cluster.log # Restart cluster service sudo systemctl restart wazuh-manager数据库迁移错误# Check database file permissions sudo ls -l /var/wazuh-manager/var/db/ # Review wazuh-manager.log for migration messages sudo grep -i database\|migration /var/wazuh-manager/logs/wazuh-manager.log # If migration fails, restore from backup sudo systemctl stop wazuh-manager sudo cp $BACKUP_DIR/db/global.db /var/wazuh-manager/var/db/global.db sudo chown wazuh-manager:wazuh-manager /var/wazuh-manager/var/db/global.db sudo systemctl start wazuh-manager升级中止已存在的保留目录若前一次包升级被中断保留目录可能仍留在系统中。DEB/RPM 升级遇到它会报Existing upgrade preserve backup found并中止源码升级每次尝试都使用新的临时保留目录旧目录不阻塞重试。恢复步骤检查保留目录内容将所需文件拷回etc/Manager 升级场景还包括data/删除保留目录后重试升级。# Example for manager DEB ls /var/wazuh-manager/packages_files/manager_upgrade_preserve/ # Recover if needed, then: sudo rm -rf /var/wazuh-manager/packages_files/manager_upgrade_preserveAgent 问题Agent 升级后无法启动# Check logs sudo tail -50 /var/ossec/logs/ossec.log # Verify client.keys exists sudo ls -l /var/ossec/etc/client.keys # Check permissions sudo chown -R root:wazuh /var/ossec/etcAgent 升级后无法连接 Manager# Verify manager address in configuration sudo grep address /var/ossec/etc/ossec.conf # Check network connectivity to manager ping manager_ip telnet manager_ip 1514 # Verify client.keys matches manager # Compare key on agent with managers client.keys entry # Check for enrollment password verification issues: # If you see ERROR: Invalid password (from manager) in /var/ossec/logs/ossec.log, # verify that the password in the agents /var/ossec/etc/authd.pass matches # the managers /var/wazuh-manager/etc/authd.pass. # Restart agent sudo systemctl restart wazuh-agentWindows Agent 升级失败# Check Windows event logs Get-EventLog -LogName Application -Source Wazuh -Newest 50 # Verify service status Get-Service -Name wazuh # Check installation logs Get-Content C:\Windows\Temp\wazuh-agent-install.log # Restart service Restart-Service -Name wazuh最佳实践升级前必须备份遵循 备份与恢复指南阅读 release notes了解破坏性变更与新特性非生产环境先行验证在维护窗口内升级选择低活动时段增量升级大规模部署分批执行升级期间持续监控盯紧日志与指标保持回滚就绪保留旧版本包与备份记录变更记录配置变更与遇到的问题集群中先升 Worker 后升 Master验证兼容性确保 Manager 与 Agent 版本互相兼容。相关资源备份与恢复指南安装指南配置参考集群文档升级脚本实现install.sh源码升级的 preserve/restore、DEB preinst/postinst、RPM spec【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考